# Statewave — Memory Runtime for AI Agents (API + SDKs)

> Statewave is a self-hostable memory runtime: ingest episodes, compile memories, do semantic search, and build token-bounded context bundles via REST.

## Install

Copy the content below into your project:

## Quick Use

```bash
# Start Postgres (pgvector)
docker compose up db -d

python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev,llm]"
alembic upgrade head

uvicorn server.app:app --host 0.0.0.0 --port 8100
```

## Intro

Turn messy agent history into structured, searchable memory with an API contract: episodes → compiled memories → ranked context bundles for prompts.

**Best for:** Agent products that need durable memory beyond chat logs (support agents, coding agents, multi-channel assistants)

**Works with:** Self-hosted API (default localhost:8100); Python + TypeScript SDKs; modular connectors packages (per README)

**Setup time:** 15–30 minutes

### Key facts (verified)

- Quick start runs the API on port 8100 and exposes `/docs` and `/redoc` endpoints (per README).
- API includes endpoints like `POST /v1/episodes`, `POST /v1/memories/compile`, and `GET /v1/memories/search` (per README table).
- README lists connectors packages (e.g., GitHub/Slack/Markdown) as separate modular installs via npm.
- GitHub: 214 stars · 1 forks; pushed 2026-05-11 (GitHub API verified).

## Main

A memory workflow that stays practical:

1. Ingest “episodes” as append-only facts (events, decisions, commits, incidents) — keep them small and timestamped.
2. Compile memories on a schedule (or after a threshold) so retrieval stays fast and deterministic.
3. Use semantic search for “similar past issues”, but always ask for **source episode IDs** so you can audit the chain.
4. Build a token-bounded context bundle for prompts instead of dumping raw history.

Statewave’s API-first shape makes it easier to integrate multiple channels without rewriting memory logic per tool.

### FAQ

**Q: Do I need a GPU?**
A: No. The README says the API process is CPU-only; GPUs only matter if you self-host a model/compiler.

**Q: Is there auth?**
A: Optional. The README mentions API keys via the `X-API-Key` header.

**Q: Can I use it without connectors?**
A: Yes. The README says connectors live in a separate repo and are optional; they talk to the public HTTP API.

## Source & Thanks

> Source: https://github.com/smaramwbc/statewave
> License: AGPL-3.0
> GitHub stars: 214 · forks: 1

---

<!-- ZH -->

## 快速使用

```bash
# 启动 Postgres（pgvector）
docker compose up db -d

python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev,llm]"
alembic upgrade head

uvicorn server.app:app --host 0.0.0.0 --port 8100
```

## 简介

把零散的 Agent 历史变成结构化可搜索的记忆：episodes → 编译 memories → 为 prompt 组装排序好的上下文包。

**最适合：** 需要“持久记忆”的 Agent 产品：不止聊天记录（客服/编码/多渠道助手等）

**适配：** 自托管 API（默认 localhost:8100）；Python/TypeScript SDK；模块化 connectors（见 README）

**配置时间：** 15–30 分钟

### 关键事实（已验证）

- README Quick start 把 API 跑在 8100 端口，并提供 `/docs`、`/redoc`（Swagger/ReDoc）。
- README API 表包含 `POST /v1/episodes`、`POST /v1/memories/compile`、`GET /v1/memories/search` 等接口。
- README 说明 connectors 是独立模块（npm 包），按需安装（GitHub/Slack/Markdown 等）。
- GitHub：214 stars · 1 forks；最近更新 2026-05-11（GitHub API 验证）。

## 正文

更实用的记忆工作流建议：

1. 以 append-only 的方式写入 episodes（事件/决策/提交/事故），保持单条小而清晰、带时间戳。
2. 按计划（或阈值）编译 memories，保证检索速度与确定性。
3. 语义搜索用于“相似问题复用”，但要让系统可审计：输出对应 episode ID。
4. 给 prompt 组装 token 有上限的 context bundle，而不是把原始历史全倒进去。

Statewave 的 API-first 形态更适合多渠道集成，不用每个工具重复造“记忆轮子”。

### FAQ

**需要 GPU 吗？**
答：不需要。README 写明 API 进程是 CPU-only；只有你自托管模型/编译器时才会涉及 GPU。

**有鉴权吗？**
答：可选。README 提到可通过 `X-API-Key` 头启用 API key。

**不装 connectors 也能用吗？**
答：能。README 写明 connectors 在独立仓库，按需安装，且都走同一套公共 HTTP API。

## 来源与感谢

> Source: https://github.com/smaramwbc/statewave
> License: AGPL-3.0
> GitHub stars: 214 · forks: 1


---
Source: https://tokrepo.com/en/workflows/statewave-memory-runtime-for-ai-agents-api-sdks
Author: AI Open Source