AgentMemory

这是什么？适合谁？

AgentMemory（rohitg00/agentmemory）是一个为 AI 编码 Agent 提供持久记忆的开源引擎。它通过 hook、MCP 和 REST 三种通道，把 Claude Code、Codex CLI、Cursor、Gemini CLI、OpenCode 等 20 多个编码 Agent 的所有工具调用、会话总结、代码决策实时捕获下来，压缩成结构化的事实、概念和叙事，再以「BM25 全文 + 向量语义 + 知识图谱」三路混合检索的方式按需注入到下一次会话。核心口号是「#1 Persistent memory for AI coding agents based on real-world benchmarks」。

它和每个 Agent 自带的记忆功能（Claude Code 的 MEMORY.md、Cursor 的 notepads、Cline 的 memory bank）定位不同：那些像「便利贴」，受 200 行上限约束、每次全量加载进上下文、无法跨 Agent 共享；AgentMemory 是便利贴背后的「可搜索数据库」——不限容量、top-K 检索、任意 Agent 通过 MCP/REST 共享，官方基准显示同样 240 次观测下 token 成本约 1900，比全量加载（22K+）省 92%。

在记忆领域，它和 mem0（约 63k Star，纯记忆层 API）、Letta/MemGPT（约 24k Star，完整 Agent 运行时）、Khoj（个人 AI 助手）、supermemory、Zep/Graphiti、Cognee、Hippo 等是竞品。差异在于：AgentMemory 专注「编码 Agent 的工程记忆」，直接以 12 个 Claude Code hook + 17 个技能的方式嵌入既有编码工作流，而非提供一个全新的 Agent 框架或通用知识库 API。它在 LongMemEval-S（ICLR 2025，500 题）公开基准上报告 R@5 达 95.2%，是其相对 mem0（LoCoMo 68.5%）的核心卖点。

适合谁：正在用 Claude Code / Codex / Cursor 做日常开发、苦于每次新会话都要重新解释项目背景的开发者；需要把团队里多人多 Agent 的决策沉淀为可检索知识库的技术负责人；以及想给自建 Agent 挂一层持久记忆、又不想自己写向量库和检索管线的Agent 框架作者。不适合：只想用现成低代码平台、不碰命令行的纯业务用户——它面向的是命令行和编码工作流。

准备工作

1. 安装命令：Node.js 20+ 环境，一条命令即可启动：

   npx @agentmemory/agentmemory
   

   首次运行是交互式向导，会让你勾选要接入的 Agent、选择 LLM provider（也可以完全无 key 运行），然后在 :3111 启动记忆服务器。

2. API 密钥（可选但建议）：AgentMemory 本身可无 key 运行，但要启用「LLM 压缩 + 向量嵌入」两条核心能力，需要至少一个 provider 的 key。官方 .env 支持 ANTHROPIC_API_KEY、OPENAI_API_KEY、GEMINI_API_KEY、OPENROUTER_API_KEY、MINIMAX_API_KEY，从对应厂商控制台获取。省钱关键：向量嵌入装本地模型 npm install @huggingface/transformers（all-MiniLM-L6-v2）就完全免费，还能让召回率比纯 BM25 高 8 个百分点。

3. 前置知识：熟悉自己的编码 Agent 是怎么接 hook / MCP 的（例如 Claude Code 的 /plugin 命令、~/.claude/settings.json 结构）。不需要懂向量数据库——引擎自带 BM25 + 向量 + 图谱三路检索，全部封装好。

4. Windows 用户注意：快速路径是 WSL2；原生 Windows 需要手动装 iii 引擎（下载 iii-x86_64-pc-windows-msvc.zip 的 v0.11.2 版放到 %USERPROFILE%\.local\bin\iii.exe），约 10–20 分钟，且 agentmemory connect 在原生 Windows 暂不支持。也可以走 Docker：docker 起引擎，AgentMemory 会自动拉起内置 compose。

5. 替代方案：如果只想给单个 Agent 加轻量记忆，直接用 Claude Code 的 MEMORY.md / Cursor 的 notepads 即可；需要跨 Agent 但不想自托管，可以考虑 mem0 的托管 API 或 Letta 的云服务。AgentMemory 的优势是「自托管、免费、面向编码工作流深度嵌入」。

快速上手（5步）

第 1 步：启动记忆服务器

npx @agentmemory/agentmemory

预期结果：终端进入交互式向导，完成 Agent 选择和 provider 配置后，服务器在 http://localhost:3111 就绪，实时观察面板在 http://localhost:3113。

第 2 步：跑通 30 秒演示，验证召回

npx @agentmemory/agentmemory demo

预期结果：它灌入 3 个真实会话样本（JWT 认证、N+1 查询修复、限流），当你搜索「database performance optimization」时能命中「N+1 query fix」——这是纯关键词匹配做不到的语义召回。

第 3 步：给 Agent 装上 17 个技能

npx skills add rohitg00/agentmemory -y

预期结果：Agent 学会「什么时候该去记忆里查、什么时候该存」，而不是无脑依赖。

第 4 步：接入你的编码 Agent

以 Claude Code 为例（把下面这段原样粘贴给 Claude Code 执行）：

Install agentmemory: run `npx @agentmemory/agentmemory` in a separate terminal to start the memory server.
Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory`.
Verify with `curl http://localhost:3111/agentmemory/health`.

预期结果：插件注册 12 个 hook + 17 个技能 + 自动接上 @agentmemory/mcp，共 54 个 MCP 工具（memory_smart_search、memory_save、memory_sessions 等）。

第 5 步：日常使用

agentmemory                    # 启动服务器
agentmemory stop               # 关闭
agentmemory connect <agent>    # 再接入一个新 Agent
agentmemory doctor             # 交互式诊断 + 修复提示

预期结果：之后每次编码会话的每个工具调用都被自动捕获，新会话开头自动注入项目 profile（top 概念、文件、模式，默认 2000 token 预算）。

常见踩坑

踩坑 1：MCP 里只看到 7 个工具，而不是 54 个

• 现象：Cursor / OpenCode / Gemini CLI 里只有 memory_save、memory_recall 等 7 个工具。
• 原因：@agentmemory/mcp 是薄封装 shim，只有能连到运行中的服务器（proxy 模式）时才暴露完整 54 工具面，否则回退到 7 工具的本地集。
• 解决：先起 npx @agentmemory/agentmemory，并设 AGENTMEMORY_URL=http://localhost:3111（官方文档说明）。

踩坑 2：/agentmemory/health 一直返回 503

• 现象：健康检查报 critical，导致负载均衡把节点摘掉。
• 原因：健康度按 heapUsed/heapTotal 判定（issue #1223），堆接近上限时误报。
• 解决：给 Node 进程加大堆内存，或调低健康检查阈值；留意官方后续修复。

踩坑 3：多核机器上健康报告 cpu_critical

• 现象：明明负载很低却报 CPU 危急。
• 原因：CPU 百分比按单核刻度计算，多核主机上被放大（issue #1235）。
• 解决：暂时忽略该告警或手动上调阈值，等上游修复。

踩坑 4：导入历史 JSONL 发现老会话全没了

• 现象：import-jsonl 只导入到最近一小段时间的会话。
• 原因：Claude Code 的 cleanupPeriodDays（默认 30 天）会自动删除 ~/.claude/projects/ 下更老的 JSONL。
• 解决：要么用 cron 定时 import-jsonl，要么在 ~/.claude/settings.json 调高 cleanupPeriodDays，要么直接走 hook 自动捕获（默认插件路径），让每条 turn 实时入库（README 明确提示）。

踩坑 5：升级后所有 hook 悄悄失效

• 现象：AgentMemory 升级后 hook 不再触发。
• 原因：如果你绕过 /plugin install、直接改 ~/.claude.json 接 MCP，Claude Code 无法解析 ${CLAUDE_PLUGIN_ROOT}，hook 脚本里的绝对路径又内嵌了版本号（如 0.9.22/scripts/...），升级就断。
• 解决：跑 agentmemory connect claude-code --with-hooks 重新合并正确路径；推荐始终走 /plugin install 路径。

踩坑 6：默认模型用成推理模型导致行为异常

• 现象：v0.9.29 默认 OpenAI 模型 gpt-5.6-luna 是 reasoning 模型，provider 按普通模型调用出问题（issue #1219）。
• 原因：默认模型与 provider 调用约定不匹配。
• 解决：在 ~/.agentmemory/.env 显式设置 OPENAI_MODEL 为你常用的模型。

踩坑 7：日志平台把每一行都标成 error

• 现象：接入日志收集后满屏红色报错。
• 原因：引擎把 info/warn 也写到 stderr（issue #1204）。
• 解决：日志平台侧把 stderr 的 info/warn 级别合并，或等上游改成 stdout。

初级用法

1. 开箱即用体验：npx @agentmemory/agentmemory 起服务器后，打开 :3113 面板，看每次编码会话的 prompt、工具调用、结果被实时捕获成记忆卡片。
2. 给单个项目做记忆：在 Claude Code 里正常干活，AgentMemory 自动记录；下次新会话问「这个项目之前怎么处理限流的」，它就能精准召回历史决策。
3. 会话回放排查：在 viewer 的 Replay 标签页拖时间轴，以离散事件（prompt / tool call / result / response）回放某次会话，支持 0.5x–4x 变速和键盘快捷键。
4. 导入老数据：npx @agentmemory/agentmemory import-jsonl ~/.claude/projects/-my-project/abc123.jsonl 把历史转录导入并建立索引。
5. 多 Agent 共享同一记忆：让 Claude Code 和 Codex CLI 同时指向同一个记忆服务器，共享项目背景。

高级玩法

1. 四层记忆固化：理解并调优 Working（原始观测）→ Episodic（会话摘要）→ Semantic（事实/模式）→ Procedural（工作流/决策模式）四层，配合 CONSOLIDATION_ENABLED、GRAPH_EXTRACTION_ENABLED、SLOT_REFLECT_ENABLED 控制图谱抽取和反思。
2. 团队记忆（Team memory）：用命名空间把「团队共享记忆」和「个人私有记忆」分开，配 AGENT_ID + AGENTMEMORY_AGENT_SCOPE 做多 Agent 隔离。
3. 成本感知的模型选择：给「压缩 / 召回 / 图谱抽取」分别指定不同成本档位的 LLM，本地嵌入免费，把全年成本压到个位数美元（官方基准约 $10/年）。
4. MCP 工具编排：54 个工具里 memory_governance_delete 做治理删除、memory_save/memory_smart_search 做存取，可以在自建 Agent 里直接调用这些工具实现「检索增强编码」。
5. Git 快照回滚：对记忆状态做 version、rollback、diff，像管代码一样管记忆，配合 agentmemory upgrade 谨慎升级运行时。

小技巧

1. 一定装本地嵌入 npm install @huggingface/transformers——免费，召回 +8pp，还能彻底离线。
2. 用 agentmemory doctor 定期跑一次交互式诊断，它会直接给出修复提示，比手动查日志快。
3. 中文 / 日文 / 韩文记忆记得装分词器 npm install @node-rs/jieba tiny-segmenter，否则 CJK 退化成整段 token 化，召回变差。
4. 别用 npx @agentmemory/agentmemory 时踩缓存坑——想强制最新版用 npx -y @agentmemory/agentmemory@latest，或清一次 ~/.npm/_npx 缓存。
5. 关注 demo 命令：它既验证了语义召回，也是理解「什么该存、什么该查」的最佳样本数据。

常见问题 FAQ

Q1：AgentMemory 免费吗？定价如何？

A：核心引擎开源（Apache-2.0），自托管完全免费。成本主要在 LLM：本地嵌入 all-MiniLM-L6-v2 免费；OpenAI 嵌入 text-embedding-3-small 约 $0.02/1M tokens；LLM 压缩/总结另算。官方基准给出全年成本约 $10（对比「全量粘贴上下文」不可行、LLM 总结约 $500）。来源：GitHub README。

Q2：它和 mem0 / Letta 有什么区别？

A：mem0 是通用记忆层 API（供任何应用调用），Letta/MemGPT 是完整 Agent 运行时（连模型调度一起管）。AgentMemory 是「编码 Agent 的工程记忆引擎」，直接嵌入 Claude Code/Codex 的 hook 工作流，不替代你的 Agent，只补记忆。官方 benchmark/COMPARISON.md 对 mem0、Letta、Khoj、supermemory、TencentDB Agent Memory、MemPalace、Zep/Graphiti、Cognee、Hippo 有逐项对比。

Q3：支持哪些 LLM 和嵌入模型？

A：LLM 支持 Anthropic、OpenAI、Gemini、OpenRouter、MiniMax；嵌入支持本地 all-MiniLM-L6-v2（推荐免费）、Gemini gemini-embedding-001（免费额度）、OpenAI text-embedding-3-small、Voyage voyage-code-3（代码优化）、Cohere、OpenRouter。

Q4：支持哪些编码 Agent？

A：20+ 个，包括 Claude Code（12 hooks + 插件 + MCP）、Codex CLI（6 hooks + 插件 + MCP）、GitHub Copilot CLI、Cursor、Gemini CLI、OpenCode（22 hooks）、Cline、Goose、Aider（REST）、Kilo Code、Claude Desktop，以及 OpenClaw、Hermes、OpenHuman、pi 等。

Q5：数据安全吗？会存我的 API key 吗？

A：隐私优先设计——在存储前会剥离 API key、secrets 和 <private> 标记内容；记忆可本地自托管，不经过第三方。自带「写时来源溯源」，每条记忆都能追回原始观测。来源：GitHub README。

进阶学习建议

• 啃透 memory_smart_search 的三路融合：理解 BM25（词干 + 同义词扩展）、向量（余弦相似度）、图谱（实体匹配 + BFS）如何用 Reciprocal Rank Fusion（RRF，k=60）融合、并做会话多样化（每会话最多 3 条），这是它召回率高于竞品的技术内核。
• 复现官方基准：eval/ 目录提供可插拔 adapter 的评测 harness，可本地重跑 LongMemEval-S（公开 500 题）和 in-house 的 coding-agent-life-v1 语料，把 grep / 向量 / agentmemory 三种 adapter 并排打分。
• 研究 benchmark/COMPARISON.md：这是少见的「记忆引擎横向测评」一手资料，逐项对比 mem0、Letta、Khoj 等 9 个竞品的类型、检索 R@5、成本，适合选型参考。
• 搭配 codegraph / Graphify / Understand Anything：官方推荐与这三个项目组合——AgentMemory 记「做过什么」，codegraph 建代码图索引，Graphify 扩文档/PDF/图片/视频知识图谱，参见 docs/recipes/pairings.md。
• 读 docs/COORDINATION 式的记忆治理思路：重点理解「近重复提示（similarTo）」「版本链 + 超集」「TTL 过期 + 矛盾检测 + 重要性淘汰」这套自动遗忘机制，这是「记忆会越长越脏」问题的答案。

参考链接

• AgentMemory GitHub
• AgentMemory 官网
• AgentMemory 基准对比（benchmark/COMPARISON.md）
• AgentMemory 评测复现（eval/README.md）

免责声明：本文基于官方文档和公开资料整理，AI 辅助生成，MagicNetWorld 尚未完成独立实测。