cavemem: frozen cross-agent memory for coding assistants, and what the freeze means

The problem cavemem targets: assistants that start every session blank

A coding assistant ends a session and forgets it. The next session re-reads the same files, re-derives the same conclusions, and asks the same questions. cavemem exists to put a persistent store behind that gap. Hooks fire at session boundaries, capture what happened, and write it to local SQLite; the agent later queries its own history through MCP tools. The intended user is someone running more than one assistant against the same codebase and wanting the history to survive across them. The README lists Claude Code, OpenCode, Codex, GitHub Copilot, Augment Code, Cursor, Gemini CLI, Antigravity and IBM Bob, though not all of them capture. The stated design constraints are local-only: no network, no cloud, and a read-only web viewer on localhost. That framing matters, because it rules out the hosted-memory product category by construction rather than by policy.

The capture path: hooks in, redaction, compression, SQLite out

The pipeline in the README is short: a session event triggers redaction of anything inside private tags, then compression, then a write to SQLite with FTS5 indexing. Retrieval runs the other direction, through MCP queries issued on demand rather than at write time. Compression is the part worth understanding. It uses what the project calls the caveman grammar, which the README claims removes roughly 75 percent of prose tokens while leaving code and paths byte-for-byte intact. The worked example is concrete: a sentence about an auth middleware throwing 401 when a session token expires is stored as a shortened form and expanded back for human viewing. The claim of round-trip-guaranteed expansion is the load-bearing one, since a lossy store that cannot reconstruct meaning is worse than no store. Note that the 75 percent figure appears only as a README claim; nothing in the supplied material shows how it was measured or on what corpus. The hook handlers are described as completing in under 150 milliseconds, which is the number that decides whether capture is tolerable at a session boundary. Treat both numbers as documentation, not as verified results.

Retrieval: three MCP tools and a hybrid ranker

Agents do not get a dump of the whole store. They get search, timeline and get_observations, which the README describes as progressive retrieval: the agent filters before fetching. That ordering is the design decision that keeps token cost down, since a wide search returns identifiers and the agent then pulls full observations only for the ones it wants. Search itself is hybrid, combining SQLite FTS5 keyword matching with a local vector index and a tunable ranker. The vector side is built by a local worker that auto-spawns on the first hook and exits when idle. Embeddings are local by default, with optional remote embedding providers configured explicitly. That is the one documented path where data could leave the machine, and it is opt-in. The viewer is a read-only UI on port 37777. The README states that the worker generates a local bearer token on first start and injects it into the served page, so the viewer opens without friction while the API rejects requests lacking the token.

Getting it running: four commands and two config keys

Installation is npm-based. The README gives npm install -g cavemem, then cavemem install for Claude Code, with an --ide flag accepting cursor, gemini-cli, opencode, codex, copilot, augment, antigravity or bob. cavemem status reports wiring and embedding backfill, and cavemem viewer opens the local UI. There is no daemon to start; hooks write synchronously and the background worker spawns itself. Two configuration keys appear in the material. embedding.idleShutdownMs set to 0 keeps the worker alive until it is killed instead of letting it self-exit when idle. embedding.autoStart false disables auto-spawn entirely, and with it the HTTP listener, which is the setting to reach for if you want capture without any local server. The README also notes that cavemem doctor and cavemem install both check whether sh resolves on win32 and warn if it does not. OpenCode capture does not use hooks.json at all; a bundled bridge plugin named opencodeBridge.js is symlinked into OpenCode's plugin directory and subscribes to that editor's native event and tool.execute.after hooks, shelling out to the same cavemem hook run handlers.

The Windows trap and the silent-capture failure mode

The most useful section of the README is the one about Windows, because it documents a failure that hides itself. Claude Code runs hook commands through sh -c even on Windows. If Git for Windows' Git\bin directory is not on the user Path, sh does not resolve, hooks fail, and capture stops. The CLI keeps reporting healthy, because the failure never reaches it. The fix is to add C:\Program Files\Git\bin, or the Scoop equivalent under apps\git\current\usr\bin, to the user Path and confirm with where.exe sh. The README is candid about why this has not been engineered away: Claude Code's hooks documentation describes a shell field and a shell-free args exec form, but the maintainers could not verify those fields against every Claude Code version in the wild, so they kept the plain sh-shaped command string. The reasoning given is that the current command contains no shell metacharacters and therefore tokenizes the same way under sh or a PowerShell fallback. The second, broader failure mode is capture versus query. The capability matrix marks Cursor, Gemini CLI, Antigravity and IBM Bob as query-only, because none of them exposes a hooks system. Query-only means MCP search over memory captured elsewhere. For those editors the database never fills on its own, and the README cross-references issue 58 for exactly this confusion: status looks healthy while nothing is being written. Codex, Copilot and Augment capture but with gaps, since Codex and Copilot have no SessionEnd event and Augment has no UserPromptSubmit.

The freeze, and why caveman is the real alternative

The README opens with a status note dated August 2026: cavemem is frozen, no longer in active development, and the compressed-memory core now lives inside caveman, described as the actively developed home of the family, alongside caveman-browse. The last release in the supplied material is v0.2.1 from May 2026, and the repository's last push is August 2026, which is consistent with a freeze rather than an abandonment. This changes what the choice actually is. Comparing cavemem to a hosted memory service is the wrong comparison, because the interesting alternative is the sibling project that inherited the same compression core. The practical difference is maintenance: cavemem will keep installing and working per the README, but expect no new features or fixes, while caveman is where the core is being developed. That means the same grammar and the same compression idea sit behind both, and the question is which codebase receives attention for new editor integrations and bug fixes. A team already running cavemem is not stranded, since the store is local SQLite and the licence is permissive, but any new integration work should be aimed at the maintained repository.

Maintenance cost, licensing and what to check before adopting

The licence is MIT, which permits commercial and internal use with minimal obligation; the usual requirement is preserving the copyright notice and licence text in distributions. That is a general property of MIT, not legal advice, and anyone embedding cavemem in a product should read the LICENSE file in the repository. On maintenance, the arithmetic is straightforward. A frozen project's upgrade cost is zero because there are no upgrades, and its risk is that a future editor version breaks the hook wiring with no upstream fix. The hook contract is the fragile surface here: the README reuses Claude Code's handler shapes for Copilot and Codex, and explicitly declined to adopt newer hook fields it could not verify across Claude Code versions. That conservatism reduces breakage now and guarantees that a future Claude Code change lands on users rather than on maintainers. The store itself is the durable part, since it is a local SQLite file that outlives the tool. Before adopting, run cavemem status and read the ides line carefully, because query-only editors are flagged inline and it is easy to misread a wired MCP server as working capture. On Windows, run where.exe sh first. If either check fails, the store stays empty and the tool looks installed while doing nothing.

Editorial conclusion

Adopt cavemem only if you want a stable, MIT-licensed local memory store and accept that no fixes are coming; the README states plainly that the compressed-memory core now lives inside caveman, so new work belongs there. Skip it if you need Cursor, Gemini CLI, Antigravity or IBM Bob to capture their own sessions, because the capability matrix marks all four query-only. Before committing, run cavemem status to confirm which IDEs are actually wired, and on Windows run where.exe sh to confirm Git's bin directory is on your user Path, since the README notes hooks fail silently without it while status still reports healthy.

Official sources

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