Open-source memory runtime for AI agents. Statewave compiles raw events into ranked, token-bounded context bundles with full provenance — so your AI stops forgetting across sessions. Self-hosted on Postgres, no vendor lock-in.
Primary focus: support-agent workflows — where structured memory clearly outperforms naive history stuffing and simple RAG. Statewave gives your support agent durable customer context across sessions, with provenance, ranked retrieval, and token budgets.
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.
Statewave gives your AI system durable, structured memory with a clear data lifecycle:
- Ingest — record raw events (episodes) as they happen, append-only
- Compile — extract typed, summarised memories with confidence scores and provenance
- Retrieve — assemble ranked, token-bounded context bundles ready for your prompts
- 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.
- 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
Statewave is not a chatbot framework, a vector database, a RAG pipeline, or a hosted service. It is infrastructure you run alongside your application.
Status: v0.8.0 — actively developed. Governance & audit layer shipped: every context assembly can emit an immutable state-assembly receipt (content-hash integrity, full provenance, queryable + chainable by ULID), per-memory sensitivity labels feed a declarative YAML policy engine that filters by caller identity, and per-tenant config flips enforce mode on without a SQL shell. Builds on the v0.7.x foundation: per-kind memory TTL, Helm chart, cross-machine query embedding cache, and the full support-agent intelligence stack (session-aware context, resolution tracking, handoff packs, health, SLA, proactive alerts). See current limitations below.
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.
| 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 |
| Roadmap | What's next |
| Changelog | Release history |
| Python SDK | pip install statewave — sync + async client, Pydantic models |
| TypeScript SDK | npm install @statewavedev/sdk — fetch-based client, full type definitions |
| Connectors | Feed real-world events (GitHub, Markdown/ADRs, MCP, …) into Statewave as episodes — see Connectors below |
| Examples | Quickstart, support agent, coding agent |
| Context quality eval | Automated assertions on context correctness |
| Benchmark | Statewave vs history stuffing vs RAG |
- Episode ingestion — append-only raw event recording, single or batch (up to 100)
- Pluggable compilers — heuristic (regex) or LLM (any LiteLLM-supported provider) memory extraction
- Idempotent compilation — recompiling the same subject produces no duplicates
- Semantic search — pgvector cosine similarity with text-search fallback
- Token-bounded context — context bundles respect a configurable token budget
- Ranked retrieval — kind priority × recency × task relevance × temporal validity × semantic similarity
- Memory conflict resolution — auto-supersede older overlapping memories
- Provenance — every memory traces back to its source episodes
- Subject management — list subjects with counts, inspect timelines, permanently delete all data by subject
- Authentication — optional API key via
X-API-Keyheader - Rate limiting — per-IP fixed-window, distributed (Postgres-backed) or in-memory
- Multi-tenant — optional
X-Tenant-IDheader with real query-scoped data isolation - Webhooks — persistent HTTP callbacks with retries and dead-letter on episode, compile, and delete events
- OpenTelemetry tracing — optional spans on key operations (requires
[otel]extra) - Structured logging — structlog with JSON output in production, console in development
- Structured errors — consistent JSON error format with request-ID correlation
- Session-aware context — active session boosted, resolved sessions deprioritized
- Resolution tracking — mark issues open/resolved, surface resolution history
- Handoff context packs — compact escalation briefs with health, SLA, and issue context
- Customer health scoring — deterministic 0–100 score with explainable factors
- SLA tracking — first-response time, resolution time, breach detection
- Proactive health alerts — webhooks on health state transitions (degradation + recovery)
- Repeat-issue detection — surfaces prior resolutions when patterns recur
- State-assembly receipts — every
/v1/contextand/v1/handoffcall can emit an immutable, ULID-addressable audit record of which memories + episodes influenced the bundle, with a SHA-256 hash of the bytes delivered to the agent and tenant-scoped retrieval viaGET /v1/receipts - Per-memory sensitivity labels — operator-supplied capability tags (
pii,financial,secret, …) carried as aTEXT[]column with a GIN index; set viaPATCH /v1/memories/{id}/labels - Declarative policy engine — YAML/JSON policy bundles with six predicates (label match, caller_type, caller_id), two actions (
deny,redact), and first-match-wins evaluation; bundles are content-hashed and immutable, addressable bybundle_hash; per-tenant policy_mode toggles betweenlog_only(record decisions to receipts, no filtering) andenforce(drop denied memories before ranking) - Caller identity —
caller_idandcaller_typeon context/handoff requests feed the policy evaluator; tenant configrequire_caller_identity: true401s anonymous calls - Per-tenant config —
GET / PATCH /admin/tenants/{id}/configfor receipts emission, retention, policy_mode, caller-identity gating; PATCH-shape merge with optimistic concurrency viaexpected_version
# Start Postgres (pgvector)
docker compose up db -d
# Create virtualenv and install
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev,llm]"
# Run migrations
alembic upgrade head
# Start the server
uvicorn server.app:app --host 0.0.0.0 --port 8100The API is available at http://localhost:8100.
| 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 |
See the full getting started guide for step-by-step setup including environment configuration.
| 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.
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-markdown
npm install @statewavedev/connectors-slack
npm install @statewavedev/connectors-n8n
npm install @statewavedev/connectors-zapier
npm install @statewavedev/mcp-serverA 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 startWhere to go next:
- Connector ecosystem repo: statewave-connectors (Phase-1 packages — core, CLI, MCP server, GitHub, Markdown — landing soon; npm publication is a follow-up)
- 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.
All settings use the STATEWAVE_ env prefix. Copy .env.example to .env to get started.
For best results: Set
STATEWAVE_COMPILER_TYPE=llmandSTATEWAVE_EMBEDDING_PROVIDER=litellmwith anSTATEWAVE_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 settingSTATEWAVE_LITELLM_MODELto 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_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 |
# 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/ -vStatewave is in active development (v0.8.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) layered on top, but no Postgres RLS yet
- PostgreSQL required — no alternative storage backends
- No built-in auth provider — validates API keys you configure, doesn't issue them
- Policy retention purge worker —
tenant_configs.receipt_retention_daysis read by the config surface but no scheduled worker deletes expired receipts yet; planned for v0.9
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.
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.
| 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) |
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