cavemem: frozen cross-agent memory for coding assistants

The problem cavemem solves: agents that forget between sessions

A coding assistant starts each session with no record of the last one. The README poses the question directly: "why agent forget when agent can remember". cavemem is the answer to that, and it is aimed at people who run more than one agent-shaped tool against the same codebase. The README lists support for Claude Code, OpenCode, Codex, GitHub Copilot, Augment Code, Cursor, Gemini CLI, Antigravity and IBM Bob, which is a wide spread for a tool this small. The point is not a single assistant with a memory feature. The point is a shared store that several assistants read from.

Two design choices define the project. Storage is local: the README states there are no network calls and no cloud, and that observations land in SQLite. Retrieval is pull-based: agents call three MCP tools (`search`, `timeline`, `get_observations`) rather than receiving a preloaded context blob. That matters because the alternative, pasting history into every prompt, spends context on observations the current task does not need.

The audience is narrower than the IDE list suggests. Anyone with a single assistant and short sessions gets little from this. The value shows up when sessions are long enough to produce useful observations and when the same person returns to the same repository across days.

Hooks, compression and the SQLite store

The pipeline in the README is short: a session event fires a hook, `<private>` blocks are redacted, the observation is compressed, and the result is written to SQLite with FTS5 indexing. MCP queries read from that store on demand.

Capture is hook-driven, and the capability matrix makes the consequences explicit. Claude Code gets five hooks: SessionStart, UserPromptSubmit, PostToolUse, Stop and SessionEnd. OpenCode has no `hooks.json`-style event system, so capture goes through a bundled bridge plugin, `opencodeBridge.js`, symlinked into OpenCode's plugin directory on install; it subscribes to OpenCode's native `event` and `tool.execute.after` hooks and shells out to the same `cavemem hook run` handlers. Codex and Copilot have no SessionEnd event, and Augment Code has no UserPromptSubmit, so those lifecycle moments never fire for those tools. Cursor, Gemini CLI, Antigravity and IBM Bob have no hooks system at all and are query-only.

Compression is the part worth reading closely. The README gives a worked example: the sentence "The auth middleware throws a 401 when the session token expires; we should add a refresh path." is stored as "auth mw throws 401 @ session token expires. add refresh path." and expands back to "The auth middleware throws a 401 when session token expires. Add refresh path." The grammar is described as deterministic and round-trip-guaranteed, and code blocks, URLs, paths, identifiers and version numbers are never touched. The README claims roughly 75% fewer prose tokens. That number is the project's own claim, not something I measured, and the guarantee that code and paths survive byte-for-byte is the more useful property for anyone deciding whether to trust the store.

Search is hybrid: SQLite FTS5 keyword matching combined with a local vector index, merged by a ranker the README calls tunable. Embeddings are built by a background worker that auto-spawns on the first hook and self-exits when idle. Setting `embedding.idleShutdownMs` to `0` keeps it running until killed, and `cavemem config set embedding.autoStart false` disables auto-spawn along with the HTTP listener.

Installing cavemem and capturing a first session

The README gives a global npm install and one command per IDE. Node 20 or newer is required according to the root package.json engines field. The default `cavemem install` targets Claude Code; other IDEs are selected with `--ide`.

npm install -g cavemem
cavemem install
cavemem install --ide cursor
cavemem status

The third line is the one to remember. `cavemem status` reports which IDEs are wired up and shows query-only ones inline, for example `ides: claude-code, antigravity (query-only)`. It also reports embedding backfill. If your IDE appears without capture, no amount of normal use will fill the database.

There is no daemon to start. Hooks write synchronously, and the background worker spawns itself when needed. To read what was captured, start the viewer.

cavemem viewer

The README says this opens `http://127.0.0.1:37777` (the install block also shows `http://localhost:37777`). The page is read-only and in human-readable form, with compressed observations expanded back into prose. The worker generates a local bearer token on first start and injects it into the served page, so the viewer opens without extra steps while `/api/*` rejects requests that lack the token.

An example settings file lives at `examples/settings.example.json` in the repository. The README documents two config keys by name: `embedding.idleShutdownMs` and `embedding.autoStart`, both set through `cavemem config set`.

Where cavemem breaks: silent capture failure and query-only IDEs

The most serious failure mode is documented in the README itself, and it is a Windows one. Claude Code runs hook commands through `sh -c` even on Windows. If Git for Windows' `Git\bin` is not on the user `Path`, `sh` does not resolve, hooks fail silently, and capture stops. Meanwhile `cavemem doctor` and `cavemem status` keep reporting healthy, because the failure never reaches the CLI. The README's fix is to add `C:\Program Files\Git\bin` (or `<scoop dir>\apps\git\current\usr\bin` for a Scoop install) to the user `Path` and verify with `where.exe sh`. Both `cavemem doctor` and `cavemem install` check `sh` resolvability on win32 and print a warning if it is missing. A memory tool that silently records nothing while reporting health is worse than no memory tool, and this is the clearest example of that risk in the project.

The second limitation is structural. The README flags issue #58 to make the point: for a query-only IDE, the database never fills for that IDE no matter how healthy `cavemem status` looks. Cursor, Gemini CLI, Antigravity and IBM Bob can search memory captured elsewhere, but they contribute nothing. If your team standardised on Cursor, cavemem is a read layer over data produced by some other tool, and if nobody runs that other tool, the store stays empty.

The third is incompleteness rather than breakage. Codex and Copilot have no SessionEnd event, and Augment Code has no UserPromptSubmit. The README is candid that the handlers are reused unmodified because the payload shapes are close to Claude Code's, but the event sets are not equivalent across tools. Sessions end without a closing observation on some agents.

Finally, the README states plainly that `cavemem` is frozen as of August 2026 and no longer in active development. The last push to the repository was on 2026-08-14. Everything still installs and works, but new features and fixes should not be expected.

cavemem against caveman, and against a plain memory file

The obvious alternative is the project's own successor. The README states that cavemem's compressed-memory core now ships inside caveman, described as the actively developed home of the family, alongside caveman-browse. The difference in approach is one of scope rather than mechanism: cavemem is the frozen cross-agent memory layer you install today, while caveman is where the same compression core continues to be developed. If the compression and retrieval behaviour is what you want, caveman is the place to look for current work. If you need exactly what is documented here and nothing more, cavemem still installs.

The other alternative is not a tool at all. A checked-in markdown file with project notes, or a `CLAUDE.md`-style context file, is what most people use instead. The difference is mechanical. A context file is loaded wholesale into every session and is written by hand. cavemem captures observations automatically at lifecycle events, compresses them at rest, and retrieves them selectively through MCP search. The trade-off runs both ways: the context file is readable, editable and version-controlled in the same diff as the code, while cavemem's store is a local SQLite database that lives outside your repository and is queried by the agent rather than reviewed by you. For a small project with a handful of conventions, the file is simpler and has no Windows `sh` dependency. For long-running work across several agents, automatic capture is the thing a hand-written file cannot do.

Maintenance, upgrade cost and the MIT licence

cavemem is licensed MIT, and the root package.json carries the same identifier. That is a permissive licence, and it means you can read, modify and redistribute the code. It says nothing about the data cavemem writes, which stays in a local SQLite file on your machine. If you plan to move that database between machines, the licence does not govern the move; your own data handling does. This is not legal advice.

On maintenance, the facts are simple. The README declares the project frozen as of August 2026, and the last push to the repository was on 2026-08-14. The most recent release listed is v0.2.1 from 2026-05-06, following v0.1.3 and v0.1.1 in April 2026. A frozen tool is not a broken tool, and the README says everything still installs and works. The upgrade cost is the part to think about: the compressed-memory core has moved into caveman, so anyone who wants the current version of that core is looking at a different repository with a different install story. Staying on cavemem means staying on the documented behaviour, including the Windows `sh` requirement and the incomplete event coverage in Codex, Copilot and Augment Code. There is no documented migration path from cavemem to caveman in the README, so treat the two as separate tools until you confirm otherwise.

Editorial conclusion

Adopt cavemem if you want local, no-network memory for a hook-capable agent such as Claude Code or OpenCode and you accept that the project is frozen. Do not adopt it for a query-only IDE and expect the store to fill on its own, because those IDEs have no hooks system and only read memory captured elsewhere. Verify first that `cavemem status` lists your IDE with capture enabled, and on Windows confirm that `sh` resolves before trusting any capture at all.

Frequently asked questions

Official sources

1. JuliusBrussee/cavemem on GitHub
2. License: MIT
3. Project website
4. README
5. Releases