5 分钟体验：先感受问题，再理解问题
在讲理论之前，先花 5 分钟亲自体验”有记忆 vs 无记忆”的区别。
实验步骤（需要已安装 Claude Code）：
# 1. 安装 claude-mem
npx claude-mem install
# 2. 重启 Claude Code，开始第一次会话
claude
# 输入："帮我在当前目录创建一个 hello.ts，里面导出一个 greet 函数"
# Claude 会创建文件。完成后退出会话（Ctrl+C 或 /exit）
# 3. 开始第二次会话
claude
# 输入："继续刚才的工作"
# 观察：Claude 会知道你刚才创建了 hello.ts，并能继续在此基础上工作如果你不想现在安装，也没关系——这个体验贯穿全书，任何时候都可以回来做。关键是理解：第二次会话中 Claude 之所以”记得”第一次做了什么，是因为 claude-mem 在 SessionStart 时自动注入了历史上下文。
下面开始分析这个问题的本质。
AI Agent 的”金鱼记忆”困境
打开一个新的 Claude Code 会话，输入”继续昨天的工作”。
Claude 的回答大概率是：“我没有之前会话的上下文，能否告诉我昨天在做什么？”
这就是 Agent Memory 问题的本质：每次会话都是一张白纸。LLM 没有持久化的工作记忆，上一轮对话中积累的所有认知——代码结构的理解、Bug 的定位过程、做出的设计决策——在会话结束时全部消失。
对于一次性的问答场景，这无所谓。但对于软件工程这种需要持续数天甚至数月的工作，记忆缺失的代价是巨大的：
第 1 天：花 30 分钟探索项目结构，理解核心模块关系
第 2 天：新会话，Agent 再花 30 分钟做同样的事
第 3 天：同上
...
第 N 天：同样的 30 分钟浪费了 N 次更严重的是决策记忆的丢失。第 1 天你和 Agent 讨论后决定用方案 A 而非方案 B，第 2 天 Agent 可能又建议方案 B——它不记得 A 的选择以及背后的理由。
会话间上下文断裂的代价
把这个问题量化：
时间成本：一个中等复杂度的项目，每次新会话需要 3-5 分钟的上下文重建。按每天 5 次会话计算，一周浪费 1-2 小时纯粹在”让 Agent 回忆”上。
质量成本：没有历史决策记录，Agent 可能给出与之前矛盾的建议。更危险的是——当它”忘记”某个已知的 Bug 或边界条件，可能引入已经修复过的问题。
认知成本：工程师被迫充当 Agent 的”外部记忆”，每次都要手动复述背景。这违背了用 Agent 提升效率的初衷。
现实中，工程师们发展出各种 workaround：
- 维护一个 CLAUDE.md 文件，手动写入项目约定
- 每次会话开头粘贴一段”背景信息”
- 把重要决策记在自己的笔记里，需要时复制给 Agent
这些做法有用，但都是手动的、不完整的、容易遗忘的。一个好的 Memory 系统应该自动化这个过程。
Memory 系统的三个核心问题
设计 Agent Memory 系统时，必须回答三个问题：
记什么（What to capture）
不是所有信息都值得记录。一次 ls 命令的输出、一个临时的变量赋值——这些是噪音。值得记忆的是：
- 决策：为什么选择方案 A 而非方案 B
- 发现：关键的 Bug 根因、性能瓶颈所在
- 变更：架构级别的代码修改及其意图
- 踩坑：已知的边界条件、已修复的问题
- 进展：任务完成状态、下一步计划
claude-mem 的选择是记录所有 Tool Usage（文件读写、命令执行、搜索等），然后用 AI 压缩提取高价值信息。原始数据全量捕获，智能摘要按需生成。
怎么记（How to store）
存储层面有两个维度的选择：
结构化 vs 非结构化：
- 纯文本存储（如 Markdown 笔记）：简单但难以精确检索
- 结构化数据库（如 SQLite）：支持精确查询，但需要预定义 Schema
- 向量存储（如 ChromaDB）：支持语义搜索——将文本转化为数学向量（Embedding），通过向量距离判断”意思是否接近”，但质量依赖 Embedding 模型
实时 vs 批量：
- 实时写入：每个操作立即持久化，不丢数据但可能影响性能
- 批量处理：积攒后统一处理，性能好但有数据丢失风险
claude-mem 选择了混合方案：SQLite 做结构化存储 + FTS5 全文搜索（SQLite 内置的全文搜索引擎，不需要额外部署 Elasticsearch）+ ChromaDB 做向量语义搜索。写入采用队列异步处理，Hook 端快速入队（< 20ms），Worker 端异步压缩和存储。
怎么用（How to retrieve）
这是三个问题中最关键的。记了 10,000 条观察，新会话开始时该注入哪些？
全量注入：把所有历史数据塞进上下文。问题：Token 窗口有限，大部分信息不相关，注意力被稀释。
智能检索：系统预判哪些信息与当前任务相关，只注入这部分。问题：系统不知道用户接下来要做什么，预判准确率低。
渐进式披露：先给一个轻量级索引（标题 + 类型 + 时间），让 Agent 自己决定需要深入了解哪些。问题：需要 Agent 有”主动搜索”的意识。
claude-mem 选择第三种——Progressive Disclosure。这个选择背后的洞察是：Agent 比系统更清楚当前任务需要什么信息。与其让系统猜，不如给 Agent 一张地图，让它自己导航。
现有方案对比
市面上的 Agent Memory 方案可以分为几类：
RAG（Retrieval-Augmented Generation）
经典做法：把历史信息 Embedding 后存入向量库，每次会话开始时检索最相关的 K 条注入上下文。
优点：概念简单，实现成熟
缺点：预检索无法感知当前任务意图
Token 浪费严重（检索出的信息 60-90% 不相关）
对 Embedding 质量依赖大结构化笔记（Structured Notes）
Agent 在工作过程中主动写笔记（如 TODO.md、NOTES.md），下次会话加载。
优点：Agent 主动管理，信息质量高
缺点：依赖 Agent "记得"写笔记
笔记格式不统一，难以系统化检索
无法自动化，容易遗漏压缩摘要（Compaction）
会话结束时生成结构化摘要，下次会话注入摘要而非原始对话。
优点：信息密度高，Token 效率好
缺点：摘要过程有信息损失
无法精确回溯原始细节
摘要质量取决于压缩 Prompt 设计claude-mem 的组合方案
claude-mem 不是上述任何一种的简单实现，而是结合了三者的优势：
| 维度 | claude-mem 的做法 |
|---|---|
| 捕获 | 自动观察所有 Tool Usage（不依赖 Agent 主动写） |
| 压缩 | AI 生成结构化 Observation（type + title + narrative + facts） |
| 存储 | SQLite + ChromaDB 双引擎 |
| 检索 | Progressive Disclosure + MCP 工具按需获取 |
claude-mem 的设计哲学：Observe → Compress → Inject
claude-mem 的核心工作流可以浓缩为三个动词：
Observe（观察）
通过 Claude Code 的 Hook 系统，非侵入式地监听每次工具调用。Agent 读了什么文件、改了什么代码、执行了什么命令——全部被 PostToolUse Hook 捕获并入队。
关键约束：观察不能影响被观察者。Hook 必须在 20ms 内返回，不能拖慢主会话。
Compress（压缩）
后台 Worker 取出队列中的原始观察，交给 Claude Agent SDK 进行 AI 压缩。从一大段 tool_input + tool_output 中提取出：
- 一个分类标签（decision / bugfix / discovery / …）
- 一个 10 字以内的标题
- 一段简短叙述
- 若干关键事实
- 关联的文件路径和概念标签
这个压缩过程将几千 Token 的原始数据浓缩为几百 Token 的结构化观察。
Inject（注入）
下次会话开始时，SessionStart Hook 注入一个轻量级索引（约 800-2000 Token）。索引只包含标题、类型、时间、预估 Token 数——Agent 通过 MCP 搜索工具按需获取完整内容。
Observe: 全量捕获，不遗漏
Compress: AI 提取高价值信息，降低噪音
Inject: 渐进式披露，让 Agent 自主决定这三步形成一个正向循环：观察越多，记忆越丰富，Agent 在未来会话中能获取的上下文越精准。
思考题
- 如果你正在做的项目只有 3 个文件、开发周期 1 天，Agent Memory 还有必要吗？Memory 系统的 ROI 拐点在哪里？
- claude-mem 选择记录 Tool Usage 而非对话消息作为记忆单元。如果你要为一个前端组件库的 AI 助手设计 Memory，你会选择什么作为观察单元？
- Progressive Disclosure 让 Agent 自己决定”看什么”。但如果 Agent 判断失误（明明相关但跳过了），怎么办？这个设计有什么 fallback 机制？
下一章我们将具体认识 claude-mem 这个项目——它的能力全景、安装方式和日常使用场景。
本书开源发布于 inferloop.dev，转载请注明出处。