Multi-Agent Memory with Statewave

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
  • Contents
  • What is Statewave
  • The problem this demo solves
  • What happens when you run it
  • How it works
    • Key concepts
  • Architecture
  • Prerequisites
  • Setup and run locally
    • Option A: Docker Compose (recommended)
    • Option B: run Python directly
  • Usage
  • Source documents
  • Environment variables
  • Statewave API endpoints used
  • Audit inspector
  • Developer reference
    • Project structure
    • SSE event types
  • 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.

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

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

• Docker and Docker Compose: required for Option A (recommended)
• LLM API key from your Groq account (default) or any provider supported by LiteLLM (set LLM_MODEL accordingly)
• Python 3.11+: only needed for Option B (run without Docker)
• Node.js 20+: optional, for the audit inspector only

Setup and run locally

Option A: Docker Compose (recommended)

One command brings up the Statewave backend, its database, and the demo app together.

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 B: 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

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

Statewave API endpoints used

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

Developer reference

Project structure

statewave-multi-agent-memory/
├── agents/
│   ├── analyst.py          # Agent logic: ingest → compile → diff
│   └── base.py             # AsyncStatewaveClient wrapper
├── sources/
│   ├── bloomberg.json      # Stale Stripe pricing (3.5%) — to be superseded
│   ├── techcrunch.json     # Corrected Stripe pricing (2.9%) — supersedes Bloomberg
│   └── earnings.json       # Corroborates TechCrunch, adds Square data
├── inspector/
│   └── src/index.ts        # Audit trail: episodes, memories, supersessions
├── static/
│   └── index.html          # Browser UI (SSE-driven, zero build step)
├── server.py               # FastAPI app: /run /ask /events /memories
├── Dockerfile              # Builds the demo server as a container image
├── docker-compose.yml      # Starts db + Statewave API + demo in one command
├── requirements.txt
└── .env.example

SSE event types

The browser receives a single /events stream. Event types:

License

Apache-2.0. See LICENSE.