cavemem

why agent forget when agent can remember

Install • How it works • CLI • MCP • Settings

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