1. 为什么 Claude Code 需要 agentmemoryClaude Code 用久了会遇到一个很具体的问题每次开新会话它就像失忆一样昨天刚讨论过的架构决策、踩过的坑、约定好的命名规范今天全都不记得。CLAUDE.md 能解决一部分——你可以把项目规范写进去但它本质是人工维护的静态文档记录的是「应该怎样」而不是「实际发生了什么」。agentmemory 补的正是这块。它通过 hooks 在 Claude Code 的生命周期里自动捕获会话中的关键观察定期合并成结构化记忆再经过多次强化升级为高置信度的长期记忆。整个过程异步、非阻塞不会拖慢 Claude Code 的响应。它提供 MCP 工具通道支持混合检索BM25 语义官方在 LongMemEval 上的 R5 达到 95.2%。这篇要解决的是落地问题怎么在本地把 Claude Code 接入 agentmemory 跑通包括 CLAUDE.md 骨架怎么写、settings.json 里 hooks 怎么配、MCP 通道怎么串起来最后演示一次记忆写入与读取的完整验证。适合已经在用 Claude Code、想让跨会话记忆持久化的开发者。2. 前置准备TaoToken 与 agentmemory 服务先说模型通道。Claude Code 需要一个能稳定调用的 API 入口我用的是 TaoToken 的 API 地址https://taotoken.net/api它兼容 Anthropic 的接口格式Claude Code 直接配置就能用。如果你还没配先去控制台拿一个 API Key然后在环境变量里设置好。agentmemory 这边是本地服务存储完全在本地没有外部依赖。它的数据目录结构是这样的~/.agentmemory/ ├── data/ # KV 存储记忆条目、会话索引 ├── vectors/ # 向量索引语义检索 └── .env # 配置文件服务默认跑在 3111 端口Viewer 在 3113 端口。MCP shim 在没有服务运行时只会退化成 7 个核心工具完整的 53 个工具需要服务在 3111 端口正常运行。所以第一步是确认服务起来了# 启动 agentmemory 服务 agentmemory serve # 另开一个终端确认端口 curl http://localhost:3111/health返回{status:ok}就说明服务正常。这一步别跳过后面 hooks 和 MCP 都依赖它。3. 可复制配置CLAUDE.md 骨架与 settings.json3.1 CLAUDE.md 骨架CLAUDE.md 记录「应该怎样」agentmemory 记录「实际发生了什么」两者互补。我的 CLAUDE.md 骨架大概长这样# 项目约定 ## 技术栈 - 语言TypeScript 5.x - 框架Next.js 14 App Router - 包管理pnpm ## 命名规范 - 组件文件用 PascalCase - 工具函数用 camelCase - 常量全大写下划线分隔 ## 架构说明 - API 层统一走 src/lib/api/ - 状态管理用 zustand不用 redux ## 注意事项 - 不要直接改 generated/ 下的文件 - 提交前跑 pnpm lint pnpm typecheck这份文件是给 Claude Code 看的静态规范。agentmemory 会在会话中自动捕获实际决策比如「为什么这个接口要加缓存」「上次那个 bug 的根因是什么」这些动态信息不会写进 CLAUDE.md而是进 agentmemory。3.2 settings.json 的 hooks 配置hooks 写在项目的.claude/settings.json项目级连接或~/.claude/settings.json全局连接。我建议项目级不同项目上下文混在一起反而降低召回精度。配置如下{ hooks: { PreToolUse: [ { matcher: , hooks: [ { type: command, command: agentmemory hook pre-tool --project $(pwd) } ] } ], PostToolUse: [ { matcher: , hooks: [ { type: command, command: agentmemory hook post-tool --project $(pwd) } ] } ], Stop: [ { matcher: , hooks: [ { type: command, command: agentmemory hook stop --project $(pwd) } ] } ] } }这里注册了三个关键 hookPreToolUse 捕获 tool 调用意图并更新工作上下文PostToolUse 记录执行结果并提取关键信息Stop 在会话结束时触发记忆合并 pipeline。agentmemory 一共注册 12 个 hook 覆盖完整生命周期这三个是最核心的。3.3 MCP 通道串联hooks 负责自动捕获MCP 负责主动读写。在 Claude Code 的 MCP 配置里加上 agentmemory{ mcpServers: { agentmemory: { command: agentmemory, args: [mcp, --port, 3111] } } }配好之后Claude Code 就能调用 memory_save、memory_recall、memory_smart_search 这些工具了。核心工具始终可用高级操作consolidate、crystallize、export需要服务在跑。4. 验证请求一次记忆写入与读取配置完别急着用先做一次完整的写入和读取验证确认链路通了。4.1 写入一条记忆在 Claude Code 会话里直接说请用 memory_save 保存这条记忆项目 API 层统一走 src/lib/api/ 所有请求必须经过 request.ts 里的拦截器加 token。Claude Code 会调用 MCP 工具写入。写入成功后去 Viewer 确认# 浏览器打开 http://localhost:3113在 Memory 面板里应该能看到刚写入的条目带时间戳和项目路径。4.2 读取验证新开一个会话测试召回/agentmemory:recall API 层的请求怎么加 token或者直接用 MCP 工具请用 memory_smart_search 检索「API 拦截器 token」如果返回了刚才写入的那条记忆说明 hooks 捕获 MCP 读写 混合检索整条链路都通了。混合检索会同时走 BM25 全文和向量语义再重排序返回最相关结果。4.3 观察 hooks 自动捕获除了手动写入hooks 会在你正常干活时自动记录。做一次 tool 调用然后去 Viewer 的 Live 面板看# 在 Claude Code 里让它读一个文件 请读取 src/lib/api/request.ts 并解释拦截器逻辑Live 面板应该实时出现这次 tool 调用的 Observation带重要性评分。会话结束后Stop hook 会触发合并把碎片观察整合成 Memory 条目。5. 本篇常见错排查5.1 MCP 工具只有 7 个现象调用 memory_consolidate 报工具不存在。原因agentmemory 服务没在 3111 端口运行MCP shim 退化成 7 个核心工具。排查curl http://localhost:3111/health # 如果连不上先启动服务 agentmemory serve5.2 hooks 不触发现象Viewer 的 Live 面板一直空的没有 Observation。原因settings.json 路径不对或者 command 里的$(pwd)没展开。排查确认.claude/settings.json在项目根目录手动跑一次 hook 命令看报错agentmemory hook pre-tool --project $(pwd)如果提示 command not found说明 agentmemory 没在 PATH 里用绝对路径替换。5.3 召回结果不相关现象memory_smart_search 返回一堆无关记忆。原因全局连接导致多项目记忆混在一起或者低质量记忆积累太多噪音。排查改成项目级连接每个项目单独agentmemory connect claude-code。定期用 Viewer 审查通过 memory_governance_delete 清理低置信度条目。5.4 会话结束记忆没合并现象Stop hook 跑了但 Memory 面板没新条目。原因本次会话没有达到合并阈值或者 Observation 重要性评分都太低。排查在会话末尾手动触发一次请用 memory_save 保存本次会话的关键决策和注意事项手动保存能确保重要信息被标记高优先级Stop hook 的自动合并是补充不是替代。6. 把记忆链路用起来跑通之后日常使用有几个习惯能让 agentmemory 发挥更大价值。新会话开始时上下文注入是自动的但跨项目的通用知识可以主动触发/agentmemory:recall恢复上次断点用/agentmemory:handoff看近期摘要用/agentmemory:recap。不适合存进记忆的内容也要注意临时调试代码、一次性 patch、包含密钥密码的敏感信息、频繁变动的配置值这些存进去只会增加噪音。agentmemory 有隐私过滤但最好从源头避免。如果你还没配模型通道先去 TaoToken 控制台 拿 API Key接入文档在 这里。想先验证模型对话效果可以直接用模型对话试。长期跑编码和 Agent 任务的话Coding Plan 更划算。API Key 管理在 API Keys 页面。最后说个我踩过的坑hooks 的 command 里如果用了相对路径Claude Code 在不同工作目录下启动会找不到 agentmemory。统一用绝对路径或者$(pwd)显式展开能省掉很多「为什么昨天还好今天就不触发」的排查时间。
