AGENTS.md

1# mem — cavemem, durable agent memory (commercial Go core + MIT clients)
2 
3Durable, cross-session memory: `remember` / `recall` / `supersede` / `history` / `forget`. A local SQLite store holds the
4**raw** memories (the source of truth); recall ranks them with deterministic **BM25** behind a
5conservative threshold and compresses each hit through the [engine](../engine/CLAUDE.md) so the
6inferred token cost is honest and the dropped detail stays recoverable via CCR. Everything is
7`inferred`.
8 
9## Layout
10- `store.go` — `Remember`/`Recall`/`Supersede`/`History`/`Forget`/`Recover` over SQLite + engine; legacy schemas migrate in place.
11- `bm25.go` — deterministic tokenizer + BM25 scorer (non-negative scores, so the threshold is meaningful).
12- `cmd/cavemem/` — MCP server + `remember`/`recall`/`supersede`/`history`/`forget` CLI subcommands (JSON).
13- `js/` + `py/` — thin TS and Python clients that shell out to the binary (mirrored libraries; they reimplement nothing).
14 
15## The cavemem_* MCP tools
16`cavemem_remember(text)` · `cavemem_recall(query, limit?, token_budget?)` ·
17`cavemem_supersede(id, text)` · `cavemem_history(id)` · `cavemem_forget(id)`,
18served through `mcp.NewServer` so the framing matches caveman-mcp exactly.
19 
20## Conventions
21- Build/test: `make product-build PRODUCT=mem` / `make product-test PRODUCT=mem`
22  for the Go core; root `make test` also runs mirrored JS/Python wrapper tests.
23- The wrappers shell out to the gated binary — keep recall/scoring logic in Go, never forked into TS/Python.
24 
25## Gotchas (honesty invariants)
26- **byte-safe write** — raw text is written to SQLite before any engine call, so a memory is never lost; compression is transient, at recall time only.
27- **bounded recall** — omitted/Go-zero `TokenBudget` defaults to 2000 inferred tokens. Public CLI/MCP/JS/Python callers must explicitly pass `token_budget=0` for unlimited recall; adapters map it to `UnlimitedTokenBudget`.
28- **fail toward nothing** — a query below the threshold (or with no term overlap) recalls nothing, never a guess.
29- **current-only recall** — superseded versions stay auditable through `History` but never enter normal recall.
30- **inferred-only** — `tokens_added`, score, and basis are inferred estimates; never `verified`.
31- **reversible** — a compressed recall hit carries a CCR `recovery_handle`; `Recover` returns the byte-exact original.
32 
33See ../../CLAUDE.md (root) · ../engine/CLAUDE.md · ../mcp/CLAUDE.md
34