codeagent-memory

cam

English · 中文

A local multi-turn conversational memory system purpose-built for coding agents

Code graph + memory · surgical reads · 100% local · MCP + CLI

Kernel written in Rust

Contents

• Why cam?
• Get Started
• Benchmarks
• Key Features
• How It Works
• Agent Workflow
• CLI Reference
• Memory Rules
• Configuration
• Supported Platforms
• Supported Agents
• Supported Languages
• License

Usage details: main agent vs subagent · MCP configs for each IDE · 中文说明

Why cam?

When an AI agent needs to understand code — or reuse what it already learned about this project — it discovers structure the slow way: grep, glob, and Read, one file at a time. Next session it does the same work again.

cam hands the agent two things it can query in one shell call:

1. A code graph — every indexed file and symbol as a virtual filesystem, plus one-hop callers / callees.
2. A memory tree — habits, project facts, designs, write-ups; recalled with vector + BM25 so the agent does not re-learn the same project.

Surgical reads, not a file-by-file search. Memories stay on disk, 100% local.

One binary, two doors: the main agent uses MCP (cam mcp); subagents usually have no MCP, so they run the same CLI. Configs: docs/mcp.md. Usage: docs/agents.md.

Get Started

1. Install the CLI

Need Rust first? Install it from rustup.rs, then:

cargo install --git https://github.com/HanochZhu/codeagent_memory --locked
cam --help

Install cam from https://github.com/HanochZhu/codeagent_memory: require a working Rust toolchain (rustup), run `cargo install --git https://github.com/HanochZhu/codeagent_memory --locked`, ensure ~/.cargo/bin (or %USERPROFILE%\.cargo\bin on Windows) is on PATH, then verify with `cam --help`. In this repo run `cam index`. For the main agent, register MCP stdio: command `cam`, args `["mcp"]` (Cursor: .cursor/mcp.json; Claude Code: .mcp.json). Subagents call `cam --json` in the shell. Do not add extra docs.

git clone https://github.com/HanochZhu/codeagent_memory.git
cd codeagent_memory
cargo install --path . --locked

docker pull ghcr.io/hanochzhu/codeagent-memory:0.1.3
docker run -i --rm -v "$PWD:/work" -w /work ghcr.io/hanochzhu/codeagent-memory:0.1.3

2. Index the project

cd your-project
cam index

_{cam index creates .cam/ if needed and parses the tree with tree-sitter into .cam/cam.db. Other commands do the same: they auto-init on first use. Leave cam watch running if you want the graph to follow later edits.}

3. Ask the graph, then remember the answer

cam ls src/
cam read src/main.rs/main
cam ref main --dir in
cam recall "how does hybrid recall fuse BM25 and vectors"
cam add --summary "..." < notes.md

Main agent (the chat session): wire cam mcp once, then call cam_* tools. Subagent (Task / explore / delegated CLI): run the same commands in the shell. Output is compact by default; pass --json when you need structured results.

{ "mcpServers": { "cam": { "command": "cam", "args": ["mcp"] } } }

Paste that into Cursor .cursor/mcp.json, Claude Code .mcp.json, or the host's MCP settings. Per-tool files: docs/mcp.md. Who should call MCP vs CLI: docs/agents.md.

The first recall / add downloads potion-multilingual-128M. If that default model is unavailable, cam falls back to a hash embedder. Set another model2vec model with cam config set embedding_model <repo-or-path> (see Configuration).

Benchmarks

cam has two retrieval planes. Each is scored against the closest open system on the same corpus. Do not fold them into one number.

Mem0, Zep, and Letta are general chat memories. They are not on these two corpora, so they are not in the score tables.

How the systems differ

Memory — coding-agent-life-v1

15 sessions, 15 queries, k=5. Same formula as agentmemory score.ts. P@5 ceiling is 0.240.

RRF matches the published hybrid ceiling and beats grep on temporal (q-015). Min-max sum still drops the second gold on temporal and multi-session-causal (q-011).

Revision chains

The corpus above is flat: one memory per session, no --supersedes. --lineage re-ingests every conversation turn as a revision that supersedes the previous one and adds two metrics. newest R@k asks whether the top-k carried the newest node of each gold chain; stale latest counts returned hits that claimed latest while a newer revision existed.

Hash embedder, 2026-09-29. Separating structural hierarchy from revision replacement and collapsing older revisions before top-k raised newest R@5 from 0.567 to 1.000 and newest R@10 from 0.800 to 1.000, while stale latest stayed at zero.

Long-term memory — LongMemEval-S

Cleaned LongMemEval-S, 100 non-abstention questions sampled with seed 42. Each raw dated session is stored as one memory; retrieval uses hash embeddings + RRF at k=10, without an LLM reader.

MRR = Mean Reciprocal Rank. Under the 8-worker run, retrieval P50 / P95 was 1.28 / 2.18 s and mean per-question ingestion was 69.6 s. This is a retrieval-only result: it measures whether gold sessions are returned, not final answer quality. The run also exposed repeated tokenizer initialization during cam add as the dominant ingestion cost.

Workflow retrieval — Agent Retrieval Bench V2

edit2ripple: 58 anchored-change queries over 44 frozen repository snapshots, no LLM. The cam adapter ranks files connected to symbols in the anchored file. All 58 questions are scored; 55 anchor files use supported languages and three Java anchors remain misses.

BCY = Budgeted Context Yield, using the benchmark's canonical 8K-token file-packing protocol. cam graph has the best first-hit rank, while lexical retrieval has much better broad gold coverage; this points to rank fusion rather than graph-only retrieval. cam query P95 was 11.6 ms; indexing the 44 snapshots took 327.6 s with 8 workers.

Code graph — LongMemCode clap

clap v4.6.1, 536 scenarios, no LLM. cam one-hop vs codegraph on the same SCIP gold.

P95 ≈ 6.5 ms, $/1k = 0.

Multi-turn tokens — DeepSeek

Same conversation twice: dump every session / every src/*.rs file, or inject cam recall (plus read / ref on code) for the current turn only. Hash embedder, 2026-09-15.

Mean prompt tokens / turn: memory 1521 → 838; code 28250 → 1004. Code misses were retrieval gaps (callers of the fusion helper, INITIAL_STABILITY_DAYS, the cam add update rule), not the model ignoring snippets.

Corpus locations for every script below live in one file, eval/datasets.toml. coding-agent-life-v1 is not redistributed here and defaults to an agentmemory checkout next to this repository; point the entry elsewhere, or override a single run with CAM_EVAL_CODING_LIFE.

python3 eval/coding_life/run.py --adapter grep
python3 eval/coding_life/run.py --hash-embed              # RRF
python3 eval/longmemeval/run.py --sample 100 --seed 42 --workers 8
git clone --depth 1 https://github.com/eyuansu62/agent-retrieval-bench \
  eval/agent_retrieval/vendor/agent-retrieval-bench
python3 -m pip install -e eval/agent_retrieval/vendor/agent-retrieval-bench
arb download-benchmark --version v2_edit2ripple \
  --local-dir eval/agent_retrieval/data --force
python3 eval/agent_retrieval/run.py --workers 8
python3 eval/llm_multiturn/run.py --track both   # needs DEEPSEEK_API_KEY
python3 eval/longmemcode/run.py --corpus clap
python3 eval/charts/generate.py

Key Features

How It Works

1. Extraction — tree-sitter walks the project and stores nodes (functions, types) and edges (calls) in SQLite.
2. Surgical read — ls / read / ref walk a virtual filesystem. read returns an outline or a symbol slice; --full is the whole file.
3. Recall — recall requires an English query, embeds it, runs English-normalized BM25, drops entries far below each path's best, and fuses the two ranked lists with RRF (k=60). The result is scaled by 0.9 + 0.1 × R. The newest replacement of each top match is pulled in and older revisions are folded before top-k.
4. Write-back — after the agent learns something worth keeping, add stores an English summary + body. --parent adds hierarchy; --supersedes replaces an older revision while preserving it for history.

Design notes (Chinese): DESIGN.md.

Agent Workflow

recall first. If nothing hits, walk the code graph. After you learn something worth keeping, add.

Main agent (MCP): cam_recall → cam_find / cam_ls / cam_read / cam_ref → cam_add. Do not shell out unless MCP is down. Full text: docs/agents.md.

Subagent (CLI):

cam --json index
cam --json sync
cam --json watch
cam --json ls src/
cam --json read src/memory/recall.rs/fuse_rrf
cam --json ref fuse_rrf --dir in
cam --json recall "how to fuse BM25 and vector recall"
cam --json add --summary "..." --body "..."
cam --json mem tree
cam --json mem show <id>
cam --json status
cam mcp

Global flags: --project <dir>, --json (compact JSON), --pretty (pretty JSON, implies --json). Without --project, resolution is CAM_PROJECT, then walk up for .cam / .git. With --json, failures print {"error":{"code":…,"message":…}} to stdout and exit non-zero. Start the MCP server with cam mcp (optional --project).

CLI Reference

cam index                                # Parse the project with tree-sitter into SQLite
cam sync                                 # Incrementally update the graph for changed files
cam watch [--debounce-ms N]              # Watch source files; --json streams one report per sync
cam ls [virt_path]                       # List directories / files / symbols
cam read <virt_path> [--full]            # File outline or symbol body
cam ref <symbol> --dir in|out [--file SUBSTR] [--kind KIND] [--scope DIR]  # One-hop callers (in) or callees (out); --callers / --callees aliases
cam find <query> [--kind KIND] [--file SUBSTR] [--scope DIR] [--limit N]   # Symbols whose name contains <query>
cam recall "<query>" [--limit N] [--no-expand] [--include-superseded] [--snippets]  # Hybrid recall: vector + BM25 fused with RRF
cam add --summary "..." [--parent ID] [--supersedes ID] [--body TEXT | --file PATH]  # Store a memory (body: --body, --file, or stdin)
cam mem tree                             # Print the memory tree
cam mem show <id>                        # Show one memory
cam status                               # Resolved project, database counts, and config
cam config get | config set stale_days N | config set embedding_model <model> # Read or update ~/.cam/config.toml
cam mcp                                  # MCP stdio server for the main agent

Virtual paths: src/main.rs is a file; src/main.rs/main is a symbol in that file. Node ids (src/main.rs:function:main:12) from an ambiguous answer are accepted wherever a symbol is.

Multi-repo folders. .gitignore and .camignore (same syntax) are honored at any depth, even when the root itself is not a git repo. Submodules and linked worktrees (directories whose .git is a file) are skipped; nested standalone clones are indexed, and cam ls lists them with kind project so you can pass that path as --scope.

Memory Rules

• Entries older than stale_days in ~/.cam/config.toml (default 30) are marked stale
• Ebbinghaus retention R = exp(-t / S): the sort score is relevance × (0.9 + 0.1 × R); R < 0.3 is marked needs_update
• A successful returned match (needs_update = false) refreshes C0 and multiplies S by 1.7. Expanded revisions and filtered older revisions are not refreshed
• Memories are never deleted. The newest node of each linear supersedes chain is latest; older revisions are hidden by default and available with --include-superseded
• Use --parent for branching hierarchy and --supersedes for a complete replacement revision
• Recall queries and stored memory summaries/bodies must be in English. Inputs containing non-Latin scripts are rejected
• BM25 splits snake_case, kebab-case, and camelCase identifiers and indexes both surface and English-stemmed terms

Configuration

~/.cam/config.toml:

stale_days = 30
# embedding_model = "minishlab/potion-base-8M"  # Hugging Face model2vec repo
# embedding_model = "/path/to/model2vec"         # local tokenizer.json + config.json + model.safetensors
# embedding_model = "hash"                       # no download; lexical hash only

embedding_model defaults to minishlab/potion-multilingual-128M. default clears a custom value. CAM_EMBED_MODEL overrides the file for one process. The first recall after a model change re-embeds stored memories with the new model before scoring, so vector recall keeps working. Downloaded models are cached under ~/.cam/models/.

Supported Platforms

cam is a Rust binary. cargo install builds it for the machine you are on:

See Get Started for the full command.

Supported Agents

Main agent: register cam mcp (stdio). Subagent: same CLI, no extra wiring.

Paste the one-sentence install into the agent, then add the MCP block. Copy-paste files: docs/mcp.md. Agent prompts: docs/agents.md.

The Cursor plugin (.cursor-plugin/plugin.json) registers the same cam mcp server and a skill. Install the cam binary first and keep it on PATH; the plugin does not ship the binary.

Supported Languages

License

MIT