Statewave: compile agent memory once, then assemble deterministic context bundles

The problem Statewave was built to solve

The README states the problem directly: most AI applications have no memory, every conversation starts from scratch, and bolting on a vector database or dumping chat logs into a prompt produces fragile, unstructured context that degrades as it scales. Statewave's answer is to stop treating retrieval as a query-time operation. Instead, raw events are recorded as episodes, compiled once per subject change into typed memories with confidence scores and provenance, and only then assembled into a context bundle on demand. The target user is an engineering team running an agent that has to remember a user, an account, a repository, or any other tracked entity across sessions, and that also has to explain why a particular piece of context ended up in a prompt. The project's own framing is that it is infrastructure, not an application layer: the README says explicitly that Statewave is not a chatbot framework, a vector database, a RAG pipeline, or a hosted service.

Episodes in, compiled memories out, bundles on demand

The data flow has four named stages. Ingest records raw events as episodes in an append-only log. Compile extracts typed, summarised memories with confidence scores and provenance. Retrieve assembles ranked, token-bounded context bundles ready for prompts. Govern covers subject timelines, tracing a memory back to its source, and deletion by subject. Everything is organised around subjects, which are string-prefixed identifiers such as user:, repo:, or account:. The compile step is where the design diverges from query-time retrieval. The README claims the runtime is idempotent at every step: recompiling a subject produces no duplicates, and reassembling a bundle for the same task at the same point in time returns the same bytes. That determinism is the core selling point, and it is also the property that makes the provenance chain meaningful. Each bundle carries provenance back to its source episodes, and the runtime writes a state-assembly receipt: an immutable, ULID-addressable record of which memories influenced each bundle, with an HMAC-SHA256 signature and an embedded policy snapshot. The receipts endpoint POST /v1/receipts/{id}/replay answers the question of what today's code would produce given the original rules. Compilers are pluggable. The default is a heuristic compiler using regex that runs fully local; the alternative is an LLM compiler that works with any LiteLLM provider. That choice matters more than most, because it determines both your data-egress surface and the quality ceiling of the compiled memories.

Installing and running the runtime

The README's quickstart is a Python client against a locally running server. The example constructs a StatewaveClient pointed at http://localhost:8100, calls create_episode with subject_id, source, type and a payload dict, calls compile_memories for that subject, then calls get_context with a task string and max_tokens and prints the assembled_context attribute. That is the whole loop in five lines. The server itself is self-hosted on Postgres with pgvector, and the README points to two deployment paths: a Docker image published as statewavedev/statewave, and a Helm chart in the helm/ directory. The package is on PyPI as statewave, requires Python 3.11 or later, and there are separate SDK repositories for Python (statewave-py) and TypeScript (statewave-ts). Nothing in the supplied material documents the server's own environment variables or the schema migration story, so treat the Docker and Helm paths as the starting point and expect to read DOCKER.md for the actual configuration surface. Two operational properties are stated plainly. The API process is CPU-only; GPUs only enter the picture if you self-host an LLM compiler or an embedding model. And multi-tenancy is query-scoped through an X-Tenant-ID header, with per-tenant configuration and policies.

Policy, sensitivity labels and region pinning

The governance layer is more developed than the README's length suggests. Policies are declarative YAML with deny and redact actions, evaluated over per-memory tags such as pii, financial and secret, and they run in either log_only or enforce mode. Version 0.9 added advisory suggested_labels produced by heuristic detectors for pii.email, pii.phone, financial.card and secret.token. The word advisory is doing real work here: the labels are suggestions that require operator review and explicit promotion through the admin app before they carry weight. That is a deliberate choice to keep a human in the loop, and it also means the sensitivity layer is only as good as the review process behind it. Region pinning is the other v0.9 addition. A tenant pinned to eu will receive a 403 from any process running in another region, which is a residency control enforced at request time rather than at the storage layer. For teams with data-residency obligations, that is a concrete mechanism you can point at in a review. The caveat is that the supplied material does not describe how regions are declared or how a process learns its own region, so that configuration needs checking against the docs before you rely on it.

Where the compile-then-use model breaks down

Determinism is a constraint as much as a feature. A bundle is stable for a given subject, task and point in time, which means the compiled memory set has to be refreshed before a new episode can influence an answer. In a workflow where the agent must react to something that arrived seconds ago, the ingest-compile-use loop introduces a step that pure query-time retrieval does not have. The README does not state compile latency, so that cost has to be measured against your own write volume. The compiler choice is the second limitation. The local heuristic compiler uses regex, which is cheap and keeps data on your infrastructure, but pattern-based extraction has a quality ceiling that an LLM compiler does not. Choosing the LLM compiler moves you back toward sending content to a provider, which is exactly the egress the self-hosted story is meant to avoid. There is no free option that is both fully local and semantically rich. The third limitation is scope. Statewave is not a vector database and not a RAG pipeline, so if your actual need is similarity search over a document corpus, this is the wrong tool. It is also not a hosted service, which means you own the Postgres instance, the pgvector index, the backups and the upgrades. The README's own limitations section is referenced by anchor but its contents are not reproduced in the material supplied here, so read it before you size the deployment.

How this differs from a managed memory API

The obvious alternative for a team that wants agent memory without operating a database is a managed memory service, where you send conversation turns to a vendor API and receive recalled facts back. The difference is not the feature list, it is where the data lives and who can reproduce a result. A managed service holds your episodes on its infrastructure and its retrieval is typically a query-time operation whose output can vary between calls. Statewave inverts both: episodes and compiled memories live in your Postgres, and the bundle for a given subject, task and point in time is byte-stable. That stability is what makes the receipt chain auditable, because you can replay a receipt and compare. The trade is operational. A managed API is a key and a client library; Statewave is a Postgres instance, a pgvector index, a running API process and a Helm or Docker deployment you maintain. Teams without database operations capacity will find the managed route cheaper in engineering time even if it costs more in dollars and in data-governance exposure. Teams that already run Postgres and have a reason to keep agent context inside their own perimeter get the better end of the trade.

Licence, maintenance and upgrade cost

Statewave is Apache-2.0, which permits commercial use, modification and redistribution provided the licence and notices are preserved. That is a permissive licence with no copyleft obligation on your own code, and it is the same licence family most infrastructure teams already accept without a legal review cycle. This is not legal advice; if you redistribute Statewave or embed it in a product, read the LICENSE file and your own counsel's guidance. On maintenance, the release cadence visible in the supplied material is roughly every six to eight weeks across v1.3.0 in late June 2026, v1.4.0 in mid July, and v1.5.0 in late August. The repository is not archived and the default branch is main. The changelog and roadmap live in a separate statewave-docs repository, which is worth noting: the documentation is versioned independently of the code, so a release tag and a doc revision can drift. Version 0.9 features such as HMAC-signed receipts, embedded policy snapshots and region pinning are described in the README while the current release is v1.5.0, which suggests the README's capability list has accumulated across several minor versions rather than describing a single tag. Budget for reading the changelog at each upgrade, particularly around the policy engine and receipt format, since both touch stored data.

Editorial conclusion

Adopt Statewave if you are building a multi-session agent that needs auditable context and you already run Postgres, or if a compliance requirement means you cannot send raw conversation logs to a managed memory vendor. Do not adopt it if you want a hosted service, a chatbot framework, or a drop-in replacement for a vector database. Before you commit, verify three things in your own environment: that the heuristic compiler's output quality is acceptable for your subjects, that your Postgres deployment can carry the pgvector index alongside your existing workload, and that your team will actually review the advisory suggested_labels rather than leaving them unpromoted.

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. smaramwbc/statewave on GitHub