Skip to main content
Glama

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

Website License: MIT Rust Install

Windows macOS Linux

Claude Code Cursor Codex Windsurf GitHub Copilot Continue Cline JetBrains

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

ls, find, read src/file.rs/symbol, ref symbol --dir in|out — surgical symbol reads instead of whole-file dumps

Memory Tree

Project facts, architecture decisions, debugging write-ups, and user habits

recall (Vector + BM25 fused with RRF) and add (with branching --parent and revision --supersedes)

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

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 .cam/cam.db, and writes the MCP config

VS Code (Copilot / Continue / Cline)

Paste into Agent / Chat mode with terminal access enabled

JetBrains (IntelliJ / RustRover / GoLand)

Paste into AI Assistant, or run cargo install in the built-in terminal

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 --help

From a local clone:

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

Docker (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.7

Or 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.md

cam 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 .cam/cam.db for instant symbol-level navigation

Virtual Paths

src/main.rs addresses a file outline; src/main.rs/main addresses the symbol body directly

Live Incremental Sync

cam mcp and cam watch share .cam/incremental.lock and hash file contents on save. A nested checkout with its own MCP is skipped; otherwise the parent writes that checkout's .cam/cam.db

Hybrid Recall (RRF)

Combines local dense embeddings (model2vec) + identifier-aware BM25 via Reciprocal Rank Fusion ($k=60$)

Revision Chains & Tree

--parent builds branching topic hierarchies; --supersedes links linear revisions and folds older entries automatically

Ebbinghaus Retention

Retention $R = e^{-t / S}$ gently weights ranking ($\le 10%$) and flags stale / needs_update memories without deleting history

Dual Interface (MCP + CLI)

Main agent uses cam_* MCP tools; subagents run cam --json … in the shell

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

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 appends one-hop linked memories as supplemental context). --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.

Role

Interface

Typical Usage

Main Agent (Chat / IDE session)

MCP (cam mcp)

Calls cam_recall, cam_find, cam_ls, cam_read, cam_ref, cam_add, cam_mem_tree, cam_mem_show directly

Subagent (Task / explore / CLI)

CLI (cam --json)

Runs cam --json --project <dir> <cmd> in the shell (subagents rarely inherit MCP tools)

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


CLI Reference

Code Graph Commands

Command

Description

cam index

Build .cam/cam.db on the first run, then apply only the incremental diff; add --force to rebuild every file

cam sync

Incrementally update the graph for modified files using content hashes

cam watch [--debounce-ms N]

Watch source files and auto-sync (--json streams one JSON report per sync)

cam ls [virt_path]

List directories, files, or symbols inside a file

cam read <virt_path> [--full]

Read a file's symbol outline, a specific symbol body (path/symbol), or the --full file

cam find <query> [--kind K] [--file S] [--scope D] [--limit N]

Case-insensitive substring search over symbol names (exact matches first, then prefixes)

cam ref <symbol> --dir in|out [--file S] [--kind K] [--scope D]

1-hop callers (in / --callers) or callees (out / --callees). Returns ranked candidates on ambiguous names

Memory Commands

Command

Description

cam recall "<query>" [--limit N] [--no-expand] [--include-superseded] [--snippets]

Hybrid RRF recall (English query). --no-expand skips newest-revision expansion; --include-superseded keeps old revisions; --snippets clips long bodies below rank 1

cam add --summary "..." [--parent ID] [--supersedes ID] [--link ID]... [--body TEXT | --file PATH]

Store one atomic fact as a memory (English summary required; body supports non-Latin characters; via --body, --file, or stdin). --link connects related facts in the knowledge graph; --parent for topic hierarchy; --supersedes to replace an older memory

cam mem tree

Render the memory hierarchy and revision chains

cam mem show <id>

Inspect a single memory entry in full

Server & Configuration Commands

Command

Description

cam mcp

Start the stdio MCP server and incrementally watch its project (see docs/mcp.md)

cam status

Show resolved project root, database path, node/edge/memory counts, and active config

cam config get

Print current ~/.cam/config.toml settings

cam config set stale_days <N>

Set age threshold (in days) for marking memories stale

cam config set embedding_model <model>

Set Hugging Face model2vec repo, local model directory, hash, or default

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 (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 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:

Plane

Baseline / Analogue

Benchmark Corpus

Headline Takeaway

Memory

agentmemory hybrid + tokenized grep

coding-agent-life-v1

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

LongMemEval-S

0.909 R@5 / 0.980 Hit@5 / 0.840 MRR with potion-multilingual-128M

Code Graph

codegraph v0.9.6

LongMemCode (clap)

0.769 vs 0.768 on supported 1-hop tasks, P95 ≈ 5.2 ms, $0

Workflow Retrieval

Lexical / BM25 file retrieval

Agent Retrieval Bench V2 edit2ripple

0.297 MRR (best first-hit rank, P95 7.3 ms)

Multi-turn Tokens

Full context dump

DeepSeek multi-turn

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

recall / ls / find / read / ref

smart-search / remember

explore / callers / callees

Interface

MCP + CLI

MCP + REST + hooks

MCP + CLI

Ranking / Fusion

Vector + BM25 + RRF + retention

BM25 + embed + rerank

FTS5 + graph walk

Cost

100% local ($0)

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

grep (tokenized substring)

15 / 15

0.967

0.227

this repo, 2026-09-23

cam min-max sum (legacy)

15 / 15

0.933

0.213

historical, hash embed

cam RRF

15 / 15

1.000

0.240

this repo, hash embed

agentmemory hybrid

15 / 15

1.000

0.240

published v0.9.26

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

k

R@k

P@k

newest R@k

stale latest

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

hash (offline test)

0.382

0.803

0.922

0.580

0.910

0.970

0.718

24.1 / 35.5 ms

potion-multilingual-128M

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

cam graph

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

cam

codegraph 0.9.6

Supported (1-hop)

478

0.769

0.768

lookup / file_symbols

293 / 55

0.808 / 0.915

0.808 / 0.915

callers / callees

67 / 18

0.397 / 0.811

0.355 / 0.867

implementors

40

0.119

0.094

Raw / Weighted (all 536)

536

0.709 / 0.704

0.704 / 0.700

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

Track

n

Full Acc.

cam Acc.

Full Tokens

cam Tokens

Token Saving

Memory (coding-agent-life)

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)

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.

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

Supported 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

.cursor/mcp.json, ~/.cursor/mcp.json, or .cursor-plugin/plugin.json

Task / explore subagents use CLI

Claude Code

.mcp.json, ~/.claude.json, or claude mcp add cam -- cam mcp

Limited-tool subagents use CLI

Codex

~/.codex/config.toml → [mcp_servers.cam]

codex exec uses CLI

Windsurf

~/.codeium/windsurf/mcp_config.json

Cascade uses MCP

GitHub Copilot

.vscode/mcp.json or ~/.copilot/mcp-config.json

Chat uses MCP; CLI scripts use CLI

Continue / Cline

~/.continue/config.yaml / ~/.cline/mcp.json

JetBrains

AI Assistant → MCP (cam / mcp)

Use absolute path to cam if IDE PATH is empty

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

.rs

functions, structs, enums, traits, calls

Python

.py

functions, classes, calls

TypeScript

.ts, .tsx

functions, methods, classes, calls

JavaScript

.js, .jsx

functions, methods, classes, calls

Go

.go

functions, methods, structs, calls

Java

.java

functions, methods, classes, interfaces, calls

C

.c

functions, structs, calls

C++

.cc, .cpp, .cxx, .h, .hpp

functions, methods, classes, structs, calls

C#

.cs

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

Report Bug · Request Feature

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Gives 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
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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 npm
      16
      Business Source 1.1
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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 PyPI
      1
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Provides 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