# statefulmemory — LLM-oriented product summary

Canonical site: https://statefulmemory.dev
Repository: https://github.com/sanudatta11/statefulmemory
License: MIT OR Apache-2.0 (self-host / OSS stack)

## Definition

statefulmemory is persistent memory for AI coding agents. It stores decisions, fixes,
and notes in per-project SQLite. A thin CLI talks to a gRPC daemon. Agents reach
memory through MCP tools (memory_search, memory_add, memory_context,
memory_recent, memory_facts, memory_health, memory_decide) or by shelling out to
the statefulmemory CLI.

**Deployment modes (both intentional product paths):**

1. **Self-host** — daemon on your laptop (Unix domain socket under ~/.statefulmemory/)
   or team TCP+TLS on infrastructure you run. Hybrid BM25 + BGE-small dense
   search needs no third-party search API key on this path.
2. **StatefulMemory Cloud** — managed SaaS: same coding-agent memory product with
   hosting and ops handled for you. Signup/regional details publish on
   statefulmemory.dev as the service rolls out.

Optional LLM steps (fact extract, conflict/supersession judge, rerank, Decide)
shell out to whichever agent CLI is on PATH (OpenCode, Cursor Agent, Claude
Code, Gemini CLI, Codex, Kilo, and others).

There is no Python/TypeScript Memory SDK today — use MCP or the CLI.

## Install (self-host, short)

```
git clone https://github.com/sanudatta11/statefulmemory && cd statefulmemory
make prereqs && make install
export PATH="$HOME/.local/bin:$PATH"
statefulmemory --version
statefulmemory install                 # auto-detect agents; registers MCP + skills
                                 # (+ git verify hooks when cwd is a repo)
```

## Everyday usage

```
statefulmemory obs save --type decision --title "..." --content "..." --session "$SID"
statefulmemory obs save --anchor src/auth.rs::login --title "..." --content "..."
statefulmemory obs search "auth" --mode hybrid
statefulmemory obs context --query "deploy" --limit 20 --max-tokens 500
statefulmemory verify                  # re-check code anchors against git HEAD
statefulmemory decide "Should we keep SQLite?"
statefulmemory mem export --out backup.mem
```

Context withdraws stale / invalidated / unprovable anchored claims by default
(verify.serve_stale = false). Search still returns them flagged. Unanchored
observations are never hidden.

## Local and open-source LLM backends

Pin or discover the agent CLI used for extract / judge / rerank / Decide:

- STATEFULMEMORY_LLM_BIN=/path/to/opencode
- STATEFULMEMORY_LLM_PROVIDER=opencode
- STATEFULMEMORY_LLM_MODEL=qwen   or   opencode/glm-5.3
- Host hints: OPENCODE_MODEL, CURSOR_MODEL, GEMINI_MODEL, ANTHROPIC_MODEL

Disable LLM features while keeping hybrid search on self-host:

```
statefulmemory config set extract.enabled false
statefulmemory config set conflict.enabled false
```

## Config locations (self-host)

- Global: ~/.statefulmemory/config.toml
- Per-project: ~/.statefulmemory/projects/<name>.config.toml
- Precedence: env > project overlay > global > code defaults

Notable keys: search.mode (hybrid|bm25), verify.serve_stale, search.max_per_type,
search.decay_lambda, search.evidence_window, embed.quantize, conflict.enabled,
extract.enabled.

## Supported install targets

claude-code, cursor, windsurf, antigravity, opencode, kimi-code, zcode, agents,
vscode, copilot-cli, copilot, gemini, codex, amazon-q.

OpenCode MCP config: ~/.config/opencode/opencode.json
Shared skills: .agents/ when the agents target is selected.

LangGraph, CrewAI, AutoGen, LlamaIndex, Vercel AI SDK: not shipped.

## Documentation index

https://statefulmemory.dev/
https://statefulmemory.dev/docs/why-statefulmemory/
https://statefulmemory.dev/docs/architecture/
https://statefulmemory.dev/docs/install/
https://statefulmemory.dev/docs/getting-started/
https://statefulmemory.dev/docs/integrations/
https://statefulmemory.dev/docs/agents/
https://statefulmemory.dev/docs/self-hosting/
https://statefulmemory.dev/docs/observations/
https://statefulmemory.dev/docs/search-context/
https://statefulmemory.dev/docs/anchors-verify/
https://statefulmemory.dev/docs/decide/
https://statefulmemory.dev/docs/mem/
https://statefulmemory.dev/docs/commands/
https://statefulmemory.dev/docs/config/
https://statefulmemory.dev/docs/locomo/
https://statefulmemory.dev/docs/troubleshooting/
https://statefulmemory.dev/llms.txt