第 7 课：claude-mem 架构与数据流解析

7.1 自动捕获的工作流

claude-mem 通过 Hook 机制实现全自动的背景记录：

1. SessionStart (会话开始)：注入相关的历史上下文。
2. PostToolUse (工具调用后)：这是最核心的环节。每当 Claude Code 执行完一个工具（如 Edit 或 run_command），Hook 会将本次操作的上下文传给后台 Worker。
3. 蒸馏 (Distillation)：Worker 调用 LLM 将原始交互“蒸馏”成一条结构化的 Observation 记录（包含类型、摘要等）。
4. 存储：记录被写入本地 SQLite 数据库，并生成向量存入 Chroma。
5. Stop (会话结束)：生成本次会话的总结报告。

7.2 检索时的数据流

当 LLM 需要查询历史时，数据流向如下：

• 发起查询：LLM 调用 search MCP 工具。
• 混合检索：系统同时在 SQLite 做全文匹配和在 Chroma 做语义向量计算。
• 返回结果：返回压缩后的 ID 列表。
• 深化背景：LLM 根据需要进一步调用 timeline 或 get_observations 获取详情。

7.3 三层存储抽象

为了平衡性能与功能，claude-mem 构建了三层数据结构：

• 原始层 (Raw)：Claude Code 本身生成的 .jsonl 会话日志（位于 ~/.claude/projects/*/sessions/）。
• 蒸馏层 (Distillation)：claude-mem 提炼出的 Observation 记录，存储在 SQLite 和 Chroma 中。
• 使用层 (Usage)：通过 Hook 注入到 System Prompt 或通过 MCP 工具供 LLM 读取。

7.4 数据隐私与合规

重要提示：虽然数据最终存储在本地，但“蒸馏”过程是需要调用远程 LLM API 的。这意味着：

• 每次工具调用的上下文会被发送给 Anthropic 进行摘要处理。
• 敏感项目可以通过 .claude/settings.local.json 针对性禁用该插件，以确保数据安全。