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)
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 | iexPrefer to run it yourself? The Getting Started guide walks through the manual git clone + docker compose up -d path in about 5 minutes.
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.4.0 — tenant-scoped memory provenance and /v1/context source-episode lookups (closes cross-tenant leakage the single-tenant repository helpers previously left open on shared infra), plus tenant-keyed admin bulk delete with explicit tenant_id IS NULL handling for global rows. Admin operational surface expands: POST /admin/jobs/reset-stuck recovers orphaned running compile jobs, DELETE /admin/jobs/{id} closes the immortal-terminal-job gap, and empty-subject stats return 200 instead of 404 so zero-data dashboards don't break. Support-docs bootstrap now runs an async compile with build-then-swap gated on the compile job's memories_created — a failed rebuild no longer empties the live pack. Non-breaking: search_mode opt-in on /v1/memories/search, subject.deleted webhook guarded against no-op fires, extended purge-event coverage. The /v1/* contract and the v1.3 hybrid-retrieval stack remain stable. Both SDKs ship v1.4.0 alongside as a parity release with no runtime changes since v1.2.0 (CI/docs hygiene only). See roadmap and CHANGELOG.