claude-mem：把 Claude Code 变成可持续工作的记忆外骨骼

先说结论

如果把 Anthropic 官方 Claude Memory 看作“产品内置的工作连续性”，那 claude-mem 更像是一套围绕 Claude Code 搭建的 记忆外骨骼。

它解决的不是“模型能不能记住”，而是更工程化的问题：

• 代码会话如何被自动记录
• 记录如何压缩成可复用知识
• 这些知识如何在下一次 session 里被重新注入
• 如何把历史工作进一步变成可问答的 corpus

所以它不是一个轻量小插件，而是一套完整的 memory harness。

它到底在做什么

claude-mem 的核心链路可以概括成一句话：

capture → store → search → compress → reinject → question-answer

更具体一点：

1. 自动捕获 Claude Code 会话中的工具调用、观察、总结和 prompt
2. 结构化存储 到本地 SQLite
3. 混合检索 通过 SQLite + Chroma 进行过滤和语义排序
4. 上下文压缩 把历史内容组织成更小、更可注入的上下文块
5. 再次注入 到未来 session，减少重复解释和重复读文件
6. 知识代理化 把筛选后的历史构造成 corpus，让你直接问问题

这和很多“记忆产品”的最大差别是：它不是只存历史，而是试图 让历史继续产生生产力。

项目体量和势能

从 GitHub 信号看，这不是个小众玩具：

• 54k+ stars
• 4.3k+ forks
• 250+ open issues
• release 节奏非常快
• 最近版本已经到 v12.1.0

这说明两个事情：

1. 它已经进入了相当大的真实使用面
2. 它的演化速度很快，说明这类“agent memory infrastructure”正在形成明确需求

换句话说，它不只是“有趣”，而是已经开始变成一类实际工作流基础设施。

架构拆解

从 repo 结构看，claude-mem 不是单一模块，而是四层体系。

1. 捕获层：hooks

它通过 hook 把会话里的事件记录下来，而不是靠用户手工写日志。

这很关键，因为记忆系统的质量上限，取决于采集层是不是足够贴近真实工作过程。

它记录的不是“最终答案”，而是：

• 用户输入
• 工具调用
• 文件读取 / 修改
• session 结束与 summary
• 各类 observation

这使它比普通聊天摘要更接近工程上下文。

2. 存储层：SQLite 为中心

src/services/sqlite/SessionStore.ts 是核心数据层。

从 schema 看，它把 memory 拆成了：

• sdk_sessions
• observations
• session_summaries
• user_prompts

这是一种很务实的设计：

• 本地优先
• 结构化
• 可迁移
• 易于按 project / platform 分隔

而且它不是只存“会话文本”，而是存 observation，也就是更接近工程行为的单位。

3. 检索层：SQLite + Chroma 的混合搜索

SearchOrchestrator 用的是分层策略：

• 没有 query 的过滤型搜索：走 SQLite
• 有 query 的语义搜索：优先 Chroma
• 元数据过滤 + 语义排序：用 hybrid strategy 组合

这类架构的优点是：

• 精确过滤不丢
• 语义搜索不死板
• 失败时可以 fallback

这比“全量向量库一把梭”更稳，也更符合本地记忆系统的实际约束。

4. 上下文层：ContextBuilder

ContextBuilder 负责把 observations、summaries 和 timeline 变成真正可注入模型的上下文。

这个阶段做了三件重要的事：

• 组织时间线
• 计算 token economics
• 控制上下文密度

也就是说，claude-mem 真正关心的不是“能不能存很多”，而是 该在什么时机喂什么上下文给模型。

核心机制：它为什么有效

1. 观察先行，而不是结论先行

很多记忆系统只存“总结”，但 claude-mem 更像是先存“行动轨迹”。

这非常适合 coding agent，因为工程工作真正重要的往往不是一句结论，而是：

• 哪个文件被看过
• 哪个文件被改过
• 哪个工具链跑过
• 哪些中间判断成立，哪些不成立

这类信息能帮助未来 session 复原上下文，而不是只记住一个结果。

2. 压缩不是一句摘要，而是层级化分发

它的压缩不是把所有东西揉成一段短文，而是构造不同层次：

• 粗索引
• 时间线
• 详细 observation
• corpus
• knowledge agent

这就是它比普通摘要工具更强的原因：它在做 memory routing，不是单纯做 summary。

3. 检索前先过滤，再做语义排序

HybridSearchStrategy 很有代表性：

• 先用 SQLite 缩小候选集
• 再用 Chroma 做语义排序
• 最后把排序后的 ID 回填完整记录

这个思路非常工程化，因为它兼顾了：

• 召回
• 精度
• 成本
• 可维护性

4. Knowledge Agents：从记忆库到问答库

v12.1.0 的 Knowledge Agents 很重要。

它把筛选后的历史 observations 打包成 corpus，再用 Agent SDK prime 一个可对话 session。

这意味着系统从“找回历史”进一步升级成：

• 对历史做二次抽象
• 把历史变成可问答资产
• 让过去的项目经验可以被持续查询

这一步，是从 memory 向 knowledge 的跨越。

优势与代价

优势

1. 真正解决了 session 断裂问题

Claude Code 这类工具的天然问题就是“每次开新会话就像失忆”。claude-mem 把这件事工程化解决了。

2. 数据模型明确

session / observation / summary / corpus 的分层清晰，后续功能扩展有依托。

3. 检索策略稳

SQLite、Chroma、fallback、dedup、platform isolation 这些都说明作者在认真处理真实生产问题。

4. 已经形成生态位

它不是一个孤立插件，而是插件、MCP、worker、viewer、skills、OpenClaw 支持的一整套系统。

代价

1. 复杂度高

它显然比“记几条偏好”重得多。要理解它，得同时接受 hooks、worker、SQLite、Chroma、session、corpus 这些概念。

2. 对本地环境依赖多

Node、Bun、SQLite、Chroma、Claude Code、插件体系都要配合。

3. 记忆质量依赖采集质量

如果 observation 记录噪声大，后面的压缩和检索再好也救不回来。

4. 合规与许可要认真看

AGPL 对企业使用不是随便能忽略的条款。

它适合谁

最适合

• 重度 Claude Code 用户
• 长期工程项目的 AI 工程师
• 想把 session 历史变成知识资产的人
• 能接受本地优先、可控、可扩展架构的人

不适合

• 想要零配置、轻量记忆的普通用户
• 不愿意折腾插件、worker、数据库的人
• 对 AGPL 许可敏感的商业团队

什么时候该选它

当你已经明显遇到这些问题时：

• Claude 每次重开都要重新解释项目背景
• 你经常重复读同一批文件
• 你希望回看过去的决策路径
• 你想把 session 历史变成可问答知识库

什么时候不该选它

如果你只是想：

• 记住少量偏好
• 让 Claude 保持一点长期上下文
• 不需要复杂检索和 corpus 化

那 Anthropic 官方 Claude Memory 可能更简单。

我的判断

claude-mem 不是一个“简单的第三方 memory provider”，而是一个试图把 Claude Code 变成持续工作台的完整记忆基础设施。

它的价值不在于“记忆更多”，而在于：

• 把 ephemeral session 变成 persistent asset
• 把历史 observation 变成 searchable knowledge
• 把 memory 变成工作流的一部分

如果说官方 Claude Memory 追求的是 可控的工作连续性，那 claude-mem 追求的就是 可编排的工程连续性。

这使它非常值得关注。

一句话总结

claude-mem 是一个把 Claude Code 的短期会话，升级成可搜索、可压缩、可问答、可持续复用的记忆外骨骼。