codeagent-memory

cam

English · 中文 · 日本語 · 한국어 · العربية · 🌐 网站

专为编码 Agent 打造的本地多轮对话记忆系统

代码图谱 + 记忆 · 精准读取 · 100% 本地 · MCP + CLI

内核采用 Rust 编写

目录

• 为什么选择 cam？
• 快速开始
• 主要功能
• 工作原理
• Agent 工作流
• CLI 参考
• 记忆规则
• 配置
• 基准测试
• 支持的 Agent
• 支持的语言
• 支持的平台
• 许可证

指南：交互式展示（网站） · 主 Agent 与子 Agent · 各 IDE 的 MCP 配置 · 中文说明

为什么选择 cam？

当 AI 编码 Agent 探索代码仓库时，通常会用低效的方式重新发现项目结构——逐个文件运行 grep、glob 并完整读取文件，然后在下一个会话中忘掉所有信息。

cam 在一个二进制文件中为 Agent 提供两个本地检索层：

一个二进制文件，两种接口： 主 Agent 通过 MCP 调用 cam（cam mcp）；子 Agent（通常不会继承 MCP 工具）调用完全相同的 CLI（cam --json …）。两者共用磁盘上的 .cam/cam.db，100% 本地运行，无 API 费用。

快速开始

选项 1：一句话安装 Agent（推荐）

将此提示词直接粘贴到你的编码 Agent（Cursor、Claude Code、Codex、Windsurf、GitHub Copilot、Cline 等）中，让它为你安装、建立索引并配置 cam：

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.

选项 2：手动设置

1. 安装 CLI

需要 Rust 工具链：

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.5
docker run -i --rm -v "$PWD:/work" -w /work ghcr.io/hanochzhu/codeagent-memory:0.1.5

2. 为项目建立索引并进行查询

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 首次使用时会自动初始化 .cam/。如果希望文件变更时实时增量更新图谱，可在后台运行 cam watch。}

3. 为主 Agent 连接 MCP

将 cam mcp 添加到宿主的 MCP 配置中（例如 .cursor/mcp.json 或 .mcp.json）：

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

请参阅 docs/mcp.md，了解各宿主专用的配置路径；另请参阅 docs/agents.md，了解主 Agent / 子 Agent 的提示词规则。

_{首次执行 recall 或 add 时，会下载默认嵌入模型（potion-multilingual-128M 至 ~/.cam/models/）；如果处于离线状态，则会回退到词法哈希嵌入器。}

主要功能

工作原理

1. 提取 — tree-sitter 遍历工作区，并将符号定义和调用边存储在 .cam/cam.db 中。
2. 精准读取 — Agent 通过虚拟路径导航（ls → find → read → ref）。读取文件会返回其符号大纲；读取 file/symbol 只会返回该符号的源代码片段。
3. 混合召回 — recall 接受英文查询，在本地生成嵌入向量，运行可识别标识符的 BM25（拆分 snake_case、kebab-case、camelCase 并进行英文词干提取），剔除低置信度的尾部结果，并通过 RRF ($k=60$) 融合两份列表，再按 $0.9 + 0.1 \times R$ 缩放。已被取代的修订会自动展开为其最新替代项。
4. 回写 — Agent 解决非平凡任务后，会提取原子事实，确保每次 add 只存储一条事实（英文摘要；正文支持非拉丁字符）。相关事实通过 --link / links 建立关联，形成知识图谱（通过 mem show 检查；召回目前尚未遍历图谱链接）。--parent 将记忆关联到一个结构化主题；--supersedes 会替换过时的记忆，同时保留其沿革关系。

架构深入解析（中文）：DESIGN.md。

Agent 工作流

每项编码任务都遵循相同的四步循环：

1. 先召回 — 在 grep 之前，先用英文查询 cam_recall / cam recall。如果命中项为 latest 且不需要更新（needs_update），则复用该结果。
2. 确保已索引 — 如果图谱工具返回 not_indexed，则为该项目运行一次 cam_index / cam index。
3. 遍历图谱 — 未命中记忆时，使用 find 或 ls 定位符号，使用 read <file>/<symbol> 读取符号正文，并使用 ref <symbol> --dir in|out 追踪调用方和被调用方。
4. 回写 — 使用 cam_add / cam add 将新发现的架构事实或修复作为原子事实持久化（每条记忆一项事实，英文摘要；正文支持非拉丁字符），并通过 links / --link 关联相关事实。

完整的 Agent 规则和可直接复制粘贴的系统提示词：docs/agents.md。

CLI 参考

代码图谱命令

记忆命令

服务与配置命令

全局标志与约定：

• --project <dir>（或 CAM_PROJECT 环境变量）会覆盖自动向上查找 .cam / .git 根目录的行为。
• --json 输出紧凑 JSON（--pretty 用于输出缩进 JSON）。使用 --json 时，错误会向 stdout 输出 {"error":{"code":…,"message":…}}，并以非零状态码退出。
• 符号不明确： 当 read 或 ref 匹配到多个定义时，cam 会返回 status: "ambiguous" 和候选节点 ID（例如 src/main.rs:function:main:12），这些 ID 可以直接传回 read 或 ref。
• 忽略规则与多仓库目录： 会遵循任意深度的 .gitignore 和 .camignore。跳过 git 子模块和链接工作树；将嵌套的独立克隆索引为 kind: "project"（可传给 --scope）。

记忆规则

• 原子事实与知识图谱链接： 每条记忆只存储一条原子事实，避免在单个条目中塞入过多信息。多个事实相关时，使用 --link / links 将它们连接起来，构建知识图谱（目前尚未启用图谱检索）。
• 英文查询与摘要： 检索查询和记忆摘要必须使用英文书写。记忆正文支持非拉丁字符。
• 保留与强化： 艾宾浩斯遗忘曲线 $R = e^{-t / S}$ 通过 $\text{relevance} \times (0.9 + 0.1 \times R)$ 调整检索分数。$R < 0.3$ 的条目会标记为 needs_update；超过 stale_days（默认值为 30）的条目会标记为 stale。每次有效的检索命中（needs_update = false）都会刷新最后访问时间，并将稳定性 $S$ 乘以 1.7。
• 非破坏性沿革： 记忆永远不会被删除。--parent 用于构建分支树；--supersedes 用于构建线性修订链，其中只有末尾条目标记为 latest，较旧的修订版则从默认检索结果中折叠隐藏。

配置

全局设置位于 ~/.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

使用 CAM_EMBED_MODEL 可为单个进程覆盖模型；也可以使用 cam config set embedding_model default 重置。嵌入模型发生变化时，下次执行 recall 会在评分前自动重新嵌入现有记忆。

基准测试

cam 在相同语料上，分别将其代码图和记忆层与最接近的开源系统进行评测：

_{通用聊天记忆框架（Mem0、Zep、Letta）针对的是对话日志，而非这些编码 Agent 语料，因此未列入下表。}

系统对比

1. 记忆 — coding-agent-life-v1

15 个会话，15 个查询，$k=5$（评分方式与 agentmemory 的 score.ts 相同；P@5 上限为 0.240）。

修订链（--lineage）： 将每一轮重新摄取为 --supersedes 修订，以测试 top-$k$ 是否会返回每条黄金链的最新节点（newest R@k），以及是否有被取代的节点错误地声称自己是 latest（stale latest）。

2. 长期记忆 — LongMemEval-S

从清理后的 LongMemEval-S 中，使用种子 42 抽取 100 个非弃答问题。检索以 $k=10$ 使用 RRF 融合嵌入和 BM25，且不使用大模型阅读器。

3. 工作流检索 — Agent Retrieval Bench V2（edit2ripple）

在 44 个冻结的仓库快照中，包含 58 个锚定变更查询（不使用 LLM；BCY = 在规范的 8K token 文件打包协议下的预算上下文产出）。

cam graph 的首次命中排名最高（MRR 0.297，查询 P95 为 7.3 ms），而词法检索能覆盖更多文件，因此我们采用图检索与词法检索的排名融合。

4. 代码图 — LongMemCode（clap）

clap v4.6.1，针对 SCIP 标注数据进行 536 个场景评测（不使用 LLM，P95 ≈ 5.2 ms，$/1k = 0）。

5. 多轮 Token 节省 — DeepSeek

完整上下文转储与逐轮 cam 检索对比（deepseek-flash、哈希嵌入器，2026-10-13）：

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/longmemcode/run.py --corpus clap
python3 eval/charts/generate.py

支持的 Agent

为主 Agent注册 cam mcp（stdio）；子 Agent可直接使用 cam --json CLI，无需额外设置。

可直接复制粘贴的配置：docs/mcp.md · 系统提示词：docs/agents.md。

支持的语言

支持的平台

cam 可通过 cargo install --git https://github.com/HanochZhu/codeagent_memory --locked 在 macOS、Linux 和 Windows 上原生编译，也可通过 Docker (ghcr.io/hanochzhu/codeagent-memory:0.1.5) 在任何环境中运行。请参阅开始使用。

许可证

MIT