---
title: "Memory: Overview"
summary: cavemem holds the context you would otherwise paste into every session.
canonical: https://docs.caveman.so/docs/memory
layer: memory
license: MIT
capability: mem
updated: 2026-08-26T03:57:26+02:00
basis: inferred
---

# Memory: Overview

> cavemem holds the context you would otherwise paste into every session.
<DocSchema slug="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

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

## Use it

```bash
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:

```json
{ "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.

```js
await remember("the deploy key lives in vault under ops/deploy");
await recall("where is the deploy key", 5, 2000);
```

```python
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.

<Note tone="warning" title="Registry status">
The npm client `cavemem` is published but currently behind the source in this repository, and its
registry description describes older behaviour. There is no PyPI package yet. Until both catch up, build
the core from source and use the Python client from the repository.
</Note>

## 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.