Statewave Multi Agent Memory

Multi-Agent Memory with Statewave

[](https://www.python.org/downloads/) [](LICENSE) [](https://statewave.ai)

Three analyst agents ingest conflicting source documents concurrently. Watch Statewave detect the contradiction, supersede the stale fact, and serve the correct answer automatically, with no merge logic written by you.

---

Contents

• [Multi-Agent Memory with Statewave](#multi-agent-memory-with-statewave)
• [Contents](#contents)
• [What is Statewave](#what-is-statewave)
• [The problem this demo solves](#the-problem-this-demo-solves)
• [What happens when you run it](#what-happens-when-you-run-it)
• [How it works](#how-it-works)
• [Key concepts](#key-concepts)
• [Architecture](#architecture)
• [Prerequisites](#prerequisites)
• [Setup and run locally](#setup-and-run-locally)
• [Option A: npx (fastest)](#option-a-npx-fastest)
• [Option B: Docker Compose](#option-b-docker-compose)
• [Option C: run Python directly](#option-c-run-python-directly)
• [Usage](#usage)
• [Source documents](#source-documents)
• [Environment variables](#environment-variables)
• [Statewave API endpoints used](#statewave-api-endpoints-used)
• [Audit inspector](#audit-inspector)
• [Reading the audit trail](#reading-the-audit-trail)
• [Adapting to your domain](#adapting-to-your-domain)
• [Using Statewave with multi-agent frameworks](#using-statewave-with-multi-agent-frameworks)
• [Developer reference](#developer-reference)
• [Project structure](#project-structure)
• [SSE event types](#sse-event-types)
• [License](#license)

---

What is Statewave

Statewave is an open-source memory runtime for AI agents. You give it raw events (episodes); it compiles them into typed, conflict-resolved memories; your agents query it to get ranked, token-bounded context ready to drop into a prompt. No GPU. No vector database. No application-level merge logic.

The loop: Ingest → Compile → Use

Full documentation at statewave.ai.

---

The problem this demo solves

In a typical multi-agent pipeline, two agents can read sources of different freshness and commit contradicting facts to the same shared store. The usual options are: blow up the context window by sending everything to the LLM and hoping it figures it out, or write custom merge logic that is brittle and hard to audit.

Statewave is the third option. When two memories about the same entity exceed a word-overlap similarity threshold, the compiler automatically supersedes the older one and records the decision with full provenance. Your agents query context and only ever see the winner.

---

What happens when you run it

You click Run pipeline. Three agents: Bloomberg, TechCrunch, and Earnings, start concurrently. Each one reads its source document, extracts structured findings, and commits an episode to the shared Statewave subject market-intel. As each agent compiles, its memories appear live in the browser panel.

Then TechCrunch's compilation finishes. The Bloomberg Stripe entry goes red with a strikethrough. The status bar reads "1 conflict resolved". You did not write any code to make that happen.

> The moment that matters: Bloomberg committed Stripe's old rate of 3.5% + 35¢. TechCrunch committed the post-reversal rate of 2.9% + 30¢. Statewave's compiler measured Jaccard word-overlap ≥ 0.6 between the two memories, marked Bloomberg as superseded by TechCrunch, and recorded the decision in the audit trail. When you ask "What is Stripe's current processing fee?", the synthesis agent queries context and gets back 2.9%, it never sees the stale figure.

---

How it works

Every agent follows the same three-step loop:

1. Ingest. The agent reads its source document, uses the LLM to extract structured findings, and calls POST /v1/episodes to append a raw, content-hashed episode to the shared subject. Episodes are append-only; nothing is overwritten.

1. Compile. The agent calls POST /v1/memories/compile. Statewave's heuristic compiler extracts typed memories from the episode log and runs conflict detection. If two memories about the same fact share enough word overlap (Jaccard ≥ 0.6), the older one is marked superseded with a provenance link to both source episodes.

1. Use. The synthesis agent calls POST /v1/context with the subject ID and the user's question. Statewave returns a ranked, token-bounded assembled_context containing only active (non-superseded) memories. The agent passes this bundle directly to the LLM and streams the answer back to the browser.

Key concepts

| Concept | What it means | | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | Episode | Append-only raw event: subject ID + source + type + payload. The immutable source of truth. | | Memory | Extracted, typed, compiled summary. Traces back to source episodes with confidence scores and provenance. | | Compile | Idempotent episodes → memories conversion. Heuristic (local) or LLM compiler. No GPU required. | | Conflict resolution | When two memories about the same fact exceed the similarity threshold, the older is automatically superseded by the newer. Deterministic. | | Context API | POST /v1/context: ranked, token-bounded context bundle ready for prompts. Same query, same bytes. | | Subject | Any entity you track: user, agent, account, repo. Here: one subject (market-intel) per pipeline run. |

---

Architecture

Three concurrent agents share a single Statewave subject. The FastAPI server orchestrates the agents and pushes live updates to the browser via SSE. Statewave runs as a separate local service.

Demo interface during a full multi-agent run:

---

Prerequisites

• Node.js 20+: required for Option A (fastest; boots Statewave via npx) and for the audit inspector
• Python 3.11+: required to run this demo app in all options
• LLM API key from your Groq account (default) or any provider supported by LiteLLM (set LLM_MODEL accordingly)
• Docker and Docker Compose: only needed for Option B

---

Setup and run locally

Option A: npx (fastest)

Statewave ships a one-line launcher: no Docker, no account, runs offline. It boots the API, admin console, and Postgres, and wires itself into your MCP clients.

1. Clone this repo

git clone https://github.com/smaramwbc/statewave-multi-agent-memory
cd statewave-multi-agent-memory

2. Start Statewave

npx @statewavedev/statewave

This starts the Statewave backend at http://localhost:8100 (leave this running in its own terminal). macOS/Linux/Windows all work; you can also use the install script instead of npx:

curl -fsSL https://www.statewave.ai/install | sh   # macOS/Linux
irm https://www.statewave.ai/install.ps1 | iex       # Windows PowerShell

3. Install Python dependencies and configure environment

pip install -r requirements.txt
cp .env.example .env

Open .env and set LLM_API_KEY to your LLM provider API key.

4. Start this demo

python server.py

Open http://localhost:8000 and click Run pipeline.

---

Option B: Docker Compose

Use this if you want Statewave running alongside the demo in containers (e.g. for a production-like Postgres setup), rather than the lightweight npx launcher.

1. Clone this repo

git clone https://github.com/smaramwbc/statewave-multi-agent-memory
cd statewave-multi-agent-memory

2. Configure environment

cp .env.example .env

Open .env and set LLM_API_KEY to your LLM provider API key.

3. Start everything

docker compose up

Open http://localhost:8000 and click Run pipeline.

---

Option C: run Python directly

Use this if you prefer to run the demo server outside Docker while still running Statewave via Docker.

1. Clone this repo

git clone https://github.com/smaramwbc/statewave-multi-agent-memory
cd statewave-multi-agent-memory

2. Install Python dependencies

pip install -r requirements.txt

3. Configure environment

cp .env.example .env

Open .env and set LLM_API_KEY. Set STATEWAVE_URL if your Statewave instance is not at the default http://localhost:8100.

4. Start the Statewave backend

docker compose up -d api db

5. Start this demo

python server.py

Open http://localhost:8000 and click Run pipeline.

---

Usage

1. Click Run pipeline. Three agent panels appear and begin logging in real time.
2. Watch the Memory panel as each agent commits its findings. When TechCrunch's memory lands, the Bloomberg Stripe entry is immediately struck through in red.
3. The status bar updates to "1 conflict resolved" once compilation finishes.
4. Type a question in the chat input, e.g. "What is Stripe's current processing fee?" and the synthesis agent answers using active memories only.
5. Click Reset to clear the subject and run again.

---

Source documents

| File | Stripe fact | Role | | ------------------------- | ----------------------------------- | ------------------------------------------------ | | sources/bloomberg.json | 3.5% + 35¢ (stale, pre-reversal) | Committed first; the fact to be superseded | | sources/techcrunch.json | 2.9% + 30¢ (correct, post-reversal) | Contradicts Bloomberg; triggers supersession | | sources/earnings.json | 2.9% + 30¢ + Square miss | Corroborates TechCrunch; contributes Square data |

The Bloomberg document intentionally contains a pre-reversal figure. The conflict is synthetic but structurally identical to what happens in real pipelines when agents pull from sources of different freshness.

---

Environment variables

| Variable | Required | Default | Description | | --------------------------- | -------- | ------------------------------ | ------------------------------------------------------------------------------------------------- | | LLM_API_KEY | Yes | (none) | API key for your LLM provider | | LLM_MODEL | No | groq/llama-3.3-70b-versatile | LiteLLM model string. Change to use a different provider, e.g. openai/gpt-4o | | STATEWAVE_URL | No | http://localhost:8100 | Statewave server base URL | | STATEWAVE_API_KEY | No | (none) | API key if your Statewave instance has auth enabled | | APP_SECRET | No | (none) | When set, all demo API endpoints require X-API-Key: . Leave unset for local dev. | | SUBJECT_ID | No | market-intel | Shared Statewave memory namespace. Change when adapting to a different domain. | | SYNTHESIS_SYSTEM_PROMPT | No | (built-in analyst prompt) | System instruction given to the LLM when answering questions. Override to match your domain. | | DEMO_SEED_BLOOMBERG_STRIPE| No | true | Pre-seeds the stale Bloomberg Stripe fact. Set to false when using your own source files. |

---

Statewave API endpoints used

| Endpoint | Purpose | | --------------------------- | ------------------------------------------------------ | | POST /v1/episodes | Ingest a raw episode from an agent | | POST /v1/memories/compile | Trigger conflict detection and memory extraction | | POST /v1/context | Retrieve ranked, token-bounded context for a query | | GET /v1/timeline | Fetch full episode + memory timeline for the inspector | | DELETE /v1/subjects/{id} | Reset subject between pipeline runs |

---

Audit inspector

The inspector/ directory contains a TypeScript tool that prints the full audit trail for any subject: episodes in chronological order, derived memories, and supersession records with source references and Jaccard similarity scores.

cd inspector
npm install
npx tsx src/index.ts --subject-id market-intel

Reading the audit trail

The inspector output has three sections:

Episodes: raw, append-only inputs from each agent. Each episode shows the source, type, and the payload text that was ingested.

Memories: the compiled, typed facts extracted from episodes. Each memory shows:

• status: active: currently the authoritative version of this fact
• status: superseded: an older version that was replaced; still in the audit trail for provenance
• superseded_by: the ID of the memory that replaced it

Supersessions: the conflict resolution decisions. Each entry shows:

• Which memory was replaced and by which
• The Jaccard word-overlap similarity score that triggered the supersession (threshold: ≥ 0.6)
• The source episodes on both sides

Example output after the demo run:

EPISODES (5 total)
  bloomberg/2026-05-16  agent.analyst.findings  Stripe pricing (bloomberg, 2026-05-16): 3.5% + 35¢...
  techcrunch/2026-06-01 agent.analyst.findings  Stripe pricing (techcrunch, 2026-06-01): 2.9% + 30¢...
  earnings/2026-06-15   agent.analyst.findings  Stripe pricing (earnings, 2026-06-15): 2.9% + 30¢...
  bloomberg/2026-05-16  agent.analyst.findings  Square positioning (bloomberg): leading mobile POS...
  earnings/2026-06-15   agent.analyst.findings  Square revenue miss Q2 2026...

MEMORIES (4 active, 1 superseded)
  [active]     techcrunch  Stripe pricing (techcrunch, 2026-06-01): 2.9% + 30¢...
  [superseded] bloomberg   Stripe pricing (bloomberg, 2026-05-16): 3.5% + 35¢...
                             superseded_by → techcrunch memory (Jaccard: 0.72)
  [active]     bloomberg   Square positioning (bloomberg): leading mobile POS...
  [active]     earnings    Square: missed Q2 revenue estimates by 8%...
  [active]     bloomberg   Square key differentiators: offline mode, hardware...

SUPERSESSIONS (1)
  bloomberg Stripe pricing → superseded by techcrunch Stripe pricing
  similarity: 0.72  (threshold: 0.60)
  older episode: bloomberg/2026-05-16
  newer episode: techcrunch/2026-06-01

The key insight: Bloomberg's independent Square facts (positioning, differentiators) survived the Stripe supersession because they are separate atomic memories with no word overlap against the Stripe memories. Only the stale pricing fact was replaced.

---

Adapting to your domain

The demo is wired for competitive intelligence on payment processors. To run it for a different domain, you only need to change .env and drop in new JSON source files. No Python changes required.

1. Set your subject ID and prompts in .env

# The shared memory namespace for this pipeline run
SUBJECT_ID=healthcare-news

# The instruction given to the LLM when answering questions in the chat panel
SYNTHESIS_SYSTEM_PROMPT=You are a h

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [smaramwbc](https://github.com/smaramwbc)
- **Source:** [smaramwbc/statewave-multi-agent-memory](https://github.com/smaramwbc/statewave-multi-agent-memory)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.