[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-11486":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":16,"stars7d":16,"stars30d":13,"stars90d":16,"forks30d":16,"starsTrendScore":16,"compositeScore":17,"rankGlobal":10,"rankLanguage":10,"license":18,"archived":19,"fork":19,"defaultBranch":20,"hasWiki":21,"hasPages":19,"topics":22,"createdAt":10,"pushedAt":10,"updatedAt":33,"readmeContent":34,"aiSummary":35,"trendingCount":16,"starSnapshotCount":16,"syncStatus":15,"lastSyncTime":36,"discoverSource":37},11486,"statewave","smaramwbc\u002Fstatewave","smaramwbc","Open-source memory runtime for AI agents — reproducible, provenance-tagged context bundles instead of query-time retrieval. Apache-2.0, self-hosted on Postgres + pgvector, Python + TypeScript SDKs.","https:\u002F\u002Fstatewave.ai",null,"Python",205,11,6,2,0,44.34,"GNU Affero General Public License v3.0",false,"main",true,[23,24,25,26,27,28,29,30,31,32],"ai-agents","ai-memory","context-engineering","developer-tools","fastapi","memory-runtime","pgvector","postgres","python","semantic-search","2026-06-12 04:00:55","\u003C!-- HERO GRAPHIC: docs\u002Fimg\u002Fhero.png landing in follow-up PR (issue #4) -->\n\n# Statewave\n\n[![CI](https:\u002F\u002Fgithub.com\u002Fsmaramwbc\u002Fstatewave\u002Fworkflows\u002FCI\u002Fbadge.svg)](https:\u002F\u002Fgithub.com\u002Fsmaramwbc\u002Fstatewave\u002Factions\u002Fworkflows\u002Fci.yml)\n[![License: Apache 2.0](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Flicense-Apache--2.0-blue.svg)](LICENSE)\n[![Python 3.11+](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fpython-3.11%2B-blue.svg)](https:\u002F\u002Fwww.python.org\u002F)\n[![PyPI](https:\u002F\u002Fimg.shields.io\u002Fpypi\u002Fv\u002Fstatewave)](https:\u002F\u002Fpypi.org\u002Fproject\u002Fstatewave\u002F)\n[![Docker Pulls](https:\u002F\u002Fimg.shields.io\u002Fdocker\u002Fpulls\u002Fstatewavedev\u002Fstatewave)](https:\u002F\u002Fhub.docker.com\u002Fr\u002Fstatewavedev\u002Fstatewave)\n\nStatewave is the open-source memory runtime that gives AI agents reproducible, provenance-tagged context — without sampling-noise from query-time retrieval.\n\n_If Statewave is useful to you, a ⭐ on the repo helps others discover it._\n\n\u003C!-- QUICKSTART GIF: docs\u002Fimg\u002Fquickstart.gif landing in follow-up PR (issue #4) -->\n\n> **v0.9.0** — actively developed. [Changelog](https:\u002F\u002Fgithub.com\u002Fsmaramwbc\u002Fstatewave-docs\u002Fblob\u002Fmain\u002FCHANGELOG.md) · [Roadmap](https:\u002F\u002Fgithub.com\u002Fsmaramwbc\u002Fstatewave-docs\u002Fblob\u002Fmain\u002Froadmap.md) · [Limitations](#current-limitations)\n\n## 🎯 Try it\n\nThe interactive comparison demo is embedded directly in the website at **[statewave.ai](https:\u002F\u002Fstatewave.ai)** — open the chat widget to see two identical AI agents answer the same question, one stateless and one backed by Statewave.\n\n## The problem\n\nMost 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.\n\n## What Statewave does\n\nStatewave gives your AI system **durable, structured memory** with a clear data lifecycle:\n\n1. **Ingest** — record raw events (episodes) as they happen, append-only\n2. **Compile** — extract typed, summarised memories with confidence scores and provenance\n3. **Retrieve** — assemble ranked, token-bounded context bundles ready for your prompts\n4. **Govern** — inspect subject timelines, trace every memory to its source, delete by subject\n\nEverything is organised around **subjects** — a user, account, agent, repo, or any entity you track.\n\nStatewave is **not** a chatbot framework, a vector database, a RAG pipeline, or a hosted service. It is infrastructure you run alongside your application.\n\n## How it works\n\nStatewave 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.\n\n\u003Cpicture>\n  \u003Csource media=\"(prefers-color-scheme: dark)\" srcset=\"docs\u002Fimg\u002Fhow-statewave-works-dark.png\">\n  \u003Cimg alt=\"How Statewave works: events → compiled memories → ranked, token-bounded context bundle with provenance\" src=\"docs\u002Fimg\u002Fhow-statewave-works-light.png\" width=\"100%\">\n\u003C\u002Fpicture>\n\nIdempotent 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.\n\n## Capabilities\n\nThe runtime essentials. [Full capability inventory →](docs\u002Fcapabilities.md)\n\n- **Compiled context bundles** — ranked, token-bounded, deterministic per subject and task\n- **Provenance** — every memory traces back to its source episodes; receipts are content-hashed\n- **Pluggable compilers** — heuristic (regex, fully local) or LLM (any [LiteLLM](https:\u002F\u002Fgithub.com\u002FBerriAI\u002Flitellm) provider)\n- **Subject-organised** — `user:`, `repo:`, `account:`, or any entity prefix you choose\n- **State-assembly receipts** — immutable, ULID-addressable record of which memories influenced each bundle\n- **Sensitivity labels + policy engine** — declarative YAML policies (`deny` \u002F `redact`) over per-memory tags (`pii`, `financial`, `secret`, …) with `log_only` and `enforce` modes\n- **Multi-tenant** — query-scoped data isolation via `X-Tenant-ID` header, per-tenant config and policies\n- **Self-hosted on Postgres + pgvector** — no vendor lock-in; runs on your infrastructure\n\n## Why Statewave\n\n- **Your AI remembers** — preferences, decisions, history persist across sessions\n- **Context is structured, not dumped** — ranked retrieval with token budgets, not raw chat-log stuffing\n- **Provenance is built in** — every memory traces back to its source episodes\n- **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](https:\u002F\u002Fgithub.com\u002Fsmaramwbc\u002Fstatewave-docs\u002Fblob\u002Fmain\u002Farchitecture\u002Fprivacy-and-data-flow.md).\n- **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](https:\u002F\u002Fgithub.com\u002Fsmaramwbc\u002Fstatewave-docs\u002Fblob\u002Fmain\u002Fdeployment\u002Fhardware-and-scaling.md).\n- **Framework-neutral** — works with any AI stack, any language, via REST API or typed SDKs\n\n## Quickstart\n\n```python\nfrom statewave import StatewaveClient\n\nwith StatewaveClient(\"http:\u002F\u002Flocalhost:8100\") as sw:\n    sw.create_episode(subject_id=\"user-42\", source=\"chat\", type=\"message\",\n                      payload={\"text\": \"Alice asked about pricing tiers\"})\n    sw.compile_memories(\"user-42\")\n    print(sw.get_context(\"user-42\", task=\"answer pricing\", max_tokens=1000).assembled_context)\n```\n\nThat's the loop: **ingest → compile → use** — ranked, token-bounded context with provenance. Run the server below, or [self-host with Docker](DOCKER.md) \u002F [Helm](helm\u002F). Full SDK docs: [statewave-py](https:\u002F\u002Fgithub.com\u002Fsmaramwbc\u002Fstatewave-py) (Python) · [statewave-ts](https:\u002F\u002Fgithub.com\u002Fsmaramwbc\u002Fstatewave-ts) (TypeScript).\n\n## Use cases\n\nThree runnable examples in [statewave-examples](https:\u002F\u002Fgithub.com\u002Fsmaramwbc\u002Fstatewave-examples):\n\n- **[Customer support agent](https:\u002F\u002Fgithub.com\u002Fsmaramwbc\u002Fstatewave-examples\u002Ftree\u002Fmain\u002Fsupport-agent-python)** — returning customer recognised across sessions, ranked context with token budget, provenance tracing, handoff pack on escalation. *(Python · TypeScript)*\n- **[Long-running coding agent](https:\u002F\u002Fgithub.com\u002Fsmaramwbc\u002Fstatewave-examples\u002Ftree\u002Fmain\u002Fcoding-agent-python)** — multi-session project memory: tech stack, preferences, architecture decisions persist between conversations. *(Python · TypeScript)*\n- **[Stateless vs memory-powered agent (live LLM)](https:\u002F\u002Fgithub.com\u002Fsmaramwbc\u002Fstatewave-examples\u002Ftree\u002Fmain\u002Fsupport-agent-llm)** — full loop with a real LLM (any LiteLLM provider) running side by side with and without Statewave so you can A\u002FB the difference yourself. *(Python)*\n\nPlus four more — minimal quickstart, docs-grounded support, eval suite (55 assertions across 23 tests), and a benchmark — in the [examples repo](https:\u002F\u002Fgithub.com\u002Fsmaramwbc\u002Fstatewave-examples).\n\n## Run the server\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fsmaramwbc\u002Fstatewave && cd statewave\ndocker compose up -d\n```\n\nBrings up Postgres (pgvector) + the API; migrations run automatically on container start. The API is available at `http:\u002F\u002Flocalhost:8100`.\n\nBy 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:\n\n```bash\nSTATEWAVE_EMBEDDING_PROVIDER=litellm\nSTATEWAVE_LITELLM_API_KEY=sk-...            # any LiteLLM provider\nSTATEWAVE_LITELLM_MODEL=gpt-4o-mini\nSTATEWAVE_LITELLM_EMBEDDING_MODEL=text-embedding-3-small\n```\n\n| Endpoint | Purpose |\n|----------|---------|\n| `http:\u002F\u002Flocalhost:8100\u002Fdocs` | OpenAPI (Swagger) |\n| `http:\u002F\u002Flocalhost:8100\u002Fredoc` | ReDoc |\n| `GET \u002Fhealthz` or `GET \u002Fhealth` | Liveness check |\n| `GET \u002Freadyz` or `GET \u002Fready` | Readiness check |\n\nCheck `GET \u002Freadyz` to confirm your LLM key was picked up — if `llm` shows `\"not configured (skip)\"`, the key isn't being read (re-check `.env` sits next to `docker-compose.yml` and re-run `docker compose up -d`).\n\nSee the full [getting started guide](https:\u002F\u002Fgithub.com\u002Fsmaramwbc\u002Fstatewave-docs\u002Fblob\u002Fmain\u002Fgetting-started.md) for step-by-step setup including environment configuration.\n\n## API\n\n| Method | Path | Description |\n|--------|------|-------------|\n| `POST` | `\u002Fv1\u002Fepisodes` | Ingest a single episode (append-only) |\n| `POST` | `\u002Fv1\u002Fepisodes\u002Fbatch` | Ingest up to 100 episodes at once |\n| `POST` | `\u002Fv1\u002Fmemories\u002Fcompile` | Compile memories from episodes (idempotent) |\n| `GET` | `\u002Fv1\u002Fmemories\u002Fsearch` | Search by kind, text, or semantic similarity |\n| `POST` | `\u002Fv1\u002Fcontext` | Assemble ranked, token-bounded context bundle |\n| `GET` | `\u002Fv1\u002Ftimeline` | Chronological subject timeline |\n| `GET` | `\u002Fv1\u002Fsubjects` | List known subjects with episode\u002Fmemory counts |\n| `DELETE` | `\u002Fv1\u002Fsubjects\u002F{id}` | Permanently delete all data for a subject |\n| `POST` | `\u002Fv1\u002Fresolutions` | Track issue resolution state per session |\n| `GET` | `\u002Fv1\u002Fresolutions` | List resolutions for a subject |\n| `POST` | `\u002Fv1\u002Fhandoff` | Generate compact handoff context pack |\n| `GET` | `\u002Fv1\u002Fsubjects\u002F{id}\u002Fhealth` | Customer health score with explainable factors |\n| `GET` | `\u002Fv1\u002Fsubjects\u002F{id}\u002Fsla` | SLA metrics — response time, resolution time, breaches |\n\nFull reference: [API v1 contract](https:\u002F\u002Fgithub.com\u002Fsmaramwbc\u002Fstatewave-docs\u002Fblob\u002Fmain\u002Fapi\u002Fv1-contract.md).\n\n## Supported platforms\n\n| Surface | Supported |\n|---|---|\n| Python | 3.11+ (CI runs 3.11; 3.12 \u002F 3.13 expected to work but not gated in CI yet) |\n| OS — server | Linux verified in CI; macOS + Windows usually fine for local dev but not CI-tested |\n| Docker image | `linux\u002Famd64` and `linux\u002Farm64` |\n| Database | PostgreSQL 14+ with [pgvector](https:\u002F\u002Fgithub.com\u002Fpgvector\u002Fpgvector) ≥ 0.4.2 |\n| LLM provider (compiler) | Any of [100+ LiteLLM-supported providers](https:\u002F\u002Fdocs.litellm.ai\u002Fdocs\u002Fproviders) — OpenAI, Anthropic, Azure, Bedrock, Ollama, Cohere, Gemini, Mistral, Groq, … |\n| Embedding provider | Any LiteLLM-supported, plus `stub` (local heuristic, no API key) |\n| SDKs | [Python](https:\u002F\u002Fgithub.com\u002Fsmaramwbc\u002Fstatewave-py) (`pip install statewave`) · [TypeScript](https:\u002F\u002Fgithub.com\u002Fsmaramwbc\u002Fstatewave-ts) (`npm install @statewavedev\u002Fsdk`) |\n\n## FAQ\n\n**How is this different from Mem0 \u002F Zep?**\nMem0 is lean and fast but loses on multi-hop reasoning in our bench. Zep extracts a graph but in our LoCoMo run its retrieval surface returned the same thread summary regardless of the query. Statewave compiles the context once per subject change, with provenance. See [statewave-bench](https:\u002F\u002Fgithub.com\u002Fsmaramwbc\u002Fstatewave-bench) for row-level data and a 20-minute reproducibility command against your own keys.\n\n**Does it work with my model provider?**\nYes — Statewave uses [LiteLLM](https:\u002F\u002Fgithub.com\u002FBerriAI\u002Flitellm) so any of 100+ providers work (OpenAI, Anthropic, Azure, Bedrock, Ollama, Groq, Cohere, Gemini, Mistral, …). Set `STATEWAVE_LITELLM_MODEL` to any LiteLLM identifier.\n\n**What's the license — can I use this commercially?**\nYes. 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](LICENSING.md).\n\n**Can I self-host?**\nYes — that's the default. Docker Compose, Helm chart, or bare-metal. See [Deployment guide](https:\u002F\u002Fgithub.com\u002Fsmaramwbc\u002Fstatewave-docs\u002Fblob\u002Fmain\u002Fdeployment\u002Fguide.md).\n\n**Why does it cost more tokens per answer than Mem0?**\nCompiled context bundles are denser than Mem0's fact-store retrieval — that's what buys the higher multi-hop accuracy. If your queries are mostly single-hop and you're cost-sensitive, Mem0 may be the right call. The bench tells you when each system wins.\n\n## Connectors\n\nStatewave 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.\n\n| Source | Memory shape | Status |\n|---|---|---|\n| MCP server | Copilot \u002F Claude \u002F Cursor \u002F agent memory | ✅ shipped |\n| GitHub | Issues, pull requests, reviews, releases → repo memory | ✅ shipped |\n| Markdown | Local docs, ADRs, RFCs → decision memory | ✅ shipped |\n| Slack | Channel + thread history (pull) + Events-API webhook (push, with opt-in DMs and group DMs) → team memory | ✅ shipped |\n| n8n | Workflow runs, failures, per-node errors → workflow memory | ✅ shipped |\n| Zapier | \"Webhooks by Zapier\" → push-mode helper for any zap | ✅ shipped |\n| Discord | Server channel + thread history → community memory | ✅ shipped |\n| Notion | Pages + opt-in body content + database scoping → decision memory | ✅ shipped |\n| Zendesk \u002F Intercom \u002F Freshdesk | Tickets + replies + notes (pull) and real-time webhook receivers (push) → customer memory | ✅ shipped |\n| Gmail | Query-scoped messages (pull, with History-API delta sync) and Cloud Pub\u002FSub push receiver → relationship memory | ✅ shipped |\n\nConnectors live in their own repository so this core stays focused on the runtime. They are **modular** — install only what you need:\n\n```bash\n# Pick what you need — every package is independent\nnpm install @statewavedev\u002Fconnectors-github\nnpm install @statewavedev\u002Fconnectors-markdown\nnpm install @statewavedev\u002Fconnectors-slack\nnpm install @statewavedev\u002Fconnectors-n8n\nnpm install @statewavedev\u002Fconnectors-zapier\nnpm install @statewavedev\u002Fmcp-server\n```\n\nA convenience meta-package `@statewavedev\u002Fconnectors` re-exports the official connectors for the rare case where you want them all at once. **It is not required** for normal usage.\n\nQuick examples (dry-run-first — nothing is ingested without your say-so):\n\n```bash\nstatewave-connectors sync github \\\n  --repo smaramwbc\u002Fstatewave \\\n  --subject repo:smaramwbc\u002Fstatewave \\\n  --dry-run\n\nstatewave-connectors sync markdown \\\n  --path .\u002Fdocs \\\n  --subject repo:smaramwbc\u002Fstatewave \\\n  --dry-run\n\nstatewave-connectors mcp start\n```\n\n**Where to go next:**\n\n- Connector ecosystem repo: [statewave-connectors](https:\u002F\u002Fgithub.com\u002Fsmaramwbc\u002Fstatewave-connectors) *(Phase-1 packages — core, CLI, MCP server, GitHub, Markdown — landing soon; npm publication is a follow-up)*\n- Connector docs: [statewave-docs\u002Fconnectors](https:\u002F\u002Fgithub.com\u002Fsmaramwbc\u002Fstatewave-docs\u002Fblob\u002Fmain\u002Fconnectors\u002Findex.md)\n- SDKs (custom ingestion paths): [Python](https:\u002F\u002Fgithub.com\u002Fsmaramwbc\u002Fstatewave-py) · [TypeScript](https:\u002F\u002Fgithub.com\u002Fsmaramwbc\u002Fstatewave-ts)\n\n> **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.\n\n## Configuration\n\nAll settings use the `STATEWAVE_` env prefix. Copy `.env.example` to `.env` to get started.\n\n> **For best results:** Set `STATEWAVE_COMPILER_TYPE=llm` and `STATEWAVE_EMBEDDING_PROVIDER=litellm` with an `STATEWAVE_LITELLM_API_KEY`. Statewave uses [LiteLLM](https:\u002F\u002Fgithub.com\u002FBerriAI\u002Flitellm) 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\u002Fllama3`, `azure\u002Fgpt-4`). The heuristic compiler still works without any LLM API key.\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `STATEWAVE_DATABASE_URL` | `postgresql+asyncpg:\u002F\u002Fstatewave:statewave@localhost:5432\u002Fstatewave` | Postgres connection string |\n| `STATEWAVE_DEBUG` | `false` | Enable debug logging |\n| `STATEWAVE_COMPILER_TYPE` | `heuristic` | `heuristic` or `llm` |\n| `STATEWAVE_EMBEDDING_PROVIDER` | `stub` | `stub`, `litellm`, or `none` |\n| `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` |\n| `STATEWAVE_LITELLM_MODEL` | `gpt-4o-mini` | Chat-completion model — any [LiteLLM identifier](https:\u002F\u002Fdocs.litellm.ai\u002Fdocs\u002Fproviders) (`claude-3-haiku-20240307`, `ollama\u002Fllama3`, `azure\u002Fgpt-4`, etc.) |\n| `STATEWAVE_LITELLM_EMBEDDING_MODEL` | `text-embedding-3-small` | Embedding model — any LiteLLM-supported (`cohere\u002Fembed-english-v3.0`, `voyage\u002Fvoyage-large-2`, …) |\n| `STATEWAVE_LITELLM_API_BASE` | — | Custom base URL (e.g. `http:\u002F\u002Flocalhost:11434` for Ollama, or a self-hosted OpenAI-compatible gateway) |\n| `STATEWAVE_LITELLM_TIMEOUT_SECONDS` | `60` | Request timeout |\n| `STATEWAVE_LITELLM_MAX_RETRIES` | `2` | Retries on transient errors |\n| `STATEWAVE_EMBEDDING_DIMENSIONS` | `1536` | Embedding vector dimensions |\n| `STATEWAVE_API_KEY` | — | API key for auth (empty = open access) |\n| `STATEWAVE_RATE_LIMIT_RPM` | `0` | Requests\u002Fmin\u002FIP (0 = disabled) |\n| `STATEWAVE_RATE_LIMIT_STRATEGY` | `distributed` | `distributed` (Postgres) or `memory` (in-process) |\n| `STATEWAVE_WEBHOOK_URL` | — | Webhook callback URL (empty = disabled) |\n| `STATEWAVE_WEBHOOK_TIMEOUT` | `5.0` | Webhook HTTP timeout in seconds |\n| `STATEWAVE_TENANT_HEADER` | `X-Tenant-ID` | Header for multi-tenant isolation |\n| `STATEWAVE_REQUIRE_TENANT` | `false` | Reject requests without tenant header |\n| `STATEWAVE_DEFAULT_MAX_CONTEXT_TOKENS` | `4000` | Default token budget for context assembly |\n| `STATEWAVE_CORS_ORIGINS` | `[\"*\"]` | Allowed CORS origins |\n\n## Running tests\n\n```bash\n# Unit tests (no DB required)\npytest tests\u002Ftest_*.py -v\n\n# Integration tests (requires Postgres)\nPGPASSWORD=statewave createdb -h localhost -U statewave statewave_test\npytest tests\u002Fintegration\u002F -v\n\n# All tests\npytest tests\u002F -v\n```\n\n## Current limitations\n\nStatewave is in active development (v0.9.0). Honest status:\n\n- **Rate limiting is per-IP** — distributed (Postgres-backed), but keyed by IP only, not per-tenant or per-API-key yet\n- **Multi-tenant is app-layer** — query-scoped data isolation (v0.5) + per-tenant config \u002F policy bundles \u002F receipts (v0.8) layered on top, but no Postgres RLS yet\n- **PostgreSQL required** — no alternative storage backends\n- **No built-in auth provider** — validates API keys you configure, doesn't issue them\n- **Policy retention purge worker** — `tenant_configs.receipt_retention_days` is read by the config surface but no scheduled worker deletes expired receipts yet; planned for v0.9\n\nSee the [roadmap](https:\u002F\u002Fgithub.com\u002Fsmaramwbc\u002Fstatewave-docs\u002Fblob\u002Fmain\u002Froadmap.md) for what's being fixed and when.\n\n> **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.\n\n## Documentation\n\n| | |\n|---|---|\n| **[Getting started](https:\u002F\u002Fgithub.com\u002Fsmaramwbc\u002Fstatewave-docs\u002Fblob\u002Fmain\u002Fgetting-started.md)** | Clone, run, ingest your first episode |\n| [What is Statewave?](https:\u002F\u002Fgithub.com\u002Fsmaramwbc\u002Fstatewave-docs\u002Fblob\u002Fmain\u002Fproduct.md) | Product overview, use cases, limitations |\n| [Why Statewave?](https:\u002F\u002Fgithub.com\u002Fsmaramwbc\u002Fstatewave-docs\u002Fblob\u002Fmain\u002Fwhy-statewave.md) | Technical comparison for support-agent workflows |\n| [API v1 contract](https:\u002F\u002Fgithub.com\u002Fsmaramwbc\u002Fstatewave-docs\u002Fblob\u002Fmain\u002Fapi\u002Fv1-contract.md) | Full endpoint reference |\n| [Architecture overview](https:\u002F\u002Fgithub.com\u002Fsmaramwbc\u002Fstatewave-docs\u002Fblob\u002Fmain\u002Farchitecture\u002Foverview.md) | System design and data flow |\n| [Compiler modes](https:\u002F\u002Fgithub.com\u002Fsmaramwbc\u002Fstatewave-docs\u002Fblob\u002Fmain\u002Farchitecture\u002Fcompiler-modes.md) | Heuristic vs LLM — when to use which |\n| [Privacy & data flow](https:\u002F\u002Fgithub.com\u002Fsmaramwbc\u002Fstatewave-docs\u002Fblob\u002Fmain\u002Farchitecture\u002Fprivacy-and-data-flow.md) | What stays local, what leaves your network |\n| [Hardware & scaling](https:\u002F\u002Fgithub.com\u002Fsmaramwbc\u002Fstatewave-docs\u002Fblob\u002Fmain\u002Fdeployment\u002Fhardware-and-scaling.md) | GPU is never required; scaling characteristics |\n| [Deployment sizing guide](https:\u002F\u002Fgithub.com\u002Fsmaramwbc\u002Fstatewave-docs\u002Fblob\u002Fmain\u002Fdeployment\u002Fsizing.md) | Hardware profiles by tier (local → enterprise) and topology patterns |\n| [Capacity planning checklist](https:\u002F\u002Fgithub.com\u002Fsmaramwbc\u002Fstatewave-docs\u002Fblob\u002Fmain\u002Fdeployment\u002Fcapacity-planning.md) | Diagnostic flow + tuning order when load grows |\n| [Deployment guide](https:\u002F\u002Fgithub.com\u002Fsmaramwbc\u002Fstatewave-docs\u002Fblob\u002Fmain\u002Fdeployment\u002Fguide.md) | Production deployment guidance |\n| [Roadmap](https:\u002F\u002Fgithub.com\u002Fsmaramwbc\u002Fstatewave-docs\u002Fblob\u002Fmain\u002Froadmap.md) | What's next |\n| [Changelog](https:\u002F\u002Fgithub.com\u002Fsmaramwbc\u002Fstatewave-docs\u002Fblob\u002Fmain\u002FCHANGELOG.md) | Release history |\n\n## Community\n\nStatewave is built in the open. Where to post what:\n\n- **[GitHub Discussions](https:\u002F\u002Fgithub.com\u002Fsmaramwbc\u002Fstatewave\u002Fdiscussions)** — questions, ideas, RFCs, integrations, roadmap input, what you're building\n- **[GitHub Issues](https:\u002F\u002Fgithub.com\u002Fsmaramwbc\u002Fstatewave\u002Fissues)** — confirmed, reproducible bugs and concrete implementation tasks\n- **Security vulnerabilities** — email [security@statewave.ai](mailto:security@statewave.ai) (do not post publicly; see [SECURITY.md](SECURITY.md))\n- **Commercial \u002F private licensing terms** — email [licensing@statewave.ai](mailto:licensing@statewave.ai) (general licensing *questions* are welcome in Discussions)\n\nThe full community guide — categories, RFC process, moderation — lives in [statewave-docs\u002Fcommunity\u002Fdiscussions.md](https:\u002F\u002Fgithub.com\u002Fsmaramwbc\u002Fstatewave-docs\u002Fblob\u002Fmain\u002Fcommunity\u002Fdiscussions.md). Copy-paste templates for questions, feature requests, RFCs, and show-and-tell are in [discussion-templates.md](https:\u002F\u002Fgithub.com\u002Fsmaramwbc\u002Fstatewave-docs\u002Fblob\u002Fmain\u002Fcommunity\u002Fdiscussion-templates.md).\n\n## Ecosystem\n\n| Project | Description |\n|---|---|\n| **Server** (this repo) | Core server — API, domain model, DB, services |\n| [Python SDK](https:\u002F\u002Fgithub.com\u002Fsmaramwbc\u002Fstatewave-py) | `pip install statewave` — sync + async client |\n| [TypeScript SDK](https:\u002F\u002Fgithub.com\u002Fsmaramwbc\u002Fstatewave-ts) | `npm install @statewavedev\u002Fsdk` — fetch-based client |\n| [Connectors](https:\u002F\u002Fgithub.com\u002Fsmaramwbc\u002Fstatewave-connectors) | `@statewavedev\u002Fconnectors-*` — GitHub, Markdown\u002Fdocs, MCP server, modular packages |\n| [Docs](https:\u002F\u002Fgithub.com\u002Fsmaramwbc\u002Fstatewave-docs) | Architecture, API contracts, ADRs |\n| [Examples](https:\u002F\u002Fgithub.com\u002Fsmaramwbc\u002Fstatewave-examples) | Quickstarts, evals, benchmarks |\n| [Website + demo](https:\u002F\u002Fgithub.com\u002Fsmaramwbc\u002Fstatewave-web) | Marketing website + embedded interactive demo ([statewave.ai](https:\u002F\u002Fstatewave.ai)) |\n| [Admin](https:\u002F\u002Fgithub.com\u002Fsmaramwbc\u002Fstatewave-admin) | Operator console (read-only) |\n\n## Licensing\n\nStatewave is licensed under the [Apache License, Version 2.0](LICENSE).\n\nYou may use, modify, and distribute it — including in proprietary or\nhosted products — without a separate agreement. Apache-2.0 includes an\nexplicit patent grant from contributors.\n\n- **License:** [LICENSE](LICENSE) (Apache-2.0)\n- **Licensing overview:** [LICENSING.md](LICENSING.md)\n- **Trademark policy:** [TRADEMARKS.md](TRADEMARKS.md)\n- **Contributing:** [CONTRIBUTING.md](CONTRIBUTING.md)\n- **Enterprise support (SLA, indemnity, procurement):**\n  [licensing@statewave.ai](mailto:licensing@statewave.ai)\n","Statewave是一个为AI代理提供持久化、结构化上下文的开源内存运行时，旨在解决会话间记忆丢失的问题。它基于Postgres自托管，通过记录原始事件、提取类型化的记忆摘要、按需组装上下文包以及对主体时间线进行管理等功能，确保了数据生命周期的清晰与可追溯性。Statewave特别适用于需要长期记忆支持的AI应用场合，如客户服务聊天机器人、个性化推荐系统等场景，帮助提升用户体验的一致性和连贯性。采用FastAPI和Python编写，并支持语义搜索技术，易于集成到现有项目中。","2026-06-11 03:31:59","CREATED_QUERY"]