那个让你崩溃的瞬间

你已经打开了 Claude Code，跟它讲清楚了你的 monorepo 结构、认证逻辑和数据库设计。终于，它完全理解了你的项目。

第二天，你打开新会话，输入"继续昨天的工作"——它回复："我没有之前会话的上下文。"

重复解释的代价

这不只是烦人的问题，它实际影响你的工作质量。

如果 AI 有一本随身笔记本……

想象你有一位顾问，每次拜访前都会翻一翻他们的工作笔记本，上面记着你们上次讨论的决策、你提到的项目偏好、以及他们自己记录的观察。

claude-mem 就是那本笔记本。它自动运行在幕后，无声地记录每次 Claude 做的事情，然后在下次会话开始时，把相关记忆偷偷注射进去。

理解检验

backstage 的五个演员

就像一台电影的幕后团队——导演、摄影师、剪辑师各司其职，claude-mem 的五个组件各自负责记忆流水线的一个环节。

点击探索每个组件

在代码里找到它们

了解文件结构，你就知道当 claude-mem 出问题时该去哪里找原因。

理解检验

Hook 是什么：快递包裹的追踪系统

想象快递公司的包裹追踪：每次包裹状态变化（揽件、分拣、派送、签收），系统自动在日志里记录一条。你不需要手动打电话问——系统自动帮你记。

Claude Code 的 生命周期钩子也是这样：在特定事件发生时，自动触发 claude-mem 注册的脚本。

真实代码：钩子是怎么配置的

这是 plugin/hooks/hooks.json 里 PostToolUse 钩子的实际配置。

"PostToolUse": [{
  "matcher": "*",
  "hooks": [{
    "type": "command",
    "shell": "bash",
    "command": "node ... worker-service.cjs hook claude-code observation",
    "timeout": 120
  }]
}]

会话启动时：记忆是怎么注入的

SessionStart 钩子做三件事：安装检查、启动 Worker、然后调用记忆注入。

function buildContextOutput(
  project: string,
  observations: Observation[],
  summaries: SessionSummary[],
  config: ContextConfig,
): string {
  const output: string[] = [];
  const economics = calculateTokenEconomics(observations);
  output.push(...renderHeader(project, economics, config));
  output.push(...renderTimeline(observations, summaries));
  output.push(...renderFooter());
  return output.join('\n');
}

PostToolUse 钩子的完整触发流程

当 Claude 执行完一次 工具调用后，发生了什么？

理解检验

为什么不直接存储原始输出？

想象一位编辑看完一部 300 页的初稿，然后写了一段 3 句话的摘要。他不会一字不差地复述全书——他提炼了核心决策、关键转折点、重要发现。

claude-mem 的压缩机制做的正是同样的事：把可能长达数千行的工具输出，提炼成一条简洁的 观察记录。

一条观察长什么样

SDK Agent 使用固定的 XML 格式输出观察，这让结构化存储和检索变得非常可靠。

<observation>
  <type>bugfix</type>
  <title>JWT 刷新竞争条件修复</title>
  <subtitle>Redis GETSET 原子性问题</subtitle>
  <facts>
    <fact>并发刷新触发双写</fact>
    <fact>用 Lua 脚本解决原子性</fact>
  </facts>
  <files_modified>
    src/auth/token-refresh.ts
  </files_modified>
</observation>

记忆是怎么注入到新会话的

SessionStart 钩子触发时，Context Generator 从数据库检索与当前项目相关的记忆，然后把它们格式化成一段文字，悄悄插入到你给 Claude 的第一条消息之前。

Claude 看到的实际上是：

# 项目记忆（由 claude-mem 自动注入）
项目：my-saas-app | 记忆：23 条 | 最近：2 天前

[2025-05-01] bugfix: JWT 刷新竞争条件修复
  并发刷新触发双写；用 Lua 脚本解决原子性
  文件：src/auth/token-refresh.ts

[2025-04-30] feature: 用户档案页面
  实现头像上传 + 压缩；使用 sharp 库
  文件：src/pages/profile.tsx

... 还有 21 条记忆（使用 mem-search 查询更多）

完整记忆管道：捕获 → 压缩 → 存储 → 注入

理解检验

安装：30 秒上手

claude-mem 用 npx 一键安装，自动完成所有配置。

配置文件：调整 claude-mem 行为

所有设置都在 ~/.claude-mem/settings.json，自动生成，可直接编辑。

主动搜索：mem-search 技能

自动注入是被动记忆，mem-search 让 Claude 可以主动检索任何历史记忆。

mem-search 实现了 3 层工作流：先用 search 获取 ID 索引，再用 timeline 看时间上下文，最后用 get_observations 按需获取完整内容。比一次性获取全部节省 10 倍 token。

隐私控制：不想被记录的内容怎么办

有时候你在对话里输入了 敏感信息——比如临时 API key 或者内部凭证。

claude-mem 支持用 <private>...</private> 标签包裹不想被记录的内容：

你： 帮我测试一下这个 API：
<private>
API_KEY=sk-prod-3x7mN2kL9pQ...
</private>
用上面的 key 调用用户 API

→ <private> 标签内的内容不会被 claude-mem 记录

最终综合检验