1. 从“记忆”这个痛点说起claude-mem 到底想解决什么如果你用 Claude 这类大模型做过稍微长一点的对话或者项目一定遇到过这种尴尬聊到第三轮它已经忘了你第一轮说的关键约束让它改一个函数它把之前确认好的接口签名给改回去了你反复强调“不要用某个库”它下一段代码里又给你 import 进来了。这不是模型笨而是它的上下文窗口是有限的、会话是无状态的——每次请求对它来说都像第一次见面。claude-mem这个项目从名字就能看出来它瞄准的就是“给 Claude 加一层记忆”。注意这里说的记忆不是模型权重层面的微调而是工程层面的记忆管理把对话中产生的重要信息抽取出来、存起来、在需要的时候再喂回去。它要解决的核心问题有三个第一跨会话的信息丢失第二长对话里关键信息的稀释第三重复交代背景带来的 token 浪费。我先把话说在前面这类“记忆层”项目本质上都是在上下文工程这个范畴里做文章。它不改变模型本身改变的是你每次发给模型的 prompt 里到底装了什么。理解了这一点后面所有的设计取舍你都能自己想明白。这篇文章我会从架构思路、存储选型、检索策略、注入时机、踩坑经验几个角度把这个项目拆透让你看完能自己动手搭一套也能判断市面上的类似方案到底靠不靠谱。适合谁看如果你正在做 AI 应用、Agent 开发、或者只是想让自己的日常 AI 协作更顺滑这篇都值得读。不需要你是算法专家但最好写过一点代码、调过 API。2. 记忆系统的三层结构原始记录、提炼摘要、结构化事实很多人一上来就想“我把所有对话都存进向量库不就行了”。我试过结论是能跑但不好用。原因很简单原始对话里 80% 是废话和重复全量检索出来的东西噪声极大反而干扰模型判断。claude-mem这类项目通常会把记忆分成三层来管理这个分层思路是我认为最值得借鉴的部分。2.1 第一层原始会话日志Raw Log这一层就是老老实实把每轮对话的 user/assistant 消息按时间顺序落盘。它的作用不是给模型读而是给你自己排查问题、做数据回溯用的。格式上我建议用 JSONL每行一个 JSON 对象因为追加写非常方便不会因为中途崩溃损坏整个文件。{ts: 1712300000, session_id: abc123, role: user, content: 项目用 FastAPI数据库是 Postgres} {ts: 1712300005, session_id: abc123, role: assistant, content: 好的我记下了}这一层的关键是只追加、不修改。你可以把它理解成数据库的 WAL 日志。我踩过的坑是早期我为了省空间做了去重和压缩结果后来想复现某个 bug 时发现原始输入没了追悔莫及。所以这一层宁可占点磁盘也别动它。2.2 第二层会话摘要Session Summary每次会话结束或者达到一定轮数触发一次“总结”调用让模型把这段对话压缩成一段 200-500 字的摘要包含聊了什么主题、确定了哪些决策、遗留了哪些待办。这一层是给检索用的主力。为什么不让模型直接读原始日志因为 token 成本。一段 50 轮的对话可能上万 token而摘要只要几百 token。检索时先命中摘要再决定要不要回捞原始细节这是性价比最高的做法。摘要的 prompt 设计有个技巧强制模型输出结构化字段而不是一段自由文本。比如要求它返回 JSON{ topics: [FastAPI 项目搭建, 数据库选型], decisions: [使用 Postgres 而非 MySQL, 接口统一用 Pydantic 校验], open_questions: [缓存层还没定], entities: [FastAPI, Postgres, Pydantic] }这样后面做过滤和匹配的时候你可以按entities精确命中比纯语义相似度靠谱得多。2.3 第三层结构化事实Structured Facts这是最“值钱”的一层也是很多简易方案会忽略的一层。所谓结构化事实就是把对话里那些长期有效的约束和偏好抽出来存成键值对或者三元组。比如事实类型示例有效期技术栈约束项目使用 Python 3.11长期编码偏好不要用可变默认参数长期项目背景这是一个内部工具不对外长期临时决策这次先用同步方案短期这一层和摘要的区别在于摘要描述“我们聊了什么”事实描述“什么是真的”。事实是可以跨会话、跨项目复用的而摘要通常绑定在某次会话上。我的经验是事实抽取要用单独的、更严格的 prompt并且要求模型给出置信度。置信度低的先不写入或者写入待确认区。因为一旦错误的事实被固化后面每次注入都会污染模型的判断比没有记忆还糟糕。3. 存储选型为什么我最后选了 SQLite 向量索引的组合存储这块是绕不开的决策点。市面上的选项大概有这么几类纯文件、关系库、向量库、图数据库。我一个个试过说说真实感受。3.1 纯文件方案的死穴一开始我用 JSON 文件存所有记忆检索就是全量加载到内存里做字符串匹配。小数据量几百条没问题一旦上千条每次启动加载就明显卡顿而且没法做复杂的组合查询。更致命的是并发——如果你有多个进程同时写文件锁能把你折腾疯。所以纯文件只适合做原型验证别上生产。3.2 向量库是不是必须的很多人觉得“记忆向量检索”其实不一定。向量检索擅长的是语义模糊匹配比如你问“之前说的那个数据库是啥”它能命中“Postgres”那条记录。但它不擅长精确条件过滤比如“找出所有标记为长期有效且属于项目 A 的事实”。所以我的结论是向量检索是补充不是全部。真正好用的记忆系统是“结构化过滤 语义召回”两条腿走路。3.3 SQLite 向量扩展的实际组合最后我落地用的是 SQLite 作为主存储配合一个轻量的向量索引可以是 sqlite-vec 这类扩展也可以把向量单独存成二进制 blob在应用层算余弦相似度。选 SQLite 的理由很实在零运维一个文件就是全部数据备份就是复制文件。事务支持写入不怕中途崩溃。SQL 过滤按时间、类型、项目、置信度做组合查询一句话的事。生态成熟Python 的sqlite3标准库直接能用不用装额外服务。表结构我简化成三张核心表CREATE TABLE facts ( id INTEGER PRIMARY KEY, content TEXT NOT NULL, category TEXT, confidence REAL, created_at INTEGER, expires_at INTEGER, embedding BLOB ); CREATE TABLE summaries ( id INTEGER PRIMARY KEY, session_id TEXT, summary TEXT, entities TEXT, created_at INTEGER ); CREATE TABLE raw_logs ( id INTEGER PRIMARY KEY, session_id TEXT, role TEXT, content TEXT, ts INTEGER );提示expires_at这个字段千万别省。很多“临时决策”如果不设过期半年后还在往 prompt 里塞纯属添乱。我一般给临时事实设 7 天过期长期事实设 NULL。向量维度这块如果你用常见的 embedding 模型一般是 768 或 1536 维。存成 BLOB 的时候记得统一用 float32别一会儿 float64 一会儿 float32算相似度时会出精度问题。这个坑我踩过排查了半天才发现是类型不一致。4. 检索与注入记忆系统的成败全在这一步存得好不如取得准取得准不如塞得巧。这一节是整个项目最核心的部分也是最容易做砸的地方。4.1 检索多路召回再融合单靠一种检索方式一定会漏。我的做法是三路并行召回然后做加权融合关键词/实体匹配用户当前输入里出现的实体直接去 facts 表里精确匹配。速度快准确率高。向量语义召回把当前输入 embedding 后和 facts、summaries 的向量算相似度取 top-K。时间衰减加权越近的记忆权重越高。一个简单的公式是score similarity * exp(-λ * age_days)λ 取 0.05 左右意味着一个月前的记忆权重衰减到约 22%。三路结果合并去重后按综合分排序。这里有个细节不同来源的分数不能直接相加因为量纲不一样。我的做法是先各自归一化到 0-1再加权。关键词匹配权重给 0.5向量给 0.4时间新鲜度给 0.1这个比例是我调了几轮之后比较满意的。4.2 注入不是越多越好新手最容易犯的错就是把检索到的所有记忆一股脑塞进 system prompt。结果就是token 爆了模型还被无关信息干扰回答质量反而下降。我的注入策略是分级 限额必注入结构化事实里 confidence 0.8 且未过期的全部注入但控制在 500 token 以内。选注入向量召回 top-3 的摘要每条截断到 150 token。不注入原始日志永远不进 prompt只在需要深挖时由工具调用去查。注入的位置也有讲究。我习惯放在 system prompt 的末尾、用户消息之前并且用明确的分隔标记[已知背景信息] - 项目使用 FastAPI Postgres - 用户偏好函数式写法 - 上次遗留缓存层未定 [背景信息结束]这样模型能清楚区分“这是历史记忆”和“这是当前任务”不会把记忆当成当前指令来执行。这个边界感很重要我见过因为没做分隔模型把历史里的“待办”当成新任务去执行的案例。4.3 一个真实的检索失败案例有次用户问“我们之前定的缓存方案是什么”系统检索出来一堆关于“缓存”的摘要但都是讨论过程没有结论。因为当时那次会话根本没定方案只是聊了聊。结果模型基于这些“讨论”编了一个方案出来用户以为真定过。这个坑让我意识到检索要区分“讨论过”和“决定过”。后来我在摘要里强制加了decisions和discussions两个字段检索时优先返回 decisions。如果只有 discussions就在注入时明确标注“以下为讨论内容尚未形成决策”。这一句话的标注能极大降低模型幻觉。5. 落地时必须处理的几个工程细节原理讲完了说说真正动手时会遇到的那些“文档里不会写”的问题。5.1 摘要触发的时机什么时候触发摘要生成三个可选时机每 N 轮、会话结束、定时任务。我推荐每 N 轮 会话结束双触发。N 取 10 左右比较合适。为什么不能只在会话结束触发因为用户可能永远不主动结束会话或者会话中途崩溃那这段记忆就丢了。每 10 轮做一次增量摘要相当于给记忆上了个保险。增量摘要的实现要注意不是把前 10 轮重新总结一遍而是把“上一次摘要 新的 10 轮”一起喂给模型让它输出更新后的摘要。这样能保持摘要的连贯性不会出现前后矛盾。5.2 去重与冲突消解同一个事实可能被多次抽取比如“用 Postgres”这句话在三次会话里都出现过。如果不去重facts 表会膨胀检索时也会重复注入。我的去重策略是先向量相似度粗筛阈值 0.9再让模型判断是否语义等价。为什么不让模型直接判断所有因为成本。先用便宜的向量筛掉明显不同的只对高度相似的做模型判断能省 80% 的调用。冲突消解更麻烦。如果新事实和旧事实矛盾怎么办比如旧的说“用 MySQL”新的说“改用 Postgres 了”。我的做法是新事实写入时把冲突的旧事实标记为 superseded而不是删除。保留历史但检索时只返回最新的。这样既不会丢信息又不会让模型困惑。5.3 隐私与数据边界记忆系统会存大量对话内容隐私问题必须正视。几个基本动作敏感字段密钥、密码、个人信息在写入前做正则过滤命中就跳过或脱敏。数据库文件加密存储别裸奔。提供“一键清空某个会话记忆”的接口用户有权删除。这些不是可选项是底线。我见过有人把 API key 直接存进记忆库的那真是灾难。6. 我踩过的三个坑以及怎么爬出来的6.1 坑一记忆污染导致模型“精神分裂”早期我没做置信度过滤模型抽取的所有事实都无脑写入。结果有一次它把用户的一句玩笑话“要不我们把数据库换成 Excel 吧”当成了真实决策存了下来。之后每次注入模型都会认真考虑 Excel 方案回答变得莫名其妙。修复方案所有事实抽取必须带 confidence低于 0.7 的进待确认区不参与注入。同时增加一个“事实复核”的定时任务让模型定期回顾待确认区确认的转正否定的删除。6.2 坑二向量检索的“语义漂移”有段时间我发现检索结果越来越离谱。排查后发现是 embedding 模型版本升级了新旧向量不在同一个语义空间里算相似度完全是乱的。修复方案embedding 模型版本号必须和向量一起存。升级模型时要么全量重算要么新旧分开检索。我现在的做法是 facts 表加一列embedding_model检索时只比对同版本的向量。这个细节很小但能救命。6.3 坑三注入顺序影响模型行为同样的记忆内容放在 system prompt 开头和放在末尾模型的表现不一样。我实测下来放在末尾靠近用户消息的约束模型遵守得更好。因为大模型对靠近当前位置的 token 注意力更高。所以我的注入顺序是通用系统指令 → 项目背景 → 具体约束和偏好 → 用户消息。把最需要模型遵守的约束放在最靠近用户消息的位置。7. 怎么判断你的记忆系统做得好不好最后分享几个我用来评估的土办法不需要复杂的 benchmark。第一个指标重复交代率。统计用户在多轮对话里重复说明同一背景的次数。好的记忆系统应该让这个数字趋近于零。我优化前后对比重复交代率从 35% 降到了 8%。第二个指标事实命中率。人工标注一批“应该被记住”的事实看系统实际检索到的比例。低于 80% 说明检索策略有问题高于 95% 要警惕是不是注入太多了。第三个指标token 效率。统计每次请求注入的记忆 token 占总 token 的比例。我的目标是控制在 15% 以内。超过 25% 基本就是注入过量了该做减法。这三个指标不需要写代码就能大致估算但比任何花哨的评测都实用。记忆系统这东西最终是服务于“让协作更顺”这个目的的别为了技术而技术。我在实际使用中最大的体会是记忆系统的难点从来不是存而是“什么时候该忘”和“什么时候该说”。存得再多不会取舍反而成了负担。把过期机制、置信度、注入限额这三件事做好一个简单的 SQLite 方案就能跑赢很多复杂的架构。