codeagent-memory

Contents

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

Guides: Interactive Showcase (Website) · Main Agent vs Subagent · MCP Configs by IDE · 中文说明

Why cam?

When an AI coding agent explores a repository, it usually rediscovers structure the slow way — running grep, glob, and full-file Read one file at a time — and forgets everything in the next session.

cam gives the agent two local retrieval planes in a single binary:

One binary, two interfaces: The main agent calls cam over MCP (cam mcp); subagents (which rarely inherit MCP tools) call the exact same CLI (cam --json …). Both share .cam/cam.db on disk, 100% local, zero API cost.

Get Started

Option 1: One-Sentence Agent Install (Recommended)

Paste this prompt directly into your coding agent (Cursor, Claude Code, Codex, Windsurf, GitHub Copilot, Cline, etc.) and let it install, index, and wire cam for you:

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.

Option 2: Manual Setup

1. Install the CLI

Requires a Rust toolchain:

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

git clone https://github.com/HanochZhu/codeagent_memory.gitcd codeagent_memorycargo install --path . --locked

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

2. Index & query your project

cd your-projectcam index                                              # parse repo into .cam/cam.db
# Query the code graphcam ls src/                                            # list files or symbols in a filecam read src/main.rs/main                              # read a single symbol bodycam ref main --dir in                                  # 1-hop callers (in) or callees (out)
# Query & write to the memory treecam recall "how does hybrid recall fuse BM25 and vectors"cam add --summary "..." < notes.md

_{cam auto-initializes .cam/ on first use. Run cam watch in the background if you want live incremental graph updates as files change.}

3. Connect MCP for the main agent

Add cam mcp to your host's MCP configuration (e.g. .cursor/mcp.json or .mcp.json):

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

See docs/mcp.md for host-specific config paths and docs/agents.md for main-agent / subagent prompt rules.

_{The first recall or add downloads the default embedding model (potion-multilingual-128M to ~/.cam/models/) and falls back to a lexical hash embedder if offline.}

Key Features

How It Works

[How cam works]

1. Extract — tree-sitter walks the workspace and stores symbol definitions and call edges in .cam/cam.db.
2. Surgical Read — Agents navigate via virtual paths (ls → find → read → ref). Reading a file returns its symbol outline; reading file/symbol returns only that symbol's source slice.
3. Hybrid Recall — recall takes an English query, embeds it locally, runs identifier-aware BM25 (splitting snake_case, kebab-case, camelCase + English stemming), prunes low-confidence tails, and fuses both lists with RRF ($k=60$) scaled by $0.9 + 0.1 \times R$. Superseded revisions are automatically expanded to their newest replacement.
4. Write-Back — When an agent solves a non-trivial task, it extracts atomic facts so each add stores only one fact (English summary; body supports non-Latin characters). Related facts are connected via --link / links into a knowledge graph (inspected via mem show; recall does not traverse graph links yet). --parent attaches a memory to a structural topic; --supersedes replaces an outdated memory while preserving lineage.

Architecture deep dive (Chinese): DESIGN.md.

Agent Workflow

Every coding task follows the same four-step loop:

1. Recall first — Query cam_recall / cam recall in English before grepping. Reuse a hit if it is latest and not needs_update.
2. Ensure indexed — If graph tools return not_indexed, run cam_index / cam index once for the project.
3. Walk the graph — On a memory miss, locate symbols with find or ls, read symbol bodies with read <file>/<symbol>, and trace callers/callees with ref <symbol> --dir in|out.
4. Write back — Persist newly discovered architecture facts or fixes with cam_add / cam add as atomic facts (one fact per memory, English summary; body supports non-Latin characters), linking related facts with links / --link.

Full agent rules & copy-paste system prompts: docs/agents.md.

CLI Reference

Code Graph Commands

Memory Commands

Server & Configuration Commands

Global flags & conventions:

• --project <dir> (or CAM_PROJECT env var) overrides automatic upward .cam / .git root detection.
• --json emits compact JSON (--pretty for indented JSON). Errors on --json print {"error":{"code":…,"message":…}} to stdout and exit non-zero.
• Ambiguous symbols: When read or ref matches multiple definitions, cam returns status: "ambiguous" with candidate node IDs (e.g. src/main.rs:function:main:12) that can be passed directly back to read or ref.
• Ignore rules & multi-repo directories: Honors .gitignore and .camignore at any depth. A nested directory with its own .git (standalone clone, submodule, or linked worktree) is indexed into that directory's .cam/cam.db. The parent database keeps a catalog of those graphs and queries fan out into them, so opening the nested directory reuses the graph. cam ls lists them as kind: "project" (passable to --scope).

Memory Rules

• Atomic facts & knowledge graph links: Store only one atomic fact per memory to avoid packing excessive information into a single entry. When multiple facts are related, link them with --link / links to form a knowledge graph (graph recall is not enabled yet).
• English queries and summaries: Recall queries and memory summaries must be written in English. Memory bodies support non-Latin characters.
• Retention & reinforcement: Ebbinghaus retention $R = e^{-t / S}$ adjusts recall score via $\text{relevance} \times (0.9 + 0.1 \times R)$. Entries with $R < 0.3$ are marked needs_update; entries older than stale_days (default 30) are marked stale. Every valid recall hit (needs_update = false) refreshes last-accessed time and multiplies stability $S$ by 1.7.
• Non-destructive lineage: Memories are never deleted. --parent forms branching trees; --supersedes forms linear revision chains where only the tail is marked latest and older revisions are folded out of default recall results.

Configuration

Global settings live in ~/.cam/config.toml:

stale_days = 30# embedding_model = "minishlab/potion-multilingual-128M" # default (cached under ~/.cam/models/)# embedding_model = "minishlab/potion-base-8M"           # lighter Hugging Face model2vec repo# embedding_model = "/path/to/local/model2vec"           # dir with tokenizer.json, config.json, model.safetensors# embedding_model = "hash"                               # zero-download lexical hash embedder

Use CAM_EMBED_MODEL to override the model for a single process, or cam config set embedding_model default to reset. When the embedding model changes, the next recall automatically re-embeds existing memories before scoring.

Benchmarks

cam evaluates its code graph and memory planes separately against the closest open-source systems on identical corpora:

_{General chat memory frameworks (Mem0, Zep, Letta) target conversational logs rather than these coding-agent corpora and are omitted from the tables below.}

System Comparison

1. Memory — coding-agent-life-v1

15 sessions, 15 queries, $k=5$ (same scoring as agentmemory score.ts; P@5 ceiling is 0.240).

[coding-agent-life headline R@5 and P@5 / ceiling]

[coding-agent-life R@5 by question type]

Revision chains (--lineage): Re-ingesting every turn as a --supersedes revision tests whether top-$k$ returns the newest node of each gold chain (newest R@k) and whether any superseded node falsely claims latest (stale latest).

2. Long-Term Memory — LongMemEval-S

100 non-abstention questions sampled with seed 42 from cleaned LongMemEval-S. Retrieval fuses embeddings + BM25 with RRF at $k=10$ without an LLM reader.

3. Workflow Retrieval — Agent Retrieval Bench V2 (edit2ripple)

58 anchored-change queries across 44 frozen repository snapshots (no LLM; BCY = Budgeted Context Yield under the canonical 8K-token file-packing protocol).

cam graph achieves the highest first-hit rank (MRR 0.297, query P95 7.3 ms), while lexical search provides broader multi-file coverage — motivating graph + lexical rank fusion.

4. Code Graph — LongMemCode (clap)

clap v4.6.1, 536 scenarios against SCIP gold (no LLM, P95 ≈ 5.2 ms, $/1k = 0).

[LongMemCode clap accuracy bars]

[LongMemCode clap accuracy by operation]

5. Multi-Turn Token Savings — DeepSeek

Full context dump vs. per-turn cam retrieval (deepseek-flash, hash embedder, 2026-10-13):

[DeepSeek multi-turn prompt token bars]

[DeepSeek multi-turn prompt tokens]

6. Memory writing — who decides what one memory is

The notes are a separate case set, cam-write-memory-eval. This repo keeps the runner. The first eval/write_memory/run.py downloads cases.json to eval/write_memory/data/ (override with CAM_EVAL_WRITE_MEMORY). That is the same split as LongMemEval and LoCoMo: the corpus stays outside, and the script here fetches it when you run the benchmark.

A model receives one note and calls cam_add. legacy asks for one full write-up. split asks for one fact, or one problem's solution path, and links pieces from the same solution with #0. A fact counts as exclusive when one stored memory contains every required phrase and no other gold fact. The notes are public behavior of this repository: recall fusion, the stale-binary restart notice, retention, and read versus delete. Labels and source files are in the case-set README.

python3 eval/coding_life/run.py --adapter greppython3 eval/coding_life/run.py                                             # potion; errors if the model failspython3 eval/coding_life/run.py --hash-embed                                # hash embedderpython3 eval/longmemeval/run.py --sample 100 --seed 42 --workers 8          # potionpython3 eval/longmemeval/run.py --sample 100 --seed 42 --workers 8 --hash-embedpython3 eval/locomo/run.py --workers 4                                      # potion, evidence recall
git clone --depth 1 https://github.com/eyuansu62/agent-retrieval-bench \  eval/agent_retrieval/vendor/agent-retrieval-benchpython3 -m pip install -e eval/agent_retrieval/vendor/agent-retrieval-bencharb download-benchmark --version v2_edit2ripple --local-dir eval/agent_retrieval/data --forcepython3 eval/agent_retrieval/run.py --workers 8
python3 eval/llm_multiturn/run.py --track both   # potion; requires DEEPSEEK_API_KEYpython3 eval/write_memory/test_score.py          # downloads the case set; no model callpython3 eval/write_memory/run.py                 # downloads the case set; DEEPSEEK_API_KEYpython3 eval/longmemcode/run.py --corpus clappython3 eval/charts/generate.py

Supported Agents

Register cam mcp (stdio) for the main agent; subagents use the cam --json CLI directly with zero extra setup.

Copy-paste configs: docs/mcp.md · System prompts: docs/agents.md.

Supported Languages

Supported Platforms

cam compiles natively on macOS, Linux, and Windows via cargo install --git https://github.com/HanochZhu/codeagent_memory --locked, or runs anywhere via Docker (ghcr.io/hanochzhu/codeagent-memory:0.1.6). See Get Started.

License

MIT