# Statewave

> Statewave is an open-source memory runtime for AI agents. It records events, compiles them into semantic and episodic memories, and retrieves compact, ranked context bundles for LLM applications.

For the long-form reference (full REST API, SDK usage, and a complete agent integration flow), see https://www.statewave.ai/llms-full.txt.

Statewave is a self-hostable memory runtime for LLM apps and agents. It helps applications remember users, decisions, projects, sessions, tool calls, and prior interactions without relying on prompt stuffing or naive chat history.

Statewave stores immutable episodes, compiles them into typed memories with provenance, and retrieves deterministic, token-bounded context bundles that can be inserted into prompts, tools, copilots, agents, or MCP-style workflows.

## Primary links

- [Website](https://www.statewave.ai/) — product overview, positioning, FAQ, and project updates.
- [How It Works](https://www.statewave.ai/product) — lifecycle: record, compile, retrieve, govern.
- [Why Statewave](https://www.statewave.ai/why) — comparison with prompt stuffing, naive RAG, and temporary chat history.
- [Use Cases](https://www.statewave.ai/use-cases) — support agents, coding copilots, account intelligence, voice continuity, and multi-agent systems.
- [Connectors](https://www.statewave.ai/connectors) — GitHub, Jira, Slack, Notion, Discord, Zendesk, Intercom, Freshdesk, Gmail, n8n, Zapier, databases, Markdown/ADRs, MCP, and more.
- [Developers](https://www.statewave.ai/developers) — SDKs, docs, API reference, and examples.
- [About](https://www.statewave.ai/about) — what Statewave is, who it's for, the repos that ship it, and how to get in touch.
- [Blog](https://www.statewave.ai/blog) — design notes, deployment patterns, and how the runtime works under the hood. Also at [/blog/rss.xml](https://www.statewave.ai/blog/rss.xml), [/blog/atom.xml](https://www.statewave.ai/blog/atom.xml), [/blog/feed.json](https://www.statewave.ai/blog/feed.json).
- [FAQ](https://www.statewave.ai/faq) — common questions about Statewave, answered directly.
- [Benchmarks](https://www.statewave.ai/benchmarks) — LoCoMo and LongMemEval retrieval scores measured on the incumbent's own evaluation harness, with the run methodology.

## Use cases

- [Multi-Agent Memory](https://www.statewave.ai/use-cases/multi-agent-memory) — one shared, append-only memory layer for agent pipelines: each agent writes findings as episodes and reads ranked, token-bounded context before acting, resumable across partial failures.
- [Personal Assistant Memory](https://www.statewave.ai/use-cases/personal-assistant-memory) — cross-session memory for chat assistants: turns become typed, confidence-ranked facts recalled within a fixed token budget.
- [Multi-Agent Shared Context](https://www.statewave.ai/use-cases/multi-agent-shared-context) — parallel agents coordinating through one authoritative context layer instead of message-passing, so conflicts are prevented rather than detected after wasted compute.
- [Grounded Shop Assistant](https://www.statewave.ai/use-cases/grounded-shop-assistant) — a shopper/ops assistant pair that answers strictly from retrieved evidence, validates every citation, and turns ungrounded questions into coverage-gap episodes.

## Comparisons

- [Statewave vs Mem0](https://www.statewave.ai/vs/mem0) — deterministic, token-bounded context assembly with policy enforcement and integrity-hashed receipts vs ranked similarity retrieval, plus LoCoMo and LongMemEval results measured on Mem0's own harness.
- [Statewave vs Letta](https://www.statewave.ai/vs/letta) — runtime-managed vs agent-managed memory: Letta's agent edits and searches its own memory with tool calls; Statewave assembles the bundle mechanically.
- [Statewave vs Zep](https://www.statewave.ai/vs/zep) — inspectable bundle vs opaque Context Block: typed, provenance-traced memories with per-row confidence and validity against a knowledge-graph string.
- [Statewave vs Supermemory](https://www.statewave.ai/vs/supermemory) — deterministic assembly with per-row provenance vs hybrid vector-plus-keyword search with context-aware reranking.

## Blog posts

- [Episodic vs Semantic Memory in AI Agents](https://www.statewave.ai/blog/episodic-vs-semantic-memory): What to store as an episode vs a semantic fact, when to convert one to the other, and why agents forget between sessions.
- [Agent memory provenance: why your LLM app needs an audit trail](https://www.statewave.ai/blog/agent-memory-provenance-audit-trails): The provenance model in Statewave — what's stored, what it costs, and what it enables for compliance and debugging.
- [AI agent memory vs RAG](https://www.statewave.ai/blog/ai-agent-memory-vs-rag): Where a memory runtime and retrieval-augmented generation overlap, where they diverge, and which to reach for.
- [How to add persistent memory to your AI support agent](https://www.statewave.ai/blog/persistent-memory-for-ai-support-agents): A practical walkthrough — record, compile, retrieve, splice — plus what the support workflow benchmark measures.
- [Self-hosted AI memory with Postgres and pgvector](https://www.statewave.ai/blog/self-hosted-memory-postgres-pgvector): Why Statewave is Postgres-only by design, and what pgvector buys you over a dedicated vector database.
- [AI Data Governance for AI Agents](https://www.statewave.ai/blog/ai-data-governance-for-ai-agents): Governance on the retrieval path — receipts, sensitivity labels, policy bundles, residency, and the EU AI Act dates.
- [Multi-Tenant Isolation in AI Memory](https://www.statewave.ai/blog/multi-tenant-isolation-in-ai-memory): Where the tenant boundary belongs, the surfaces that aren't tenant-scoped, and the NULL-tenant backfill step.
- [Token-Bounded Context Assembly](https://www.statewave.ai/blog/token-bounded-context-assembly): Scoring, the greedy fill, what a bigger budget actually buys, and why determinism matters more than compression.
- [Idempotent Compilation and Conflict Resolution](https://www.statewave.ai/blog/idempotent-compilation-and-conflict-resolution): The four meanings of idempotent, why a TTL'd dedup marker won't protect derived facts, and why supersession beats overwrite.
- [AI Support Agents: Why Session State Beats More Memory](https://www.statewave.ai/blog/ai-support-agent-session-state): The ranking arithmetic that makes a support agent read ticket state instead of similarity, and the four schema mistakes that break it.
- [Repeat-Issue Detection in Customer Support Automation](https://www.statewave.ai/blog/repeat-issue-detection-customer-support-automation): Why a resolved session is suppressed on purpose, the two-point margin that surfaces the prior fix, and what to write in the resolution summary.
- [6 Best Open-Source Alternatives to Mem0 (2026)](https://www.statewave.ai/blog/open-source-alternatives-to-mem0): What Mem0's self-hosted build leaves out, which of the six alternatives hold features back from their free edition, and how to pick by requirement.
- [The Customer Health Score Your Support Agent Can Explain](https://www.statewave.ai/blog/customer-health-score-handoff-context-packs): The eight scoring signals and their caps, why the number drifts on quiet days, and what a handoff context pack keeps under its token budget.

## Documentation

- [Getting Started](https://github.com/smaramwbc/statewave-docs/blob/main/getting-started.md) — 5-minute Docker Compose setup.
- [REST API v1](https://github.com/smaramwbc/statewave-docs/blob/main/api/v1-contract.md) — API contract.
- [Architecture](https://github.com/smaramwbc/statewave-docs/blob/main/architecture/overview.md) — system overview.
- [Compiler Modes](https://github.com/smaramwbc/statewave-docs/blob/main/architecture/compiler-modes.md) — heuristic compiler and LLM compiler.
- [Ranking and Retrieval](https://github.com/smaramwbc/statewave-docs/blob/main/architecture/ranking.md) — deterministic scoring and context assembly.
- [Privacy and Data Flow](https://github.com/smaramwbc/statewave-docs/blob/main/architecture/privacy-and-data-flow.md) — storage, processing, and data boundaries.
- [Deployment](https://github.com/smaramwbc/statewave-docs/blob/main/deployment/guide.md) — Docker Compose, Fly.io, Railway.
- [Roadmap](https://github.com/smaramwbc/statewave-docs/blob/main/roadmap.md) — planned capabilities.

## Repositories

- [statewave](https://github.com/smaramwbc/statewave) — core server.
- [statewave-py](https://github.com/smaramwbc/statewave-py) — Python SDK.
- [statewave-ts](https://github.com/smaramwbc/statewave-ts) — TypeScript SDK.
- [statewave-connectors](https://github.com/smaramwbc/statewave-connectors) — connector ecosystem.
- [statewave-docs](https://github.com/smaramwbc/statewave-docs) — docs, architecture, API contracts, ADRs.
- [statewave-examples](https://github.com/smaramwbc/statewave-examples) — runnable examples and evaluation flows.
- [statewave-admin](https://github.com/smaramwbc/statewave-admin) — read-only operator console.
- [statewave-web](https://github.com/smaramwbc/statewave-web) — marketing site.

## Core concepts

- Subject — user, account, agent, repo, project, or session Statewave remembers around.
- Episode — immutable event record such as a conversation turn, tool call, decision, or observation.
- Memory — typed fact compiled from episodes, with confidence, validity, embedding, and provenance.
- Context bundle — ranked, token-bounded runtime output for LLM prompts.
- Compiler — heuristic or LLM-backed process that turns episodes into memories.
- Ranking — deterministic scoring based on priority, recency, relevance, validity, and token budget.

## Install

- Quickstart (one command) — boots a local Statewave (API + admin console + Postgres via Docker Compose), auto-configures your MCP clients (Claude Code, Claude Desktop, Cursor, VS Code Copilot, Codex CLI), and seeds a repo. Self-hosted, offline, no account.
  - macOS / Linux: `curl -fsSL https://www.statewave.ai/install | sh`
  - Windows: `powershell -Command "irm https://www.statewave.ai/install.ps1 | iex"`
  - Node.js 20+ alternative: `npx @statewavedev/statewave`
  - API at `http://localhost:8100`, admin at `http://localhost:8080`; tear down with `npx @statewavedev/statewave --down`.
- Server (manual): clone `https://github.com/smaramwbc/statewave` and run `docker compose up -d`.
- Python SDK: `pip install statewave`.
- TypeScript SDK: `npm install @statewavedev/sdk`.

## Scope

Statewave is self-hosted. There is currently no managed Statewave cloud.

The strongest evaluated workflow today is support-agent memory, including handoff packs, health scoring, SLA tracking, and repeat-issue detection. Other use cases use the same primitives but may have fewer pre-built helpers.

Ranking weights are currently fixed. Per-call ranking overrides are not yet exposed.

Horizontal scaling is supported by design through a stateless API and Postgres-backed infrastructure, but high-RPS load testing is still in progress.