cavemem

why agent forget when agent can remember

Install • How it works • CLI • MCP • Settings

🪨 Caveman Ecosystem  ·  caveman talk less  ·  cavemem remember more _{(you are here)}  ·  cavekit build better

---

Cross-agent persistent memory for coding assistants. Hooks fire at session boundaries, compress observations with the caveman grammar (~75% fewer prose tokens, code and paths preserved byte-for-byte), and write to local SQLite. Agents query their own history through three MCP tools. No network. No cloud.

Supports: Claude Code · Cursor · Gemini CLI · OpenCode · Codex

• Persistent memory across sessions. Hooks capture what happened; the store keeps it.
• Compressed at rest. Deterministic caveman grammar, round-trip-guaranteed expansion for humans.
• Progressive MCP retrieval. search, timeline, get_observations — agents filter before fetching.
• Hybrid search. SQLite FTS5 keyword + local vector index, combined with a tunable ranker.
• Local by default. No network calls. Optional remote embedding providers via config.
• Web viewer. Read-only UI at http://localhost:37777 for browsing sessions in human-readable form.
• Cross-IDE installers. Claude Code, Gemini CLI, OpenCode, Codex, Cursor — one command each.
• Privacy-aware. <private>...</private> stripped at write boundary. Path globs exclude whole directories.

---

Install

npm install -g cavemem
cavemem install                    # Claude Code
cavemem install --ide cursor       # cursor | gemini-cli | opencode | codex
cavemem status                     # see wiring + embedding backfill
cavemem viewer                     # open http://127.0.0.1:37777

No daemon to start. Hooks write synchronously. A local worker auto-spawns in the background on the first hook to build embeddings; it self-exits when idle. Disable with cavemem config set embedding.autoStart false.

---

How it works

session event  →  redact <private>  →  compress  →  SQLite + FTS5
                                                           ↑
                                                MCP queries on demand

What compression looks like in practice:

Input:  "The auth middleware throws a 401 when the session token expires; we should add a refresh path."
Stored: "auth mw throws 401 @ session token expires. add refresh path."
Viewed: "The auth middleware throws a 401 when session token expires. Add refresh path."

Code blocks, URLs, paths, identifiers, and version numbers are never touched. Hook handlers complete in under 150ms. Full bodies fetched on demand via get_observations.

---

CLI

Command
cavemem install [--ide <name>]	Register hooks + MCP for an IDE
cavemem uninstall [--ide <name>]	Remove hooks + MCP
cavemem status	Single dashboard: wiring, DB counts, embedding backfill, worker pid
cavemem config show\|get\|set\|open	View/edit settings — schema is self-documenting
cavemem start\|stop\|restart	Control the worker daemon (usually unnecessary — auto-starts)
cavemem viewer	Open the memory viewer in your browser
cavemem doctor	Verify installation
cavemem search <query> [--limit N] [--no-semantic]	Search memory (BM25 + cosine re-rank)
cavemem compress <file>	Compress a file with caveman grammar
cavemem reindex	Rebuild FTS5 + vector index
cavemem export <out.jsonl>	Dump observations to JSONL
cavemem mcp	Start MCP server (stdio)

---

MCP

Progressive disclosure: search and timeline return compact results; get_observations fetches full bodies.

Tool	Returns
search(query, limit?)	[{id, score, snippet, session_id, ts}] — BM25 + optional cosine re-rank
timeline(session_id, around_id?, limit?)	[{id, kind, ts}]
get_observations(ids[], expand?)	Full bodies, expanded by default
list_sessions(limit?)	[{id, ide, cwd, started_at, ended_at}]

---

Settings

~/.cavemem/settings.json

Key	Default
dataDir	"~/.cavemem"	SQLite location
compression.intensity	"full"	lite / full / ultra
compression.expandForModel	false	Return expanded text to model
embedding.provider	"local"	local / ollama / openai
workerPort	37777	Local viewer port
search.alpha	0.5	BM25 / vector blend
search.defaultLimit	10	Default result count
privacy.excludePatterns	[]	Paths never captured

Content inside <private>...</private> is stripped before write. Paths matching excludePatterns are never read. The worker binds to 127.0.0.1 only.

---

🪨 The Caveman Ecosystem

Three tools. One philosophy: agent do more with less.

Repo	What	One-liner
caveman	Output compression skill	why use many token when few do trick — ~75% fewer output tokens across Claude Code, Cursor, Gemini, Codex
cavemem (you are here)	Cross-agent persistent memory	why agent forget when agent can remember — compressed SQLite + MCP, local by default
cavekit	Spec-driven autonomous build loop	why agent guess when agent can know — natural language → kits → parallel build → verified

They compose: cavekit orchestrates the build, caveman compresses what the agent says, cavemem compresses what the agent remembers. Install one, some, or all — each stands alone.

Also by Julius Brussee

• Revu — local-first macOS study app with FSRS spaced repetition. revu.cards

License

MIT