claude-mem 记忆层实战：写入、存储、检索、注入四段式架构

1. 从“聊完就忘”说起：claude-mem 到底想解决什么

如果你用 Claude 这类对话式 AI 做过稍微长一点的项目，大概率遇到过这种尴尬：昨天聊了三个小时，把需求、约束、命名规范、踩过的坑都对齐了，今天开个新会话，它一脸无辜地问你“请问你想做什么”。你不得不把昨天的上下文重新贴一遍，贴到一半发现 token 快满了，于是又得删删减减。这个体验，说难听点，就像跟一个每天失忆的同事协作。

claude-mem这个名字，直译过来就是“Claude 的记忆”。它要干的事情非常朴素：给 Claude 加上一层可持久化的记忆，让跨会话的上下文不再从零开始。注意，它不是官方功能，而是一个围绕 Claude 生态构建的记忆层方案，核心思路是把对话中值得留存的信息抽取出来，存到本地或可控的存储里，在需要的时候再按相关性召回，塞回新的会话上下文。

这件事为什么值得单独拿出来讲？因为“记忆”这个词听起来简单，做起来全是坑。你让模型记住一切，token 立刻爆炸；你让它只记重点，那什么算重点？谁来判定？判定错了怎么办？召回的时候怎么保证不把无关信息塞进去污染当前任务？这些问题没有一个是靠一句“加个向量数据库”就能糊弄过去的。claude-mem这类项目的价值，恰恰在于它把“记忆”拆成了写入、存储、检索、注入四个可独立优化的环节，而不是一个黑盒。

这篇文章适合谁看？三类人。第一类是把 Claude 当日常生产力工具、被上下文断裂折磨过的重度用户；第二类是想自己动手搭一套 AI 记忆系统的开发者，你会在这里看到完整的架构取舍和参数思路；第三类是对“AI 长期记忆”这个概念好奇、想知道它到底能做到什么程度的技术观察者。我会尽量把每个设计决策背后的“为什么”讲清楚，而不是甩一堆代码让你自己猜。

需要先说明一点：claude-mem目前没有官方统一的标准实现，社区里有多种形态，有的做成 MCP 服务，有的做成命令行工具，有的直接是一组脚本加本地数据库。所以下面讲的内容，是基于这类记忆层方案的通用工程实践来展开的，具体到你手上的版本，接口和字段名可能有差异，但底层逻辑是相通的。

2. 记忆层的四段式架构：写入、存储、检索、注入

2.1 为什么不能直接把历史对话全塞回去

最直觉的做法是：把过去所有对话存成一个文本文件，每次新会话开头全量贴进去。这个方案在对话量小的时候能用，一旦超过某个阈值就彻底崩了。原因有两个，一个是硬性的，一个是软性的。

硬性原因是上下文窗口。Claude 的上下文长度是有限的，你贴进去的历史越多，留给当前任务的“工作空间”就越少。假设窗口是 200K token，你贴了 150K 的历史，那当前这轮对话只剩 50K 可用来思考、生成、读文件。更糟的是，很多历史信息对当前任务是噪音，模型要在噪音里找信号，注意力被稀释，回答质量反而下降。

软性原因更隐蔽：历史里的错误会固化。昨天你随口说了一句“这个字段先叫 temp 吧，回头改”，今天模型把它当成正式命名写进代码。记忆系统如果不做筛选和时效管理，就会把临时决策、废弃方案、甚至口误一起永久保存，越积越毒。所以“全量记忆”不是记忆，是负债。

2.2 写入环节：什么值得记，谁来判定

写入是记忆系统的第一道闸门，也是最容易被做烂的一环。常见的三种策略，我按推荐程度从低到高排：

claude-mem这类方案通常走第三条路：在对话过程中或会话结束时，用一个轻量的抽取步骤，让模型把值得留存的信息提炼成结构化条目。抽取的粒度很关键，太粗会丢细节，太细会碎片化。实践中比较稳的做法是按“事实、决策、偏好、待办”四类来分：

• 事实：项目用了什么技术栈、目录结构长什么样、某个接口的返回格式。
• 决策：为什么选 A 不选 B，当时排除了哪些方案。
• 偏好：用户习惯的命名风格、代码缩进、注释语言、回复详略程度。
• 待办：还没做完的事、下次要继续的点。

这四类的生命周期完全不同。事实和偏好相对稳定，可以长期保留；决策有过期风险，项目方向一变就作废；待办一旦完成就该归档。把它们混在一起存，检索时就没法按类型加权，这是很多自建记忆系统效果差的根因。

提示：抽取步骤本身也要消耗 token，所以不要每轮都抽。比较经济的做法是会话结束前抽一次，或者每积累 N 轮抽一次，N 取 5 到 10 之间比较平衡。

2.3 存储环节：向量库不是唯一答案

一提到 AI 记忆，很多人条件反射就是“上向量数据库”。向量检索确实擅长语义相似，但它不是万能的，甚至在某些场景下不如传统方案。

向量检索的强项是“意思相近但用词不同”的召回，比如你搜“登录超时”，它能召回“认证过期”。但它的弱项也很明显：精确匹配差、可解释性差、更新成本高。如果你要查的是“上次那个叫 user_token 的字段”，向量检索可能给你返回一堆语义相关但字段名不对的条目，而一个简单的全文索引反而一击即中。

所以成熟的记忆层通常是混合存储：结构化字段（时间、类型、标签、项目名）走关系库或文档库，做精确过滤；文本内容走向量索引，做语义召回。检索时先用结构化条件缩小范围，再在候选集里做语义排序。这个“先过滤后排序”的顺序不能反，反了就是拿大炮打蚊子，又慢又不准。

存储位置也有讲究。本地文件（SQLite、JSON）胜在简单、可控、无隐私顾虑；云端服务胜在跨设备同步。claude-mem这类工具大多默认本地，因为记忆里往往包含项目细节甚至敏感信息，放本地是最稳妥的默认值。如果你确实需要多设备，再考虑加密同步，而不是一上来就上云。

2.4 检索与注入：召回多少条才合适

检索出来的记忆怎么塞回上下文，这一步直接决定体验好坏。塞太少，模型还是“失忆”；塞太多，等于变相全量。我的经验是控制在一个预算内，而不是一个固定条数。

具体做法：给记忆注入分配一个 token 预算，比如 2000 token。检索时按相关性排序，从高到低往预算里填，填满为止。这样无论召回条目长短，总占用是可控的。相关性打分可以综合几个维度：语义相似度、时间新鲜度、类型权重（待办和决策通常比陈旧事实更重要）、项目匹配度。

注入的位置也有讲究。放在系统提示里，模型会当成“背景知识”，比较稳定；放在用户消息前，模型会当成“当前上下文”，注意力更高但可能干扰当前指令。比较稳的做法是分两层：稳定的偏好和事实放系统层，与当前任务强相关的记忆放对话层。这样既保证了长期一致性，又不会让无关记忆抢占当前任务的注意力。

3. 动手搭一套最小可用的记忆流

3.1 环境与依赖的现实选择

假设你要自己实现一个claude-mem风格的最小系统，第一步是选技术栈。我的建议是能用标准库就不用第三方，记忆系统本身不复杂，依赖越多越难维护。

• 语言：Python 或 Node 都行，看你顺手。Python 生态里处理文本和向量的库更成熟。
• 存储：起步用 SQLite，单文件、零配置、支持全文检索（FTS5），足够撑到几万条记忆。
• 向量：如果记忆量不大（几千条以内），可以先用简单的 TF-IDF 或 BM25 做召回，不急着上 embedding。等量级上来了再引入向量索引。
• 接口：如果要做成 Claude 能调用的工具，MCP 是当前比较顺的路径；如果只是自己用，一个命令行脚本加一个注入钩子就够了。

这里有个容易忽略的点：记忆的写入和读取要解耦。写入可以慢、可以异步，读取必须快，因为它在每次会话开始时都要跑。所以别把抽取逻辑塞在读取路径上，否则每次开新会话都要等模型抽一遍，体验极差。

3.2 抽取提示词怎么写才不跑偏

抽取质量几乎完全取决于提示词。我踩过的坑是：一开始让模型“总结这段对话的重点”，结果它总结出一堆正确的废话，比如“用户讨论了项目需求”。这种记忆存了等于没存。

有效的抽取提示词要满足三个条件：限定类型、要求具体、强制结构化。下面是一个我实测比较稳的模板思路：

从以下对话中抽取值得长期记忆的条目，只输出 JSON 数组。 每条包含字段： - type: fact | decision | preference | todo - content: 一句话，必须包含具体名词（文件名、字段名、技术名），禁止抽象概括 - project: 所属项目标识 - confidence: 0-1，表示这条信息的确信度 规则： 1. 临时性、试探性的内容不要抽取 2. 已经被后续对话推翻的内容不要抽取 3. 没有具体名词的条目直接丢弃 4. 最多输出 10 条，按重要性排序

关键在第三条“没有具体名词的条目直接丢弃”。这一条能过滤掉绝大部分废话。你可以试试，不加这条限制，模型能给你整出一半的“用户希望项目顺利进行”这种垃圾条目。

3.3 检索排序的权重怎么调

检索排序没有万能公式，但有一个可用的起点。我一般用加权求和：

score = 0.5 * semantic_similarity \ + 0.2 * recency_score \ + 0.2 * type_weight \ + 0.1 * project_match

其中recency_score用指数衰减，半衰期设 7 天左右比较合适——太短会丢掉稳定事实，太长会让过期决策阴魂不散。type_weight里 todo 和 decision 给高权重，fact 中等，preference 看场景。project_match是硬性加成，当前项目匹配的记忆直接加满。

调参的时候别凭感觉，准备一组测试查询，人工标注哪些记忆该被召回，然后看你的排序能不能把它们排进前 5。这个评估集不用大，20 条查询就够你发现明显的权重问题。

3.4 注入格式对模型行为的影响

记忆注入的格式会实实在在影响模型的表现。我对比过几种写法，结论是：结构化、带来源、带时间的格式效果最好。

[记忆 - 2024-06-12 - 决策] 项目 X 的认证方案选用 JWT 而非 Session，原因是需要支持多端无状态调用。 [记忆 - 2024-06-15 - 偏好] 用户偏好 Python 代码使用 4 空格缩进，注释用中文。

带时间让模型能判断信息新鲜度，带类型让它知道这条是硬约束还是软偏好，带项目避免跨项目串味。相比之下，把记忆拼成一段无格式的散文，模型经常分不清哪条是当前任务相关的，哪条是历史遗留。

注意：注入的记忆里如果包含与当前指令冲突的内容，模型可能优先服从记忆。所以当用户明确改变主意时，要有一条“覆盖”机制，把旧记忆标记为失效，而不是简单追加新记忆。否则新旧两条并存，模型会精神分裂。

4. 那些文档不会告诉你的坑

4.1 记忆污染：错误信息如何自我强化

这是最阴险的坑。假设某次抽取把“用户说这个方案可能不行”错误地记成了“用户决定采用这个方案”。下次会话这条错误记忆被召回，模型基于它继续推理，产出的内容又被抽取成新记忆，错误就被“洗白”成了事实。几轮之后，你根本找不到错误是从哪来的。

防御手段有三个。第一，抽取时保留confidence字段，低置信度的记忆在注入时降权或标注“待确认”。第二，给记忆加来源引用，指向原始对话的某一段，出问题时能回溯。第三，定期做记忆审计，把长期没被召回、或者被后续记忆频繁覆盖的条目清理掉。别指望一次抽取永远正确，记忆系统需要维护，就像数据库需要清理一样。

4.2 上下文窗口的隐形消耗

很多人只算注入记忆的 token，忘了检索过程本身也在消耗。如果你的检索要调用 embedding 接口，那是额外成本；如果检索结果要经过一次重排序，又是一次模型调用。这些开销在会话频繁的时候会累积得很快。

我的做法是给记忆系统设一个总预算，包括检索开销和注入开销，超过就降级。比如正常情况注入 2000 token，如果这次检索特别慢或特别贵，就只注入 500 token 的高置信度记忆。宁可少记一点，也不能让记忆系统本身成为瓶颈。

4.3 多项目串味与命名冲突

如果你同时维护多个项目，记忆串味是高频问题。项目 A 里有个config.json，项目 B 里也有个config.json，检索时如果不做项目隔离，模型会把两个项目的配置混为一谈。

解决办法是在存储层就做好隔离，每条记忆强制带project字段，检索时默认只查当前项目，跨项目查询要显式开启。另外，项目标识别用容易重名的名字，用路径哈希或者带命名空间的 ID 更稳。我见过有人用“test”当项目名，结果三个测试项目的记忆全糊在一起，排查了半天才发现是命名问题。

4.4 记忆的“遗忘”比“记住”更难设计

删除记忆听起来简单，实际很棘手。硬删除会丢失审计线索，软删除（标记失效）又会让存储膨胀。而且“什么时候该忘”本身就没有标准答案：三个月前的技术决策，可能还有参考价值，也可能早就过时了。

我目前的策略是分层遗忘：待办类记忆完成后立即归档；决策类记忆保留但降权，超过一定时间（比如 90 天）只保留摘要；事实和偏好长期保留，但定期去重合并。这个策略不完美，但比“永不遗忘”和“定期清空”都更实用。遗忘机制的设计，某种程度上比记忆机制更能体现一个系统的成熟度。

5. 把记忆层接进日常工作流

5.1 会话开始时的自动注入

最顺手的集成方式是做一个会话启动钩子：新会话一开始，自动根据当前工作目录或用户输入的第一句话，检索相关记忆并注入。这样你不需要手动“回忆”，记忆是自动到位的。

实现上，钩子要做三件事：识别当前项目、跑一次检索、把结果格式化后拼到系统提示或首条消息里。注意检索要用当前任务的意图做查询，而不是用空查询。如果会话开始时还没有明确任务，可以先用项目名做一次宽泛召回，等用户说了第一句话再补一次精准召回。

5.2 会话结束时的批量抽取

抽取放在会话结束时做，好处是不打断对话节奏，而且此时上下文最完整，模型能判断哪些信息最终被确认了。实现上可以在退出时触发，也可以定时触发（比如每 10 轮）。

抽取完别忘了做一次冲突检测：新抽取的条目和已有记忆有没有矛盾？如果有，是覆盖还是并存？这个判断可以交给模型做，但要有明确的规则，比如“同一项目、同一主题的新决策覆盖旧决策，事实类冲突则都保留并标注”。

5.3 手动干预的入口要留好

再智能的自动系统也需要手动兜底。至少要留三个入口：手动添加记忆（“记住这个”）、手动删除记忆（“忘掉那个”）、手动查询记忆（“我之前说过什么关于 X 的”）。这三个入口不需要多漂亮，但必须有，否则一旦自动抽取出错，你只能干瞪眼。

我自己的习惯是每周花十分钟翻一遍最近新增的记忆，把明显不对的删掉。这十分钟省下来的，是后面无数次被错误记忆带偏的时间。

5.4 效果评估：怎么知道记忆有没有用

最后说一个容易被忽略的点：你得有办法判断记忆系统到底有没有提升效率。我的做法是记录两个指标：一是重复解释次数，即同一个背景信息你需要向模型重复说明的频率；二是任务首次成功率，即不需要纠正就能得到可用结果的对话比例。这两个指标在引入记忆层前后对比，如果没改善，说明你的记忆系统要么抽取质量差，要么检索不准，得回去调。

别用“感觉变好了”来评估，感觉最不靠谱。跑两周数据，用数字说话，你才知道自己搭的这套东西是真有用，还是只是心理安慰。

这套记忆流的搭建过程，本质上是在给 AI 协作补上“连续性”这一课。工具会迭代，接口会变，但写入、存储、检索、注入这四个环节的权衡逻辑是稳定的。把这套逻辑吃透，不管以后换成什么模型、什么平台，你都能快速搭出一套顺手的记忆层。