claude-mem 长期记忆管理：抽取-存储-注入三段式设计

1. 从零认识 claude-mem：它到底解决什么问题

第一次看到claude-mem这个名字，很多人会以为它又是一个套壳的对话客户端。实际上完全不是。claude-mem是一套围绕 Claude 对话过程做长期记忆管理的工具方案，核心目标只有一个：让 AI 在跨会话、跨项目的协作中，记住你之前告诉过它的关键信息，而不是每次开新对话都从零开始。

我接触它的起因很朴素。那段时间我同时在推进三个项目，每个项目都有各自的代码规范、目录结构、命名习惯和业务背景。每次打开新对话，我都要把同样的背景信息重新粘贴一遍，少则几百字，多则上千字。更麻烦的是，有些偏好是逐步积累出来的，比如"这个项目里所有时间字段统一用 UTC 存储""接口返回结构不要包一层 data"——这些约定散落在历史对话里，新会话根本读不到。claude-mem要解决的，就是这种上下文断裂问题。

它适合谁？三类人最受益。第一类是长期用 Claude 做开发辅助的工程师，项目周期长、上下文多；第二类是内容创作者，需要 AI 记住自己的写作风格、选题偏好、常用素材；第三类是研究者或学生，需要 AI 记住某个课题的术语体系、参考文献脉络。如果你只是偶尔问几个独立问题，那它对你的价值有限；但只要你的对话有连续性，它就能明显减少重复沟通成本。

从技术定位上看，claude-mem不是模型本身，也不是官方功能，而是一层记忆中间件。它把对话中值得留存的信息抽取出来，结构化存储，再在合适的时机注入到新的对话上下文中。理解这一点很关键，因为它决定了后面所有的设计取舍——记忆存什么、怎么存、什么时候取、取多少，全都是围绕"中间件"这个角色展开的。

2. 整体设计思路：为什么是"抽取-存储-注入"三段式

2.1 记忆系统的核心矛盾

做记忆系统，绕不开一个根本矛盾：上下文窗口是有限的，而信息是无限的。你不可能把所有历史对话都塞进新会话，那样既浪费 token，又会稀释真正重要的信息，甚至让模型抓不住重点。所以任何记忆方案的本质，都是在做信息压缩与筛选。

claude-mem采用的是"抽取-存储-注入"三段式结构。这个结构不是拍脑袋定的，而是被现实逼出来的。我试过更简单的方案，比如直接把历史对话全文存成文件，新会话时整段读进来。结果很惨：几千字的对话里，真正有用的可能就三五条，其余全是寒暄和试错过程，读进去反而干扰模型判断。

三段式的逻辑是：抽取阶段负责从原始对话里挑出"值得记"的内容，做第一次压缩；存储阶段负责把这些内容按类别、按项目组织好，方便检索；注入阶段负责在新会话开始时，只把最相关的那部分记忆取出来，拼进上下文。每一段都在做减法，最终进入上下文的是精华中的精华。

2.2 为什么不用向量数据库一把梭

很多人第一反应是上向量数据库，做语义检索。我一开始也这么想，但实测下来，纯向量方案在个人记忆场景里有几个坑。

第一，记忆条目往往很短。一条记忆可能就是"项目 X 用 pnpm 不用 npm"，这种短文本做 embedding，语义区分度不高，检索时容易把不相关的条目也召回来。第二，记忆有强时效性和强归属。同一个"命名规范"，项目 A 和项目 B 可能完全相反，纯语义检索分不清该用哪条。第三，维护成本高。向量库要跑服务、要管索引、要处理更新，对个人用户来说太重了。

所以claude-mem更偏向结构化存储 + 规则检索的组合。用文件或轻量数据库按项目、按类别分桶，检索时先按归属过滤，再按关键词或标签匹配。这套方案不炫技，但胜在可控、可解释、易调试。你随时能打开存储文件，肉眼看到 AI 到底记住了什么，这对建立信任非常重要。

2.3 分层记忆的设计

我在实践中把记忆分成三层，这个分层思路后来被证明是整个方案里最有价值的部分。

• 全局层：跨项目通用的偏好，比如"回答尽量简洁，不要客套话""代码示例优先用 Python"。这层记忆对所有会话生效。
• 项目层：绑定到具体项目的约定，比如技术栈、目录结构、业务术语。只在对应项目的会话里注入。
• 会话层：临时的、短期的上下文，比如"这次我们在调试登录超时问题"。会话结束就可以丢弃或降级。

分层的意义在于精准注入。如果只有一层，你要么注入太多无关信息，要么漏掉关键约定。分层之后，注入时按"全局 + 当前项目 + 当前会话"组合，既完整又不冗余。这个设计我踩过坑才定下来——早期没分层，结果在项目 B 的会话里注入了项目 A 的规范，AI 给出的建议直接跑偏。

3. 核心细节解析：记忆到底怎么抽取和存储

3.1 抽取什么：判断"值得记"的四条标准

抽取是整套方案里最难的一环，因为它需要判断"什么值得记"。我总结出四条标准，实测下来覆盖了绝大多数场景。

第一条，稳定性。只记那些不会频繁变化的信息。比如"这个项目用 TypeScript"值得记，"今天先改这个文件"不值得记。判断方法很简单：问自己"这条信息一周后还有效吗"，答案是否定的就跳过。

第二条，复用性。只记那些未来还会用到的信息。一次性的调试过程、临时的报错排查，用完就完了，没必要记。但如果某个报错暴露了项目的某个固有约束，那这个约束值得记。

第三条，特异性。只记那些"不记就会重复解释"的信息。通用常识不用记，模型本来就知道；只有你的个人偏好、项目特有约定才需要记。

第四条，可执行性。优先记那些能直接影响 AI 输出的信息。比如"接口错误码统一用字符串"比"这个项目很重要"有用得多，因为前者能直接约束 AI 的代码生成。

这四条标准不是绝对的，但能帮你过滤掉八成噪音。我早期贪多，什么都想记，结果存储文件迅速膨胀，注入时反而抓不住重点。后来严格按这四条筛，记忆库精简了很多，效果反而更好。

3.2 怎么存：文件结构设计

存储结构直接决定了检索效率。我采用的是目录分桶 + 单条记忆独立成行的方式，具体结构大致如下：

memory/ global.md # 全局层记忆 projects/ project-a.md # 项目 A 的记忆 project-b.md # 项目 B 的记忆 sessions/ 2024-xx-xx.md # 会话层临时记忆

每个文件内部，一条记忆占一行或一个条目，格式尽量简单：

- [规范] 时间字段统一用 UTC 存储 - [工具] 包管理用 pnpm，不用 npm - [术语] "订单"在代码里叫 order，"工单"叫 ticket

为什么用 Markdown 而不是 JSON？因为可读性优先。记忆库是要给人看的，你要能随时打开检查、手动修正。JSON 虽然结构化好，但手改容易出错，Markdown 一目了然。而且注入时直接把 Markdown 拼进上下文，格式天然友好，不需要额外转换。

注意：每条记忆前面加一个方括号标签（如 [规范]、[工具]、[术语]），检索和注入时可以按标签过滤。这个小习惯能大幅提升后续的精准度。

3.3 抽取的触发时机

抽取不是每轮对话都做，那样太频繁，会拖慢响应。我一般设两个触发点：一是会话结束时，做一次批量抽取；二是用户显式指令，比如输入"记住这条"时立即抽取。

会话结束抽取的好处是，此时上下文完整，模型能综合整段对话判断哪些值得记。缺点是如果会话中途崩溃，可能丢失。所以关键信息我会用显式指令即时保存，双保险。

抽取时给模型的提示词很关键。我用的模板大意是："请从以下对话中提取值得长期记忆的信息，按 [规范]/[工具]/[术语]/[偏好] 分类，每条一行，只保留稳定、可复用、项目特有的内容，忽略寒暄和一次性操作。"这个提示词里的每个限定词都是踩坑换来的，少一个都会导致抽取质量下降。

4. 实操过程：从安装到跑通第一条记忆

4.1 环境准备与依赖

claude-mem本身是轻量方案，对环境的依赖很少。核心就是能读写本地文件、能调用 Claude 的接口。我用的是 Python 环境，主要依赖就一个 HTTP 请求库和一个文件处理库。

pip install requests

如果你用的是 Node 环境，换成对应的axios或原生fetch也一样。关键是不要引入重型框架，记忆系统本身逻辑不复杂，引入框架只会增加调试难度。

目录初始化很简单，建一个memory文件夹，按前面的结构建好子目录即可：

mkdir -p memory/projects memory/sessions touch memory/global.md

4.2 配置注入逻辑

注入是让记忆生效的关键一步。我的做法是在每次发起新对话前，先读取相关记忆文件，拼成一段"背景说明"，放在用户消息的最前面。

def build_context(project=None, session=None): parts = [] parts.append(open("memory/global.md").read()) if project: parts.append(open(f"memory/projects/{project}.md").read()) if session: parts.append(open(f"memory/sessions/{session}.md").read()) return "\n\n".join(parts)

这段代码很朴素，但有几个细节要注意。第一，顺序有讲究：全局在前，项目在中，会话在后，越靠后越具体，模型理解时有个从泛到细的过程。第二，要加分隔，用空行或标题把不同层隔开，避免模型混淆。第三，要控制总量，如果拼出来超过一定长度（我一般控制在 2000 字以内），就要做裁剪，优先保留项目层和会话层。

提示：注入内容建议加一个明确的引导语，比如"以下是本次对话需要遵循的背景约定"，让模型知道这段是约束而非普通对话。

4.3 跑通第一条记忆的完整流程

我拿一个真实场景走一遍。假设我在做项目 A，第一次对话时告诉 AI："这个项目用 pnpm，时间字段用 UTC。"对话结束后，触发抽取。

抽取结果写入memory/projects/project-a.md：

- [工具] 包管理用 pnpm - [规范] 时间字段统一用 UTC 存储

第二天开新会话，我先调build_context(project="project-a")，把这段记忆拼进上下文。然后问 AI："帮我写个获取订单列表的函数。"AI 生成的代码里，import 用的是 pnpm 风格的依赖声明，时间处理也自动用了 UTC。整个过程我没再重复任何约定。

这个流程跑通的那一刻，我就知道这套方案值了。它把"重复解释"这件事彻底消灭了，省下的不只是打字时间，更是每次重新对齐上下文的脑力消耗。

4.4 参数选择：注入多少条记忆合适

注入条数不是越多越好。我做过对比测试：注入 5 条、15 条、30 条记忆，观察 AI 回答质量。结果是10 到 15 条是甜点区。少于 10 条，关键约定可能漏掉；多于 20 条，模型开始出现"注意力分散"，回答里会莫名其妙地提到不相关的约定。

所以我在注入前会做一次排序和截断：按"项目层 > 全局层 > 会话层"的优先级，同层内按最近使用时间排序，取前 15 条。这个策略在多个项目上验证过，稳定性不错。

5. 常见问题与排查技巧实录

5.1 记忆没生效：从三个方向排查

最常见的问题是"我明明记了，AI 却没遵守"。排查按这个顺序走。

先查注入。打开你拼好的上下文，确认那条记忆真的在里面。很多时候是注入逻辑的 bug，比如项目名拼错、文件路径不对，导致记忆根本没读进来。

再查冲突。如果记忆注入了但没生效，很可能是多条记忆互相矛盾。比如全局层写"回答要详细"，项目层写"回答要简洁"，模型就懵了。解决办法是项目层覆盖全局层，在注入时对同类别记忆做去重，保留更具体的那条。

最后查表述。记忆的措辞也会影响效果。"尽量用 UTC"就不如"时间字段统一用 UTC 存储"来得明确。模糊的表述模型可能理解偏，改成祈使句、明确约束，效果立竿见影。

5.2 记忆库膨胀：定期清理的三个动作

用久了记忆库一定会膨胀，这时候要主动清理。我一般做三个动作。

合并同类项。多条讲同一件事的记忆合并成一条。比如"用 pnpm""不用 npm""锁文件用 pnpm-lock"可以合成"包管理统一用 pnpm，锁文件为 pnpm-lock.yaml"。

降级过期项。有些记忆当时有效，现在项目已经不用了，就移到归档文件或直接删除。我每月做一次，删掉大概两成。

提升高频项。反复用到的记忆，从项目层提升到全局层，让它对所有项目生效。比如"代码注释用中文"这种，如果多个项目都这么要求，就该进全局层。

5.3 常见问题速查表

5.4 几个踩过的坑

坑一：把过程当结论记。早期我把"我们试了方案 A 不行，又试了方案 B"整段记下来，结果新会话里 AI 还在纠结方案 A。记忆要记结论，不记过程。

坑二：跨项目污染。有一次全局层写了条很具体的规范，结果所有项目都被约束了。教训是：越具体的记忆越要放项目层，全局层只放真正通用的。

坑三：忘了版本。项目技术栈升级后，旧记忆没更新，AI 还在按老规范生成代码。所以技术栈变更时，要同步更新记忆库，最好在记忆里带上时间戳。

6. 进阶玩法：让记忆系统更聪明

6.1 记忆的自动衰减

手动清理毕竟费精力。我后来加了个简单的衰减机制：每条记忆记录最后使用时间，超过 60 天没被注入过的，自动标记为"待确认"，下次注入时排在最后，或者干脆不注入。这样过时记忆会自然沉底，不用我天天盯着。

实现上就是在每条记忆后面加个时间戳，注入时按时间排序。简单，但有效。

6.2 按任务类型切换记忆集

同一个项目，写代码和写文档需要的记忆不一样。写代码关心技术栈和规范，写文档关心术语和风格。所以我给记忆加了"场景标签"，注入时根据当前任务类型筛选。

比如记忆写成- [规范][代码] 时间字段用 UTC，当任务是写代码时，只注入带[代码]标签的。这样注入更精准，条数也能压得更少。

6.3 记忆的版本管理

记忆库本质上是会演进的配置文件，那就该像管代码一样管它。我用 Git 管理memory目录，每次修改都提交，这样能追溯"某条记忆是什么时候加的、为什么加"。出问题时可以回滚，也能看到记忆的演化历史。这个习惯看起来小题大做，但当你发现某条记忆导致 AI 连续跑偏时，能快速定位是哪次改动引入的，省下大量排查时间。

6.4 和其他工具的配合

claude-mem不排斥其他工具。我把它和本地的笔记系统打通，记忆库里的条目可以一键同步到笔记里做二次整理；反过来，笔记里标记为"重要"的内容也能导入记忆库。这样记忆库专注服务 AI 对话，笔记系统专注个人知识管理，各司其职。

我个人在实际操作中的体会是，记忆系统的价值不在于技术多复杂，而在于坚持维护。再好的方案，如果记了不清理、不更新，很快就会变成负担。反过来，哪怕只是最简单的文件存储，只要你能持续维护，它带来的效率提升都是实打实的。最后分享一个小技巧：每次开新项目时，先花五分钟把已知的约定写进记忆库，后面能省下几十次的重复解释——这笔账怎么算都划算。