先说一个很多人都踩过的坑：你跟AI助手聊了好几个小时，把项目背景、技术偏好、写作风格都交代得明明白白，结果窗口一关，下次再开它又像个陌生人，开口就是“请问您需要什么帮助”。这种体验很像每次见面都得重新自我介绍一遍，时间全耗在重复沟通上。我后来实在忍不了，就自己动手做了一个叫 claude-mem 的小项目，说白了就是给AI配一个“长期记事本”，让它跨会话记得你、记得你的项目、记得你们上次聊到哪。
这个项目的思路不复杂：模型本身没有持久记忆，每次会话基本都是“翻篇重来”，所以我们要在外面搭一层记忆库，把值得留的东西存下来，在下一次对话开始前再喂回去。听起来像是给大脑外挂了一块硬盘。但这块硬盘怎么设计、怎么写入、怎么在每次对话时精准调出最相关的内容，才是真正有嚼头的地方。这篇文章就把 claude-mem 从需求拆解到落地实现完整捋一遍，包括我踩过的坑、调过的参数，还有那些文档里不会写但你早晚会碰上的怪问题。
1. 为什么AI需要一块“记忆外挂”
1.1 上下文窗口不是记忆
很多刚接触AI的人会有一个错觉：模型能记住对话内容，是因为它有“上下文窗口”。这个理解其实只对了一半。上下文窗口更像是工作台，你把图纸、工具、材料都摊在上面，工作期间随拿随用；但下班一收摊，台面清空，下次开工还得重新搬东西。Claude这类模型也是如此，它能“想起”的只是当前窗口内的内容，窗口之外的上一轮、上上一轮交流，全都跟没发生过一样。
窗口本身还有一个硬约束，就是长度。比如常见的200K上下文窗口，看着很大，但换算成对话轮次也就几百轮。聊得越久，早先的内容越容易被“挤”出窗口，或者被后面的内容稀释掉。更麻烦的是，如果你想保留信息，就得把旧对话原文全部带上，每次提问都背负着越来越重的历史包袱，成本和延迟都在涨。
所以，上下文窗口的定位应该是“短期工作记忆”，不是“长期档案”。长期档案必须放在模型外部，由我们主动管理。
1.2 claude-mem 到底解决什么问题
我一开始的目标非常朴素：下次打开对话，它应该知道我在做什么项目、用什么技术栈、喜欢什么语气回复，而不是我又花二十分钟从头喂背景信息。后来用着用着，我发现自己其实在解决三类非常具体的问题。
第一类是个人偏好的记忆。比如我习惯回复里附带代码示例，喜欢结论前置，不喜欢长篇大论的铺垫。这些偏好如果每次都要手动说明，很容易遗漏，而且说得越多，占用上下文越多，真正有效的交流空间就越少。
第二类是项目上下文的记忆。比如某个模拟项目X用的是什么架构、当前进度到哪一步、下一步计划是什么。这类信息一旦跨会话遗失，每次续聊都要重新对齐，效率极低。
第三类是临时事实的记忆。比如“上周我们讨论过用A方案替代B方案，原因是性能瓶颈”、“这个接口的鉴权方式是token而非cookie”。这些关键的决策记录，恰恰是最容易被上下文窗口冲掉的。
claude-mem 的定位就是给这堆信息找个家，并且让模型在需要的时候能即时取用。它不改变模型本身的能力，只是在模型和用户之间加了一层可持续累积的“外置记忆层”。
1.3 什么样的人适合这套方案
我整理了一下实际使用场景，发现三类人获益最大。
一是重度AI用户。每天跟AI对话十几个来回，涉及工作、学习、内容创作，重复交代背景的时间成本已经高到无法忽视。
二是本地工具链爱好者。很多AI聊天工具默认只存对话记录，不上传分析，记忆能力基本靠云端。如果你对数据隐私敏感，或者希望记忆内容完全掌握在自己手里，用本地文件做记忆库就是很舒服的方案。
三是做AI应用开发的开发者。不管你是给机器人加人设，还是给客服系统加知识库，claude-mem 的记忆读写、注入、更新思路都很有参考价值。它本质上是一个通用的记忆管理模板，不绑死在某一个具体产品上。
2. 整体设计思路：短期记忆靠提示词，长期记忆靠文件
2.1 把记忆拆成两层
刚开始我想得很简单，把所有聊天记录一股脑存成一个文件，每次对话前全量塞进上下文。结果第一次测试就翻车了：上下文被撑得又长又乱，模型反而抓不住重点，回复质量直线下降。后来我把记忆拆成了两层来管理。
第一层叫工作记忆，对应的是当前会话内需要聚焦的信息。比如这次对话的目标、用户刚提到的临时要求、最近几条消息的关键结论。这一层不用落盘，或者最多临时缓存，会话结束就清空。
第二层叫长期记忆，对应的是跨会话必须保留的信息。包括用户画像、项目背景、重要决策、待办事项。这一层必须结构化落地，并且要有增删改查的能力。claude-mem 主要管的就是这一层。
这个分层思路很像人脑：短期记忆负责当下任务，长期记忆负责沉淀经验。如果什么都往长期记忆里塞，记忆库就会变成一个内容垃圾场，召回的时候什么都像相关，什么都帮不上忙。
2.2 为什么我选了文本文件而不是数据库
说到存储，很多人第一反应是上SQLite或者向量数据库。我在实践里反而走了另一条路，第一版完全基于纯文本文件，就是一个目录加几个Markdown文件。这样做有几个非常实际的好处。
首先是可读。Markdown 文件你可以直接打开看，记忆里存了什么一目了然，改起来也方便。不像数据库表结构，要查个内容还得写SQL。
其次是可版本管理。记忆文件放在Git仓库里，每次更新都有记录，哪天改坏了还能回滚。这个优势在迭代过程中帮了我好几次大忙。
第三是低依赖。纯文件方案不引入任何额外的服务，复制到任何机器上都能用，配合文件同步工具就能实现多端共享。
等到记忆条目多到用关键词匹配已经不够用的时候，再去引入向量检索也不迟。文本文件完全可以作为向量库的数据源，两者不冲突。
2.3 记忆注入的两种时机
有了记忆库，下一步最关键的问题是什么时候把记忆喂给模型。我试过两种方式，各有优劣。
一种是静态注入。每次开启新会话时，把长期记忆中的核心内容拼接到系统提示词或者首轮消息里。优点是无脑简单，模型从一开始就具备基础背景；缺点是不够精准，不管你这次要聊什么，记忆都是一股脑全上，容易浪费上下文。
另一种是动态召回。根据用户当前的第一句话，先去记忆库搜索相关内容，只把匹配度最高的几条注入到对话里。优点是精准、省token；缺点是响应多了一步检索开销，而且检索算法要做得足够好，否则相关资料没被找出来，模型就会“记忆短路”。
我最终的方案是两者结合：静态注入放“人物画像”和“全局偏好”，体量控制在很小；动态召回负责项目和事实类记忆，按需加载。这样既保证了基础背景不丢，又不会让上下文被无关内容填满。
2.4 token成本是一笔必须算的账
网上很多记忆方案看起来很美好，一上来就把成千上万个记忆条目灌进去，完全不考虑token消耗。实测下来，几百字的记忆大概占几百token，确实不算多；但如果你累积了几万字的记忆，一次全量注入就可能让对话还没开始就消耗掉几千token，既费钱又影响模型注意力。
我的经验是：每次会话注入的记忆总量控制在1200字以内比较稳妥。其中固定画像300字左右，动态召回的临时条目控制在900字以内。超出这个阈值，回复质量会出现肉眼可见的下降，模型开始“记混”或者忽略部分内容。
所以，记忆系统设计里必须带一个限制器：不是所有记忆都值得被记住，也不是所有记忆都要被回忆起来。这个“取舍”的意识，是整个项目里最核心的认知。
3. 从零实现一个可用的轻量级记忆层
3.1 目录结构与记忆文件格式
我的第一版结构非常简单，三个文件解决全部问题。
~/.claude-mem/ ├── profile.md # 用户长期画像，全局唯一 ├── projects/ │ ├── project-a.md # 每个项目单独一份记忆 │ └── project-b.md └── facts.json # 结构化的临时事实，方便程序处理profile.md 存放的是关于用户本人的稳定信息，比如称呼、职业方向、沟通偏好、常用工具链。这类信息更新频率低，适合纯文本维护，读起来也方便。
projects 目录下每个项目一个文件，记录项目目标、当前状态、技术选型、最近进展、下一步计划。项目文件采用固定的小标题结构，方便后续写程序解析。
facts.json 则存放那些“有明确结论、需要结构化处理”的条目，比如“登录模块已切换为JWT方案”“生产环境Java版本升级到17”。之所以单独放JSON，是因为这类信息以后要做冲突检测和时效判断，结构化字段会更顺手。
3.2 记忆写入：如何从对话里提取“值得留”的东西
记忆写入是最容易偷懒，但也最需要把关的一步。一开始我试过把整段聊天记录存下来，结果记忆库迅速膨胀，后面根本没法用。后来我调整了策略：让模型在对话过程中按固定规则输出“记忆候选”。
我用的提取提示词模板大概是这样的：
请从当前对话中提取值得长期保留的信息，按以下分类输出：
- 用户明确表达的偏好或习惯
- 项目相关的关键决策、技术选型、进度变更
- 用户交代的待办事项或承诺
- 对已有记忆的修正或补充 输出时每行一条，格式为“[分类] 内容描述”。如果没有值得记录的，输出“无”。
这个提示词在会话结束时执行，或者在用户明确说出“记住/别忘了/以后都用这个”这类指令时触发。运行结果会回到我这边，由脚本按分类追加到对应文件。
这个流程的核心价值是“只在关键节点写入”，避免把记忆库变成聊天记录大全。信息量少了，反而每条都更有用。
3.3 记忆召回：先用最简单的方法做相关性筛选
在没上向量数据库之前，我用的是关键词打分去做召回。对每个记忆条目，计算命中用户当前问题的关键词数量，命中越多权重越高，最后按权重取前三条注入。
import json, re from pathlib import Path def load_facts(): path = Path.home() / ".claude-mem" / "facts.json" if not path.exists(): return [] return json.loads(path.read_text(encoding="utf-8")) def score_fact(fact, query_words): text = fact.get("content", "") score = 0 for word in query_words: if word in text: score += 1 return score def recall_facts(query, top_k=3): words = re.findall(r"[\w\u4e00-\u9fff]+", query) facts = load_facts() ranked = sorted(facts, key=lambda f: score_fact(f, words), reverse=True) return ranked[:top_k]这段代码不复杂，但已经能解决70%的召回需求。原因在于，需要长期记忆的信息大多包含明确的名词，比如“支付模块”、“评审”、“生产环境”，用户提问时往往也会用同样或相近的词。只有当你需要跨语义匹配（比如问“钱的事”却要召回“支付账单”）时，关键词匹配才会失灵，到那一步再上向量库也不迟。
3.4 注入模板与更新策略
召回之后，记忆需要格式化注入。我用的是一个头部说明加列表的方式，让模型明确知道下面这些是背景资料。
以下是关于用户的长期记忆，供本次对话参考。这些信息可能不适用于当前问题，如果无关请忽略。
【用户画像】
- 称呼：A同学
- 技术方向：后端开发，主要用Java和Python
【项目记忆】
- 项目X当前采用微服务架构，认证使用JWT
- 最近正在解决订单超时问题，下一步计划引入消息队列
注意最后那句“如果无关请忽略”，这句话非常重要。它告诉模型：记忆只是参考资料，不是本轮对话的强制指令。少了这句，模型有时会把记忆当成最高优先级，行为变得特别僵硬，明明用户已经改主意了还抱着旧偏好不放。
更新策略我采用“追加+回写”的混合模式：平时新信息追加到文件尾部，不修改旧条目；当模型或脚本判断新旧信息冲突时，才进行覆盖。这种做法能最大限度保留记忆演变过程，也方便出问题时回看历史。
4. 关键参数、配置技巧与避坑经验
4.1 控制每次注入的记忆条数
我踩过最深的坑，就是“贪多”。有一阵子为了让模型显得聪明，我把记忆库里所有相关条目全塞进去，结果模型回答质量奇差。后来逐项试下来，得出一组比较合适的数值。
用户画像不超过5条，挑每条不超过20字的核心信息。项目记忆每次最多注入3条，每条控制在50字左右。临时事实最多2条，必须是最新且跟当轮问题直接相关的。总量超过1200字的情况，我会强制截断，宁可少给也不硬塞。
这组数值不是绝对的，跟你的实际场景有关。但原则是通用的：记忆条数越少，模型越能扎扎实实地依据它们回答；注入太多，模型反而会迷失在“哪条才是关键信息”的选择里。
4.2 更新时机要卡在“点”上
记忆更新如果做得太勤，比如每轮对话结束都跑一次提取，模型会频繁改写记忆库，反而把稳定的信息搅乱，成本也高。如果做得太懒，比如只在会话结束时更新，又会漏掉用户中途抛出的重要信息。
我目前的做法是设置三类触发点。用户在对话中明确说“记住/以后都用”这类关键词，立即触发写入。用户的回答中出现了跟现有记忆矛盾的信息，触发冲突检测并写入“修正待确认”状态。会话自然结束或超时，执行一次全量提取，把本轮值得留的东西统一落盘。
这个节奏在实践中比较舒服，既不打扰对话流畅性，又不会遗漏关键信息。
4.3 记忆库的定期“体检”
长期积累之后，记忆库一定会出现三类问题：过期信息、重复信息、互相矛盾的信息。所以必须养成定期清理的习惯，我一般是每两周手动过一遍。
清理时我会关注几个信号。日期倒推超过三个月且没有后续更新的项目状态条目，直接归档删除。内容重复率超过90%的条目，保留更完整的那条。时间戳最新且明确取代旧结论的条目，删除旧版。还有一个容易被忽略的点，就是记忆库文件本身不要做得太大。一旦单个文件超过50KB，读写和召回的速度都会下滑，这时候把文件拆成多个维度会更好管理。
4.4 隐私边界的硬约束
说到最后，记忆系统有一个绕不开的问题：隐私边界。你的记忆库里存的，很可能比你自己记得还清楚：你的工作内容、项目进展、个人偏好，甚至一些敏感决策。
我的做法是定三条硬规则。不在记忆库中记录任何密码、token、密钥、身份证号、银行卡号之类的敏感信息。涉及他人隐私的内容，一律不主动记录，宁可让模型多问一次。记忆文件默认本地存储，不上传任何云端服务，如果要同步，也必须用加密通道。
这三条规则是硬约束，不是软提醒。因为记忆系统一旦接入真实业务，信息泄露的风险会随记忆体量的增长同步放大。很多事故不是因为模型不够聪明，而是因为人类把太多敏感信息写进了“永久存储”。
5. 常见问题与排查技巧实录
5.1 记忆一点都没生效
这是反馈最多的一个现象。排查时候先确认记忆文件里真有内容，很多人是文件建好了，但初始化时忘了调用提取流程，导致记忆库一直空空如也。其次看注入位置。记忆文本如果放在用户消息之后，往往会被当成“用户当前说的新内容”，模型会优先响应它而不是把它当背景。正确的位置是系统提示词或者系统消息里。
最后看注入格式。模型对“背景资料”和“用户要求”是分开处理的。如果你注入的信息没有明确的“仅供参考”标记，模型可能把它当成需要执行的任务，行为会变得很奇怪。
5.2 上下文突然被撑爆
走完“全量注入”的思路，很容易触发上下文超限或成本飙升。解决方式就是给记忆系统加限制器。如果非要做全量注入，至少按“重要性”和“时效性”两个维度做排序，只取最高的20%。再不行就把旧记忆做摘要压缩，把一整段项目进展压成一句话，保留核心信息，丢掉细节描述。
另一个被我忽略过的点，是有些API有单次请求的token上限。当你注入的记忆加上对话内容已经贴近上限，再让模型生成长回复就会被截断。这种时候优先砍记忆注入量，不要砍用户的实际对话内容。
5.3 注入记忆后回答风格跑偏
记忆注入后常见的副作用，是模型变得“过度顺从记忆”。比如用户这次想聊一个全新的方向，但记忆里写的是用户偏好后端开发，模型就反复往那个方向带节奏。原因在于，注入的记忆没有加“参考”定性，模型把它当成了优先级很高的约束。
处理方案是在注入模板开头明确写“记忆仅供参考，以当前对话为准”。同时，在构造记忆条目时少用斩钉截铁的语气，多用“倾向于”“近期”“可能”。这既保留了信息，又不会变成一道锁死的指令。
5.4 新旧记忆互相矛盾
当记忆库里的旧信息和新信息打架，模型就会精神分裂，一会儿说A，一会儿说B。我最开始遇到这个情况时很懵，查了半天发现是同一个项目在两周前的记忆里写的是“采用Spring Boot”，而新记忆已经更新成“迁移到Go微服务”，旧条目却还留在文件里没清理。
解决办法就是在记忆文件里给每条核心信息加时间戳，召回时按时间排序，强制最新优先。冲突检测不能只靠人工，最好在写入时对比已有文件，发现同主题条目就自动标记“待确认”，人工确认后再覆盖或合并。这个流程跑顺之后，矛盾问题基本绝迹。
5.5 检索不到相关记忆
关键词召回最大的命门是“表述不一致”。用户记忆里写的是“登录模块”，提问时却说的是“账号验证”，关键词完全对不上，召回自然为0。这个问题到后期一定会遇到，毕竟人的表达不可能一直稳定。
我的做法分两步走。第一步，写入时做关键词扩展，把同义词也一起存进去，比如“登录模块”同时记录“账号验证、认证、sign in”。第二步，升级到向量检索，用文本向量算相似度，语义匹配就不吃关键词差异了。轻量方案可以用本地embedding模型加简单的向量比对，几千条记忆量级跑起来非常轻松。
6. 结语：记忆系统的关键不在“存”，而在“取舍”
做 claude-mem 这段时间，我最大的体会是：给模型加记忆，难点从来不是存得够不够多，而是舍弃得是否果断。存所有聊天记录很容易，但那只会拖垮上下文；真正难的是判断哪些信息值得跨越会话留下来，哪些只是当下任务的一次性产物。
我现在的习惯是，每隔一段时间就翻一遍记忆文件，删掉过时的、合并重复的、修正冲突的。这个动作做得越勤，记忆库的质量越高，模型在下次对话里的表现就越“懂我”。有时候我甚至觉得，与其说是模型记住了我，不如说是我在通过记忆文件不断校准它对我的理解。
如果你也在做类似的事情，给你一个建议：先别急着上向量数据库，先用文本文件加关键词匹配把流程跑通，等数据量自然增长到检索力不从心的时候，再考虑换更重的方案。工具永远可以换，但记忆分层、取舍、注入、更新这套方法论才是 claude-mem 真正值钱的地方。
最后分享一个小技巧：把你的记忆文件放在一个支持Git的目录里，每次修改后用一句话提交。这样万一某次清理手滑删多了，还能一条git log回到几天前的干净状态。这个习惯挽救过我至少三次，建议你从一开始就养成。
