Statewave

Statewave is an open-source memory runtime designed to give AI agents durable, structured, and reproducible context across sessions. Instead of relying on raw conversation history or performing unpredictable retrieval every time an agent needs information, it turns events into organized memories and assembles focused context bundles when needed.

This approach is particularly useful for developers building agents that need to remember customer preferences, project decisions, account history, technical details, or other information over long periods. The project is self-hosted, runs with PostgreSQL and pgvector, and provides both Python and TypeScript SDKs, making it practical for a wide range of AI applications.

One of its strongest ideas is provenance. Memories can be traced back to the original events that created them, giving developers a clearer view of why particular information became part of an agent's context.

Key Features

• Durable memory for AI agents across multiple sessions
• Structured memory compilation from raw events
• Ranked, token-bounded context bundles
• Provenance tracking from memories back to source episodes
• Deterministic context assembly for reproducible results
• Heuristic or LLM-powered memory compilation
• PostgreSQL and pgvector based self-hosting
• Python and TypeScript SDK support
• Multi-tenant data isolation
• Sensitivity labels and policy-based controls
• State-assembly receipts with verification and replay capabilities
• REST API and framework-neutral architecture

User Interface

This is primarily developer infrastructure rather than a conventional end-user application, so the experience centers around APIs, SDKs, documentation, and deployment tools. The project also provides an administrative interface and an interactive demonstration that lets developers compare a stateless AI agent with one that has persistent memory.

The setup is straightforward for technical teams. A server can be started with a package command or deployed using Docker Compose or Helm. API documentation is available through OpenAPI and ReDoc endpoints, which makes exploring the available operations much easier during development.

Accuracy & Performance

The architecture focuses on reducing the inconsistency that can appear when an AI system searches its memory from scratch for every request. Memories are compiled when a subject changes and can then be assembled into a bounded context for a particular task.

That design also makes the output reproducible: the same subject, task, and point in time can produce the same context bytes. For applications where an agent's decisions need to be inspected later, this is a meaningful advantage.

The project includes evaluation tests and benchmarks, while its architecture is built around PostgreSQL and pgvector. The API itself does not require a GPU, although developers can choose to use GPU-backed models when self-hosting their own language or embedding infrastructure.

Capabilities

The system follows a clear ingest, compile, retrieve, and govern workflow. Raw events are stored as append-only episodes, then transformed into typed memories containing information such as confidence and provenance. Those memories can subsequently be ranked and assembled into context according to a task and token limit.

Developers can organize information around virtually any entity, including users, accounts, repositories, agents, or customers. The framework also supports multiple compiler modes, with a local heuristic option for lightweight deployments and LLM-based compilation through LiteLLM for more advanced memory extraction.

For teams that care about governance, the platform includes sensitivity labels, declarative policies, tenant isolation, state-assembly receipts, HMAC-SHA256 signatures, and replay functionality. These features make it more than a simple memory store; it provides infrastructure for tracking how context was assembled and controlled.

Security & Privacy

Self-hosting is one of the project's biggest advantages from a data-control perspective. Episodes and compiled memories can remain in the organization's own PostgreSQL environment rather than being stored in a third-party hosted memory service.

The default heuristic compiler can operate locally, while teams can decide whether to send information to an external model provider when using LLM-based compilation or hosted embeddings. Sensitivity policies can also be used to deny or redact information according to memory labels.

Multi-tenant deployments include query-scoped isolation and tenant-specific configuration. Regional pinning is also available for deployments that need to keep particular tenants within a designated region.

Use Cases

A customer support agent can use persistent memory to recognize returning customers, remember previous interactions, assemble relevant context within a token budget, and provide a useful handoff when a conversation is escalated.

Long-running coding agents are another strong fit. Instead of treating every development session as a new project, an agent can retain information such as technology choices, architectural decisions, coding preferences, and project history.

The same architecture can support AI applications that maintain user preferences, business account history, research context, repository information, or other subject-specific knowledge over time. Developers can also connect the system to different AI stacks through its REST API and SDKs.

Pros and Cons

• Pros: Open-source and Apache-2.0 licensed, self-hosted, reproducible context assembly, strong provenance tracking, PostgreSQL and pgvector support, Python and TypeScript SDKs, multi-tenant capabilities, policy controls, and no mandatory GPU requirement.
• Cons: It is developer infrastructure rather than a ready-made chatbot platform, so some engineering work is required. Teams also need to manage their own deployment and PostgreSQL infrastructure when self-hosting.

Pricing Plans

The project is available under the Apache License 2.0, allowing it to be used, modified, and distributed in commercial and proprietary applications without a separate licensing agreement. There is no conventional subscription plan for the open-source runtime itself.

Because the software is self-hosted, organizations are responsible for their own infrastructure and any external AI model or embedding costs they choose to use. This model can be attractive to teams that want control over their data and deployment rather than paying for a hosted memory platform.

How to Use It

Getting started is aimed at developers. The server can be launched locally with the available package command, installed through the provided installation script, or deployed using Docker Compose. Helm is also available for Kubernetes-oriented environments.

Once the server is running, a typical workflow begins by creating an episode for a subject. The stored events can then be compiled into memories, after which the application requests a context bundle for a particular task and token limit.

For example, an application might record a customer's conversation, compile the customer's memories, and then request the most relevant context before generating the next response. Python and TypeScript SDKs provide a convenient way to integrate these operations into an existing application.

Comparison with Similar Tools

Traditional vector databases are excellent at storing and searching embeddings, but they do not necessarily provide a complete memory lifecycle for an AI agent. A basic RAG implementation can retrieve documents at query time, yet it may leave developers responsible for deciding how memories are created, structured, governed, and traced.

This project takes a broader approach. It combines event ingestion, memory compilation, context assembly, provenance, policies, and governance into one runtime. The emphasis on deterministic context and source tracing is particularly interesting for applications where developers need to understand not only what an agent remembers, but also where that information came from.

It therefore fits best alongside an AI application rather than replacing the application itself. Teams looking for a complete chatbot builder may need additional software, while developers building sophisticated agents can use it as the memory layer underneath their own stack.

Conclusion

Persistent memory is becoming an important part of serious AI agents, especially when conversations, projects, or customer relationships extend beyond a single session. This project offers a thoughtful developer-focused solution by treating memory as structured state rather than simply a collection of searchable messages.

The combination of self-hosting, provenance, deterministic context assembly, policy controls, PostgreSQL support, and multiple SDKs gives it a particularly appealing profile for engineering teams that want control over how agent memory works. It requires technical involvement, but for developers who are comfortable managing their own infrastructure, it provides a solid foundation for building AI agents that can actually remember.

Frequently Asked Questions (FAQ)

What is Statewave used for?

It provides persistent memory infrastructure for AI agents and applications. It helps applications store events, compile them into structured memories, and retrieve relevant context across sessions.

Is it a chatbot platform?

No. It is infrastructure that runs alongside an AI application. Developers use its APIs or SDKs to add memory capabilities to their own agents and applications.

Can it be self-hosted?

Yes. The project is designed for self-hosting and can run with PostgreSQL and pgvector. Docker Compose, Helm, and other deployment approaches are available.

Does it support Python and TypeScript?

Yes. Official SDKs are available for both Python and TypeScript, while the REST API allows integration from other programming environments.

Does it require an LLM?

Not necessarily. A heuristic compiler can operate locally. Developers can also configure an LLM-based compiler through LiteLLM when they need more advanced memory extraction.

Is it free for commercial use?

Yes. The server and SDKs are released under the Apache License 2.0, which permits commercial and proprietary use.

Can memories be traced back to their sources?

Yes. Provenance is a core part of the architecture. Memories can be connected to their originating episodes, and state-assembly receipts provide additional information about which memories influenced a context bundle.

Does it work with different AI model providers?

Yes. Through LiteLLM, the project can work with a broad range of model providers and deployment options, giving developers flexibility when choosing their language and embedding models.