Claude Code × agentmemory：深入原理与最佳实践

摘要：本文深入解析 Claude Code 与 agentmemory 的集成原理与最佳实践。agentmemory 通过异步 hooks 自动捕获会话中的关键观察（Observations），定期合并为结构化记忆（Memory），并强化为高置信度长期记忆（Crystal）。它提供 53 个 MCP 工具，支持混合检索（BM25 + 语义），召回准确率（R@5）达 95.2%。最佳实践包括：优先项目级连接、会话结束前手动总结、主动使用 /agentmemory:recall 等命令、定期清理低质量记忆，并与 CLAUDE.md 形成互补——CLAUDE.md 记录“应该怎样”，agentmemory 记录“实际发生了什么”。

---

---

记忆的生命周期

理解 agentmemory 的核心，需要先搞清楚一条记忆从产生到被召回的完整路径：

原始会话内容
    │
    ▼ hooks 捕获
Observation（观察）
    │
    ▼ 定期合并（LLM 或 BM25）
Memory（记忆条目）
    │
    ▼ 结晶化（crystallize）
Crystal（高置信度长期记忆）
    │
    ▼ 语义检索 + BM25
Recall（召回注入上下文）

Observation

最原始的记忆单元。每次会话中，hooks 自动将以下内容标记为 Observation：

• 用户的关键 prompt
• Claude 做出的重要决策
• tool call 的输入输出摘要
• 代码变更的上下文

每条 Observation 带有时间戳、项目路径、重要性评分（0–10）。

Memory → Crystal

Observations 随时间积累后，agentmemory 定期触发合并流程：将同一主题的碎片观察整合成结构化的 Memory 条目，再经过多次验证强化的条目升级为 Crystal（晶体）——高置信度、长期保留的知识。

这个过程类似人类的记忆巩固：短期记忆通过反复强化变成长期记忆。

---

Hooks 机制

agentmemory 注册 12 个 hooks，覆盖 Claude Code 的完整生命周期：

Hook 时机	触发动作
PreToolUse	捕获 tool 调用意图，更新工作上下文
PostToolUse	记录 tool 执行结果，提取关键信息
Notification	处理 Claude 的状态通知
Stop（会话结束）	触发记忆合并 pipeline，写入本次会话摘要

关键设计：hooks 是异步、非阻塞的。它们在后台执行，不会让 Claude Code 的响应变慢。

hooks 写入项目的 .claude/settings.json（按项目连接时）或 ~/.claude/settings.json（全局连接时），格式如下：

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "",
      "hooks": [{"type": "command", "command": "agentmemory hook pre-tool ..."}]
    }]
  }
}

---

MCP 工具分类

53 个 MCP 工具按功能分为几类：

核心记忆操作（始终可用）

工具	说明
memory_save	手动保存一条记忆
memory_recall	语义检索相关记忆
memory_smart_search	混合检索（语义 + BM25）
memory_sessions	列出历史会话

高级操作（需服务运行）

工具	说明
memory_consolidate	手动触发记忆合并
memory_crystallize	将记忆升级为 Crystal
memory_export	导出记忆为 Markdown
memory_governance_delete	审计删除特定记忆

注意：MCP shim 在没有服务运行时退化为 7 个核心工具。完整 53 工具需要 agentmemory 服务在 3111 端口运行。

---

存储架构

agentmemory 的存储完全本地，无外部依赖：

~/.agentmemory/
├── data/          # KV 存储（记忆条目、会话索引）
├── vectors/       # 向量索引（语义检索）
└── .env           # 配置文件

召回策略：Hybrid Search

1. BM25 全文检索：基于关键词，无需 GPU，速度快
2. 向量语义检索：使用本地 all-MiniLM-L6-v2 模型，捕捉语义相似性
3. 重排序：综合两者分数，返回最相关的结果

官方 benchmark（LongMemEval）：R@5 = 95.2%，即检索 5 条结果中有 95.2% 的概率包含正确答案。

---

实时 Viewer

访问 http://localhost:3113 打开 Viewer，提供：

• Live 面板：实时观察当前会话的记忆写入过程
• Replay 面板：选择任意历史会话回放，逐步查看 prompts、tool calls、responses
• Memory 面板：浏览所有存储的记忆条目、Crystal、会话列表

Viewer 是调试和理解「Claude 现在知道什么」的最直观方式。

---

最佳实践

1. 项目级连接优于全局连接

不同项目有不同的上下文，混在一起反而降低召回精度。对每个重要项目单独执行 agentmemory connect claude-code。

2. 会话结束前做一次手动总结

# 在会话末尾告诉 Claude：
请用 memory_save 保存本次会话的关键决策和注意事项

Stop hook 会自动做合并，但手动触发一次能确保重要信息被标记高优先级。

3. 利用 /agentmemory:recall 主动检索

新会话开始时，上下文注入是自动的，但对于跨项目的通用知识，可以主动触发：

/agentmemory:recall  # 检索与当前任务相关的历史记忆
/agentmemory:handoff # 恢复上次会话的断点
/agentmemory:recap   # 查看近期会话摘要

4. 定期清理低质量记忆

记忆积累过多会引入噪音。使用 Viewer 定期审查，或：

# 通过 MCP 工具审计低置信度记忆
memory_audit

5. 不适合存入记忆的内容

• 临时调试代码和一次性 patch
• 包含敏感信息（密钥、密码）的内容——agentmemory 有隐私过滤，但最好避免
• 频繁变动的配置值

---

与 CLAUDE.md 的关系

agentmemory 和 CLAUDE.md 是互补的：

	CLAUDE.md	agentmemory
内容	人工维护的规范和约定	自动捕获的会话历史和决策
更新	手动	自动
适合	项目规范、架构说明	「上次为什么这么做」「踩过什么坑」

实践建议：CLAUDE.md 写「应该怎样」，agentmemory 记「实际发生了什么」。