Statewave is the open-source memory runtime for AI agents. It 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.
This repo contains the architecture docs, product specs, API contracts, and development coordination for the Statewave workspace.
This repo contains no production runtime code.
📋 Issues & feature requests: statewave/issues (centralized tracker)
The interactive comparison demo is embedded directly in the website at statewave.ai — open the chat widget to see two identical AI agents answer side by side, one stateless and one backed by Statewave.
Got a question about Statewave? Ask Statewave Support → — a docs-grounded agent that answers from this very docs corpus and cites the pages it used (read-only; built on the docs memory pack).
- Getting Started ← start here
- What is Statewave?
- Why Statewave? — technical comparison for support-agent workflows
- Design partner onboarding — 30-minute setup, evaluation checklist, success criteria, FAQ — for teams adopting Statewave early
- Use Cases map — categorized inventory of what you can build (support, coding, workspace, account, voice, agent infrastructure, connectors, frontier ideas)
- Connectors — feed real-world events (GitHub, Markdown/ADRs, MCP, and more) into Statewave as normalized episodes
- Subject Design — the architectural treatment of subjects (entity granularity, tenancy, modelling)
- Architecture Overview
- Repo Map
- API v1 Contract
- State-assembly receipts — the immutable audit artifact emitted on each context assembly
- Sensitivity labels & policy — per-memory capability tags + bundled rules consulted on every assembly call
- Deployment Guide
- Deployment Sizing Guide — hardware profiles by tier, topology patterns, bottleneck guidance
- Capacity Planning & Tuning Checklist — diagnostic flow when load grows, tuning order, when to move up a tier
- Default support docs memory pack — the docs-only knowledge base shipped for out-of-the-box support agents
- Roadmap
- Development Conventions
- License — Apache-2.0
- Community guide — where to post what, how to write good questions and RFCs, tone and moderation
- Discussion templates — Q&A, feature request, RFC, show-and-tell, integration, research
- Pinned discussion drafts — ready-to-copy posts (welcome, what-are-you-building, roadmap priorities, RFCs)
- Operator setup checklist — for maintainers configuring categories, pins, and recurring review
GitHub Discussions live on the core repo: statewave/discussions.
- ADR-001: PostgreSQL + pgvector as sole data store
- ADR-002: Heuristic compilation for v1
- ADR-003: v0.2 production hardening decisions
- ADR-004: v0.3 advanced features decisions
| Project | Description |
|---|---|
| Server | Core server — API, domain model, DB, compilation, search |
| 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 | This repo — architecture, specs, ADRs (no runtime code) |
| Examples | Runnable examples, evals, benchmarks |
| Website + demo | Marketing website + embedded comparison demo (statewave.ai) |
| Admin | Operator console — system health, jobs, usage (read-only) |
v1.0.0 — the first stable public developer release. The /v1/* API contract and the v0.9 governance surfaces (HMAC-signed receipts with content-hash integrity, receipt-driven replay, per-memory sensitivity labels feeding a declarative YAML policy engine, opt-in detector-suggested labels, per-region data residency) are now stable for developer use under a self-hosted deployment model. Both SDKs (statewave on PyPI, @statewavedev/sdk on npm) cut their first stable v1.0.0 releases with typed surfaces matching the REST contract. Builds on the v0.8.0 governance & audit layer, the v0.7.x foundation (memory TTL, Helm, cross-machine embedding cache), and the v0.6.x support-agent intelligence stack (session-aware context, resolution tracking, handoff packs, health scoring, SLA tracking, proactive alerts). What is not yet proven is documented honestly in why-statewave.md. See roadmap and CHANGELOG.