Memory

cavemem is a local store for the context you keep re-explaining. You write something once, and later ask a question. It returns only the parts that answer the question, compressed through the engine on the way out.

Licence

Go core BSL 1.1. The JavaScript and Python clients are MIT.

Storage

~/.caveman/mem

Ranking

BM25 behind a conservative threshold.

Basis

Always inferred.

Binary

cavemem

Build it#

go build -o cavemem ./public/mem/cmd/cavemem

Use it#

cavemem remember "the deploy key lives in vault under ops/deploy"
cavemem recall "where is the deploy key"
cavemem recall "full migration context" 5 0
cavemem supersede mem_xxxxxxxx "deploy key moved to vault ops/deploy-v2"
cavemem history mem_yyyyyyyy
cavemem forget mem_xxxxxxxx
cavemem recover ccr_xxxxxxxx > original.txt

recall returns JSON with the hits and a basis field. The two trailing numbers on the second recall are the result limit and the token budget. A budget of 0 means unlimited, and you have to write it out, because unbounded recall should be a decision rather than a default.

Run cavemem with no subcommand and it speaks MCP over stdio:

{ "mcpServers": { "cavemem": { "command": "cavemem" } } }

Four guarantees#

Byte safe on write. Raw text is stored first. Compression happens on the way out, never on the way in, so a compressor bug can never cost you the original.

Fails toward nothing. An off-topic query recalls nothing rather than returning the closest thing it found. A memory system that always answers is worse than one that admits it has nothing.

Bounded by default. Recall packs at most 2,000 inferred tokens unless you explicitly opt out.

Reversible. Every compressed hit carries a recovery handle, and cavemem recover returns the original bytes exactly.

Superseding rather than editing#

supersede writes a new version and links it to the old one. recall returns only current entries. history shows the chain from oldest to current.

Facts about a codebase go stale, and a store that silently overwrites gives you no way to notice when the thing you remembered stopped being true.

Clients#

Both clients shell text over stdin rather than passing it as an argument, so a large block does not hit an operating system argv limit.

import { remember, recall } from "cavemem";
await remember("the deploy key lives in vault under ops/deploy");
await recall("where is the deploy key", 5, 2000);

import cavemem
cavemem.remember("the deploy key lives in vault under ops/deploy")
cavemem.recall("where is the deploy key", limit=5, token_budget=2000)

Set CAVEMEM_BIN if the binary is not on PATH. An oversized remember exits with code 65.

One thing to know about handles#

cavemem keeps its own recovery store at ~/.caveman/mem/ccr.db, separate from the engine's store at ~/.caveman/ccr.db. Handles are not interchangeable between the two. A handle from a cavemem recall is recovered with cavemem recover, not with the engine.