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.3.0 — hybrid retrieval (pgvector + Postgres BM25, on by default with a hybrid=false opt-out) and compile-pipeline recall improvements (dedup/reconcile), plus provider-aware LLM key routing. The /v1/* API contract and governance surfaces (HMAC-signed receipts, receipt-driven replay, per-memory sensitivity labels + declarative YAML policy, opt-in detector-suggested labels, per-region data residency) remain stable, as do the v1.2 additions (dynamic settings endpoint for topology-agnostic hot-reload, a production-readiness probe, SSRF + DNS-rebinding protection on the webhook URL probe, LIKE metachar escaping in admin search, and six admin inspection endpoints). Both SDKs ship alongside: statewave (PyPI) v1.2.0 adds per-call timeout overrides and CancelledError propagation; @statewavedev/sdk (npm) v1.2.0 adds AbortSignal support on all HTTP methods. See roadmap and CHANGELOG.