claude-mem 拆解：110k star 的记忆层，怎么把「会话里干过什么」捕获、压缩、回注进下一次会话

admin@yesmiracle.net (万戈) — Tue, 03 Nov 2026 00:00:00 +0000

claude-mem 现在的星数是 110,816，fork 9,661，Apache-2.0，TypeScript 写的，作者 Alex Newman，仓库 2025 年 8 月底建，版本号已经跑到 15.9.0。一句话说清它做什么：它挂进你的编码 agent 生命周期，把会话里每次工具调用捕获下来，交给一个后台进程用模型压成结构化的「观察」，下次会话开始时按预算把相关的那几条回注进上下文。

记忆类工具今年不少，站内前面也拆过几个，所以先说清楚这篇的价值在哪。它的星数不构成理由。我拆它的理由是两个：第一，它把记忆这件事拆成了一条可以逐段验证的流水线，而这条流水线里最讲究的部分落在注入预算这一层，压缩反倒更容易做对；第二，我在读源码的过程中核出四处文档和代码打架的地方，这四处比任何功能列表都更能说明一个十万星项目现在处在什么阶段。

先说四条 hook 和三层存储的骨架，再说这几个打架的地方。

捕获层：五个 hook，和一次 250 毫秒的捎信

它的钩子注册在一个文件里，全部命令形如 claude-mem hook claude-code <event>。五个事件各自干一件事：会话开始拉上下文、用户提交 prompt 时记录身份、每次工具调用后捕获观察、agent 停止生成时写会话摘要、会话结束时收尾。PostToolUse 和 PostToolUseFailure 共用同一个 handler，工具成功和失败都会被记下来，这点比只记成功要诚实。

真正值得说的是它怎么做到「不拖慢你的 agent」。多数同类工具的做法是 hook 里发一个 HTTP 请求给后台服务，尽量做成非阻塞。claude-mem 不是这么做的，它连那个请求都不发。

src/cli/spool-hook-event.ts 里，handler 只做两件事：把事件序列化落盘到一个 spool 目录，然后「戳」一下 worker 让它来取。那个戳的动作有一个 250 毫秒的超时，而且源码注释把边界划得很死：这个调用永远不启动 worker，也永远不因为失败而报错。配套的一行注释解释了这么做的原因：一次写 hook 已经把事件放进 spool 并开始捎信了，就让它落地，最多 250 毫秒。

会话结束那条更极端。session-end.ts 的文件头注释写着：Claude Code 给插件的 SessionEnd hook 只有 1.5 秒预算，所以这个 hook 只把请求放进 spool 并戳一下 worker，它从不等待 worker。也就是说，你的会话关掉之后，压缩和入库还在后台继续跑。

这个设计带来一个直接的工程结论：捕获的可靠性不依赖后台进程活着。后台挂了，事件还在磁盘上排队，等它起来再消费。

捕获什么、跳过什么，代码里有五道过滤。递归调用自己的记忆工具会直接短路返回，避免自己记录自己。被排除的项目整个跳过。subagent 产生的观察会被丢弃，注释写的理由很实际：要在任何 worker 请求或 provider 调用之前丢掉它们，防止 Dynamic Workflows 的扇出把 provider 配额耗光。还有工具白黑名单，以及环境变量级的整体关闭。

每条记录叫 observation，字段有十六个左右，包括标题、副标题、叙事、概念、读过的文件、改过的文件、prompt 序号，以及两个很关键的：discovery_tokens 和 occurrence_count。

类型标签一共九种，权威定义在一个 route 文件的常量里：decision、bugfix、feature、refactor、discovery、change，加上 security_alert、security_note、sensitive。要注意这九种是观察模型按提示词自己挑出来的，代码里没有按规则判定的启发式。提示词里那一段写得很明确，要求必须是这九种之一，不许有别的值。

最后一种 sensitive 的定义值得单独抄下来，原文列的是「内部 URL、未发布计划、个人细节、业务指标、客户或合作方名字」这类信息。它是个语义标签，跟密钥检测没关系。这一点后面讲隐私时会再碰到。模型也可以选择什么都不记，判据是回一句特定的跳过标记，理由写 noise。

压缩层：跑在 Bun 里的后台 worker

后台进程是 src/services/worker-service.ts。它导入了 import type { Database } from 'bun:sqlite'，也就是说它跑在 Bun 而不是 Node 上，这在 TypeScript 项目里是个明确的技术选择。

端口这里有个坑，因为不少二手资料写错了。默认端口是 37700 加上你的 uid 对 100 取模，流传较广的 37777 属于另一个组件，host observer。仓库自己的 UI 代码里还硬编码了 37777 当本地 worker 地址，两处不一致，可以算是它自己的小 bug。

默认用于压缩的模型是 Haiku 别名，provider 默认走订阅制的 Claude。模型别名的解析在 model-aliases.ts，层级路由的注释写着一句很实在的话：默认设置下，简单层和主模型都是 Haiku。

压缩就是把原始工具调用变成结构化观察，靠的是一段提示词。它要求的输出骨架长这样：

<observation>
  <type>[ decision | bugfix | feature | refactor | discovery | change | security_alert | security_note | sensitive ]</type>
  <title>…</title>
  <subtitle>…</subtitle>
  <facts><fact>…</fact>…</facts>
  <narrative>…</narrative>
  <concepts><concept>…</concept>…</concepts>
  <files_read><file>…</file>…</files_read>
  <files_modified><file>…</file>…</files_modified>
</observation>

输入那边是另一层包装，把这次工具调用包成一个「从主会话观察到的东西」的块，里面有工具名、发生时间、工作目录、参数和结果。参数或结果太长时会被截成头尾两段并插一个省略标记，而不是丢掉整条。这个细节说明它更怕丢信息，不怕截断。

提示词里塞了一段系统身份，要求很直接：记录学到了什么、建了什么、修了什么、部署了什么、配了什么，而不是记录观察者自己在做什么。角色那段更狠，明确写着这个观察者是静默的、绝不去联系或通知任何其它 agent 或会话。

把这两段放在一起看，能看出它的自我定位：它不是一个协作的 agent，它是一个躲在旁边的记录员。这个定位决定了它不参与你的任务，也因此不会改变你的任务结果。

存储层：三张表，靠迁移长宽

数据库默认在 ~/.claude-mem/claude-mem.db，SQLite。三张主表：会话、观察、会话摘要。

这里有个我觉得挺值得抄的细节。基础版的 observations 表非常窄，只有 id、会话 id、项目、文本、类型、时间这么几列。后来它靠一连串迁移把这张表重建了两次，才长成现在带标题、副标题、facts、narrative、concepts、读写文件列表、token 统计的样子。代码里是 observations_new 这种重建写法。

也就是说，它一开始只想存一段文本加一个类型，是后来才意识到「一条观察需要这么多维度才能被有效检索回来」。这个演化路径比最终的 schema 更有信息量。

全文检索用的是 SQLite 的 FTS5，而且是外部内容表：索引表不存内容，指回 observations 表，配触发器同步。这个选择很省空间。有意思的是它还准备了一个探测语句，如果目标环境编译的 SQLite 不支持 FTS5，就降级到向量库加 LIKE 查询，而不是直接崩掉。

向量层是可选的 Chroma，默认开、默认本地模式，靠一个 MCP 子进程管理，依赖 uv。混合检索就是 FTS5 的关键词加 Chroma 的向量。

回注层：功夫在预算上

回到我最开始说的那句话，这条流水线里最讲究的是回注，不是压缩。

会话开始时注入的是什么，在 AgentFormatter.ts 里有模板原文。它先给一个带项目名和时间戳的标题行，然后是模式名，接着一行说明格式，然后是统计行，形如「多少条观察、读了多少 token、干了多少 token 的活、省了多少、省了百分之几」。再往下是按天分组的日期标题，每一条是一行表格：ID、时间、类型图标、标题。最后一行告诉你还能怎么取更多。

这个格式里藏着它的设计意图：注入给你的是一张索引，不是原文。你知道有哪些活干过、大概是什么、花了多少 token，需要细节时再用 ID 去取。

数字上，预算是硬性的：注入输出上限一万个字符，默认最多五十条观察，并且默认只包括当前这个 harness 的记录。候选的裁剪有一个专门的预算函数，还有一个终端横幅的预留量。

三层检索的成本阶梯是它反复宣传的东西：第一层搜索返回 ID、标题、日期、类型的紧凑索引，每条约 50 到 100 token；第二层时间线给一条观察前后发生了什么，每条约 100 到 200 token；第三层按 ID 批量取全文，每条约 500 到 1000 token。README 里给的总账是省了大约十倍 token。

这里我要把几个数字的性质说清楚，因为二手转述经常把它们混成一件事。那个被引用最多的对照是：天真的做法一次性把三万五千 token 塞进上下文，其中真正相关的只有两千左右，信号率 6%。这个数字有一手出处，在仓库的 docs/public/progressive-disclosure.mdx 里，配了一张 ASCII 图，还写了一句话：把 94% 的注意力预算浪费在不相关的上下文上。同一个文档的另一处写着「相关 token 占总上下文超过 80%」。

但这两处的位置不一样。6% 那处是在描述现状，80% 那处出现在一个评估标准或目标的段落里。仓库里没有任何可复现的 benchmark 脚本或数据能证明 80% 达成过。所以准确的写法是：6% 是作者文档给出的现状描述，80% 是同一份文档给出的目标指标，而那个十倍的节省也只是 README 的说法，没有基准支撑。这三个数字都不该被当成实测结论引用。

这不是要否定它的方向。索引加按需展开这个设计本身是对的，而且它连「取一条要花多少 token」都摊开告诉模型，这一点比多数记忆系统都诚实。我只是认为，一个项目自己文档里的目标值，不该在传播过程中长成实测值。

它已经不只是一个本地插件了

这是我读源码时发现的更大的变化，也是站内前面几篇记忆层文没有覆盖到的部分。

仓库根目录下有三个服务目录：services/sync-hub、services/sync-api、services/viewer-host。第一个是部署在 Cloudflare Workers 上的同步中枢，后两个部署在 Fly.io。客户端那侧，CloudSync.ts 的文件头注释把协议写得很完整：数据库本身就是队列，每一行记忆带一个 synced_at 列，为空表示还没进中枢的日志；线上契约是往 {hubUrl}/v1/sync/ops 发 POST，协议版本 2；单个正文最大 256,000 个 UTF-8 字节，单个请求压在 4 MB 和 500 个操作以下。

服务端那侧有一个 2,363 行的 Postgres 路由文件，注册了二十六条 /v1/* 路由，从用量、密钥、事件、观察、搜索、时间线一直到 MCP over HTTP，配了认证、限流、月度配额三个中间件。它还有一份 docker-compose，里面有 Postgres 和 Valkey。

托管端点是 sync.cmem.ai。

现在说边界。默认配置下云同步是关闭的，判据是中枢 URL 为空，源码注释就写着「空表示同步关闭」。默认运行时也还是本地 worker 而不是 server。所以「本地优先」这个说法在默认配置下是成立的。

但边界文档和仓库内容之间有个张力，值得写出来。项目的许可文档和一份 IP 边界文档都明确说，托管的云、团队同步、管理后台、SSO、企业权限这些属于「保留在 Apache-2.0 公开实现之外」的区域。然而这些同步服务的代码就躺在公开仓库里，而且三个服务目录里都没有 LICENSE 文件，其中 sync-hub 的 package.json 明确标着 private: true。

我的判断是这样的：这不是偷偷闭源，因为代码确实公开可读；但它意味着这个仓库的许可覆盖范围比看上去要窄。Apache-2.0 那份 LICENSE 覆盖的是记忆引擎、CLI、SDK、适配器和 MCP 工具那一套，作者自己那份生产部署的产物既没有跟着开源协议，也没有标成私有仓库。对要拿它进企业的团队来说，这是一条需要自己走一遍法务的线：你能用的是引擎，不能默认那三个服务的代码也在同样的许可下。

顺带一句成本上的一手数据：那个同步中枢的部署文档里写了它的降级路径成本，大约每人每月三分钱。这是个很小的数目，但它是作者自己写在仓库里的，比任何推测都可靠。

隐私：默认值选得好，但有两个开关要自己想清楚

默认不出数据，这一条是站得住的。默认运行时是本地 worker，云同步 URL 为空，截图和图像推理默认关，媒体采集默认关。

但有两个开关的默认值会让不读文档的人意外。

第一个是脱敏。它内置了二十多个厂商的密钥正则，从 AWS 的这两个前缀、GitHub 的几种 token、OpenAI 和 Anthropic 的 key、Slack、Stripe、Google、GitLab、HuggingFace、npm、Docker、Shopify、PyPI，一直到它自己的 key 前缀，写得相当全。还有一层低置信的通用规则（密码、通用 token、Bearer、Basic），默认关。超长字段会整体替换成一个 oversize 标记，属于失败时朝安全的方向倒。但整个脱敏功能默认是关的，源码那一行的注释解释了原因：默认 false，这也是面向用户的文档默认值。

第二个是 sensitive 这个类型。前面说过它只是个语义标签，由模型判定。而配置里它被用作推送触发条件：Telegram 触发器默认包含 security_alert 和 sensitive，Grok bot 的 awareness 推送默认包含四种，其中有 sensitive。Grok bot 那条会把这类观察追加写进一个按月组织的 markdown 日志里，默认开着。

我没有在同步或压缩路径里找到任何「把 sensitive 类型排除在外」的过滤逻辑，也没有找到加密相关的代码。同步走 HTTPS 加 Bearer token，本地库是明文 SQLite。

所以结论是：默认配置是收敛的（都关），但如果你同时打开云同步又不开脱敏，你等于把原始的工具调用内容推到了外部基础设施上，而那个 sensitive 标签不会替你挡住任何东西。它挡的是「模型下次不该把这条带进新任务」，不是「这条不该出你的机器」。这两件事长得很像，但完全不是一回事，我认为这是这类工具最容易被误读的一点。

还有一份代码值得给个好评：PrivacyCheckValidator.ts 只有五十一行，它区分两种情况，一种是用户 prompt 的记录行根本不存在（注释明确写着这不是隐私信号，放行并告警），另一种是行存在但被剥空了（说明用户真的隐藏了这一轮，抑制）。能把「数据缺失」和「用户主动隐藏」分开处理，是很细的地方。

工程体量：和昨天那篇正好是两个极端

这里可以直接和昨天那篇对照。

claude-mem 的源码是 654 个 TypeScript 文件、159,659 行。测试是 1,156 个文件、219,924 行，测试比源码多出 38%。而且我去看了测试目录里装的是什么：最大的一项 tests/worker/ 占 62,235 行，而 fixtures 只有 1,555 行。也就是说那 22 万行里绝大部分是按源码模块镜像写出来的测试代码，不是测试数据。这个比例不是摆设。

体量上它高度集中：src/services/ 一个目录占全部源码的 54%。最大的单文件是 src/services/sqlite/SessionStore.ts，5,055 行；第二是 npx 安装器的 install.ts，3,548 行；后面还跟着一串两三千行的文件，从 worker 工具、Postgres 路由、Chroma 同步，一直到 worker 主服务。

行数约定方面，它有 109 个源文件超过 400 行，最大的七个都超过两千行。也就是说没有任何文件长度约束。

而昨天那篇的 agent-desktop 是另一个极端：2,741 个 Rust 文件，最大值恰好 400 行，超过 400 行的 0 个，而且这条规则被写进开发规范、由一个会给自己灌违规样本的脚本在 CI 里强制。

这两个极端没有谁对谁错。一个 400 行硬上限的代码库，说明它把「可被人逐行读完」当成前提；一个单文件 5,055 行的代码库，说明它把「改动的速度和覆盖面的完整」放在了前面。前者的更新频率应该很慢，后者的更新频率很快：claude-mem 的 CHANGELOG 已经 9,308 行，最近几天几乎每天都在发新版本，11 月 1 日到 2 日之间发了五个版本。

近每日多次发布加上二十二万行测试，这两个数字是配套的。发得快就得测得多，否则回归面撑不住。这一点是它工程上最值得认可的地方。

它能挂在哪些 agent 上

安装是一条命令加一个 IDE 参数，装完会在宿主的配置里写两处：指定 claude-mem 作为记忆 provider，以及注册它的 MCP 服务。

有一点很多人会踩：npm install -g claude-mem 只装 SDK 和库，它不会帮你注册 hook，也不会起 worker 服务。要真正用起来得走安装器。

它宣称支持的宿主里包括 Hermes，所以我专门看了那份集成。它是 642 行纯标准库的 Python，一张明确的事件映射表：轮次开始映射到初始化会话、工具调用后映射到记录观察、预取映射到语义检索、系统提示词块映射到取注入上下文，连宿主自己写的记忆笔记都会被转成 claude-mem 的笔记。超时给得很克制：写 5 秒、读 3 秒，连续失败 3 次就开 30 秒熔断；所有写操作走一个后台线程保证顺序，注释写着宿主永不等待它们。这份集成来自社区，署名和主项目作者并非同一人。

这里也有一处文档与实现对不上：README 的徽章里列了 Copilot，但仓库根目录下没有对应的集成目录。

文档和代码打架的四处

把这几处集中列一下，因为它们的性质不一样。

工具数量。README 说四个 MCP 工具，正文里只点出了三个名字。而源码里实际注册了二十六个，多出来的包括语料库系列、工作状态、团队检索这些。这个不一致属于纯文档没跟上代码。

端口号。默认 worker 端口是 37700 + uid 对 100 取模，不是流传较广的 37777，后者是另一个组件的。而且仓库自己的 UI 里还硬编码着 37777，属于代码内部的不一致。

许可边界。前面说过，这是四处里唯一有实质影响的一处，因为它直接影响你能不能把某段代码当成 Apache-2.0 来用。

默认模型。网上不少介绍会说它默认用某个便宜的 Gemini 小模型来压缩。代码里的默认是 Haiku，Gemini 那条线只有在你显式选择 provider 时才用。我在仓库里没有找到任何支撑「默认 Gemini 加对应成本」的说法，唯一出现过那个模型名的地方是一个第三方的模型流行度数据文件。这属于二手传言。

把这四处放在一起，我的判断是：一个十万星、近每日多次发布的项目，文档已经明显跟不上代码了。前两处只是需要读者自己核一下源码；第三处需要读它的人自己判断合不合规；第四处说明这个项目的传播量已经超过了它自己能维护准确度的范围。这不是它的独有问题，任何涨到十万星的工具都会经历这一阶段，但作为要用它的人，你得知道自己在读哪一版真相。

我的结论

站内前面拆过记忆层的三个方向：腾讯那套四层金字塔管线、用明文文件树当第三极的做法、以及一篇把记忆拆成四层的通用工程方案。claude-mem 的路子是第三种形状：不去设计记忆的层次，而是设计一条从会话到下一次会话的流水线，把中间每一步都做成可以单独替换和验证的环节。

它的价值我认为集中在两点。第一，捕获那一层的 spool 设计是对的：把可靠性从「后台进程活着」里解耦出来，代价只是一次 250 毫秒的捎信。第二，注入那一层的索引化是对的：给你一张带 token 成本的地图，而不是一堆原文。

它需要你留心的地方也很清楚。文档里那几个漂亮的百分比，性质各不相同，其中至少一个是目标值。以及那条「引擎开源、部署产物不开源」的边界，落在同一个仓库里，却没有许可证跟着。

真正决定这类工具好不好用的，从来不在「记不记得住」上，而在它记下了什么、什么时候把什么拿出来、以及那些被记错的东西会不会被反复放大。它在这三件事上前两件做得比多数同类扎实，第三件我还没看到明确的治理机制：仓库里有近重复检测和合并，但我没有找到针对过时记忆的保留策略或半衰期逻辑。这大概是记忆层下一个要打的仗。

想把记忆拆成四层的通用工程方案先看一遍，见《Agent 记忆系统设计：从上下文窗口到跨会话持久化，一套能落地的工程方案》；想知道另一条完全不同的路（不建库、直接写明文文件树）怎么走，见《AI Agent 记忆层的「第三极」：明文文件树用 200–900 个 token 记住一切》；而记忆再多也救不了长程会话的思维死局，那个问题见《长程运行的 Agent 如何保证不会陷入思维死局》。

SQLite on AI博士 万戈