1. 为什么 Claude Code 需要 agentmemory
Claude Code 用久了会遇到一个很具体的问题：每次开新会话，它就像失忆一样，昨天刚讨论过的架构决策、踩过的坑、约定好的命名规范，今天全都不记得。CLAUDE.md 能解决一部分——你可以把项目规范写进去，但它本质是人工维护的静态文档，记录的是「应该怎样」，而不是「实际发生了什么」。
agentmemory 补的正是这块。它通过 hooks 在 Claude Code 的生命周期里自动捕获会话中的关键观察，定期合并成结构化记忆，再经过多次强化升级为高置信度的长期记忆。整个过程异步、非阻塞，不会拖慢 Claude Code 的响应。它提供 MCP 工具通道，支持混合检索（BM25 + 语义），官方在 LongMemEval 上的 R@5 达到 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.json
3.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)" } ] } ] } }这里注册了三个关键 hook：PreToolUse 捕获 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)显式展开，能省掉很多「为什么昨天还好今天就不触发」的排查时间。
