Claude-Mem：给 Claude Code 装上长期记忆
用 Claude Code 写代码时，最头疼的莫过于每次开新会话都要重新解释项目背景。我们借着 Claude-Mem 这个开源项目，聊聊为什么 AI 编程助手需要'长期记忆'，它是怎么实现的，以及在工程上有哪些值得借鉴的地方。
概述
这篇文章主要写给三类人看：日常在用 Claude Code 或 VS Code AI 插件写代码的开发者、正在做 Agent 或 RAG 方向的工程师，以及对 AI 编程效率感兴趣的技术爱好者。
核心问题只有一个：如何用一个开源插件，把'金鱼记忆'的 Claude Code，改造成记得住你项目细节的'老同事'？
痛点：为什么 AI 编程助手必须要'长期记忆'？
场景有多难受？
周一你和 Claude 反复讨论微服务架构和数据库分片，周二为了修 Bug 切了分支，周三回来接着做架构，Claude 却一脸懵：'这是什么项目？'
这种体验在 GitHub 的 issue 里被直接称为'重大工作流程中断'。本质上，现在的 IDE 插件大多是'短期 + 纯上下文'，而不是'长期 + 按需召回'。这导致项目一旦跨天，重复解释成本极高，多人协作时新人也无法顺畅接上历史上下文。
开发者已经开始自救
GitHub 上已经出现了 memory-mcp、mcp-memory-keeper 等自建方案。这说明痛点是真痛，社区已经在尝试给 AI 装记忆。Claude-Mem 恰好踩在这个需求点上：专为 Claude Code 设计，免费开源，装完就能用。
Claude-Mem 是什么？
一句话概括：这是一个给 Claude Code 用的本地持久化记忆插件。通过事件驱动、混合存储和三层渐进式检索，把你和 AI 一起做过的事压成结构化'长期记忆'，在后续会话中按需注入，同时大幅减少 Token 消耗。
它是开源项目，由 @thedotmack 开发。截至 2026 年 2 月 7 日，GitHub Star 超过 2.2 万。官方数据显示，常规场景节省约 90% Token，'无尽模式'最高可达 95%，工具调用上限提升约 20 倍。对于一个'记忆插件'来说，这个量级说明它不只是玩具，而是踩到了真实需求。
整体架构：怎么把碎片操作变成记忆？
思路可以拆成三步：监听生命周期捕获观察记录、本地混合存储、新会话按需注入。
事件驱动：不干扰你的关键动作捕获
内部挂了 5 个生命周期钩子，对用户几乎隐形：
| 钩子 | 触发时机 | 作用 |
|---|---|---|
| SessionStart | 会话启动 | 初始化检索和上下文准备 |
| UserPromptSubmit | 用户提交问题时 | 记录用户意图和上下文 |
| PostToolUse | 工具调用完成之后 | 捕获文件读写、代码改动等 |
| Stop | 任务暂停 | 保存中间状态 |
| SessionEnd | 会话结束 | 触发总结、压缩与入库 |
重点记录的是'工具使用带来的变化'，比如改了哪些文件、执行了什么命令。这些统称为'观察记录'（Observations），类似时间序列的项目事件日志。
本地混合存储：结构化 + 全文 + 语义
存储设计很务实：
- SQLite + FTS5：存结构化数据（会话 ID、文件路径、时间戳）和做全文检索。
- Chroma 向量库：把摘要向量化，处理模糊问题，比如'上周讨论的那个支付风控策略'。
所有数据统一存放在用户本地目录 ~/.claude-mem/ 下，不走云端。这对隐私敏感行业很重要。从工程角度看，部署成本低，查询灵活，且用户可见可控。
记忆压缩：别把原始流水账端给模型
只存不够，还得压。SessionEnd 阶段会调用 Claude Agent SDK，把累计的 Observations 汇总成结构化摘要，包含调研内容、学习成果、已完成工作和后续步骤。不再把完整原始历史塞进上下文，而是注入高度浓缩后的'记忆索引 + 摘要'。
三层渐进式披露：Token 成本怎么砍到 95%？
核心创新是'三层渐进式披露'。不是一开始就把所有历史端给模型，而是分三层按需解锁。
三层结构长什么样？
| 层级 | 主要内容 | Token 开销 | 使用场景 |
|---|---|---|---|
| 第一层：Search | 摘要级索引与概要 | 约 50–100 / 结果 | 快速定位相关历史 |
| 第二层：Timeline | 会话 / 事件时间轴 | 中等开销 | 理解前后因果 |
| 第三层：Get_Observations | 完整观察记录详情 | 约 500–1000 / 结果 | 深挖实现细节 |
流程大概是：用户提问 -> 插件先 Search 找相关摘要 -> 若需更多则拉 Timeline -> 若还不够才调 Get_Observations 拉具体操作记录。
为什么能省 Token？
常规做法要么暴力全扔（Token 爆炸），要么手动翻历史（累且易漏）。三层设计把'召回'和'注入'拆开，优先注入压缩后的高价值摘要。常规场景省 90% Token，无尽模式省 95%。因为 Token 压力下降，工具调用上限也能放宽到原来的 20 倍。体感上就是：同样的预算，AI 陪你做更长时间的活，而且不会越用越傻。
实战效果：不同场景的变化
企业团队：复杂项目的'团队记忆库'
在大型代码库或多团队协作中，它能持续记录模块设计演变、跟踪缺陷修复过程，给新人提供可查询的历史上下文。有团队反馈新人上手时间缩短约 40%，代码评审效率提升约 25%。记忆系统让 AI 真正融入了现有协作流程。
个人开发者：长线 side project 的'自动笔记助手'
你可以用自然语言问之前的决策，比如'上周我重新设计过登录流程，当时用了什么鉴权策略？'。插件能回溯选项、方案和代码范围。打开本地 Web 界面（默认 http://localhost:37777），能看到记忆流和会话摘要。对间歇性推进的个人项目尤其友好。
隐私敏感行业：合规边界怎么守？
金融、医疗等行业担心数据上传云端。Claude-Mem 数据全部本地存储，目录可见可控。支持标签机制，可以给某些内容打上'不要记录'类标签，阻止敏感信息被纳入记忆。你可以自定义'能记什么、不能记什么'。
安装与使用体验
/plugin marketplace add thedotmack/claude-mem /plugin install claude-mem
执行完插件安装后，重启 Claude Code，大部分功能就能直接用上。无需改动现有工作流，不用写额外脚本，也不用部署后端。多数配置有合理默认值，用起来更像开关一个功能。如果想定制，比如不同项目用不同策略，就需要了解一些配置项和阈值设定。
和其他方案对比
| 方案类型 | 优点 | 缺点 | 适用场景 |
|---|---|---|---|
| 传统 RAG 系统 | 功能强大，可接多种数据源 | 部署复杂，依赖额外基础设施 | 企业内部知识库 |
| 简单文件注入 | 实现容易，维护成本低 | 缺乏智能检索，容易信息过载 | 小项目 |
| 手动复制粘贴 | 不需要额外工具 | 非常耗时，无法扩展 | 偶发需求 |
| Claude-Mem | 本地混合存储 + 渐进式披露 | 依赖 Claude Code 生态，需调阈值 | Claude 用户 |
Claude-Mem 走的是一条'中等复杂度'路线：比简单注入强得多，又比全自研 RAG 系统轻量很多。这也是很多人称之为 IDE 内部实用层面目前最接地气的长期记忆方案。
局限与风险
摘要质量取决于底层模型
记忆压缩靠 Claude Agent SDK 来做。极端复杂场景下，摘要可能会出现信息遗漏。所以在关键决策类项目中，仍有必要保留人类写的设计文档，不能完全依赖自动摘要当唯一真相来源。
对版本和生态有一定依赖
作为插件，需要较新的 Claude Code 版本支持。IDE 更新时可能会遇到兼容性问题。企业大规模部署需要在内部有一套插件版本管理和回滚机制。
需要一点'调参意识'
默认配置可以直接用，但要在复杂项目里顺手，多少需要调一下参数，比如检索阈值、注入上限、不同项目是否需要单独命名空间。既要让 AI 记得你，又不要记得太多，把上下文弄成信息垃圾场。
工程视角：Agent 时代的标配能力雏形
把 Claude-Mem 放在更大背景里，AI Agent 时代，记忆将从加分项变成标配。
记忆应该是分层的
第一层轻量索引适合高频调用，第二层带时间序用来理解过程，第三层完整细节用于审计还原。这逻辑其实跟人脑挺像：先想大概、再回忆过程、最后才是翻日记。
本地优先 + 可控隐私
不是什么东西都能放到云上跑。有些国家监管要求数据必须留在本地，有些企业不接受把源代码交给第三方。Claude-Mem 采用本地数据库 + 本地向量库的实践，证明在很多 IDE AI 场景下，这条路是可行的。
社区驱动的插件生态
模型厂商提供了足够开放的插件能力，社区开发者能在此基础上做出高价值增强功能。开放能力加激励社区，比自己闭门造车往往走得更远。
实用建议
如果你现在就在用 Claude Code，可以按下面几步来实践。
先从一个真实项目开始
不要拿 demo 仓库测感受，建议选一个开发周期至少一周以上、有明确功能演进的项目。开启 Claude-Mem 正常工作一段时间，观察是否减少了重复解释的时间，AI 是否能更准确理解当前任务所处的上下文。
刻意用几次带检索的提问方式
尝试这类问法：'帮我接着上次我们讨论用户权限系统的地方继续完善表结构。'、'列一下过去三天我们在支付模块里改过哪些东西。'这些问题能很好地压测记忆系统的检索与注入效果。
对团队：把记忆系统写进开发规范
如果你是技术负责人，可以考虑统一在某些关键项目上启用 Claude-Mem，约定一些可检索问题模版，定期 review 记忆摘要质量。这样，Claude-Mem 不只是某个工程师自己安装的插件，而是变成团队协作流程的一部分。
结语
Claude-Mem 做的事情不神秘，也谈不上黑科技，但很扎实。它把真实痛点抓得很准，用的是现成可靠的工程手段，设计上有节制感。未来几年，让 AI 真正记住你和在正确时机想起正确的事，会变成所有智能工具绕不过去的基础能力。Claude-Mem 做的，是帮我们先给这块拼图拼了一个还不错的第一版样子。
