Codeagent Memory README

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
• Key Features
• How It Works
• Agent Workflow
• CLI Reference
• Memory Rules
• Configuration
• Benchmarks
• Supported Agents
• Supported Languages
• Supported Platforms
• License

Guides: 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 --locked
cam --help

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 & query your project

cd your-project
cam index                                              # parse repo into .cam/cam.db

# Query the code graph
cam ls src/                                            # list files or symbols in a file
cam read src/main.rs/main                              # read a single symbol body
cam ref main --dir in                                  # 1-hop callers (in) or callees (out)

# Query & write to the memory tree
cam 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

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, add stores an English summary and body. --parent attaches it 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 in English.

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. Skips git submodules and linked worktrees; indexes nested standalone clones as kind: "project" (passable to --scope).

Memory Rules

• English-only indexing: Queries, summaries, and bodies must be written in English (non-Latin scripts are rejected so BM25 stemming and embeddings share one language space).
• 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).

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

5. Multi-Turn Token Savings — DeepSeek

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

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          # hash
python3 eval/longmemeval/run.py --sample 100 --seed 42 --workers 8 --potion

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   # requires DEEPSEEK_API_KEY
python3 eval/longmemcode/run.py --corpus clap
python3 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.3). See Get Started.

License

MIT