给 AI 编码 Agent 装一块硬盘：agentmemory 实测

上周在用 Claude Code 做一个 Express 项目。Session 1 搭好了 JWT 认证，用的 jose 库，中间件写在 src/middleware/auth.ts。Session 2 想加限流功能，结果 Agent 又问我一遍："你的认证方案是什么？用的哪个库？"

这个场景你大概也遇过。CLAUDE.md 写了 200 行就顶了，内容还会过时。每次开新会话都得把上下文重讲一遍。

agentmemory 想解决的就是这个问题。它在本地跑一个记忆服务，自动抓取 Agent 的操作记录，压缩成可搜索的记忆片段，下次开会话时把相关上下文注入进去。一条命令启动，支持 Claude Code、Cursor、Codex CLI、Gemini CLI 等十几个 Agent。

GitHub 上目前 15k star，本周新增 8000+。我花了两天把它接到自己的工作流里，记一下过程和发现。

它到底做了什么

先说清楚 agentmemory 不是什么：它不是一个 Agent 框架，不替代你的 Claude Code 或 Cursor。它是一个独立的记忆层，通过 MCP 协议和 Hooks 机制挂到现有 Agent 上。

启动后它做三件事：

捕获：通过 12 个生命周期 Hook（SessionStart、PreToolUse、PostToolUse 等）自动记录 Agent 的每次操作
压缩：把原始记录经过 4 层整理------原始 → 压缩 → 合并 → 长期记忆，越往后越精炼
召回：下次会话开始时，用混合搜索（BM25 + 向量 + 知识图谱）找到相关记忆，注入上下文

整个过程不需要手动干预。你不用写 remember("我用了 jose 库")，它自己会从工具调用记录里抽取这个信息。

混合搜索怎么做的

agentmemory 的搜索不是单纯的向量相似度。它用了三路融合：

sql 复制代码

查询 "数据库性能优化"
    ├── BM25 文本匹配 → 命中 "N+1 query fix" 相关记忆
    ├── 向量搜索 → 命中 "database optimization" 语义相近片段
    └── 知识图谱 → 通过 "prisma → database → performance" 关系链路找到关联
    
三路结果用 RRF (Reciprocal Rank Fusion) 合并排序

实际效果：在 LongMemEval-S（ICLR 2025 的记忆评测基准，500 道题）上，agentmemory 的 R@5 达到 95.2%，BM25 单独跑只有 86.2%。

向量模型用的 all-MiniLM-L6-v2，本地推理，不需要 API key，不花钱。这个选择挺实际------编码记忆的召回对精度要求没那么极端，用小模型就够了。

安装和接入 Claude Code

bash 复制代码

# 全局安装
npm install -g @agentmemory/agentmemory

# 启动记忆服务（默认 3111 端口）
agentmemory

# 接入 Claude Code
agentmemory connect claude-code

connect 命令做了两件事：注册 12 个 Hook 到 Claude Code 的 hooks 配置，再把 @agentmemory/mcp 作为 MCP server 接入。跑完之后 Claude Code 里多了 53 个 MCP 工具------memory_smart_search、memory_save、memory_sessions 等。

验证一下服务是否正常：

bash 复制代码

curl http://localhost:3111/agentmemory/health
# 应该返回 { "status": "ok", ... }

还有个实时查看器在 3113 端口：

bash 复制代码

open http://localhost:3113

打开能看到记忆条目的实时更新，包括每条记忆的来源、置信度、关联的知识图谱节点。

跑一下 demo 看看效果

bash 复制代码

agentmemory demo

这条命令会写入 3 组模拟会话数据：JWT 认证配置、N+1 查询修复、限流实现。然后跑几个搜索来验证召回效果。

比较有意思的一个测试：搜 "database performance optimization"，它能找到 "N+1 query fix" 的记忆------纯关键词匹配做不到这个，因为两个短语没有词重叠。向量搜索在这里起了作用。

在自研的 coding-agent-life-v1 评测集（15 个编码会话）上，agentmemory 的 Precision@5 是 0.578，grep 基线只有 0.267。Top-5 命中率两者都是 100%（15/15），但 agentmemory 返回的前 5 条结果里有效信息密度高了一倍多。p50 延迟 14ms。

4 层记忆整理机制

这是我觉得 agentmemory 设计上最值得看的部分。它不是把所有记录原样存下来，而是有一个渐进式的整理流程：

第一层：原始记录 Agent 的每次工具调用、每段对话都原样写入 SQLite。数据量大，但完整。

第二层：压缩 把同一个会话内的多次相关操作合并。比如你在同一个文件上 read → edit → read → edit 了 4 次，压缩后变成一条记忆："修改了 src/middleware/auth.ts，添加了 JWT 验证逻辑，用了 jose 库"。

第三层：合并 跨会话的相关记忆合并。Session 1 里写的认证逻辑和 Session 3 里改的认证 bug，合并成一条关于这个项目认证方案的完整记忆。

第四层：长期记忆 高频被召回的记忆提升权重，长期不用的记忆自动衰减。过了衰减阈值的记忆会被标记为 "forgettable"，再过一段时间自动清理。

每条记忆还带一个置信度分数。新记忆置信度低，被多次召回验证后置信度上升。这个设计来自 Karpathy 提的 LLM Wiki 模式。

和现有方案比一下

我之前试过 mem0 和直接用 CLAUDE.md，说下体感差异：

CLAUDE.md / .cursorrules 手动维护，写到 200 行就开始膨胀。每次 context window 都会全量加载，一个 240 行的 CLAUDE.md 吃掉 22000+ token。而且内容会过时------上个月写的架构决策，这个月可能已经改了，但你忘了更新文件。

mem0 需要外接向量数据库（Qdrant 或 pgvector），不能自动捕获，得自己调 add() 方法往里写。在 LoCoMo 基准上 R@5 是 68.5%。

agentmemory 零外部依赖，全部存在本地 SQLite。12 个 Hook 自动捕获，不用手动写入。token 消耗约 1900/会话（$10/年），比 CLAUDE.md 的 22000/会话少了一个数量级。

数据放一起看：

方案	自动捕获	搜索方式	R@5	外部依赖	token/会话
CLAUDE.md	手动	全量加载	N/A	无	22000+
mem0	手动 add()	向量+图谱	68.5%	Qdrant/pgvector	不定
Letta/MemGPT	Agent自编辑	向量	83.2%	Postgres+向量DB	不定
agentmemory	12 Hooks 自动	BM25+向量+图谱	95.2%	无(SQLite)	~1900

接入其他 Agent

除了 Claude Code，agentmemory 支持十几个 Agent。接入方式分三种：

Hook + MCP（最完整） Claude Code、Codex CLI、OpenCode 支持这种方式。Hook 负责自动捕获，MCP 负责主动查询。

bash 复制代码

agentmemory connect claude-code
agentmemory connect codex

纯 MCP Cursor、Gemini CLI、Cline、Windsurf 用这种方式。没有自动捕获，但可以通过 MCP 工具手动存取记忆。

在 Cursor 里加 MCP 配置：

json 复制代码

{
  "mcpServers": {
    "agentmemory": {
      "command": "npx",
      "args": ["-y", "@agentmemory/mcp"],
      "env": {
        "AGENTMEMORY_URL": "http://localhost:3111"
      }
    }
  }
}

REST API Aider 之类不支持 MCP 的工具走 HTTP 接口：

bash 复制代码

# 存一条记忆
curl -X POST http://localhost:3111/agentmemory/memory \
  -H "Content-Type: application/json" \
  -d '{"content": "项目用 Prisma 做 ORM，数据库是 PostgreSQL 15"}'

# 搜索记忆
curl "http://localhost:3111/agentmemory/search?q=数据库配置"

关键的一点：所有 Agent 共享同一个记忆服务。在 Claude Code 里做的认证配置，切到 Cursor 也能搜到。

踩过的几个坑

npx 缓存问题 第一次用 npx @agentmemory/agentmemory 启动后，后面即使有新版本发布，npx 还是会用缓存的旧版。解决办法：

bash 复制代码

# 强制拉最新
npx -y @agentmemory/agentmemory@latest

# 或者清缓存
rm -rf ~/.npm/_npx && npx @agentmemory/agentmemory

建议直接全局安装，省心：

bash 复制代码

npm install -g @agentmemory/agentmemory

Codex Desktop 的 Hook 不生效 Codex CLI 的 Hook 引擎（codex-rs/hooks/src/engine/discovery.rs）能正常分发 plugin-local 的 hooks.json，但 Codex Desktop 版本目前有 bug（openai/codex#16430），Hook 不会触发。MCP 工具照常用，只是自动捕获功能缺失。

临时方案是把 Hook 配置写到全局的 ~/.codex/hooks.json：

bash 复制代码

agentmemory connect codex --with-hooks

记忆膨胀 跑了一个多月后，SQLite 文件涨到了 200MB 左右。agentmemory 有自动衰减机制（第四层的 auto-forget），但衰减周期默认比较长。如果记忆增长太快，可以手动触发清理：

bash 复制代码

# 看下当前记忆状态
curl http://localhost:3111/agentmemory/stats

# 手动触发整理
curl -X POST http://localhost:3111/agentmemory/consolidate

doctor 命令 遇到问题先跑诊断：

bash 复制代码

agentmemory doctor

它会检查服务状态、Hook 注册、MCP 连接、记忆数据完整性，发现问题还会给修复建议。

适合什么场景

用了两周下来，我觉得 agentmemory 在这些场景下收益最大：

长期迭代的项目------项目代码量大、架构决策多，每次开会话不用重新解释技术栈
多 Agent 协作------Claude Code 写代码，Cursor 做 review，共享记忆让切换更顺滑
团队项目------新成员接手时，Agent 已经"知道"项目的历史决策和踩过的坑

不太适合的场景：一次性脚本、临时调试、不太需要上下文延续的零散任务。这些场景 CLAUDE.md 写几行就够了，没必要多跑一个服务。

小结

agentmemory 做了一件该做的事------把 AI 编码 Agent 的上下文问题从"手动维护文件"推到了"自动捕获 + 智能召回"。混合搜索的 R@5 95.2% 说明召回质量不错，1900 token/会话的消耗也控制得住。

代码开源在 rohitg00/agentmemory，MIT 协议。想试的话一条命令就能跑起来：

bash 复制代码

npx @agentmemory/agentmemory