codeagent-memory

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

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

How each IDE / agent handles this prompt

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

Alternative: Build from local clone or run via Docker

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

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

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. 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, 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 / , and trace callers/callees with ref --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

| cam recall " " [--limit N] [--no-expand] [--include-superseded] [--snippets] | Hybrid RRF recall (English query). --no-expand skips newest-revision expansion; --include-superseded keeps old revis