# Statewave Multi Agent Memory > MCP server from smaramwbc/statewave-multi-agent-memory. - **Type:** MCP server - **Install:** `agentstack add mcp-smaramwbc-statewave-multi-agent-memory` - **Verified:** Pending review - **Seller:** [smaramwbc](https://agentstack.voostack.com/s/smaramwbc) - **Installs:** 0 - **Category:** [Integrations](https://agentstack.voostack.com/c/integrations) - **Latest version:** 0.1.0 - **License:** Apache-2.0 - **Upstream author:** [smaramwbc](https://github.com/smaramwbc) - **Source:** https://github.com/smaramwbc/statewave-multi-agent-memory ## Install ```sh agentstack add mcp-smaramwbc-statewave-multi-agent-memory ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # 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](https://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. 2. **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. 3. **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** ```bash git clone https://github.com/smaramwbc/statewave-multi-agent-memory cd statewave-multi-agent-memory ``` **2. Start Statewave** ```bash 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`: ```bash 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** ```bash 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** ```bash python server.py ``` Open [http://localhost:8000](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** ```bash git clone https://github.com/smaramwbc/statewave-multi-agent-memory cd statewave-multi-agent-memory ``` **2. Configure environment** ```bash cp .env.example .env ``` Open `.env` and set `LLM_API_KEY` to your LLM provider API key. **3. Start everything** ```bash docker compose up ``` Open [http://localhost:8000](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** ```bash git clone https://github.com/smaramwbc/statewave-multi-agent-memory cd statewave-multi-agent-memory ``` **2. Install Python dependencies** ```bash pip install -r requirements.txt ``` **3. Configure environment** ```bash 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** ```bash docker compose up -d api db ``` **5. Start this demo** ```bash python server.py ``` Open [http://localhost:8000](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. ```bash 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`** ```bash # 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. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** yes - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** yes - **Dynamic code execution:** yes *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: flagged — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-smaramwbc-statewave-multi-agent-memory - Seller: https://agentstack.voostack.com/s/smaramwbc - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.