Claude-Mem（thedotmack/claude-mem）：钩子捕获、AI 压缩、三层检索，给编码智能体装上跨会话的长期记忆

一、导读

编码智能体最大的浪费，不是算力，而是每次新会话都要从头重新认识你的代码库。GitHub 日涨星 1145、总星数超 10.6 万（截至 2026-10-31）的 claude-mem 给出的答案是：用生命周期钩子把每一次工具调用实时压缩成带语义类型的「观察」，落进 SQLite 与 ChromaDB 双库，下一个会话启动时只注入一张约千 token 的紧凑索引，再让模型自己决定取哪些细节。本文拆解它的四层架构、三层检索的 token 账，以及一周前刚爆出的安装器隐私争议。

二、项目速览

维度	信息
仓库	thedotmack/claude-mem
作者	Alex Newman（@thedotmack），100 余名贡献者协作
Star	105,687（截至 2026-10-31，当日 +1145）
语言与许可	TypeScript，Apache-2.0（open-core，云托管部分闭源）
创建时间	2025-08-31，约 14 个月
版本节奏	v15.x，2026-10-23 至 10-29 一周连发 6 个版本（v15.0.2 → v15.6.0）
工程依赖	Node ≥ 20、Bun（Worker 进程管理与 bun:sqlite）、uv（向量检索）、SQLite WAL
支持宿主	Claude Code、OpenCode、T3 Code（Codex/Claude）、Antigravity、Pi、DeepSeek Harness、OpenClaw、Grok Bot、Cursor 等
压缩模型	claude-mem observer（托管，30 天试用）、自有 OpenRouter/Gemini Key、或走 Anthropic 订阅额度
近 4 周活跃度	约 750 次提交（周均 187），开放 issue 53 个

三、为什么是它：涨星动因

第一，它踩中了「智能体记忆」这个正在从可选项变成必需品的位置。Anthropic 在 2025 年 10 月为 Claude 推出官方 Memory 功能时，HN 上相关讨论拿到 559 点、312 条评论——需求侧的热度早已验证。claude-mem 做的是更工程化的一层：官方记忆面向对话产品，它面向写代码的智能体工作流，把「记住」拆成了捕获、压缩、存储、检索四个可观测的环节。

第二，迭代速度快到离谱。近 4 周约 750 次提交，仅 10 月 23 日至 29 日就发出 v15.0.2 到 v15.6.0 六个版本：v15.1 重写了 React 版 My Work 观察面板，v15.2 加入浏览器安装漏斗（这也是后面隐私争议的源头），v15.3 给每张请求卡加了内容寻址的「交付物」快照，v15.4 引入焦点区域自动归类，v15.5 补了一轮密钥脱敏（覆盖 token、secret、api_key、Authorization Bearer、Slack 各类 token），v15.6 把前端状态收敛进单一 Zustand store。对一个「记忆库」来说，它已经长成了一个带工作台面的产品。

第三，生态位扩张。早期它只是 Claude Code 插件，现在同一套 npx claude-mem install --ide <宿主> 命令能装进 OpenCode、T3 Code、Antigravity、Pi、DeepSeek Harness、OpenClaw 网关等十余个宿主；没有钩子机制的宿主（如 Grok Bot）退而求其次直接监视聊天日志文件。宿主面越宽，「装一个就全都有记忆」的吸引力越强。

第四，社区与话题效应。仓库进了 Awesome Claude Code 与 Trendshift 榜单；作者公开「拥抱」了社区自发发行的 CMEM 代币（BASE 链），为项目带来加密社区的关注（这同样是把双刃剑，见第八节）。而 10 月 29 日那个指控安装器上传用户提示词的 issue（#5176），客观上也把讨论度推高了一轮。

四、架构原理

4.1 整体架构与数据流

claude-mem 是典型的「宿主外挂」形态：它不改宿主进程，而是挂在宿主暴露的生命周期钩子上，把记忆的采集与生成全部搬进一个本地后台服务。

claude-mem 手绘架构信息图：宿主层钩子与 MCP 客户端、CLI 层降级纪律、Worker 服务五模块、SQLite 与 ChromaDB 双库存储，右侧为三层渐进式检索的 token 成本

flowchart TB
    subgraph Host["宿主层：Claude Code / OpenCode / Codex 等"]
        H1["生命周期钩子<br/>Setup / SessionStart / UserPromptSubmit<br/>PostToolUse / Stop / SessionEnd"]
        H2["MCP 客户端<br/>search / timeline / get_observations"]
    end
    subgraph Cli["CLI 层（Bun）"]
        C1["bun-runner 桥接"]
        C2["hook-command 编排<br/>传输错误 exit 0，客户端缺陷 exit 2"]
    end
    subgraph Worker["Worker 服务（Express 守护进程，端口 37700 + uid 取余）"]
        W1["SessionManager 会话状态"]
        W2["SDKAgent（Claude Agent SDK）<br/>工具调用压缩成观察"]
        W3["SearchManager 混合检索"]
        W4["ProcessRegistry + 孤儿回收"]
        W5["ChromaSync 向量同步"]
    end
    S1[("SQLite claude-mem.db<br/>六张核心表 + FTS5 全文索引")]
    S2[("ChromaDB<br/>观察向量投影")]
    H1 -->|"HTTP fire-and-forget，2 秒超时"| C2
    C2 --> Worker
    W2 -->|"结构化观察写入"| S1
    W5 -->|"向量投影"| S2
    W3 --> S1
    W3 --> S2
    H2 -->|"JSON-RPC over stdio 转发 HTTP"| W3

官方文档把系统分成四层。宿主层只做两件事：按事件触发钩子命令，以及通过 MCP 协议暴露的四个检索工具。CLI 层是钩子与后台服务之间的缓冲带——每个钩子实际执行 claude-mem hook claude-code <事件>，由安装器放到 PATH 的小启动器拉起，再桥接进 Bun 运行时。Worker 层是核心：一个每用户端口（37700 + (uid % 100)）的 Express 守护进程，内含会话管理、压缩代理、检索编排、子进程注册表和向量同步五个部件。存储层则是双库分工：SQLite 持有记忆的现状（current state），ChromaDB 只持有它的检索投影（search projection）。

4.2 钩子生命周期：永不阻塞宿主

整套系统对宿主的承诺浓缩成一条纪律：Worker 挂了，绝不能拖累编码会话。实现上是两层超时设计。钩子进程对 Worker 的 HTTP 调用一律 fire-and-forget，2 秒超时不等待 AI 处理完成——压缩是异步队列里的活；钩子自身在 hooks.json 里按事件配不同的预算：会话初始化 15 秒、观察上报与摘要 120 秒（异步）、SessionStart 拉起 Worker 与注入上下文 60 秒。

hook-command.ts 里的降级规则写得很明确：连接被拒、超时、5xx 这类传输错误一律 exit 0（不阻塞）；4xx、TypeError 这类客户端自身的缺陷则 exit 2（阻塞报错，逼你修）。这套二分法保证「基础设施坏了」和「代码有 bug」不会被混为一谈——前者静默降级，后者立刻暴露。

4.3 压缩管线：从工具调用到结构化观察

PostToolUse 钩子把每次工具调用的输入输出（工具名、入参、响应、工作目录）推给 Worker 排队。SDKAgent 用 Claude Agent SDK 起一个小型代理会话，把原始 I/O 压缩成一条「观察」，含标题、副标题、叙述、要点、概念、涉及文件等层级字段。存储层 observations.type 标注六类：决策（decision）、修复（bugfix）、特性（feature）、重构（refactor）、发现（discovery）、变更（change）；注入索引时再套一层九种 emoji 图标的展示体系——🔴 gotcha（坑）、🟤 decision、⚖️ trade-off、🟣 discovery 等，让模型扫一眼就能判断轻重缓急。

工程细节上有三处值得注意。一是去重：SHA256(会话 ID + 标题 + 叙述) 取前 16 位十六进制做内容哈希，30 秒窗口内命中即复用既有 ID，不重复入库。二是双会话 ID：宿主给的 contentSessionId 会话内不变，SDK 代理的 memorySessionId 在 Worker 重启后变化，两者由 SessionStore 换算来满足外键约束——这是重启频繁的本地服务里很容易踩错的坑。三是原始 I/O 不丢：v51 迁移加的 tool_uses 表与观察走同一个 ingest 入口，以 UNIQUE(内容会话 ID, tool_use_id) 幂等落库，载荷超 64 KB 截断并打标。压缩是主线，原始字节是底牌——这直接支撑了检索的第四层（后述）。

4.4 检索：三层工作流与 10 倍 token 账

claude-mem 最有辨识度的设计是把「渐进式披露」做进了工具结构本身。它曾用 9 个 MCP 工具（约 2718 行实现），工具定义在会话开始就吃掉约 2500 token；重构后收敛为 4 个工具、约 312 行薄封装——MCP 服务器不再含业务逻辑，只做 JSON-RPC 到本地 HTTP API 的协议翻译。

检索被组织成层级递进的工作流：

第一层 search：返回紧凑索引（ID、时间、类型图标、标题、约需 token 数），每条约 50–100 token
第二层 timeline：以某条观察为锚，取前后 N 条的时间线，理解来龙去脉，约 300–600 token
第三层 get_observations：只为筛过的 ID 批量取全文，每条约 500–1000 token
第四层 get_tool_uses：极端情况才取原始工具 I/O，单条可达 64 KB

官方文档给的对比账是：传统 RAG 一次性预取 20 条观察要花 1 万至 2 万 token，而真正相关的只有约 10%；三层工作流全程约 2800 至 5600 token，且模型「看索引再取详情」后相关性接近 100%——官方据此宣称约 10 倍节省（该数字来自项目文档的自述口径，属设计目标而非第三方基准，待确认）。SessionStart 注入的索引本身也控制在千 token 级：文档示例中 50 条观察的索引约 800 token，换来的效果是模型保留约 99% 的上下文预算干活。

底层检索是双引擎：SQLite FTS5 负责关键词全文检索（触发器同步索引、查询转义防注入配了 332 条攻击测试），ChromaDB 负责语义向量检索——每条观察按叙述与各条要点拆成多个向量文档（obs_{id}_narrative、obs_{id}_fact_0……）。两库的一致性靠「每集合单写者」排序保证：回填与同步在拿到写权后重读 SQLite 行，防止旧快照覆盖新版本；但文档明确承认 SQLite 与 Chroma 之间没有跨库事务，写库后的变更仍需各自的重建索引路径。

4.5 与同类架构路线的差异

同样做「智能体记忆」，mem0 的路线是通用 Memory API：抽取事实后经 ADD/UPDATE/DELETE 决策合并进记忆库，谁都能调；Letta（原 MemGPT）把记忆做进智能体内核，智能体自己管理分页；Zep/Graphiti 走实时知识图谱。claude-mem 的差异化在于三点：它是会话压缩器而非事实抽取器——记录的是「干了什么」的过程记忆，不只是「知道什么」的事实记忆；它把检索成本显式标在索引里（每条约需 token 数），让模型做 ROI 决策；它默认「注入索引、按需取用」而非预取内容，把相关性判断的权力交给模型本身。项目文档把这总结为「上下文即货币」：先看菜单，再点菜，而不是别人替你上满一桌。官方文档还专门留了一页《Architecture Evolution》记录从 v3 到 v5 的演进——早期的会话转储思路才收敛为如今的观察模型，说明记忆系统自身的形态也在被高频率地反复重构。

五、应用场景

场景一：长周期项目的会话接力

痛点：一个开发周期跨数周的项目，每次重开 Claude Code 会话，模型对「为什么当初这么设计」「哪个模块刚踩过坑」一无所知，要么靠人肉重讲，要么靠模型重读代码库反推，又慢又容易得出与历史决策相悖的结论。

如何解决：装好 claude-mem 后，压缩代理在后台持续归档每个会话的决策与发现；新会话的 SessionStart 钩子自动注入按日期与文件路径分组的观察索引，形如下面的紧凑表格：

### 10 月 30 日

**src/hooks/context-hook.ts**
| ID | 时间 | 类型 | 标题 | 约需 |
|----|------|------|------|------|
| #2591 | 1:15 AM | ⚖️ | Stderr 消息方案已放弃 | ~155 |
| #2592 | 1:16 AM | ⚖️ | Web UI 策略重新设计 | ~193 |

收益：模型不必预取全文，看到相关标题再按 ID 精取；按官方口径，索引注入约千 token，替换掉传统方案上万 token 的历史转储。对没有宿主钩子机制的环境（如 Grok Bot），它退化为监视聊天日志文件，捕获链路仍然成立。适用边界：记忆质量取决于压缩模型，观察是摘要而非原文，需要原始字节时走第四层取 tool_uses；涉密内容用 <private> 标签包裹可完全不入库。

场景二：把「踩过的坑」变成可检索的资产

痛点：调试经验散落在聊天记录里，同一个坑换个项目、换个会话还会再踩一次。

如何解决：压缩代理会把「默认 60 秒钩子超时对大型依赖树的 npm install 不够用，需在 hooks.json 配 120 秒」这类教训标注为 🔴 gotcha。排查问题时先搜历史：

// 第一步：只取索引，识别相关观察的 ID
search(query="hook timeout npm install", obs_type="bugfix", limit=10)
// 第二步：看锚点附近发生了什么
timeline(anchor=2543, depth_before=3, depth_after=3)
// 第三步：批量取全文
get_observations(ids=[2543, 2891])

收益：跨会话复用修复经验，避免重复排查；gotcha、decision、trade-off 三类高价值观察值得优先精取。适用边界：同名概念在不同项目间会互相干扰，务必带 project 参数过滤；快速检索有 dumb_search 兜底，但它只按标题词面匹配、不做冲突消解，可靠性要求高时仍用三层工作流。

场景三：多人团队的共享工作面（TeamBrain + My Work）

痛点：团队里每个人与智能体的协作成果互相看不见，交接靠口口相传。

如何解决：v15.1 起的 My Work 面板把每条人类请求聚合为一张卡片，带进度、目标对齐与交付物；v15.3 的交付物快照会在会话结束时把智能体产出的报告、页面等文件做内容寻址复制（如 report-3f9a1c2b.md），使其独立于临时目录存活；可选的 TeamBrain 则在个人工作面旁加一块共享区，成员各自选择公开什么，私人请求与评审笔记保持隔离。

收益：「谁在做什么、产出了什么、被驳回了什么」有了单一事实源；规则保存带版本化的批准回执，改动可撤销。适用边界：TeamBrain 与云端能力依赖 cmem.ai 账号，涉及外发内容需对照隐私考量（见第八节）；纯本地用户可以只用 My Work 与 Classic 视图。

场景四：CI 与无人值守环境的静默接入

痛点：自动化流水线里既没有浏览器可扫码登录，也没有人在场点确认。

如何解决：安装器对非交互 shell 自动跳过账号环节；也可以显式控制——传 --provider 指定压缩模型来源（claude-mem observer、自有 OpenRouter 或 Gemini Key、Anthropic 订阅），或设置 CLAUDE_MEM_ONLINE_OPTIN=false，整条链路不产生任何账号交互。

收益：记忆管线可以完全离线本地跑，嵌入 CI 检查或定时任务不引入外部依赖。适用边界：无云端备份，数据只在 ~/.claude-mem/ 本地；托管 observer 的免费试用到期后自动回落到订阅额度，计费行为要提前看清。

场景五：把观察史沉淀成可问答的知识库

痛点：几百条观察躺在库里，逐条检索仍嫌碎，想要的是「对这个项目的问题，给一个综合了历史的回答」。

如何解决：/knowledge-agent 技能可以把匹配的观察历史编排成一个可问答的语料代理，先读全部相关观察再以对话方式作答；另有 Claude Desktop 技能可在桌面端对话里直接搜记忆。

收益：从「找记录」升级到「要答案」，适合做新成员上手简报或周报复盘。适用边界：合成答案的质量仍受底层观察质量约束——垃圾进垃圾出；对关键结论保留观察 ID 引用以便回溯原文。

六、快速上手

标准安装一条命令（装完重启 Claude Code，旧会话上下文即自动出现在新会话）：

npx claude-mem install
# 或在 Claude Code 内走插件市场
/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem

中文用户建议把观察生成语言切到简中（内置无需额外安装，改完重启宿主生效）：

{
  "CLAUDE_MEM_MODE": "code--zh"
}

日常运维只依赖本地 Worker 的健康接口与设置文件：

WORKER_PORT=$(jq -r .CLAUDE_MEM_WORKER_PORT ~/.claude-mem/settings.json)
curl "http://127.0.0.1:$WORKER_PORT/api/health"

注意 npm install -g claude-mem 只装 SDK 库，不会注册钩子与 Worker 服务——必须走 npx claude-mem install 或插件市场命令。对隐私敏感的读者，请在安装前先读第八节，用非交互或显式 --provider 方式避开安装漏斗的历史上传环节。

七、横向对比

维度	claude-mem	mem0	supermemory	Letta
定位	编码智能体的会话记忆压缩器	通用智能体记忆 API	记忆与上下文引擎（可自托管）	有状态智能体平台
记什么	过程记忆：工具调用压缩成观察与摘要	事实记忆：抽取后合并更新	文档与对话记忆	智能体自管理的分层记忆
存储	SQLite（FTS5）+ ChromaDB 双库	多向量库后端可插拔	自研引擎，可全本地	平台内置存储
检索特色	三层渐进式披露，token 成本显式标注	操作式记忆管理（增删改判）	主打低延迟检索	记忆块自编辑
宿主形态	钩子插件 + 本地 Worker + MCP	SDK/API 调用	API + 自托管	独立智能体服务
许可	Apache-2.0（open-core）	Apache-2.0	MIT	Apache-2.0
Star（截至 2026-10-31）	105,687	68,108	31,470	25,292

一句话选型：在 Claude Code 等编码宿主里要「开箱即用的跨会话记忆」，claude-mem 最贴合；做自己的应用要一层可编程的记忆基础设施，mem0 更合适；Letta 适合从零构建自带状态的智能体；supermemory 介于引擎与应用之间。值得注意的是星数——claude-mem 的 10.6 万星已经明显超过 mem0 的 6.8 万，说明「宿主插件」这个贴近工作流的形态，传播势能强于通用 API。

八、局限与风险

安装器隐私争议（当前最大风险，2026-10-29 由 issue #5176 提出，截至 10-31 仍为开放状态）。 报告者详述并经 cmem.ai 部分确认的事实链是：v15.2.0 起的交互式安装会打开浏览器设置页，页面加载即读取本机近 30 天的对话历史（覆盖 Claude Code、Codex、Gemini CLI、Antigravity、OpenCode 五类工具的本地记录文件），把其中的用户提示词全文连同会话 ID、项目名、路径与时间戳上传到 cmem.ai 做意图提取；界面文案只说「正在检查你的 AI 使用情况」，未明示上传；页面上预选的「帮助改进」复选框在勾掉后也不能阻止这次上传。上传的提示词经 OpenRouter 路由到了 deepseek/deepseek-v4-flash-0731，请求未设置零数据保留或 data_collection: deny，cmem.ai 表示其记录未保存实际接单的供应商、已按请求删除自家库记录（但不覆盖 OpenRouter 与供应商侧的副本）。这与隐私政策中「除非显式开启云同步，否则没有任何内容离开你的设备」的承诺直接矛盾。截至 v15.5.0 该行为未改。规避方式：用非交互安装、显式 --provider、或设 CLAUDE_MEM_ONLINE_OPTIN=false；已在装的环境检查设置文件并按官方文档关闭相关开关。

压缩是有损的。 观察是模型生成的摘要，细节可能在压缩中丢失；第四层 get_tool_uses 能取回原始字节，但单条 64 KB 截断意味着超大输出（如完整构建日志）本就残缺。对正确性敏感的场景要保留引用 ID 回溯的习惯。

双库一致性无事务。 SQLite 与 Chroma 之间靠单写者排序而非事务保证，进程崩溃窗口内可能出现向量投影滞后的短暂不一致；官方文档如实标注了这一边界。

脱敏不是万全。 v15.5 已对 token、secret、api_key 裸键值、Authorization Bearer、MYSQL_PWD 及 Slack 各类令牌做存储前脱敏，但规则本质是键名匹配，非常规命名的密钥仍可能随工具输出入库；建议配合 <private> 标签与观察记录的定期清理一起使用。

快速变动的工程栈。 一周六版意味着行为随时可能变；依赖 Bun、uv、Chroma 侧车进程的完整链路在 Windows 上仍有路径类问题（如 8.3 短路径查询的修复记录）。生产环境建议锁版本升级节奏。

代币与商业边界。 社区自发发行的 CMEM 代币（BASE 链）获作者「官方拥抱」，但与项目工程能力无关，勿把代币热度当作技术价值的代理指标；Apache-2.0 只覆盖核心引擎，Magic Recall 云托管、团队同步、企业 RBAC 等在开源边界之外，深度依赖前先读 docs/ip-boundary.md。

九、小结与行动建议

claude-mem 的价值不在「又造了一个向量库」，而在把记忆工程拆成了可审计的四段流水线：钩子捕获不阻塞宿主、AI 压缩带语义类型、双库各司其职、检索把成本标给模型自己决策。10 倍 token 节省的数字出自官方自述，但「索引先行、按需精取」的方向与当下上下文工程的主流共识一致。给不同读者的建议：

个人开发者：可以装来体验，但用 CLAUDE_MEM_ONLINE_OPTIN=false 或显式 --provider 装本地版，跳过安装漏斗的历史上传环节，等 #5176 闭环后再考虑云端功能。
团队负责人：先把 My Work 当共享工作面试点，TeamBrain 上线前让成员知情同意数据的本地/云端边界；观察索引是很好的交接文档底稿。
平台工程师：若要嵌入自有智能体设施，重点评估双库一致性模型与版本变动速度，锁 tag 部署并订阅 releases；它的 hooks.json 超时与 exit code 纪律值得直接抄进自家钩子设计。
研究者：三层渐进式披露与 2718 行到 312 行的 MCP 重构是上下文工程的好案例，可与 Anthropic 官方记忆、mem0 的操作式合并对照做消融实验。

参考资料

thedotmack/claude-mem 仓库与 README（获取日期：2026-10-31）
Architecture Overview 及仓库内 docs/architecture-overview.md（获取日期：2026-10-31）
Search Architecture / Database Architecture / Worker Service（仓库内 docs/public/architecture/，获取日期：2026-10-31）
Progressive Disclosure（仓库内 docs/public/progressive-disclosure.mdx，获取日期：2026-10-31）
Releases v15.0.2 – v15.6.0（获取日期：2026-10-31）
Issue #5176：Installing claude-mem uploads your last 30 days of prompts to cmem.ai, no opt-in（获取日期：2026-10-31）
docs/ip-boundary.md：开源与商业边界（获取日期：2026-10-31）
mem0 / supermemory / Letta 仓库元数据（GitHub API，截至 2026-10-31）