你的 Agent 是不是每天都在「重新认识你的项目」？
昨天 Claude Code 花了四十分钟排查出一个诡异的 bug——根因是某个第三方库的版本行为和文档不一致。你松了口气，关掉终端。今天新开一个会话，让 Agent 继续改旁边的模块，它又一头扎进同一个坑：重新读文档、重新怀疑环境、重新踩一遍昨天的雷。
这不是 Agent 笨。是它没有记忆。每个新会话都是一张白纸，昨天的排查结论、定下的架构决策、验证过的坑，全部随会话结束蒸发。你只能靠两样东西补救：要么手动把结论写进 CLAUDE.md（然后忘更新），要么每次开聊前重新贴一大段上下文（然后烧 token）。
claude-mem 就是冲着这个来的：一个持久记忆压缩系统——自动捕获 Agent 会话里发生的所有事，用 AI 压缩成语义摘要存下来，下次会话自动把相关的记忆注入回去。90,083 Star、7,841 Fork，2025 年 8 月 31 日创建，不到一年冲到 9 万——记忆赛道目前的绝对王者，昨天（8月8日）还在更新。
它到底是什么
一句话：claude-mem 是给 Coding Agent 装「海马体」——短期记忆（当前会话上下文）自动转长期记忆（跨会话语义库）的引擎。
作者是 Alex Newman（@thedotmack）。它的工作方式不是让你手动存东西，而是完全自动化：Agent 每次调用工具、每次你提交 prompt、每次会话结束，它都通过 Claude Code 的 hook 系统「偷看」一眼，把观察记录下来，后台用 AI 压缩、聚类、索引。下次会话开始，它自动把「跟当前任务相关的历史记忆」注入上下文——你什么都不用做。
核心数据：
- 90,083 Star，2025年8月31日创建，TypeScript/JavaScript，Apache-2.0（作者特意选这个协议：持久记忆应该能被自由嵌入各种工具和 Agent 框架）
- 不挑 Agent——README 明确支持 Claude Code、OpenCode、Codex、Gemini、Hermes、Copilot，还有 OpenClaw 网关的一键安装脚本
- 本地优先——所有记忆存本地 SQLite，可选 cmem.ai 云同步备份
- v13.4.0，迭代极快，main 分支稳定发布，另有 core-dev / community-edge 两个源运行分支
- 完整工具链：5 个生命周期 Hook + Worker 服务 + SQLite + Chroma 向量库 + MCP 搜索工具 + Web 查看器 UI
核心机制：捕获 → 压缩 → 注入 → 检索，一条闭环
1. 捕获：5 个生命周期 Hook 全自动记录
它挂在 Claude Code 的 hook 系统上，用 5 个生命周期钩子（6 个脚本）覆盖 Agent 的完整活动周期：SessionStart（会话开始）、UserPromptSubmit（你每次发话）、PostToolUse（Agent 每次调用工具后）、Stop（Agent 停下来等你）、SessionEnd（会话结束）。
PostToolUse 是灵魂：Agent 读了哪个文件、改了什么、跑了什么命令、报了什么错，全被记录成 observation。SessionEnd 时再统一压缩——把这一整段会话的观察用 AI 提炼成语义摘要，存进 SQLite。你说「帮我排查一下为什么登录偶尔超时」，它记住的不只是这句话，而是后面 Agent 查过的每个文件、验证过的每个假设。
2. 存储：SQLite + FTS5，附送 Chroma 向量检索
底层是 SQLite（内置，零配置），存三类数据：sessions（会话）、observations（观察）、summaries（摘要）。全文搜索走 SQLite 的 FTS5，语义搜索走 Chroma 向量库——混合检索：关键词查得到精确的，向量查得到「意思相近的」。
Worker 服务是本地 HTTP API + Web 查看器 UI，由 Bun 管理。启动 claude-mem 后终端会打印一个本地地址，浏览器打开就是记忆流实时视图——所有 observation 像聊天记录一样滚动，还能按项目、按类型过滤。
3. 注入：Progressive Disclosure（渐进式披露）
这是它最值得抄的设计：记忆注入不是「一股脑全塞进上下文」，而是分层的。默认只注入精简摘要（低 token 成本），需要细节时再按需展开。文档里把 token 成本可视化——每一层记忆注入多少 token 都标得明明白白，你可以在 settings 里精细控制什么上下文进、什么不进。
4. 检索：MCP 三件套，先看索引再取详情
MCP 搜索工具按「3 层工作流」设计，token 效率拉满：
search——先拿紧凑索引，每个结果约 50-100 token，支持按类型/日期/项目过滤timeline——对感兴趣的结果，拿它周围的时序上下文，看当时发生了什么get_observations——最后只对筛选出的 ID 批量取完整详情（约 500-1,000 token/条）
先索引、后详情，避免「搜一次把全部详情拉爆上下文」——官方称这套流程能省约 10 倍 token。另外还带一个 mem-search skill，Agent 可以用自然语言直接查项目历史。
和 engram、手写 CLAUDE.md 比，差在哪
我们 8 月 3 日写过 engram（5.8K Star 的 Go 单二进制记忆系统），当时说它「比 claude-mem 更简单」——今天把两个放一起掰开看：
| 维度 | claude-mem（90K Star） | engram（5.8K Star） | 手写 CLAUDE.md |
|---|---|---|---|
| 记忆怎么进来 | 5 个 Hook 全自动捕获，零操作 | MCP 工具显式读写 | 手动维护 |
| 记忆怎么出去 | 自动渐进式注入相关上下文 | 显式调用才注入 | 每次全量读入 |
| 检索方式 | SQLite FTS5 + Chroma 向量混合 | SQLite FTS5 全文 | grep |
| 依赖 | Node 20+ / Bun / uv / SQLite | 单 Go 二进制，零依赖 | 无 |
| token 效率 | 3 层检索，约省 10x | 一般 | 文件越写越大，全量烧 |
| 跨 Agent | Claude Code / Codex / Gemini / Hermes / Copilot / OpenCode | Claude Code / Cursor / Windsurf | 谁读谁用 |
| 可视化 | Web 查看器实时记忆流 | CLI 查询 | 编辑器里看文件 |
| 隐私控制 | <private> 标签排除敏感内容 | 本地存储 | 文件即隐私 |
结论很直接：engram 是「极简够用」，claude-mem 是「全自动闭环」。如果你享受掌控感、记忆量不大，engram 的零依赖很香；如果你想要「装完就忘、它自己记」的体验，claude-mem 是唯一做到全自动的。至于 CLAUDE.md——它依然是必需品，但它是「静态项目知识」，替代不了「动态会话记忆」，两者互补不冲突。
上手：一分钟装完，剩下全自动
# Claude Code 一键安装（默认）
npx claude-mem install
# 装给 OpenCode
npx claude-mem install --ide opencode
# 或者从 Claude Code 插件市场装
/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem装完重启 Claude Code 就行——旧会话的上下文会自动出现在新会话里。首次启动会打印 worker 的本地地址，浏览器打开就是记忆流 Web 查看器。
# 配置文件（首次运行自动生成）
# ~/.claude-mem/settings.json
# 想用中文生成记忆摘要？加一行：
{
"CLAUDE_MEM_MODE": "code--zh"
}Agent 侧的记忆检索走 MCP 工具，典型用法是三步：
# 第 1 步：搜索引（先别拉详情）
search(query="authentication bug", type="bugfix", limit=10)
# 第 2 步：看命中的 ID（比如 #123、#456），用 timeline 看当时上下文
# 第 3 步：只对相关 ID 批量取详情
get_observations(ids=[123, 456])实际体验的几个坑
npm install -g claude-mem是个陷阱——README 专门加粗提醒：全局安装只装 SDK 库，不注册插件 hooks、不启动 worker，装了等于没装。必须走npx claude-mem install或 /plugin 命令- 依赖链不浅——Node 20+、Bun（worker 进程管理）、uv（向量搜索的 Python 包管理）、SQLite。Bun 和 uv 号称「缺了自动装」，但公司网络/代理环境下自动安装经常静默失败，装完发现 worker 没起来，记忆一条没记
- 默认记录一切，包括敏感信息——PostToolUse 会把 Agent 看到的都记下来，你要是让 Agent 读过 .env 或密钥文件，这些内容会进本地库。要用
<private>标签明确排除敏感内容，先配好隐私策略再裸奔 - Windows 环境先查 PATH——报
npm is not recognized这类错就是 Node 没进 PATH，官方 troubleshooting 第一条就是这个 - 改 settings 要重启 Claude Code 才生效——mode、上下文注入配置改完不重启，静默不生效，容易让人以为坏了
- CMEM 币跟项目是两回事——README 末尾说明 CMEM 是第三方发的 token，作者官方「认可」但它是社区催化剂的定位。Star 是记忆引擎挣来的，别把币价跟项目进度画等号
跟我们有关的一件事
这个项目跟本工坊读者的关系比想象中近：claude-mem 的 README 支持列表里明确写着 Hermes。而且它是「记忆四件套」里唯一做到全自动闭环的——之前我们写过 engram（极简 Go 记忆）、codebase-memory-mcp（代码库记忆）、beads（token 压缩），它们各自解决记忆的一个侧面，claude-mem 把「捕获-压缩-注入-检索」整条链都做了，还顺手把检索做成了省 token 的 3 层工作流。
就算你不打算装它，它的两个设计也值得抄：一是渐进式披露——上下文注入按层收费，先摘要后细节，这个思路能直接套进你自己的 RAG 系统；二是「先索引后详情」的 MCP 工具设计——任何给 Agent 用的检索接口，都应该先给 50 token 的索引、再按需给 500 token 的详情，而不是一次全倒。
要不要我帮你把 claude-mem 和 engram 在你常用的 Agent 上做个实际对比评测？或者看看它的 hook 脚本怎么挂到别的 Agent 上？
适合谁用
- 每天开多个 Claude Code 会话的人——跨会话记忆是刚需，装完就忘的体验最省心
- 项目历史长、上下文贵的人——3 层检索省 token 的效果是实打实的
- 受够了「每次重新解释项目背景」的人——它记住的不只是结论，还有排查过程
- 在用 engram 但觉得手动读写烦的人——全自动捕获是另一个思路，值得对比
- 做 Agent 上下文工程的人——progressive disclosure 和分层检索是现成的教科书
总结
claude-mem 做的不是「又一个记忆插件」，而是把「失忆」这件事从 Agent 的默认状态变成了可选项。90K Star 只用了不到一年，说明「Agent 需要长期记忆」不是伪需求——而是每个认真用 Coding Agent 的人迟早撞上的墙，它把这面墙拆了。
技术含量也在线：hook 捕获、AI 压缩、混合检索、渐进注入、token 分层，每一层都有值得抄的设计。Apache-2.0 意味着你可以放心把它嵌进自己的工具链。唯一要掂量的是依赖链和隐私边界——但比起每天重复烧掉的 token 和耐心，这点成本大概率是值的。
项目地址：github.com/thedotmack/claude-mem（文档：docs.claude-mem.ai · 主页：claude-mem.ai）