Statewave

Statewave is the open-source memory runtime that gives AI agents reproducible, provenance-tagged context — without sampling-noise from query-time retrieval.

If Statewave is useful to you, a ⭐ on the repo helps others discover it.

v1.3.0 — actively developed. Changelog · Roadmap · Limitations

🎯 Try it

The interactive comparison demo is embedded directly in the website at statewave.ai — open the chat widget to see two identical AI agents answer the same question, one stateless and one backed by Statewave.

🚀 Skip to Getting Started →

The problem

Most AI applications have no memory. Every conversation starts from scratch. Context is lost between sessions, decisions aren't remembered, and user history disappears the moment a session ends. Bolting on a vector database or dumping chat logs into a prompt doesn't solve this — it creates fragile, unstructured context that degrades as it scales.

What Statewave does

Statewave gives your AI system durable, structured memory with a clear data lifecycle:

1. Ingest — record raw events (episodes) as they happen, append-only
2. Compile — extract typed, summarised memories with confidence scores and provenance
3. Retrieve — assemble ranked, token-bounded context bundles ready for your prompts
4. Govern — inspect subject timelines, trace every memory to its source, delete by subject

Everything is organised around subjects — a user, account, agent, repo, or any entity you track.

Statewave is not a chatbot framework, a vector database, a RAG pipeline, or a hosted service. It is infrastructure you run alongside your application.

How it works

Statewave reads raw events, compiles them once per subject change into typed memories, and assembles a token-bounded context bundle on demand. Each bundle carries provenance back to its source episodes — the same query against the same subject at the same point in time always produces the same bytes. That determinism is what separates compile-then-use from query-time retrieval, where sampling noise leaks into every answer.

Idempotent at every step — recompiling a subject produces no duplicates; reassembling a bundle for the same task at the same point in time returns the same bytes.

Capabilities

The runtime essentials. Full capability inventory →

• Compiled context bundles — ranked, token-bounded, deterministic per subject and task
• Provenance — every memory traces back to its source episodes; receipts are content-hashed
• Pluggable compilers — heuristic (regex, fully local) or LLM (any LiteLLM provider)
• Subject-organised — user:, repo:, account:, or any entity prefix you choose
• State-assembly receipts — immutable, ULID-addressable record of which memories influenced each bundle. HMAC-SHA256 signature (v0.9), embedded policy snapshot (v0.9), and POST /v1/receipts/{id}/replay for "what would today's code say with the original rules?"
• Sensitivity labels + policy engine — declarative YAML policies (deny / redact) over per-memory tags (pii, financial, secret, …) with log_only and enforce modes. v0.9 adds advisory suggested_labels from heuristic detectors (pii.email/phone, financial.card, secret.token) with operator review + explicit promotion via the admin app
• Multi-tenant — query-scoped data isolation via X-Tenant-ID header, per-tenant config and policies. v0.9 adds per-tenant region pinning for residency: requests for a tenant pinned to eu are 403'd at any process running in another region
• Self-hosted on Postgres + pgvector — no vendor lock-in; runs on your infrastructure

Why Statewave

• Your AI remembers — preferences, decisions, history persist across sessions
• Context is structured, not dumped — ranked retrieval with token budgets, not raw chat-log stuffing
• Provenance is built in — every memory traces back to its source episodes
• You own the storage — self-hosted, open source, no vendor lock-in. Episodes and compiled memories live in your Postgres. The default heuristic compiler runs fully local; choose an LLM compiler or hosted embeddings if you want them. See Privacy & Data Flow.
• No GPU required — the API process is CPU-only. GPUs only enter the picture if you self-host an LLM compiler or embedding model. See Hardware & Scaling.
• Framework-neutral — works with any AI stack, any language, via REST API or typed SDKs

Quickstart

from statewave import StatewaveClient

with StatewaveClient("http://localhost:8100") as sw:
    sw.create_episode(subject_id="user-42", source="chat", type="message",
                      payload={"text": "Alice asked about pricing tiers"})
    sw.compile_memories("user-42")
    print(sw.get_context("user-42", task="answer pricing", max_tokens=1000).assembled_context)

That's the loop: ingest → compile → use — ranked, token-bounded context with provenance. Run the server below, or self-host with Docker / Helm. Full SDK docs: statewave-py (Python) · statewave-ts (TypeScript).

Use cases

Three runnable examples in statewave-examples:

• Customer support agent — returning customer recognised across sessions, ranked context with token budget, provenance tracing, handoff pack on escalation. (Python · TypeScript)
• Long-running coding agent — multi-session project memory: tech stack, preferences, architecture decisions persist between conversations. (Python · TypeScript)
• Stateless vs memory-powered agent (live LLM) — full loop with a real LLM (any LiteLLM provider) running side by side with and without Statewave so you can A/B the difference yourself. (Python)

Plus the minimal quickstart, docs-grounded support, eval suite (56 assertions across 23 tests), a benchmark, and drop-in framework integrations — LangChain, CrewAI, and AutoGen — in the examples repo.

Run the server

Fastest — one line to a running server:

# macOS / Linux
npx @statewavedev/statewave
# or
curl -fsSL https://www.statewave.ai/install | sh

# Windows (PowerShell)
irm https://www.statewave.ai/install.ps1 | iex

Prefer to run it yourself?

git clone https://github.com/smaramwbc/statewave && cd statewave
docker compose up -d

Brings up Postgres (pgvector) + the API; migrations run automatically on container start. The API is available at http://localhost:8100.

By default the server boots in demo mode — stub hash-based embeddings + the heuristic compiler, no real semantic search. For LLM-backed behaviour, add a .env next to docker-compose.yml and re-run docker compose up -d to pick it up:

STATEWAVE_EMBEDDING_PROVIDER=litellm
STATEWAVE_LITELLM_API_KEY=sk-...            # any LiteLLM provider
STATEWAVE_LITELLM_MODEL=gpt-4o-mini
STATEWAVE_LITELLM_EMBEDDING_MODEL=text-embedding-3-small

Endpoint	Purpose
http://localhost:8100/docs	OpenAPI (Swagger)
http://localhost:8100/redoc	ReDoc
GET /healthz or GET /health	Liveness check
GET /readyz or GET /ready	Readiness check

Check GET /readyz to confirm your LLM key was picked up — if the llm check shows "detail":"STATEWAVE_LITELLM_API_KEY is not set", the key isn't being read (re-check that .env sits next to docker-compose.yml and re-run docker compose up -d).

See the full getting started guide for step-by-step setup including environment configuration.

API

Method	Path	Description
POST	/v1/episodes	Ingest a single episode (append-only)
POST	/v1/episodes/batch	Ingest up to 100 episodes at once
POST	/v1/memories/compile	Compile memories from episodes (idempotent)
GET	/v1/memories/search	Search by kind, text, or semantic similarity
POST	/v1/context	Assemble ranked, token-bounded context bundle
GET	/v1/timeline	Chronological subject timeline
GET	/v1/subjects	List known subjects with episode/memory counts
DELETE	/v1/subjects/{id}	Permanently delete all data for a subject
POST	/v1/resolutions	Track issue resolution state per session
GET	/v1/resolutions	List resolutions for a subject
POST	/v1/handoff	Generate compact handoff context pack
GET	/v1/subjects/{id}/health	Customer health score with explainable factors
GET	/v1/subjects/{id}/sla	SLA metrics — response time, resolution time, breaches

Full reference: API v1 contract.

Supported platforms

Surface	Supported
Python	3.11+ (CI runs 3.11; 3.12 / 3.13 expected to work but not gated in CI yet)
OS — server	Linux verified in CI; macOS + Windows usually fine for local dev but not CI-tested
Docker image	linux/amd64 and linux/arm64
Database	PostgreSQL 14+ with pgvector ≥ 0.4.2
LLM provider (compiler)	Any of 100+ LiteLLM-supported providers — OpenAI, Anthropic, Azure, Bedrock, Ollama, Cohere, Gemini, Mistral, Groq, …
Embedding provider	Any LiteLLM-supported, plus stub (local heuristic, no API key)
SDKs	Python (pip install statewave) · TypeScript (npm install @statewavedev/sdk)

FAQ

How is this different from other memory systems? Most memory layers store isolated facts and retrieve them per query; some extract a graph whose retrieval surface can return the same summary regardless of the question. Statewave compiles the context once per subject change, with provenance — which is what buys the higher multi-hop accuracy in our benchmarks.

Does it work with my model provider? Yes — Statewave uses LiteLLM so any of 100+ providers work (OpenAI, Anthropic, Azure, Bedrock, Ollama, Groq, Cohere, Gemini, Mistral, …). Set STATEWAVE_LITELLM_MODEL to any LiteLLM identifier.

What's the license — can I use this commercially? Yes. Statewave (server + SDKs) is Apache-2.0 — a permissive license with an explicit patent grant. Use it freely in proprietary, hosted, or commercial products with no source-disclosure obligations. See LICENSING.md.

Can I self-host? Yes — that's the default. Docker Compose, Helm chart, or bare-metal. See Deployment guide.

Why does it cost more tokens per answer than a plain fact store? Compiled context bundles are denser than fact-store retrieval — that's what buys the higher multi-hop accuracy. If your queries are mostly single-hop and you're cost-sensitive, a lighter fact store may be the right call.

Connectors

Statewave is not limited to live chat transcripts. Connectors feed real-world events into Statewave as episodes, so your agents can build memory from repos, communities, docs, support tools, email, and workflows — without you hand-writing an ingest path for each source.

Source	Memory shape	Status
MCP server	Copilot / Claude / Cursor / agent memory	✅ shipped
GitHub	Issues, pull requests, reviews, releases → repo memory	✅ shipped
Markdown	Local docs, ADRs, RFCs → decision memory	✅ shipped
Slack	Channel + thread history (pull) + Events-API webhook (push, with opt-in DMs and group DMs) → team memory	✅ shipped
n8n	Workflow runs, failures, per-node errors → workflow memory	✅ shipped
Zapier	"Webhooks by Zapier" → push-mode helper for any zap	✅ shipped
Discord	Server channel + thread history → community memory	✅ shipped
Notion	Pages + opt-in body content + database scoping → decision memory	✅ shipped
Zendesk / Intercom / Freshdesk	Tickets + replies + notes (pull) and real-time webhook receivers (push) → customer memory	✅ shipped
Gmail	Query-scoped messages (pull, with History-API delta sync) and Cloud Pub/Sub push receiver → relationship memory	✅ shipped

Connectors live in their own repository so this core stays focused on the runtime. They are modular — install only what you need:

# Pick what you need — every package is independent
npm install @statewavedev/connectors-github
npm install @statewavedev/connectors-jira          # preview
npm install @statewavedev/connectors-database      # preview — postgres/mysql/mariadb/mssql
npm install @statewavedev/connectors-markdown
npm install @statewavedev/connectors-slack
npm install @statewavedev/connectors-n8n
npm install @statewavedev/connectors-zapier
npm install @statewavedev/mcp-server

A convenience meta-package @statewavedev/connectors re-exports the official connectors for the rare case where you want them all at once. It is not required for normal usage.

Quick examples (dry-run-first — nothing is ingested without your say-so):

statewave-connectors sync github \
  --repo smaramwbc/statewave \
  --subject repo:smaramwbc/statewave \
  --dry-run

statewave-connectors sync markdown \
  --path ./docs \
  --subject repo:smaramwbc/statewave \
  --dry-run

statewave-connectors mcp start

Where to go next:

• Connector ecosystem repo: statewave-connectors — published on npm under @statewavedev/connectors-* (incl. preview Jira + database source connectors)
• Connector docs: statewave-docs/connectors
• SDKs (custom ingestion paths): Python · TypeScript

No connector code lives in this repo. Connectors talk to Statewave through the same public HTTP API documented above. If you don't need any of them, you don't install any of them.

Configuration

All settings use the STATEWAVE_ env prefix. Copy .env.example to .env to get started.

For best results: Set STATEWAVE_COMPILER_TYPE=llm and STATEWAVE_EMBEDDING_PROVIDER=litellm with an STATEWAVE_LITELLM_API_KEY. Statewave uses LiteLLM as its single provider abstraction, so you can use any supported provider — OpenAI, Anthropic, Azure, Ollama, Cohere, Gemini, Bedrock, Mistral, Groq, and 100+ others — by setting STATEWAVE_LITELLM_MODEL to any LiteLLM model identifier (e.g. gpt-4o-mini, claude-3-haiku-20240307, ollama/llama3, azure/gpt-4). The heuristic compiler still works without any LLM API key.

Variable	Default	Description
STATEWAVE_DATABASE_URL	postgresql+asyncpg://statewave:statewave@localhost:5432/statewave	Postgres connection string
STATEWAVE_DEBUG	false	Enable debug logging
STATEWAVE_COMPILER_TYPE	heuristic	heuristic or llm
STATEWAVE_EMBEDDING_PROVIDER	stub	stub, litellm, or none
STATEWAVE_LITELLM_API_KEY	—	Provider-neutral API key (e.g. OpenAI sk-..., Anthropic sk-ant-...) — passed through to the provider chosen by STATEWAVE_LITELLM_MODEL
STATEWAVE_LITELLM_MODEL	gpt-4o-mini	Chat-completion model — any LiteLLM identifier (claude-3-haiku-20240307, ollama/llama3, azure/gpt-4, etc.)
STATEWAVE_LITELLM_EMBEDDING_MODEL	text-embedding-3-small	Embedding model — any LiteLLM-supported (cohere/embed-english-v3.0, voyage/voyage-large-2, …)
STATEWAVE_LITELLM_API_BASE	—	Custom base URL (e.g. http://localhost:11434 for Ollama, or a self-hosted OpenAI-compatible gateway)
STATEWAVE_LITELLM_TIMEOUT_SECONDS	60	Request timeout
STATEWAVE_LITELLM_MAX_RETRIES	2	Retries on transient errors
STATEWAVE_EMBEDDING_DIMENSIONS	1536	Embedding vector dimensions
STATEWAVE_API_KEY	—	API key for auth (empty = open access)
STATEWAVE_RATE_LIMIT_RPM	0	Requests/min/IP (0 = disabled)
STATEWAVE_RATE_LIMIT_STRATEGY	distributed	distributed (Postgres) or memory (in-process)
STATEWAVE_WEBHOOK_URL	—	Webhook callback URL (empty = disabled)
STATEWAVE_WEBHOOK_TIMEOUT	5.0	Webhook HTTP timeout in seconds
STATEWAVE_WEBHOOK_EVENTS	—	Comma-separated event-type allowlist (empty = deliver every event)
STATEWAVE_RECEIPT_SIGNING_KEYS	—	JSON {"<key_id>": "<base64>"} map of HMAC keys for receipt signing (≥32 bytes each). Never persisted to the DB; per-tenant active key id set via tenant_configs.config.receipt_signing_key_id.
STATEWAVE_AUTO_LABELING_ENABLED	false	Run heuristic detectors at compile time and stamp advisory suggested_labels on memories (v0.9). See docs/auto-labeling.md.
STATEWAVE_AUTO_LABELING_PROVIDER	heuristic	Detector provider. Only heuristic is currently supported (since v0.9); the switch is reserved for future LLM-based classifiers.
STATEWAVE_REGION	—	Region this server process is running in. When set, requests for tenants pinned to a different region are refused with HTTP 403 residency.mismatch (v0.9). Empty = single-region mode, residency disabled. See docs/residency.md.
STATEWAVE_TENANT_HEADER	X-Tenant-ID	Header for multi-tenant isolation
STATEWAVE_REQUIRE_TENANT	false	Reject requests without tenant header
STATEWAVE_DEFAULT_MAX_CONTEXT_TOKENS	4000	Default token budget for context assembly
STATEWAVE_CORS_ORIGINS	["*"]	Allowed CORS origins

Running tests

# Unit tests (no DB required)
pytest tests/test_*.py -v

# Integration tests (requires Postgres)
PGPASSWORD=statewave createdb -h localhost -U statewave statewave_test
pytest tests/integration/ -v

# All tests
pytest tests/ -v

Current limitations

Statewave is in active development (v1.3.0). Honest status:

• Rate limiting is per-IP — distributed (Postgres-backed), but keyed by IP only, not per-tenant or per-API-key yet
• Multi-tenant is app-layer — query-scoped data isolation (v0.5) + per-tenant config / policy bundles / receipts (v0.8) + HMAC-signed audit + tenant region pin (v0.9), but no Postgres RLS yet
• No built-in auth provider — validates API keys you configure, doesn't issue them
• No admin-action identity yet — the v0.9 auto-labeling promote endpoint stamps promoted_at + labels on every promotion, but promoted_by is null until an admin-identity layer ships
• No visual policy editor — policy bundles are authored as YAML in git and uploaded through the admin workflow; a no-YAML form-based editor is deferred to a future admin release
• No federated cross-region audit — v0.9 ships strict per-region isolation by design; operators running multiple regions cannot search receipts or memories across regions from a single console yet. Federated audit should be added explicitly later, not through implicit cross-region access
• Replay is "current code + original policy" — v0.9 receipt replay re-runs the original retrieval against today's memories using the original policy bundle (frozen on every v0.9+ receipt). Byte-for-byte historical reproduction needs memory snapshots, which are deferred

See the roadmap for what's being fixed and when.

Horizontal scaling. Statewave runs multi-replica in production (Fly multi-machine + Helm HPA both verified). The policy bundle cache that previously assumed single-process was dropped in v0.8 (#77) precisely so multi-replica deploys behave correctly under enforce mode. Heavy load is bottlenecked by Postgres + your embedding provider, not the API.

Documentation

Getting started	Clone, run, ingest your first episode
What is Statewave?	Product overview, use cases, limitations
Why Statewave?	Technical comparison for support-agent workflows
API v1 contract	Full endpoint reference
Architecture overview	System design and data flow
Compiler modes	Heuristic vs LLM — when to use which
Privacy & data flow	What stays local, what leaves your network
Hardware & scaling	GPU is never required; scaling characteristics
Deployment sizing guide	Hardware profiles by tier (local → enterprise) and topology patterns
Capacity planning checklist	Diagnostic flow + tuning order when load grows
Deployment guide	Production deployment guidance
State-assembly receipts	Receipt schema, HMAC signing, verify semantics
Receipt replay	v0.9 — re-run a historical retrieval against current memories + original policy
Auto-labeling	v0.9 — heuristic detectors + review/promote workflow
Residency	v0.9 — per-region deployment + tenant pinning + ops runbook
Roadmap	What's next
Changelog	Release history

Community

Statewave is built in the open. Where to post what:

• GitHub Discussions — questions, ideas, RFCs, integrations, roadmap input, what you're building
• GitHub Issues — confirmed, reproducible bugs and concrete implementation tasks
• Security vulnerabilities — email security@statewave.ai (do not post publicly; see SECURITY.md)
• Commercial / private licensing terms — email licensing@statewave.ai (general licensing questions are welcome in Discussions)

The full community guide — categories, RFC process, moderation — lives in statewave-docs/community/discussions.md. Copy-paste templates for questions, feature requests, RFCs, and show-and-tell are in discussion-templates.md.

Ecosystem

Project	Description
Server (this repo)	Core server — API, domain model, DB, services
Python SDK	pip install statewave — sync + async client
TypeScript SDK	npm install @statewavedev/sdk — fetch-based client
Connectors	@statewavedev/connectors-* — GitHub, Markdown/docs, MCP server, modular packages
Docs	Architecture, API contracts, ADRs
Examples	Quickstarts, evals, benchmarks
Website + demo	Marketing website + embedded interactive demo (statewave.ai)
Admin	Operator console (read-only)

Licensing

Statewave is licensed under the Apache License, Version 2.0.

You may use, modify, and distribute it — including in proprietary or hosted products — without a separate agreement. Apache-2.0 includes an explicit patent grant from contributors.

• License: LICENSE (Apache-2.0)
• Licensing overview: LICENSING.md
• Trademark policy: TRADEMARKS.md
• Contributing: CONTRIBUTING.md
• Enterprise support (SLA, indemnity, procurement): licensing@statewave.ai