1. 项目缘起与核心定位
第一次看到claude-mem这个名字，我的直觉是：这应该是一个给 Claude 系列模型做“记忆层”的项目。事实也确实如此。它要解决的是一个所有长期跟大模型打交道的人都会遇到的痛点——模型没有持久记忆。每次开新会话，之前聊过的偏好、项目背景、技术栈约定、甚至你反复纠正过的错误，全部归零。你得像复读机一样重新交代一遍上下文，效率极低。
claude-mem的核心价值，就是给 Claude 这类对话式模型外挂一套可持久化的记忆系统。它把对话中值得留存的信息抽取出来，存到本地或指定存储里，在后续会话中按需召回，再注入到提示词中。这样一来，模型就能“记住”你是谁、你在做什么项目、你习惯用什么技术栈、你讨厌什么样的代码风格。
这个项目适合几类人：一是长期用 Claude 做开发辅助的工程师，二是把 Claude 接入自己工作流的产品或自动化玩家，三是对“AI 记忆机制”这个方向感兴趣、想自己动手改造的爱好者。哪怕你只是想搞明白“记忆”这件事在工程上到底怎么落地，这个项目也是一个非常好的解剖样本。
我先把话说在前面：claude-mem不是一个开箱即用的商业产品，它更像一套思路 + 工具链的组合。你需要理解它的设计逻辑，才能把它用得顺手。下面我会从整体设计、核心机制、实操落地、问题排查几个层面，把它拆开讲透。
2. 整体设计思路与方案选型
2.1 为什么“记忆”不能只靠加大上下文窗口
很多人第一反应是：现在上下文窗口都到 20 万 token 了，还需要单独做记忆吗？我实测下来的结论是：窗口大不等于记忆好。原因有三个。
第一，成本。每次会话都把历史全量塞进去，token 消耗是线性增长的。聊得越久，每一轮的开销越大，长期下来账单很难看。
第二，注意力稀释。上下文里塞的东西越多，模型对关键信息的注意力就越容易被分散。你会发现它开始忽略你早期强调过的约束，这就是所谓的“中间遗忘”现象。
第三，跨会话断裂。窗口再大，关掉会话就没了。而真正的记忆需求，恰恰是跨会话、跨天、跨项目的。
所以claude-mem的思路不是“塞更多”，而是“存下来、挑出来、再注入”。这是一个典型的检索增强思路，只不过检索的对象从文档变成了“关于你的记忆”。
2.2 记忆分层的设计哲学
我在研究这个项目时，最认同的一点是它对记忆做了分层。不是所有信息都值得同等对待。它大致把记忆分成几类：
- 事实型记忆：你的身份、项目名称、技术栈、目录结构约定。这类信息变化慢，优先级高。
- 偏好型记忆：你喜欢的代码风格、命名习惯、回复语气。这类信息需要从对话中慢慢提炼。
- 情境型记忆：当前任务的目标、正在处理的 bug、临时约定。这类信息生命周期短，任务结束就可以淡出。
为什么要分层？因为召回策略不同。事实型记忆几乎每次都要带上，偏好型记忆按需带上，情境型记忆只在相关任务里带上。如果不分层，一股脑全塞，等于又回到了“塞满上下文”的老路。
提示：分层的关键不是分类本身，而是每层对应不同的“召回触发条件”和“过期策略”。这是整个项目最值得借鉴的设计点。
2.3 存储选型的取舍
claude-mem在存储上没有搞得很重。常见做法是用本地文件 + 轻量索引，比如 JSON 或 SQLite 存记忆条目，再用向量或关键词做检索。为什么不直接上重型向量数据库？
我的理解是：记忆条目量级不大。一个人的偏好和项目背景，撑死几百上千条，远没到需要分布式向量库的程度。用本地文件的好处是透明、可编辑、可版本控制。你甚至可以直接打开文件看模型到底记住了你什么，这在调试时非常有用。
如果你追求检索精度，可以加一层 embedding；如果追求简单，关键词匹配 + 标签过滤就够用。这个取舍完全取决于你的使用强度。我个人的建议是：先跑通关键词方案，等真的觉得召回不准了，再上向量。过早引入复杂度，只会让你在调试检索质量时怀疑人生。
3. 核心机制拆解与实操要点
3.1 记忆的写入：什么时候该记
写入是整个系统的入口，也是最容易做砸的地方。如果什么都记，记忆库很快就会被噪音淹没；如果记得太少，又起不到作用。claude-mem的常见做法是在会话结束或关键节点触发抽取。
具体来说，抽取的触发点通常有这么几个：
- 用户明确表达偏好时，比如“以后都用 TypeScript”“注释写中文”。
- 用户纠正模型时，比如“不对，这个项目用的是 pnpm 不是 npm”。
- 会话结束时，对整段对话做一次摘要，提炼出值得留存的事实。
这里有个实操心得：抽取最好用一次独立的模型调用，而不是让主对话模型顺手做。因为主对话模型正沉浸在任务里，它没有“元视角”去判断什么值得记。单独调用一次，给它明确的指令——“从以下对话中提取关于用户的长期事实和偏好，忽略临时任务细节”——效果会好很多。
写入的条目建议带上元数据：时间戳、来源会话、置信度、标签。置信度这个字段特别有用，因为模型抽取的东西不一定准，你可以给低置信度的条目打个标记，召回时降权或人工复核。
3.2 记忆的召回：怎么挑出该用的
召回是决定体验的关键。claude-mem的召回逻辑，我总结成一句话：先过滤，再排序，最后截断。
- 过滤：根据当前对话的主题，先按标签或类别筛掉不相关的记忆。比如当前在聊前端，就没必要把后端部署的记忆拉进来。
- 排序：对候选记忆按相关性打分。相关性可以来自关键词重叠、向量相似度、时间新鲜度、置信度加权。
- 截断：只取 top-N 条注入提示词。N 不能太大，否则又变成上下文污染。
这里有个参数需要你根据实际情况调：注入的记忆条数上限。我一般从 5 条起步，观察模型是否用上了这些信息。如果发现它经常忽略，可能是条数太多被稀释了，降到 3 条试试；如果发现它老是缺关键背景，就适当加。
注意：召回的记忆要带来源标注。比如“根据你之前的偏好……”。这样模型知道这是外部注入的信息，而不是当前对话里说过的，能减少它把记忆和当前指令混淆的概率。
3.3 记忆的更新与遗忘：别让它变成垃圾场
一个只写不删的记忆系统，用不了多久就会退化。claude-mem必须处理更新和遗忘。
更新指的是：当新信息和旧记忆冲突时，以新的为准，并标记旧条目失效。比如你之前说用 npm，后来说改用 pnpm 了，系统应该把 npm 那条标记为过期，而不是两条都留着让模型纠结。
遗忘有两种策略：时间衰减和容量淘汰。时间衰减是给每条记忆算一个“新鲜度”，越久没被召回的记忆权重越低。容量淘汰是设一个上限，超了就淘汰最不常用的。我倾向于两者结合：情境型记忆靠时间衰减，事实型记忆靠人工或显式更新。
实操中我踩过的坑是：遗忘策略太激进，把重要偏好删了。后来我改成事实型记忆永不自动删除，只标记失效，需要人工确认才物理删除。这样安全很多。
4. 完整落地流程与关键环节实现
4.1 环境准备与依赖梳理
要跑起一套claude-mem式的记忆系统，你需要准备的东西其实不多：
- 一个能调用 Claude 的 API 环境（或你用的任何对话模型接口）。
- 一个本地存储位置，用来放记忆文件。
- 一个检索层，关键词或向量二选一。
- 一个注入层，负责把召回的记忆拼进提示词。
我建议的目录结构是这样的：
claude-mem/ memories/ facts.json # 事实型记忆 preferences.json # 偏好型记忆 context.json # 情境型记忆 index/ embeddings.db # 可选，向量索引 config.yaml # 召回参数配置用 JSON 存的好处是人可读、可手改。调试阶段你会频繁打开这些文件看模型到底记了什么，JSON 比数据库友好太多。
4.2 记忆抽取的提示词设计
抽取质量直接决定记忆质量。我用的抽取提示词大致是这样的结构：
你是一个记忆抽取器。请从以下对话中提取关于用户的长期信息。 只提取以下三类： 1. 事实：用户的身份、项目、技术栈、环境约定。 2. 偏好：用户喜欢的风格、习惯、明确表达的好恶。 3. 约束：用户强调过的必须遵守的规则。 忽略：临时任务细节、一次性的问题、闲聊内容。 输出 JSON 数组，每条包含： - type: fact | preference | constraint - content: 一句话描述 - confidence: 0-1 - tags: 相关标签数组 对话内容： {conversation}这个提示词的关键在于明确排除项。你不告诉它忽略什么，它就会把“今天天气不错”也记下来。另外，要求输出结构化 JSON，方便后续程序处理。
4.3 召回注入的拼接方式
召回之后，怎么把记忆拼进提示词也有讲究。我试过几种方式，最后固定成这个模板：
[系统记忆] 以下是你需要记住的关于用户的背景信息： - {memory_1} - {memory_2} - {memory_3} 请在回复时考虑以上背景，但不要主动复述这些信息。最后那句“不要主动复述”很重要。不加的话，模型有时候会莫名其妙地来一句“根据我记住的，你喜欢 TypeScript”，显得很出戏。加上之后，它会自然地运用这些信息而不点破。
4.4 一个最小可运行的闭环
把上面几块串起来，一个最小闭环是这样的：
- 用户发起对话。
- 系统根据当前输入，从记忆库召回 top-N 条。
- 把召回结果拼进系统提示词。
- 调用模型生成回复。
- 会话结束，触发抽取，把新记忆写入库。
- 对冲突的旧记忆做失效标记。
这个闭环跑通之后，你就能明显感觉到：第二天的对话，模型还记得昨天的事。那种体验上的提升是很直观的。
5. 常见问题与排查技巧实录
5.1 记忆不生效的排查顺序
“我明明存了记忆，模型却像没看见一样。”这是最常见的问题。排查我一般按这个顺序走：
| 排查点 | 检查方法 | 常见原因 |
|---|---|---|
| 记忆是否写入 | 打开 memories 文件看 | 抽取没触发或抽取为空 |
| 召回是否命中 | 打印召回结果 | 标签不匹配或相似度阈值太高 |
| 注入是否成功 | 打印最终提示词 | 拼接逻辑被覆盖 |
| 模型是否使用 | 观察回复内容 | 记忆条数太多被稀释 |
大部分问题出在第二步：召回没命中。要么是标签体系设计得太细，要么是相似度阈值设得太高。我的经验是，阈值先设低一点，宁可多召回几条，再靠排序截断，比一开始就卡死要好调。
5.2 记忆冲突与污染的处理
另一个高频问题是记忆互相矛盾。比如库里同时有“用 npm”和“用 pnpm”两条。这时候模型的行为会变得不稳定。
解决办法是引入冲突检测：写入新记忆前，先检索是否有语义相近的旧记忆。如果有，就走更新流程而不是新增。更新时保留历史版本，但标记旧版本为失效。这样既不会丢信息，也不会让模型纠结。
提示：冲突检测不用做得很复杂，关键词重叠 + 同标签就足够覆盖大部分场景。别一上来就搞语义去重，容易误伤。
5.3 隐私与数据安全的自查清单
记忆系统存的是关于你的信息，安全不能马虎。我整理了一份自查清单：
- 记忆文件是否在本地，还是上传到了第三方？
- 是否包含敏感信息，比如密钥、账号、内部地址？
- 抽取时是否做了敏感信息过滤？
- 记忆文件是否有访问权限控制？
我的做法是：抽取后过一遍敏感词过滤，命中就直接丢弃该条。宁可少记，也不要记进不该记的东西。另外，记忆文件建议放在项目私有目录，别提交到公开仓库。
5.4 性能与成本的实际观察
最后说说成本。加了记忆系统之后，每轮对话的 token 消耗会增加，主要来自两部分：召回的记忆注入，以及会话结束时的抽取调用。
我的实测数据是：注入 5 条记忆，大约增加 200 到 400 token；抽取一次大约消耗 1000 到 2000 token。相比全量塞历史，这个开销是可控的。真正需要注意的是抽取频率——如果你每轮都抽取，成本会翻好几倍。所以抽取一定要放在会话结束或关键节点，而不是每轮都做。
6. 我个人的使用体会
用了一段时间之后，我最大的感受是：记忆系统的价值不在于“记得多”，而在于“记得准”。早期我贪多，什么都往里塞，结果召回质量一塌糊涂，模型反而被误导。后来我把抽取标准收紧，只留真正长期有效的信息，体验立刻上了一个台阶。
另一个体会是：记忆需要人来维护。完全自动化的记忆系统，迟早会积累错误和过时信息。我现在会定期打开记忆文件，手动清理和修正。这个过程本身也帮我理清了自己到底在哪些事情上有稳定的偏好。
如果你打算自己动手做一套，我的建议是先从最小的闭环开始：只做事实型记忆，只做关键词召回，只注入 3 条。跑通了，再逐步加偏好、加向量、加遗忘策略。一步到位往往意味着一步都跑不起来。
