AgentMemory：基于真实基准测试的AI编程代理持久化记忆系统

这是什么

agentmemory 是一个基于 TypeScript 构建的开源 AI 编程代理持久化记忆系统。它由 rohitg00 开发，基于 iii engine 构建，旨在为各类 AI 编程助手提供跨会话的长期记忆能力。

该项目不仅仅是一个简单的缓存工具，它是对 Andrej Karpathy 提出的 LLM Wiki 模式的扩展，引入了置信度评分、生命周期管理、知识图谱以及混合搜索机制。其核心目标是让编程代理（如 Claude Code、Cursor、GitHub Copilot CLI 等）能够“记住”之前的开发上下文、偏好设置和架构决策，从而避免在每次新会话中重复解释相同的问题。

解决的问题

在当前的 AI 辅助编程工作流中，开发者面临以下主要痛点：

1. 上下文丢失与重复劳动：开发者需要在每个新会话中重新解释项目架构、技术栈偏好和已知的 Bug。现有的内置记忆机制（如 CLAUDE.md 或 .cursorrules）通常限制在 200 行以内，且容易过时。
2. 跨会话知识断层：代理无法自动关联不同会话中的操作。例如，在 Session 1 中配置了 JWT 认证，在 Session 2 中处理速率限制时，代理往往不知道之前的认证实现细节（如使用了 jose 中间件而非 jsonwebtoken），导致无法提供连贯的建议。
3. 手动维护成本高：开发者需要手动复制粘贴代码片段或配置信息，效率低下且容易出错。

agentmemory 通过静默捕获代理的行为，将其压缩为可搜索的记忆，并在下一个会话开始时自动注入正确的上下文，实现了“一次配置，处处可用”的体验。

核心功能

• 持久化记忆与混合搜索：

  • 利用本地嵌入模型 all-MiniLM-L6-v2（无需 API Key，免费）进行向量化存储。
  • 结合关键词匹配与向量搜索的混合检索机制，能够理解语义（例如搜索“数据库性能优化”能找到关于“N+1 查询修复”的内容）。
  • 支持知识图谱构建，可视化展示记忆节点之间的关联。

• 广泛的代理兼容性：

  • 支持 Claude Code、GitHub Copilot CLI、Cursor、Gemini CLI、Codex CLI、Hermes、OpenClaw、pi、OpenCode 等主流 AI 编程工具。
  • 通过 MCP (Model Context Protocol) 协议连接，任何支持 MCP 或 HTTP 的代理均可接入。
  • 提供专用的连接命令，如 agentmemory connect claude-code，自动配置 hooks 和 skills。

• 多代理隔离与协作：

  • 支持多代理环境下的记忆隔离（通过 AGENTMEMORY_AGENT_SCOPE=isolated 配置），确保不同项目或代理的记忆互不干扰。
  • 所有代理共享同一个记忆服务器，实现跨工具的上下文同步。

• 交互式记忆查看器与回放：

  • 提供 Web 界面（默认端口 3113），实时展示记忆构建过程。
  • 支持会话回放（Replay），以时间轴形式展示提示词、工具调用、结果和响应，支持播放/暂停、速度调节（0.5x-4x）和键盘快捷键。
  • 支持导入旧的 JSONL 格式会话记录（如 Claude Code 的历史记录）。

• 自动化技能注入：

  • 安装后自动为代理安装 8 个原生 Skills，使代理知道何时调用记忆工具。
  • 通过 MCP 协议暴露 53 个工具（如 memory_smart_search, memory_save 等），无需额外配置即可使用。

亮点 / 与同类相比

• 本地优先，无 API 依赖：

  • 核心嵌入模型 all-MiniLM-L6-v2 在本地运行，无需支付 OpenAI 或 Anthropic 的 API 费用，保护隐私且零成本。
  • 相比之下，许多竞品（如 mem0、Letta）依赖外部 API 或云服务。

• 基于 iii engine 的高性能架构：

  • 底层使用 iii engine，支持高效的内存管理和快速检索。
  • 提供详细的基准测试报告（benchmark/LONGMEMEVAL.md, benchmark/QUALITY.md），在 LongMemEval 和内部语料库上表现优异。

• 丰富的生态集成：

  • 与 codegraph、Understand Anything 和 Graphify 等工具配合使用，扩展了代码图索引和多代理构建管道的能力。
  • 提供详细的配对食谱（Recipes）和问题路由表，指导如何组合使用这些工具。

• 活跃的更新与维护：

  • 版本迭代迅速（如 v0.9.22 新增 Qwen Code、Antigravity、Kiro 适配器，修复 ERESOLVE 问题等）。
  • 提供 agentmemory doctor 命令进行交互式诊断和修复。

• 与竞品的对比：

  • 相较于 mem0、Letta、Khoj、claude-mem 和 Hippo，agentmemory 更侧重于本地化、低延迟和与现有 MCP 生态的深度集成，且完全开源。

适合谁用 / 上手

适合人群：

• 深度依赖 AI 编程助手（如 Cursor、Claude Code、Copilot）的开发者。
• 希望减少重复性上下文解释工作，提升编码效率的团队或个人。
• 关注数据隐私，希望记忆数据完全本地化的开发者。
• 使用多种 AI 工具，希望实现跨工具上下文同步的用户。

上手指南：

1. 安装：

   npm install -g @agentmemory/agentmemory
   # 如果遇到权限问题，使用 sudo
   # sudo npm install -g @agentmemory/agentmemory
   

2. 启动服务：

   agentmemory
   # 服务将在 localhost:3111 启动
   

3. 连接代理（以 Claude Code 为例）：

   agentmemory connect claude-code
   

   此命令会自动配置 hooks 和 skills，将 agentmemory 的记忆能力注入到 Claude Code 中。

4. 体验演示：

   agentmemory demo
   

   该命令会种子化 3 个真实的会话场景（JWT 认证、N+1 查询修复、速率限制），并演示语义搜索能力。

5. 查看记忆： 打开浏览器访问 http://localhost:3113，即可看到实时的记忆构建过程和回放功能。

注意事项：

• 如果使用 npx 运行，注意版本缓存问题。建议使用全局安装以获得最佳体验，或使用 npx -y @agentmemory/agentmemory@latest 强制获取最新版本。
• 对于 Claude Code 用户，推荐使用 agentmemory connect claude-code --with-hooks 以确保路径正确解析，避免升级后 hooks 失效。