cam
Provides a local memory and code-graph backend for Windsurf, Codeium's AI IDE, enabling recall of project facts and symbol-level code navigation.
Provides a local memory and code-graph backend for GitHub Copilot, enabling recall of past project context and symbol-level code navigation.
Provides a local memory and code-graph backend for GoLand through JetBrains AI Assistant, enabling recall of project facts and symbol-level code navigation.
Provides a local memory and code-graph backend for JetBrains IDEs via AI Assistant, enabling recall of project facts and symbol-level code navigation.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
cam
English · 中文 · 日本語 · 한국어 · العربية · 🌐 Website
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
Guides: Interactive Showcase (Website) · Main Agent vs Subagent · MCP Configs by IDE · 中文说明
Related MCP server: koragraph
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:
Plane | What it stores | How the agent uses it |
Code Graph | Tree-sitter symbols (functions, types, methods) as a virtual filesystem + 1-hop callers/callees |
|
Memory Tree | Project facts, architecture decisions, debugging write-ups, and user habits |
|
One binary, two interfaces: The main agent calls
camover MCP (cam mcp); subagents (which rarely inherit MCP tools) call the exact same CLI (cam --json …). Both share.cam/cam.dbon 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.Environment | What to do |
Cursor / Windsurf / Claude Code / Codex | Paste into Agent / Chat; the agent runs the terminal install, builds |
VS Code (Copilot / Continue / Cline) | Paste into Agent / Chat mode with terminal access enabled |
JetBrains (IntelliJ / RustRover / GoLand) | Paste into AI Assistant, or run |
Note: cargo install places cam in ~/.cargo/bin (Windows: %USERPROFILE%\.cargo\bin). Restart your terminal or IDE if cam is not immediately found on PATH.
Option 2: Manual Setup
1. Install the CLI
Requires a Rust toolchain:
cargo install --git https://github.com/HanochZhu/codeagent_memory --locked
cam --helpFrom a local clone:
git clone https://github.com/HanochZhu/codeagent_memory.git
cd codeagent_memory
cargo install --path . --lockedDocker (no Rust toolchain required):
docker pull ghcr.io/hanochzhu/codeagent-memory:0.1.7
docker run -i --rm -v "$PWD:/work" -w /work ghcr.io/hanochzhu/codeagent-memory:0.1.7Or build locally: docker build -t cam https://github.com/HanochZhu/codeagent_memory.git
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.mdcam auto-initializes .cam/ on first use. cam mcp incrementally watches that project. A nested checkout with its own MCP is skipped; otherwise the parent writes the checkout's .cam/cam.db. cam watch uses the same lock.
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
Feature | Details |
SQLite Code Graph | Tree-sitter parses functions, types, and call edges into |
Virtual Paths |
|
Live Incremental Sync |
|
Hybrid Recall (RRF) | Combines local dense embeddings ( |
Revision Chains & Tree |
|
Ebbinghaus Retention | Retention $R = e^{-t / S}$ gently weights ranking ($\le 10%$) and flags |
Dual Interface (MCP + CLI) | Main agent uses |
100% Local & Private | Zero external API keys; runs entirely on local SQLite and on-disk embeddings |
9 Languages | Rust, Python, TypeScript, JavaScript, Go, Java, C, C++, C# |
How It Works
Extract —
tree-sitterwalks the workspace and stores symbol definitions and call edges in.cam/cam.db.Surgical Read — Agents navigate via virtual paths (
ls→find→read→ref). Reading a file returns its symbol outline; readingfile/symbolreturns only that symbol's source slice.Hybrid Recall —
recalltakes an English query, embeds it locally, runs identifier-aware BM25 (splittingsnake_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.Write-Back — When an agent solves a non-trivial task, it extracts atomic facts so each
addstores only one fact (English summary; body supports non-Latin characters). Related facts are connected via--link/linksinto a knowledge graph (inspected viamem show; recall appends one-hop linked memories as supplemental context).--parentattaches a memory to a structural topic;--supersedesreplaces an outdated memory while preserving lineage.
Architecture deep dive (Chinese): DESIGN.md.
Agent Workflow
Every coding task follows the same four-step loop:
Recall first — Query
cam_recall/cam recallin English before grepping. Reuse a hit if it islatestand notneeds_update.Ensure indexed — If graph tools return
not_indexed, runcam_index/cam indexonce for the project.Walk the graph — On a memory miss, locate symbols with
findorls, read symbol bodies withread <file>/<symbol>, and trace callers/callees withref <symbol> --dir in|out.Write back — Persist newly discovered architecture facts or fixes with
cam_add/cam addas atomic facts (one fact per memory, English summary; body supports non-Latin characters), linking related facts withlinks/--link.
Role | Interface | Typical Usage |
Main Agent (Chat / IDE session) | MCP ( | Calls |
Subagent (Task / explore / CLI) | CLI ( | Runs |
Full agent rules & copy-paste system prompts: docs/agents.md.
CLI Reference
Code Graph Commands
Command | Description |
| Build |
| Incrementally update the graph for modified files using content hashes |
| Watch source files and auto-sync ( |
| List directories, files, or symbols inside a file |
| Read a file's symbol outline, a specific symbol body ( |
| Case-insensitive substring search over symbol names (exact matches first, then prefixes) |
| 1-hop callers ( |
Memory Commands
Command | Description |
| Hybrid RRF recall (English query). |
| Store one atomic fact as a memory (English summary required; body supports non-Latin characters; via |
| Render the memory hierarchy and revision chains |
| Inspect a single memory entry in full |
Server & Configuration Commands
Command | Description |
| Start the stdio MCP server and incrementally watch its project (see docs/mcp.md) |
| Show resolved project root, database path, node/edge/memory counts, and active config |
| Print current |
| Set age threshold (in days) for marking memories |
| Set Hugging Face model2vec repo, local model directory, |
Global flags & conventions:
--project <dir>(orCAM_PROJECTenv var) overrides automatic upward.cam/.gitroot detection.--jsonemits compact JSON (--prettyfor indented JSON). Errors on--jsonprint{"error":{"code":…,"message":…}}tostdoutand exit non-zero.Ambiguous symbols: When
readorrefmatches multiple definitions,camreturnsstatus: "ambiguous"with candidate node IDs (e.g.src/main.rs:function:main:12) that can be passed directly back toreadorref.Ignore rules & multi-repo directories: Honors
.gitignoreand.camignoreat 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 lslists them askind: "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/linksto form a knowledge graph (one-hop linked memories are appended as supplemental context).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 thanstale_days(default30) are markedstale. Every valid recall hit (needs_update = false) refreshes last-accessed time and multiplies stability $S$ by1.7.Non-destructive lineage: Memories are never deleted.
--parentforms branching trees;--supersedesforms linear revision chains where only the tail is markedlatestand 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 embedderUse 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:
Plane | Baseline / Analogue | Benchmark Corpus | Headline Takeaway |
Memory | agentmemory hybrid + tokenized | 1.000 R@5 / 0.240 P@5 (matches hybrid ceiling, 1.000 newest R@5 on revision chains) | |
Long-term Memory | BM25 / dense retrievers | 0.909 R@5 / 0.980 Hit@5 / 0.840 MRR with | |
Code Graph | codegraph v0.9.6 | LongMemCode ( | 0.769 vs 0.768 on supported 1-hop tasks, P95 ≈ 5.2 ms, |
Workflow Retrieval | Lexical / BM25 file retrieval | Agent Retrieval Bench V2 | 0.297 MRR (best first-hit rank, P95 7.3 ms) |
Multi-turn Tokens | Full context dump | 57% fewer tokens on memory track, 98% fewer tokens on code track |
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
cam | agentmemory | codegraph | |
What it stores | Code graph + memory tree | Session / chat memories | Code graph |
Query primitives |
|
|
|
Interface | MCP + CLI | MCP + REST + hooks | MCP + CLI |
Ranking / Fusion | Vector + BM25 + RRF + retention | BM25 + embed + rerank | FTS5 + graph walk |
Cost | 100% local ( | Local server | Local |
1. Memory — coding-agent-life-v1
15 sessions, 15 queries, $k=5$ (same scoring as agentmemory score.ts; P@5 ceiling is 0.240).
System | Hit Rate | R@5 | P@5 | Source |
| 15 / 15 | 0.967 | 0.227 | this repo, 2026-09-23 |
| 15 / 15 | 0.933 | 0.213 | historical, hash embed |
| 15 / 15 | 1.000 | 0.240 | this repo, hash embed |
| 15 / 15 | 1.000 | 0.240 | published v0.9.26 |
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).
k | R@k | P@k | newest R@k | stale |
5 | 1.000 | 0.240 | 1.000 | 0 |
10 | 1.000 | 0.120 | 1.000 | 0 |
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.
Embedder | R@1 | R@5 | R@10 | Hit@1 | Hit@5 | Hit@10 | MRR | Retrieval P50 / P95 |
| 0.382 | 0.803 | 0.922 | 0.580 | 0.910 | 0.970 | 0.718 | 24.1 / 35.5 ms |
| 0.474 | 0.909 | 0.952 | 0.740 | 0.980 | 0.990 | 0.840 | 1.12 / 1.34 s |
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).
System | Recall@5 | Recall@10 | Recall@20 | MRR | BCY@8k |
| 0.300 | 0.335 | 0.378 | 0.297 | 0.300 |
Lexical | 0.412 | 0.536 | 0.588 | 0.243 | 0.447 |
BM25 | 0.207 | 0.287 | 0.499 | 0.154 | 0.243 |
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).
Slice | n |
|
|
Supported (1-hop) | 478 | 0.769 | 0.768 |
| 293 / 55 | 0.808 / 0.915 | 0.808 / 0.915 |
| 67 / 18 | 0.397 / 0.811 | 0.355 / 0.867 |
| 40 | 0.119 | 0.094 |
Raw / Weighted (all 536) | 536 | 0.709 / 0.704 | 0.704 / 0.700 |
5. Multi-Turn Token Savings — DeepSeek
Full context dump vs. per-turn cam retrieval (deepseek-flash, hash embedder, 2026-10-13):
Track | n | Full Acc. |
| Full Tokens |
| Token Saving |
Memory ( | 15 | 1.00 | 0.87 | 22,796 | 9,904 | 57% (1,471 → 616 / turn) |
Code (this repo indexed) | 6 | 0.83 | 0.33 | 379,066 | 6,342 | 98% (63,076 → 1,000 / turn) |
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.
Dataset paths are configured in eval/datasets.toml (coding-agent-life-v1 defaults to ../agentmemory or CAM_EVAL_CODING_LIFE).
python3 eval/coding_life/run.py --adapter grep
python3 eval/coding_life/run.py # potion; errors if the model fails
python3 eval/coding_life/run.py --hash-embed # hash embedder
python3 eval/longmemeval/run.py --sample 100 --seed 42 --workers 8 # potion
python3 eval/longmemeval/run.py --sample 100 --seed 42 --workers 8 --hash-embed
python3 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-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 # potion; requires DEEPSEEK_API_KEY
python3 eval/write_memory/test_score.py # downloads the case set; no model call
python3 eval/write_memory/run.py # downloads the case set; DEEPSEEK_API_KEY
python3 eval/longmemcode/run.py --corpus clap
python3 eval/charts/generate.pySupported Agents
Register cam mcp (stdio) for the main agent; subagents use the cam --json CLI directly with zero extra setup.
Host | MCP Configuration | Subagent / Notes |
Cursor |
|
|
Claude Code |
| Limited-tool subagents use CLI |
Codex |
|
|
Windsurf |
| Cascade uses MCP |
GitHub Copilot |
| Chat uses MCP; CLI scripts use CLI |
Continue / Cline |
| |
JetBrains | AI Assistant → MCP ( | Use absolute path to |
Gemini CLI / Antigravity / OpenCode / Zed / Droid | See docs/mcp.md |
Copy-paste configs: docs/mcp.md · System prompts: docs/agents.md.
Supported Languages
Language | Extensions | Indexed Nodes & Edges |
Rust |
| functions, structs, enums, traits, calls |
Python |
| functions, classes, calls |
TypeScript |
| functions, methods, classes, calls |
JavaScript |
| functions, methods, classes, calls |
Go |
| functions, methods, structs, calls |
Java |
| functions, methods, classes, interfaces, calls |
C |
| functions, structs, calls |
C++ |
| functions, methods, classes, structs, calls |
C# |
| functions, methods, classes, interfaces, calls |
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.7). See Get Started.
License
MIT
Made for AI coding agents — Claude Code, Cursor, Codex, Windsurf, Copilot, and JetBrains
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Shared memory for coding agents. Stop re-explaining your codebase every session.
Persistent memory, knowledge graph, task management and more for AI agents via MCP.
Persistent engineering memory designed to follow developers across coding agents.
Team memory for AI coding agents and code reviews, reviewed by humans and served over MCP.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceGives coding agents a local, SQLite-backed memory of a codebase, enabling them to query symbol impact, change history, and task scope through MCP while recording what actually changed after edits.MIT
- AlicenseNot gradedqualityBmaintenanceEnables coding agents to query a local, multi-repo code graph for symbol exploration, blast radius analysis, co-change mining, and durable code-anchored memory via MCP tools.271 npm16Business Source 1.1
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to retrieve hyper-targeted, token-efficient context from a codebase by querying a locally built AST knowledge graph, and to persist cross-session agent memory through 17 MCP tools. All indexing and retrieval run entirely offline, so proprietary code never leaves the machine.85 PyPI1MIT
- AlicenseNot gradedqualityBmaintenanceProvides coding agents with persistent, queryable repository memory over MCP, enabling code search, cited question answering, repo maps, decision logs, and cross-session notes through local-first tools.MIT