AgentMemory 完全指南：AI 编码 Agent 的持久记忆引擎
📖 目录
为什么 AI 编码 Agent 需要持久记忆
用过 Claude Code、Cursor 或 Codex CLI 的开发者都有过这个体验——每个新会话，Agent 就像失忆了一样
- 上回刚定好的架构决策又要重新解释
- 之前发现的 bug 又走一遍同样的排查路径
- 项目偏好的代码风格、测试框架、工具链每次都要重复设定
传统的解决方案无非两种：要么往 CLAUDE.md 里塞大量上下文（很快就满了），要么每次手动粘贴——两个都不靠谱
AI 编码 Agent 真正缺少的，是一个能自动积累、高效检索的长期记忆系统
AgentMemory 是什么
AgentMemory 是一个开源的持久记忆引擎，专为 AI 编码 Agent 设计。它本质上是一个 MCP 记忆服务器，运行在后台，默默地记录 Agent 每次会话的关键信息，下次会话时自动把最相关的上下文注入回来
核心团队基于 iii-engine 构建，采用 SQLite 本地存储，零外部数据库依赖
核心特性
- 12 个自动捕获钩子——零手动操作，Agent 每做一件事都自动记忆
- 混合检索——BM25 关键词 + Vector 语义 + Knowledge Graph 三路融合排序
- 4 级记忆生命周期——从短期缓存到长期巩固，自动衰减和遗忘
- 跨 Agent 共享——Claude Code、Cursor、Codex CLI、Gemini CLI 共享同一个记忆服务器
- 实时可视化——本地 3113 端口提供记忆浏览器
- 零外部依赖——SQLite + iii-engine 就够了
基准测试：检索准确率 95.2%
在 ICLR 2025 的 LongMemEval-S 基准（500 道题）上，AgentMemory 的检索准确率表现亮眼
| 系统 | R@5 | R@10 | MRR |
|---|---|---|---|
| AgentMemory | 95.2% | 98.6% | 88.2% |
| BM25 纯关键词 | 86.2% | 94.6% | 71.5% |
预算对比更直观——传统做法是把全部上下文塞进 prompt，一年下来 token 消耗 19.5M+，直接超过窗口上限。AgentMemory 每年的 token 成本控制在约 170K（约 10 美元），如果本地跑 embedding 甚至零成本
| 方案 | 年消耗 Token | 年成本 |
|---|---|---|
| 全量上下文 | 19.5M+ | 超出窗口上限 |
| LLM 摘要压缩 | ~650K | ~500 美元 |
| AgentMemory | ~170K | ~10 美元 |
| AgentMemory + 本地 embedding | ~170K | 0 美元 |
快速开始：一键启动
启动记忆服务器只需要一条命令
npx @agentmemory/agentmemory
启动后可以在另一个终端跑 demo 看看效果
npx @agentmemory/agentmemory demo
Demo 会写入 3 个真实的开发会话（JWT 鉴权实现、N+1 查询优化、限流中间件），然后演示语义检索效果——搜 "database performance optimization" 能找回 "N+1 query fix"
打开浏览器访问 http://localhost:3113，可以看到记忆库的实时可视化界面
接入各种 AI 编码 Agent
AgentMemory 通过 MCP 协议与主流 AI 编码 Agent 互通，以下是各 Agent 的接入方式
Claude Code
完整支持 12 个捕获钩子，是最深度的集成——Agent 的每一步操作都会被自动记录
claude mcp add agentmemory -- npx @agentmemory/agentmemory mcp
Cursor
通过 MCP 服务器接入
npx @agentmemory/agentmemory mcp
Codex CLI (OpenAI)
同样通过 MCP 协议
-- npx @agentmemory/agentmemory mcp
Gemini CLI
-- npx @agentmemory/agentmemory mcp
还可以接入 OpenCode、Cline、Goose、Kilo Code、Aider、Windsurf、Roo Code 等——只要支持 MCP 或 REST API 的 Agent 都可以
实战工作流
用一个真实的开发场景来说明 AgentMemory 如何改变工作流
场景：开发 JWT 认证模块
第一天：你让 Claude Code 实现 JWT 认证
- Claude 创建了
src/middleware/auth.ts，用了 jose 库而非 jsonwebtoken（因为要兼容 Edge Runtime） - 写了完整的测试覆盖 token 签发、验证、过期处理
- AgentMemory 自动捕获了这个会话的所有决策
第二天：你让同一个 Agent 添加限流中间件
- Agent 自动检索到昨天的上下文——知道项目用了 jose、测试结构、Edge 兼容需求
- 新写的限流中间件直接采用了同样的错误处理模式
- 不需要手动解释任何背景
一周后：你让 Cursor 修复一个认证相关的 bug
- AgentMemory 的共享记忆让 Cursor 也知道了整个项目的架构决策
- Bug 修复自动遵循了既定的代码风格和测试约定
竞品对比
市面上的 Agent 记忆方案并不少，但 AgentMemory 有一些明显的差异化优势
| 维度 | AgentMemory | mem0 (53K ⭐) | Letta/MemGPT (22K ⭐) | CLAUDE.md 内置 |
|---|---|---|---|---|
| 类型 | 记忆引擎 + MCP 服务器 | 记忆层 API | 完整 Agent 运行时 | 静态文件 |
| 检索 R@5 | 95.2% | 68.5% | 83.2% | N/A |
| 自动捕获 | 12 个钩子（零手动） | 手动调用 add() | Agent 自编辑 | 手动编辑 |
| 搜索方式 | BM25 + Vector + Graph + RRF 融合 | Vector + Graph | Vector（归档） | 全部加载到上下文 |
| 跨 Agent | ✅ MCP + REST + leases | ❌ 仅 API | ❌ 仅 Letta 运行时 | ❌ 每个 Agent 独立文件 |
| 外部依赖 | 无（SQLite + iii-engine） | Qdrant / pgvector | Postgres + Vector DB | 无 |
| 记忆生命周期 | 4 级巩固 + 衰减 + 自动遗忘 | 被动提取 | Agent 管理 | 手动清理 |
| 自托管 | ✅ 默认 | 可选 | 可选 | ✅ |
进阶配置
1. 导入已有会话
如果之前用 Claude Code 积累了大量 JSONL 会话记录，可以一键导入
npx @agentmemory/agentmemory import-jsonl
# 或导入单个文件
npx @agentmemory/agentmemory import-jsonl ~/.claude/projects/my-project/abc123.jsonl
2. 本地 Embedding
默认使用 all-MiniLM-L6-v2 模型做本地 embedding，无需 API key 也没有网络请求
AGENTMEMORY_EMBEDDING_MODEL=all-MiniLM-L6-v2 \
npx @agentmemory/agentmemory
3. 文件系统监听
v0.9.0 新增的 @agentmemory/fs-watcher 模块可以监听文件变化自动生成记忆，比如你改了一个配置文件，AgentMemory 自动记录
4. 升级维护
⚠️ 注意：这个命令会更新 JavaScript 依赖并可能运行 cargo install 更新 iii-engine
5. OpenClaw 集成
AgentMemory 已经内置了 OpenClaw 插件支持
openclaw config set agentmemory.enabled true
总结
AgentMemory 解决的是 AI 编码 Agent 生态中一个一直被忽视的核心问题——长期记忆的缺失
它的设计理念很简单：让上下文自动积累而不是每次都从零开始。通过 MCP 协议实现跨 Agent 共享记忆，通过混合检索实现精准召回，通过本地 SQLite 实现零依赖部署
对于重度使用 AI 编码 Agent 的开发者来说，这可能是 2026 年最值得装上的工具——省掉的不只是重复解释的时间，更重要的是 Agent 能真正"了解"你的项目
GitHub: github.com/rohitg00/agentmemory
官网: agent-memory.dev
NPM:
@agentmemory/agentmemory一键启动:
npx @agentmemory/agentmemory