从金鱼记忆到资深同事一个被低估的 Claude Code 长期记忆插件深度拆解01. 写在前面的灵魂拷问你被 AI 失忆坑过几次先来三个场景看你有没有中招场景一周一早上你打开终端敲下claude想赶紧收尾上周遗留的OrderService批量查询功能。你打字“为 OrderService 增加一个批量查询订单的方法根据订单 ID 列表批量返回订单详情。”Claude 秒回一段代码。你扫了一眼眉头就皱了——它又用了for循环 单条 SQL一条一条查。而你们项目里明明封装好了batchQuery()上周刚跟它强调过。你深吸一口气“用batchQuery()别手撸循环。”Claude“好的我改。”然后——它又忘了你们约定的异常处理规范不要e.printStackTrace()要用BusinessException。场景二你让 Claude 帮团队排查一个 P0 bug前前后后聊了 40 分钟、调试了 12 个文件终于定位到根因。你关掉终端第二天开会前想让它把昨天的分析整理成 wiki。“你帮我把昨天那个 bug 的分析整理一下。”Claude“抱歉我不知道你在说什么。”40 分钟的推理链灰飞烟灭。场景三新人入职你让他看代码熟悉业务逻辑。但代码之外那些为什么用 MyBatis-Plus 不用 JPA、为什么订单状态用枚举不用字符串的设计决策从来没人系统整理过。新人只能去翻 git log、读聊天记录、抓老员工问。这些场景的共同根源是Claude Code 本质是个金鱼——上下文窗口用完就清零会话结束就失忆。200K Token 的窗口看着大跑复杂项目十几分钟就撑爆。更扎心的是就算窗口够长它也不知道上周三我跟你说过这个约定。痛点在那摆着谁来解决今天要拆解的这个开源项目GitHub 56,800 Stars被 30 万 Claude Code 用户装上之后口碑炸裂——它就是claude-mem。02. claude-mem 是什么一句话讲清楚claude-mem Claude Code 的外接硬盘 私人秘书。它做三件事自动记录把 Claude 每次工具调用读文件、写代码、执行命令、每次对话全部抓下来。AI 压缩用 Claude Agent SDK 把 1000-10000 Token 的原始输出压缩成 500 Token 的语义观察记录。智能检索新会话开始时自动把最近的记忆喂回给 Claude让它记起你昨天干了啥。整个过程对用户透明——你正常写代码它在背后默默搬砖。2.1 关键信息速览维度数据项目名claude-mem仓库github.com/thedotmack/claude-mem官网claude-mem.ai文档docs.claude-mem.aiGitHub Stars56,8002026 年 4 月已达 59.8K首次发布2025 年 8 月协议AGPL-3.0维护者Alex Newman (thedotmack)最新版本v12.4.72026 年 4 月平台支持Windows / macOS / Linux兼容框架Claude Code / OpenClaw / Codex / Gemini / Hermes / Copilot / OpenCode2.2 它解决了哪三个核心痛点痛点 1跨会话失忆每次开新窗口都要重新讲项目背景10 分钟能讲完重复 10 次就是 100 分钟。痛点 2决策脉络断裂为什么用策略模式不用继承这种设计权衡AI 不会自动记过两天就忘。痛点 3Token 成本飙升为了让它想起来你只能把所有历史往 prompt 里塞。20K Token 的项目背景每开一次会话就烧一遍。claude-mem 的解法是让记忆外置让检索按需。03. 技术架构五层流水线造一个仿生大脑claude-mem 的架构被作者称为仿生记忆架构Biomimetic Memory Architecture分五层┌─────────────────────────────────────────────────────┐ │ ① 客户端层 (Claude Code / OpenClaw / Codex ...) │ │ ↓ Hook 机制无侵入式埋点 │ ├─────────────────────────────────────────────────────┤ │ ② Hook 系统5 个生命周期事件 │ │ SessionStart / UserPromptSubmit / PostToolUse │ │ Stop / SessionEnd │ ├─────────────────────────────────────────────────────┤ │ ③ 编排层Bun Runtime handlers/ │ │ 协调 Worker / SDK Agent / Search Manager │ ├─────────────────────────────────────────────────────┤ │ ④ Worker DaemonExpress 守护进程端口 37777 │ │ SessionManager / SDKAgent / ProcessRegistry │ ├─────────────────────────────────────────────────────┤ │ ⑤ 存储层 │ │ SQLite (结构化) FTS5 (全文检索) │ │ ChromaDB (向量语义检索) │ └─────────────────────────────────────────────────────┘3.1 第一层Hook 机制——像埋点一样无感采集claude-mem 不改 Claude Code 源码而是利用 Claude Code 官方提供的Hook 扩展点在 5 个关键时刻埋点Hook触发时机作用SessionStart会话启动启动 Worker 服务 注入最近 3 条记忆摘要UserPromptSubmit用户提问创建新会话记录 保存 promptPostToolUse工具调用完成捕获 Read/Write/Edit/Bash/Glob/Grep 结果Stop任务暂停保存中间状态SessionEnd会话结束触发 AI 摘要 持久化入库整个过程零侵入你感受不到它在工作。3.2 第二层混合存储——SQLite Chroma 的双引擎这是最见功力的设计结构化数据 → SQLite存什么会话 ID、时间戳、文件路径、工具名、参数、结果摘要。全文检索 → SQLite FTS5适合场景精确关键词搜索比如找出所有batchQuery()的修改记录。语义检索 → ChromaDB 向量库适合场景模糊语义搜索比如上个月我们讨论的订单性能优化。两路结果通过RRF倒数排名融合算法合并召回准确度比单引擎高 30%。3.3 第三层渐进式披露——不一次塞爆上下文窗口这是 claude-mem 最精妙的设计。它借鉴了前端懒加载思想把记忆分成三层按需加载Level 1自动注入最近 3 条会话摘要会话一启动就把这三条喂给 Claude。开销极小 500 Token但保持了短期连续性。Level 2用户查询时相关观察记录你说上周我们怎么改的订单服务系统从历史中捞出相关 5-10 条观察记录。Level 3深度检索完整历史通过mem-searchMCP 工具做完整库搜索找具体某行代码、某个决策的完整链路。效果对比不用 claude-mem每次开新会话塞 20K Token 历史背景 → 烧钱 撑爆窗口用 claude-memLevel 1 自动塞 500 Token → 按需触发 Level 2/3 → 节省 95% Token3.4 第四层可视化界面——http://localhost:37777启动 Worker 后浏览器打开http://localhost:37777可以实时看到记忆流每次工具调用实时滚动展示统计今日捕获次数、Token 节省量、压缩比搜索框自然语言搜历史“找 3 月份所有 Spring Boot 的配置修改”时间线可视化查看会话演进这个 Web UI 是白送的——你以为只是装了个插件结果送了个项目管理后台。3.5 第五层隐私控制——private标签v7.0 之后支持隐私黑名单。用法把敏感内容用privateAPI_KEYsk-xxxxx/private包起来claude-mem完全不会记录。GitHub 搜 “claude-mem leak API key”——零结果。这就是本地优先 隐私标签的价值。04. 快速上手5 分钟跑起来4.1 环境要求组件最低版本说明Node.jsv22.14Claude Code 已经自带Bun≥ 1.1.14Worker 运行时没装会自动装Git任意拉源码uv≥ 0.11Python 包管理器chroma-mcp 用操作系统Win10 / macOS 12 / Ubuntu 20全平台支持4.2 安装npx 一键法# 推荐方式npx 自动安装 npx claude-mem install # 验证打开新 Claude Code 会话输入 /help # 应该能看到 claude-mem 相关命令4.3 源码安装自定义配置git clone https://github.com/thedotmack/claude-mem.git cd claude-mem npm install4.4 第一次使用# 在 Claude Code 里直接问 帮我看一下昨天改的 OrderService 文件 # claude-mem 会自动 # 1. 检索昨天的 PostToolUse 记录 # 2. 找到 Edit 工具调用 # 3. 注入相关上下文 # 4. Claude 回答昨天你在 OrderService.java 的 142 行加了 batchQuery() 方法...4.5 高级玩法组合其他工具claude-mem 只解决记忆问题不解决工作流问题。黄金组合claude-mem记忆层 planning-with-files任务层 Superpowers流程层 ↓ ↓ ↓ 记得你是谁 记得要做什么 知道怎么做得对我之前拆解过的planning-with-filesManus 20 亿美金的核心工作流开源复刻和SuperpowersAnthropic 黑客松一等奖框架都是和 claude-mem 互补的。05. 五大核心亮点 vs 三大典型场景5.1 五大亮点亮点 1真正的零侵入你写代码的方式完全不变。它在背后默默干活。亮点 25 平台兼容Claude Code、OpenClaw、Codex、Gemini、Hermes、Copilot、OpenCode 都能用。不是 Claude 专属。亮点 3本地优先 隐私可控所有数据在你本地 SQLite Chroma。private标签兜底敏感信息。亮点 4渐进式披露省 Token实测节省 80%-95% 的重复 context 注入成本。亮点 5可视化记忆流Web UI 实时展示开发过程可追溯、可审计。5.2 三大典型场景场景 1长期项目协作最常用“上周我们怎么改的”→ 一句话召回完整历史。 “为什么用 X 不用 Y”→ 找出当时的决策讨论。场景 2复杂 Bug 排查链救命的昨天调试 40 分钟的 P0今天开会要复盘 直接问“昨天那个分布式锁超时问题怎么定位的” claude-mem 给你完整 5 步推理链 相关文件 命令记录。场景 3新人 Onboarding管理者的福音新人装上 claude-mem跑几天项目后记忆库里就有项目完整演进史。 问为什么订单状态用枚举自动得到老员工的完整决策记录。06. 同类工具横评claude-mem 凭什么杀出来工具定位Stars记忆方式最佳场景claude-mem长期记忆压缩56.8KHook SQLite Chroma跨会话项目协作planning-with-files任务规划22.3K3 文件结构复杂任务分阶段Superpowers工作流框架123K14 个 Skill 链式严格工程流程CLAUDE.md项目交接文档-静态 Markdown一次性背景信息mattpocock/skills编程方法论33.9KSkill 库编码质量与 TDDGitNexus代码图谱32.9KAST 图数据库代码理解与重构关键差异CLAUDE.md静态文档写完不变。claude-mem 动态捕获自动进化。planning-with-files解决当前任务怎么拆。claude-mem 解决过去发生了什么。两者互补。Superpowers流程框架怎么写代码。claude-mem 数据底座记得什么。层叠使用。GitNexus代码图谱聚焦代码理解。claude-mem 聚焦对话记忆。正交关系。一句话总结claude-mem 是 AI Agent 的长期记忆海马体其他工具是前额叶规划、“小脑”流程、“视觉皮层”代码理解。它负责最底层的记得。07. 优缺点实话实说7.1 优点✅真省 Token——渐进式披露设计实测减少 80% 重复 context 成本。 ✅真零侵入——Hook 机制不影响 Claude Code 正常工作流。 ✅真本地优先——数据不出本机隐私可控。 ✅真跨平台——Win/Mac/Linux 通用5 Agent 框架兼容。 ✅真可视化——Web UI 是送的彩蛋。7.2 缺点⚠️配置有门槛——Bun uv Node 三件套新手可能踩坑。 ⚠️首次启动慢——Worker 初始化 Chroma 冷启动要 3-5 秒。 ⚠️AGPL-3.0 协议——商业项目需要谨慎评估传染性。 ⚠️依赖 Chroma——Python 生态工具Windows 上偶尔出兼容性问题。 ⚠️大量会话后查询变慢——超过 1 万条记录后向量检索需要 1-2 秒。7.3 适用人群适合每天用 Claude Code 2 小时以上的开发者长期维护 3 个月以上项目团队协作 新人 Onboarding复杂 Bug 排查需要复盘不适合偶尔用 AI 写个脚本的轻度用户杀鸡用牛刀完全不能接受 AGPL 协议的商业闭源项目一次性原型开发不需要记忆08. 三个进阶 TipsTip 1定期清理记忆记忆库会越积越大建议每月清理一次# 删除 30 天前的会话 sqlite3 claude-mem.db DELETE FROM sessions WHERE created_at datetime(now, -30 days);Tip 2善用private标签我的 privateOPENAI_API_KEYsk-xxx/private 帮我配到 .envclaude-mem 不会记录private里的内容但 Claude 仍能正常处理。Tip 3和 CLAUDE.md 配合CLAUDE.md写静态项目规范“用 Spring Boot 3.2”claude-mem 记动态决策“为什么不用 Spring Cloud”。两者结合AI 既懂规矩又懂原因。09. 写在最后AI 编程的记忆战争才刚开始claude-mem 不是终点而是 AI Agent 持久化记忆赛道的起点。现在整个社区都在做类似的事OpenAI在 ChatGPT 推 Memory 功能Anthropic在 Claude 加 Project ContextGoogle在 Gemini 搞 Personal ContextMeta在 Llama 3 推 1M Token 上下文但 claude-mem 的本地优先 跨平台 渐进式披露是大厂做不到的事。因为对大厂来说记忆是用户数据要上云、要训练、要变现。对独立开发者来说记忆是生产资料必须掌控在自己手里。这才是 claude-mem 真正的价值——它不只是一个工具而是AI 时代数据主权的一种实践。10. 一键体验清单# 1. 一键安装 npx claude-mem install # 2. 启动 Claude Code claude # 3. 写一段代码跑几个工具调用 # 4. 退出新开会话问 AI 你还记得我刚才改了哪些文件吗 # 5. 看 Web UI open http://localhost:37777当你看到 AI 准确说出 30 分钟前你改了哪一行代码时——你就会懂为什么 56,800 个开发者给它点了 Star。觉得有用就点个赞 在看这是对我最大的支持。下期我们拆解claude-mem 背后的 SQLite FTS5 Chroma 混合检索如何选型敬请期待。