1. 从"聊完就忘"说起：claude-mem 到底想解决什么
如果你用 Claude 这类对话式 AI 做过稍微长一点的项目，大概率遇到过这种尴尬：昨天花了两个小时跟它把一套数据清洗逻辑捋清楚了，今天开个新会话，它一脸无辜地问你"请问你想处理什么数据"。你只能把昨天的上下文重新贴一遍，贴到一半发现 token 又超了，于是开始删删改改，最后干脆放弃，自己动手写。
这个痛点不是个例，而是所有长周期、多轮次 AI 协作场景的通病。模型本身没有跨会话的持久记忆，每次对话都是一张白纸。claude-mem这个项目，从名字就能看出来，它瞄准的正是"给 Claude 加上记忆"这件事——让 AI 在多次会话之间记住你是谁、你在做什么项目、你偏好什么风格、上次卡在哪个环节。
需要先说明一点：我拿到的项目正文和关键词都是空的，所以下面所有内容，是我基于"一个给 Claude 做记忆管理的工具"这个定位，结合这类项目在真实使用中最常见的形态，做的合理还原和深度展开。如果你手上正好有一个类似的项目，或者正打算自己搭一套，这篇可以直接当参考手册用。
它适合谁？三类人最值得看：一是天天跟 AI 结对写代码的开发者，二是用 AI 做长文档、做研究、做内容策划的知识工作者，三是想自己动手搭一套本地记忆系统、不想把数据交给第三方的人。核心价值就一句话：把散落在无数次对话里的上下文，沉淀成一份可复用、可检索、可迁移的长期记忆。
2. 记忆系统的三层结构：为什么不能只做一个"聊天记录本"
很多人第一反应是：记忆嘛，不就是把历史对话存下来，下次拼进 prompt 里？我一开始也这么想，真动手做才发现，如果只是无脑拼接，系统会在几天内变得又慢又蠢。原因在于，记忆不是一种东西，它至少分三层，每层的存储方式、更新频率、检索策略都不一样。
2.1 工作记忆：当前会话的临时白板
工作记忆就是当前这轮对话的上下文窗口，生命周期最短，可能就几分钟到几小时。它的特点是读写极频繁、容量有限、过期即弃。在 claude-mem 这类系统里，工作记忆通常不落盘，或者只落一份临时快照，用于会话意外中断后的恢复。
这里有个容易踩的坑：不少人把工作记忆也当成长期记忆来存，结果数据库里堆满了"好的""继续""嗯嗯"这种无意义轮次。我的做法是给工作记忆设一个滑动窗口 + 摘要压缩机制——最近 N 轮保留原文，更早的轮次自动压缩成一句话摘要。N 取多少？实测下来 8 到 12 轮是个比较舒服的区间，既能保持对话连贯，又不会让 token 迅速膨胀。
2.2 情景记忆：项目级的上下文档案
情景记忆是这套系统的核心价值所在。它记录的是"某个项目/某个任务从开始到现在的完整脉络"——你在这个项目里做过哪些决策、试过哪些方案、哪些走通了、哪些被否决了。它对应的是人类记忆里的"我记得上个月做那个功能时踩过一个坑"。
情景记忆的关键设计是按项目/主题分桶，而不是按时间线性堆叠。因为检索的时候，你几乎总是带着"我在做 X"这个前提去找记忆，而不是"我上周三下午说过什么"。分桶之后，每个桶内部再按时间排序，检索时先定位桶，再在桶内做相似度匹配，效率和准确率都会高很多。
2.3 语义记忆：跨项目的偏好与事实
语义记忆存的是那些跟具体项目无关、但反复用得到的稳定信息：你的技术栈偏好、代码风格要求、常用术语、你的身份背景、你讨厌什么样的回答方式。这部分内容更新频率最低，但复用率最高。
举个具体例子：如果你在语义记忆里写了"我习惯用 TypeScript，偏好函数式写法，不要给我用 class"，那么之后所有会话，AI 都会默认按这个来，你就不用每次重复交代。这一层是真正让 AI"越用越懂你"的地方。
三层之间的关系可以这样理解：
| 层级 | 生命周期 | 存储位置 | 更新频率 | 典型内容 |
|---|---|---|---|---|
| 工作记忆 | 分钟到小时 | 内存/临时快照 | 每轮 | 当前对话上下文 |
| 情景记忆 | 天到月 | 本地数据库 | 每轮或每任务 | 项目决策、踩坑记录 |
| 语义记忆 | 月到永久 | 本地数据库 | 手动或低频 | 偏好、身份、术语 |
提示：三层不要混在一张表里存。我见过有人图省事全塞进一个 JSON，结果检索时噪声极大，AI 经常把临时对话当成长期偏好，回答变得莫名其妙。
3. 落地实现：从零搭一套可用的记忆管线
理解了分层，接下来是动手。这一节我按真实搭建顺序讲，每一步都说明为什么这么做，以及我实际跑下来遇到的问题。
3.1 存储选型：为什么我最终选了 SQLite + 向量索引
存储方案常见的有三种：纯文件（JSON/Markdown）、纯向量数据库、关系库 + 向量扩展。我三种都试过，最后稳定在SQLite + 向量索引这个组合。
纯文件方案上手最快，一个 JSON 文件搞定，但数据量一过几千条，检索就变成全表扫描，慢得没法用。纯向量库（比如各种专门的向量数据库）检索快，但它不擅长结构化查询——你想"找出所有标记为'已否决'的方案"这种操作，向量库做起来很别扭。
SQLite 的好处是：结构化字段（项目名、时间、标签、状态）用普通列存，需要语义检索的文本再单独建向量索引。这样既能做精确过滤，又能做模糊召回。而且 SQLite 是单文件，备份、迁移、版本管理都极其方便，直接 copy 走就行。
具体表结构我建议至少拆成两张：一张memories存记忆条目本身，一张projects存项目元信息。memories里关键字段包括id、project_id、layer（区分情景/语义）、content、embedding、tags、created_at、updated_at、status。
3.2 写入时机：什么时候该记，什么时候不该记
这是整套系统里最考验判断力的地方。记太多，噪声淹没信号；记太少，等于没记。我的经验是设三道闸门：
第一道，显式触发。当对话里出现"记住""以后都这样""这个很重要"这类词，或者用户手动调用记忆命令时，强制写入。这是最可靠的来源。
第二道，决策点触发。当一轮对话产生了明确的结论、方案选择、或者"我们决定用 A 不用 B"这种判断时，自动抽取成一条情景记忆。这类内容价值最高，因为它承载了"为什么"。
第三道，定期摘要。每隔若干轮，把这段对话压缩成一条摘要写入。这道闸门是兜底的，防止重要信息因为没被显式标记而丢失。
反过来，以下内容坚决不记：纯寒暄、重复确认、AI 的客套话、已经被后续对话推翻的中间结论。我一开始没做过滤，结果数据库里一半是废话，检索质量惨不忍睹。
3.3 检索策略：怎么让 AI 在需要时"想起"正确的事
检索的核心矛盾是：召回太少，AI 想不起来；召回太多，prompt 被塞爆还引入噪声。我的做法是两阶段检索。
第一阶段做粗筛：根据当前对话的主题，先定位到相关的项目桶，再在这个桶里用向量相似度召回 Top-K 条候选（K 一般取 10 到 20）。第二阶段做精排：对候选做一次重排序，综合考虑相似度、时间新鲜度、条目状态（未过期的优先）、以及是否被标记为"重要"。
最终注入 prompt 的，通常只保留 3 到 5 条最相关的。这里有个细节：注入时要带上时间戳和来源，比如"[2024-05 项目A] 决定用方案X，因为Y"。这样 AI 在引用时能说清楚依据，而不是把记忆当成当前事实。
# 检索伪代码示意 def retrieve_memories(query, project_id=None, top_k=5): # 第一阶段：粗筛 candidates = vector_search(query, limit=20, filter={"project_id": project_id}) # 第二阶段：精排 scored = [] for m in candidates: score = ( 0.6 * m.similarity + 0.2 * freshness(m.updated_at) + 0.2 * (1.0 if m.status == "active" else 0.0) ) scored.append((score, m)) scored.sort(reverse=True, key=lambda x: x[0]) return [m for _, m in scored[:top_k]]权重不是拍脑袋定的。0.6 给相似度是因为语义相关是首要条件；0.2 给新鲜度是因为旧记忆可能已过时；0.2 给状态是因为被标记为"已废弃"的记忆不该再影响判断。这套权重我调过好几轮，目前用着比较稳。
4. 真实场景里的坑：我踩过的五个典型问题
理论讲完，说点实战里真会让人抓狂的东西。这些坑，文档里基本不会写，但你不提前知道，大概率要花一整天去 debug。
4.1 记忆污染：AI 把临时结论当成了永久偏好
这是最常见也最隐蔽的问题。有一次我在调试一个临时脚本，随口说了句"这次先用 Python 快速验证一下"。结果这条被写进了语义记忆，之后好几天的项目里，AI 都默认我要用 Python，哪怕我明明在写 TypeScript 项目。
根因是写入时没有区分"临时"和"长期"。修复方案是给每条记忆加一个scope字段，区分session、project、global三个作用域。只有明确表达为长期偏好的内容，才允许写入global。默认情况下，所有自动抽取的记忆都进project作用域，不会跨项目污染。
4.2 检索错位：相似度高但完全不相关
向量检索有个经典毛病：两段文本字面很像，语义却南辕北辙。比如"用户登录失败的处理"和"用户登录成功的日志"，向量距离可能很近，但你要的是前者，召回后者就是纯噪声。
我的解法是在向量检索之外，加一层关键词硬过滤。具体做法是对查询做一次关键词抽取，然后在候选集里要求至少命中一个关键词，否则降权。这招对技术类内容特别有效，因为技术讨论里往往有明确的名词（函数名、库名、错误码），这些词比语义相似度更可靠。
4.3 上下文膨胀：记忆注入反而拖慢了响应
刚上线那会儿，我贪心地一次注入十几条记忆，想着"信息越多越好"。结果 prompt 长度暴涨，响应变慢不说，AI 还经常被无关记忆带偏，答非所问。
后来我定了个硬规则：注入的记忆总长度不超过 800 token。超了就按精排分数砍。同时，长记忆在注入前先做一次压缩，只保留结论和关键理由，细节留在库里按需调取。这个改动之后，响应速度和回答质量都明显回升。
4.4 时间线混乱：AI 分不清"现在"和"过去"
记忆里存的是历史，但 AI 很容易把历史当成现状。比如你三个月前决定用方案 A，上个月改成了方案 B，如果两条记忆都被召回，AI 可能又按 A 来回答。
解决办法是给记忆加版本链。同一主题的记忆，新条目通过supersedes字段指向它替代的旧条目。检索时，如果一条记忆被更新的条目取代了，就自动降权或排除。这样 AI 看到的永远是当前有效的版本，历史版本只在明确需要追溯时才调出来。
4.5 隐私与数据边界：本地优先不是口号
记忆系统存的是你最真实的思考过程、项目细节、甚至一些敏感信息。如果这些数据被上传到第三方，风险不言而喻。所以我在设计时坚持本地优先：数据库存在本地，向量索引也在本地算，只有最终注入 prompt 的那几条记忆会随对话发送出去。
如果你确实需要多设备同步，建议用加密的同步方案，而不是明文丢到某个云盘。另外，定期清理机制也要有——给记忆设一个 TTL（生存时间），超过一定时间没被访问过的低价值记忆，自动归档或删除。
5. 让记忆真正"活"起来：几个提升体验的进阶技巧
基础功能跑通之后，下面这些技巧能让你的记忆系统从"能用"变成"好用"。
5.1 记忆的主动回顾：定期让 AI 自己整理
我加了一个定时任务，每周让 AI 把过去一周新增的情景记忆做一次归并整理：把重复的合并，把过时的标记，把零散的归纳成更高层的结论。这个过程相当于让 AI 自己"复盘"，整理后的记忆质量比原始条目高一个档次。
实现上就是调一次模型，把一批记忆喂进去，让它输出结构化的整理结果，再写回数据库。注意要保留原始条目，整理结果作为新的"摘要层"存在，别直接覆盖。
5.2 标签体系：让检索从"碰运气"变成"查字典"
纯靠向量检索，本质上是碰运气。加上一套稳定的标签体系之后，检索就变成了"先按标签缩小范围，再按相似度排序"。标签不用多，十几个核心维度就够：项目名、技术栈、任务类型、状态、优先级。
标签的维护可以半自动：AI 写入记忆时顺便打标，你偶尔手动修正。跑一段时间后，标签体系会自然收敛到一套适合你工作习惯的分类。
5.3 记忆的可视化：看得见才管得好
数据库里的记忆是黑盒，时间长了你自己都不知道存了什么。我做了个简单的本地页面，把记忆按项目、按时间、按标签展示出来，支持搜索和手动编辑。有了可视化，你才能发现"哦这条记错了""这条早该删了"，系统的可维护性会大幅提升。
这个页面不用做得多漂亮，能列表、能筛选、能编辑就行。我用最朴素的方式实现，一个静态页面加一个本地 API，半天就能搞定。
5.4 跨工具复用：别把记忆锁死在一个客户端里
记忆的价值在于复用。如果你只在某一个工具里用，那它的价值就打了折扣。我的做法是把记忆层做成一个独立的本地服务，对外暴露简单的读写接口。这样无论是命令行工具、编辑器插件还是网页端，都能接进来共用同一份记忆。
接口设计尽量简单：写入就一个add_memory，检索就一个search_memories，删除就一个delete_memory。越简单越不容易出问题，也越容易替换底层实现。
6. 关于这套系统，我最后想说的几句实在话
搭记忆系统这件事，最大的诱惑是"一步到位"，最大的陷阱也是"一步到位"。我见过太多人一上来就设计复杂的多级缓存、分布式向量库、自动学习机制，结果两周后项目烂尾，因为维护成本远超收益。
我的建议是从最小可用版本开始：一张表、一个向量索引、一个写入函数、一个检索函数，先跑起来。用上一周，你自然会知道哪里不够用，再针对性加。记忆系统是长出来的，不是设计出来的。
另外，别指望 AI 能完美地自动管理记忆。它擅长抽取和归纳，但不擅长判断"什么值得长期记住"。这个判断权，最好还是留给人。把自动化和手动控制结合起来，系统才既省心又可靠。
最后分享一个我用了很久的小习惯：每次开新项目前，先花两分钟手动写一条"项目背景"记忆，把目标、约束、技术栈交代清楚。就这两分钟，能让后面所有对话的起点高一大截。这个投入产出比，是我试过的所有技巧里最高的。
