1. 从一个让我崩溃的场景说起AI 助手的“金鱼记忆”做 claude-mem 这个工具起因特别朴素。我连续一周每天跟同一个 AI 助手讨论同一个项目的接口改造每天上午打开新的会话窗口它都要礼貌地问我“这个项目的技术栈是什么现在的数据结构大概长什么样”我只好把前一天已经说过的背景重新粘贴一遍粘贴完它又问下一个类似的问题。那几天我的心情基本是我不是在做开发我是在当复读机。后来我认真想了想这其实不能全怪 AI。对话框本质上是无状态的一次会话结束上下文就没了。我指望它记住项目里所有历史背景本来就不现实。但反过来说程序员做项目会写文档、留注释、记周报为什么 AI 助手不能有一套类似的“外部记忆”于是我开始动手做 claude-mem一个把 AI 对话历史持久化、索引化、并且能在新会话里自动回放关键记忆的小工具。这个工具做的事情用一句话概括让 AI 助手每次见到你时都像昨天刚聊过一样。它适合所有用 AI 助手做正经项目的开发者尤其是那些频繁开新会话、需要在多个任务之间切换、又不想每次手动粘贴背景信息的人。如果你只是偶尔问几个一次性问题那确实用不上它但只要你把 AI 助手当成长期协作者记忆层就是刚需。1.1 上下文窗口再大也装不下一个项目的“前世”很多人会说现在上下文窗口已经很大了动辄几十万 token为什么还要搞外部记忆这个问题我一开始也困惑过直到我实测了一个中等规模的项目才明白窗口再大它也是“一次性”的。举个例子我在做某个跨平台同步模块时和 AI 助手反复讨论了数据冲突解决策略。最初定下来的方案是“以最近修改时间为主同时保留冲突副本”后来因为业务需要改成了“按设备优先级合并”。这些决策过程非常关键但散落在三四个会话里。等到第五天我开新会话让它继续优化这个模块时它根本不知道第二、第三天已经讨论过什么于是又提出了已经被否掉的旧方案。这不是上下文窗口大小的问题而是会话断裂的问题。窗口存在时AI 能看到全部对话窗口一关一切归零。真正的项目记忆需要跨越会话边界需要在关键时刻被检索出来而不是靠赌下一次对话刚好还在窗口里。更现实的问题是成本。每次把大量历史对话重新喂进去token 消耗是实打实的。我曾经把三天的对话记录拼接成一份“项目背景说明”塞进新会话结果上下文里全是流水账真正有用的决策点反而被稀释了。与其把所有历史都塞进去不如只提取其中的关键结论、参数约定、被否决的方案和原因这些才是值得长期记住的东西。1.2 记忆不应该是奢侈品而应该是基础设施做工程的都知道代码写久了最重要的不是“代码本身”而是“代码为什么变成现在这样”。需求变更的原因、性能瓶颈的定位过程、某段逻辑为什么用了看上去很绕的写法——这些信息全在对话里。如果记录不下来两个月后你回头看代码只看到结果看不到来路。人的应对方式是写文档、写评论、写设计文档但说实话程序员普遍不爱写文档尤其是项目中途的决策记录。而 AI 对话天然包含了大量这类信息只是被丢弃了。claude-mem 的定位就是把对话历史变成项目资产它自动保留每一次讨论的关键内容在新会话开始前把相关记忆注入上下文让 AI 助手带着“前世记忆”重新上场。这套思路本质上是在给 AI 助手装一个“长期记忆皮层”而对话窗口只负责当次任务的“工作记忆”。工作记忆负责专注长期记忆负责连续二者配合才能干成有跨度的项目。后面我会详细拆解我是怎么设计这个记忆层的包括存什么、怎么存、怎么召回、怎么回放以及这一路上踩过的各种坑。2. 拆解 claude-mem 的设计决策先想清楚要存什么动手写第一行代码之前我强迫自己先回答一个问题到底什么样的信息才配进记忆库直接存全量对话当然最简单但那只是把问题从“上下文装不下”变成了“数据库里躺着垃圾”。没有取舍的记忆系统本质上是另一个垃圾场。我花了不少时间做信息建模最终把记忆分成了三层每一层的有效期、写入方式和被消费的方式都不一样。2.1 三层记忆模型会话级、项目级、长期知识级我把记忆分成三个层级这是整个工具的地基。会话级记忆对应一次完整对话的压缩快照包括这次会话的目标、最终结论、产出物清单。它的有效期是“这个项目周期内”核心作用是被后续会话快速引用。比如某天我和 AI 助手完成了用户鉴权模块的接口定义那么会话级记忆就应该保存“接口路径、请求参数、返回格式、已确认的签名方案”。项目级记忆是跨多个会话沉淀下来的稳定事实比如项目技术栈约定、模块边界、已否决的方案及原因、常见陷阱。这类记忆通常从多段会话级记忆中归纳而来不一定每次会话都写入而是需要某种“沉淀”机制。我在设计时让它支持手动确认和自动抽取两种路径自动抽取负责把高频出现的术语和结论标记出来手动确认则允许我直接输入一条项目约定例如“后端统一用 UTC 时间禁止本地时间入参”。长期知识级记忆更像个人知识库和具体项目无关比如“我对某类架构模式的一贯偏好”“我常用的错误处理风格”。这一层我做得比较轻因为它的价值密度高但复用频率低过度膨胀反而会干扰项目级检索。我建议看到这篇文章的你自己评估如果只是给单个项目用前两层就足够了长期知识层可以后置。这三层记忆必须分开存储否则检索时会互相污染。我最开始偷懒把三层混在一个表里后果是查项目约定时经常翻出无关的闲聊内容后来老老实实加了类型标签和两个独立的索引空间。2.2 存储引擎选型的对比与取舍存储层我先后试过三种方案纯 JSON 文件、SQLite、嵌入式向量库。每种方案都有它的适用位置最终我做的是“组合而非单选”。方案优点缺点我用在哪个层JSON Lines 文件可读、可手动编辑、方便备份查询能力弱、不适合频繁更新会话级原始快照SQLite事务可靠、SQL 检索成熟、单文件部署需要自己管理表结构项目级结构化记忆嵌入式向量库语义检索能力强需要额外依赖、索引有膨胀问题长期知识层和语义召回先说 JSON Lines。每次会话结束时我把原始对话按时间顺序写入一个 .jsonl 文件按会话 ID 作为文件名。这么做的好处是调试极其方便我可以直接打开文件看某次会话到底记录了什么排查写入 bug 时不用连数据库。缺点当然是没法高效查询所以它只作为“原始层”真正的检索走后面的索引。SQLite 用来存项目级记忆。我把每条记忆拆成“实体、属性、值、来源会话ID、可信度、最后确认时间”这几个字段。比如“实体鉴权模块属性签名算法值HMAC-SHA256来源会话#12可信度确认”。这种结构化程度足够支持精确匹配也能做很轻量的条件过滤比如“只看最近一周确认过的约定”。向量库是我后来才引入的用来解决千万不能用关键词匹配到的语义问题。早期的测试里我问“登录这块之前怎么定的”如果只做关键词检索可能搜不到任何东西因为会话里根本没有“登录”“定”这些词只有“鉴权”“签名方案确定”。向量化之后这个问题被大幅缓解。2.3 向量化检索为什么没有一开始就上我见过很多同类工具上来就用向量数据库号称“语义记忆”实际效果却非常一般。我自己的体会是向量化解决的是召回率问题而不是精确性问题它应该被放在检索链路的最后一段而不是唯一一段。项目刚起步时我只有两百多条记忆纯 SQLite 的 LIKE 查询已经完全够用。但记忆量超过一千条后关键词检索的缺陷变得很明显同一个概念在不同会话里有不同的说法比如“鉴权”“认证”“登录态”指同一件事关键词检索会把它们当成三个无关的东西。这时候我才决定引入向量化。我用的是一个本地 embedding 模型维度选了 768每次写入记忆时生成向量、存入向量索引。代价是内存占用上升、首次加载有延迟换来的是语义召回的明显改善。但我要提醒一句千万别把所有记忆全部向量化那会同时污染精确查询和语义查询。我的做法是只对“项目级记忆”和“长期知识层”做向量化会话级快照永远走关键词和会话时间索引。3. 核心流程的工程化实现写入、索引、召回、回放设计归设计真正落地时工程细节决定了这个工具是“能用”还是“好用”。我按数据流转的顺序把整个流程拆成四段每一段都改过至少三轮。3.1 会话快照的写入时机与去重策略第一个问题是什么时候写入记忆我在最早版本里用的是“定时任务全部同步”结果发现大部分中间过程毫无价值最后反而把索引搞得很脏。后来改成“事件驱动 会话结束快照”的组合策略。事件驱动负责记录关键节点当对话中出现明显结论性语句时比如“那就这么定”“这个方案可以”我把该段对话连同上下文摘要写进暂存区。会话结束或手动触发时再把暂存区合并成一份完整快照写入 JSON Lines 原始文件并抽取结构化记忆入库。去重是我踩过的最实在的坑。同一结论可能在对话里反复出现AI 助手喜欢换着说法把一句话说三遍。如果不去重项目级记忆会被同一决策的多个变体塞满。我做的去重策略分两层文本相似度去重和语义去重。先计算新记忆和已有记忆的文本相似度超过 0.9 就视为重复如果没有命中再算向量余弦相似度超过 0.95 也会被拦下来。阈值不能设太死设太猛容易把真正的新信息滤掉我调到 0.95 之后误杀率才降到可接受范围。3.2 检索链路从关键词到语义召回再到重排检索模块是 claude-mem 最核心的部分它直接决定了注入给 AI 助手的记忆是否准确。我没有用“问一句然后返回一堆最相似片段”的简单方案而是搭了一条三级链路。第一级是条件过滤根据当前会话的项目 ID、时间范围、记忆类型先把候选集缩小。比如我在调试支付模块时必须先把记忆空间切到支付项目绝不能把别的项目里的接口约定混进来。第二级是关键词精排用 BM25 类算法对候选集打分精确匹配优先。第三级才是语义召回对前两级结果做向量相似度重排补回那些“说法不同但意思相同”的记忆。重排之后我还会做一步“新鲜度加权”。两天前确认的接口约定比两个月的记录可靠得多除非后者的可信度被人为标记为“永久有效”。加权公式很简单但我调了很久才找到合适的衰减系数半衰期设成 30 天超过 90 天的旧记录除非被手动置顶否则权重会低到几乎不影响排序。这三级链路跑完我还会把结果按“结论型记忆优先于过程型记忆”的原则做一次最终排序。过程型记忆适合用来理解来龙去脉但在给 AI 的上下文里结论型记忆的边际价值远高于冗长的推理过程。3.3 回放机制让 AI 带着“前世记忆”重新上场记忆召回到位之后下一步是怎么把结果回放给 AI 助手。这一步看似简单实则非常讲究时机和格式。如果在会话一开始就把十段记忆全塞进去AI 会被大量背景信息带偏甚至把记忆里的旧结论当成当前事实。我的做法是分三种回放时机。会话启动回放只注入三条以内的核心记忆通常是项目名、技术栈约定、上次会话的待办事项。话题触发回放当对话进入某一主题时根据最近一段对话的语义查询记忆库把相关结论实时注入。手动纠正当 AI 的回答明显偏离已确认方案时我可以手动触发一次强制检索把精确记忆原文放进去让它在给出下一次回答前先“看到”那条结论。回放格式也有讲究。我不用纯文本堆砌而是给每条记忆加上元信息前缀比如 [来源会话 #23 | 确认于三天前 | 类型接口约定]这样 AI 能理解它读到的不是用户随口说的内容而是经过确认的历史结论。这种元信息极大提高了回放内容的可信度我实测下来AI 引用历史结论时的语气都变得更确定了。4. 本地部署与日常使用的落地经验工具再精巧不好用就是摆设。我在本地部署和日常使用上花了不少精力最终形成了一套一套非常顺手的用法这里分享最关键的几个落地经验。4.1 最小可用环境的目录与配置我的部署环境不依赖任何云端服务所有数据存在本地目录里。最小目录结构大概是这样的claude-mem/ ├── raw/ │ └── 会话快照/ │ ├── 2025-06-01_接口改造.jsonl │ └── 2025-06-02_鉴权重构.jsonl ├── indexes/ │ ├── project_mem.sqlite │ └── vector_index/ ├── config.yaml └── logs/config.yaml 里最重要的几个配置项我列成表格供你参考配置项我的取值说明storage.raw_dir./raw原始对话快照目录storage.enable_sqlitetrue是否启用结构化记忆recall.top_k5单次检索最大返回条数recall.min_score0.72低于该分数不纳入回放index.embedding_dim768embedding 维度memory.shelf_life_days90新鲜度半衰期参数这些配置都能在运行中热加载不需要重启服务。我建议你一定保留 raw 目录它看起来最占空间但所有排查问题的起点都是它。4.2 三种我实测好用的用法claude-mem 我做了三种使用方式覆盖了大多数场景。第一种是CLI 查询。在终端里跑mem query 鉴权方案最终怎么定的它会直接返回相关记忆片段和对应的原始会话来源。这个用法适合我正在写代码、不想切到 AI 对话框时的快速确认。第二条命令mem inject --project payment会把项目最新记忆整理成一段上下文我直接复制粘贴给 AI 助手即可。第二种是自动注入脚本。我把mem inject --top 3的输出接到我自己常用的那个 AI 客户端配置里每次新会话启动时自动带入项目核心记忆。这个方案需要一点脚本能力但一次配好之后非常省心相当于给 AI 助手装了个“开机记忆加载器”。第三种是会话侧边栏。我在单独一个终端窗口跑mem watch监听当前项目目录每次和 AI 助手对话结束后它会自动检测新的记录文件并更新索引。这样我不用手动触发任何操作记忆库一直在后台静默生长。需要提醒的是watch 模式依赖文件系统事件接口在非本地文件系统上会失效所以我的部署一直坚持本地目录。4.3 多用户场景下的隔离与权限如果你只是自己用权限问题几乎不用考虑。但我后来把它分享给了项目组的几个同事问题就来了不同人的对话记录如果混在一起A 的接口约定可能被 B 的查询召回导致 AI 给出错误结论。我做了两层隔离。第一层是项目隔离每个项目一个独立命名空间检索时强制带上 project_id 条件。第二层是用户隔离每个用户有自己的读写入权限同事之间默认只能看到被标记为“共享”的记忆。这个设计参考了 Git 的分支思路记忆库不是一个大池子而是既共享又隔离的家族库。共享机制也很关键。几个人一起开发时最重要的共识是“哪些记忆可以被共享”。我约定接口定义、架构决策、技术栈约定这三个类别默认共享个人偏好、临时讨论、未确认想法默认私有。这样既保证团队信息流动又避免污染的噪音进到别人的记忆库里。5. 数据隐私、误召回与性能膨胀的坑工具用起来之后问题并不在“能不能记住”而在“记住的东西是否安全、是否准确、是否拖慢系统”。这一章是我最想写的因为这几个坑都是文档里不会告诉你的。5.1 隐私边界哪些内容不该进记忆库记忆库装的是敏感内容时隐私问题就绕不过去。我一开始满脑子都是“尽量多记”后来有一次实测发现对话里不小心包含了某条内部系统的完整访问口令而它正躺在明文 JSONL 文件里我心里立刻咯噔一下。从那以后我加了一条硬规则**默认不记录敏感字段只有显式标记的内容才允许入库存。**实现上我维护了一个敏感词和模式清单写入前先做脱敏检查。匹配到的内容不会被存进记忆库而是在快照文件里被替换成占位符。脱敏逻辑很简单口令、token、密钥、身份证号这类字段一旦出现高置信度模式就触发屏蔽。宁可漏存一条普通记忆也不能让敏感信息悄悄沉淀下来。另外我建议分类存放权限。SQLite 里只放脱敏后的结构化记忆原始 JSONL 文件单独设读权限只允许本机管理员读取。这类文件不需要同步到任何地方更不能放到云盘同步目录里因为那是明文备份一旦泄漏你所有的“记忆”都等于公之于众。5.2 误召回比不召回更麻烦的排查经历我以为“召回不到记忆”是最烦的直到我在一个支付模块的会话里被错误记忆带偏了整整一下午才发现误召回才是更隐蔽的杀手。当时的情况是我三周前在另一个项目的对话里讨论过一个“订单号重复”的临时排查方案结论是该方案只适用于旧订单表。结果这个结论被错误关联到了当前支付项目的命名空间下AI 助手在新会话里把它当成既定事实引用差点改坏了新订单表的索引逻辑。源头其实是写入时项目上下文的判定问题那段对话发生在“通用技术讨论”会话里没有绑定任何项目 ID入库时被我标记成了默认项目结果污染了支付项目的记忆空间。这个事件之后我加强了写入时的项目上下文绑定逻辑并且给“未绑定项目的记忆”单独建了一个待归档池。这类记忆不会自动进入任何项目的检索范围除非我手动确认它归属于哪个项目。结论型记忆入库前还会经过一次“反向校验”如果它和已有记忆冲突系统不会直接覆盖而是把冲突标记出来让我决定谁优先。5.3 索引膨胀与清理策略向量索引会随记忆量增长而膨胀这是我一开始没想到的。我用本地向量索引存储 768 维向量每条记忆大约占几千字节看起来很小但积少成多一个月后索引文件竟然膨胀到了好几百兆启动加载时间从一秒涨到将近十秒。在分析膨胀原因时我发现问题不在于条数多而在于大量“过时记忆”没有被淘汰。AI 助手的对话里充满了变体表述同一个结论产出六七次“版本”每一次都生成了新向量。为了控制膨胀我最终做了三件事第一定期归档。超过 180 天且没有被手动更新的低相关记忆自动从向量索引移入冷存储只在需要时手动解冻。第二去重时合并向量。前面提到的语义去重命中后保留最早版本的向量同时把新版本里的附加信息补充到元数据里不额外生成新向量。第三冷启动优化。初始加载只载入最近 30 天的高优先级记忆向量其他在后台按需加载。这三招组合之后索引体积回落到最初的 20% 左右启动时间也回到了两秒以内。6. 再往后走从“记住对话”到“理解意图”工具稳定跑了两个多月之后我开始觉得“记住对话”还不够。真正的长期记忆应该从“记录发生了什么”升级为“理解为什么发生”再到“预判接下来需要什么”。这个方向我一变再变最终收敛成了几个可以实际操作的扩展点。6.1 事件订阅与自定义摘要的扩展点最早 claude-mem 只有两个内置动作写入和召回。后来我发现很多高价值操作都发生在“写入之后”。比如某次会话结束后如果自动生成一份周报式的摘要后续项目复盘会省非常多时间。所以我加了一个简单的事件总线每次记忆写入、更新、召回都会发出事件允许我挂自己的回调。我现在挂了三个回调一个负责把每日的高频关键词汇总成“今日主题”一个负责在项目记忆变化超过 5% 时提醒我“该项目近期讨论活跃”另一个负责把新增记忆同步生成 Markdown 周报。这个事件总线的扩展成本非常低但它把工具从“记忆库”变成了“项目活动的数据基础设施”。如果你也要做类似设计我建议把事件结构定义成纯 JSON并且不绑定任何内部实现细节这样以后想接别的系统时只需要写一层适配。6.2 记忆库与外部知识库的边界我一度想把项目的设计文档、会议纪要、代码注释全部导入 claude-mem最后被自己劝退了。原因是这类“正式文档”有它们自己的生命周期和权威性和“对话记忆”的性质完全不同。对话记忆是动态的、口语化的、可能带猜测成分的正式文档是静态的、权威的、需要评审后才能修改的。混在一起只会让 AI 助手分不清哪句是正经结论、哪句只是我说说的想法。我现在采用的边界是正式知识库负责“标准答案”claude-mem 负责“推演轨迹”。AI 助手查询时如果二者冲突以知识库的版本为准。如果知识库里还没有对应内容但记忆中已经出现稳定的结论我会手动把它升级到知识库去而不是让记忆库长期承担“标准答案”的角色。这样记忆库始终是没那么严肃但信息量很大的“工作底稿”知识库则是干净可信的“正式档案”。6.3 给打算自己写记忆层的人三个建议如果你看完这篇文章打算也给自己做一套类似的记忆层我给你三个最实在的建议。第一先写清楚三层记忆模型再写代码。存什么比怎么存重要一万倍。我见过太多项目把全部对话倒进向量库结果语义召回一团浆糊因为噪音太多。先想清楚哪一层解决什么问题后面每一步都会简单很多。第二不要追求一次到位先做能落地的最小闭环。先用 JSONL 文件存原始快照、用 SQLite 做基础查询哪怕没有向量化也能解决 70% 的问题。我真正引入向量库是在记忆量超过一千条之后在此之前它只会增加复杂度。第三一定要给每条记忆留下可追溯的来源。没有来源的记忆是不可信的也会在冲突发生时无法仲裁。我所有的记忆都带着会话 ID 和确认时间这使我能在误召回发生后快速定位污染源而不是对着整库数据发呆。claude-mem 到现在已经迭代了好几版它让我和 AI 助手的协作方式发生了根本变化从“每次重新认识”变成“越聊越熟”。如果你也被 AI 助手的“金鱼记忆”折磨过不妨按照上面的思路自己动手搭一套轻量记忆层。先别设计得太大从保存第一次会话快照开始你会发现后面的一切都是水到渠成。
1. 从一个让我崩溃的场景说起AI 助手的“金鱼记忆”做 claude-mem 这个工具起因特别朴素。我连续一周每天跟同一个 AI 助手讨论同一个项目的接口改造每天上午打开新的会话窗口它都要礼貌地问我“这个项目的技术栈是什么现在的数据结构大概长什么样”我只好把前一天已经说过的背景重新粘贴一遍粘贴完它又问下一个类似的问题。那几天我的心情基本是我不是在做开发我是在当复读机。后来我认真想了想这其实不能全怪 AI。对话框本质上是无状态的一次会话结束上下文就没了。我指望它记住项目里所有历史背景本来就不现实。但反过来说程序员做项目会写文档、留注释、记周报为什么 AI 助手不能有一套类似的“外部记忆”于是我开始动手做 claude-mem一个把 AI 对话历史持久化、索引化、并且能在新会话里自动回放关键记忆的小工具。这个工具做的事情用一句话概括让 AI 助手每次见到你时都像昨天刚聊过一样。它适合所有用 AI 助手做正经项目的开发者尤其是那些频繁开新会话、需要在多个任务之间切换、又不想每次手动粘贴背景信息的人。如果你只是偶尔问几个一次性问题那确实用不上它但只要你把 AI 助手当成长期协作者记忆层就是刚需。1.1 上下文窗口再大也装不下一个项目的“前世”很多人会说现在上下文窗口已经很大了动辄几十万 token为什么还要搞外部记忆这个问题我一开始也困惑过直到我实测了一个中等规模的项目才明白窗口再大它也是“一次性”的。举个例子我在做某个跨平台同步模块时和 AI 助手反复讨论了数据冲突解决策略。最初定下来的方案是“以最近修改时间为主同时保留冲突副本”后来因为业务需要改成了“按设备优先级合并”。这些决策过程非常关键但散落在三四个会话里。等到第五天我开新会话让它继续优化这个模块时它根本不知道第二、第三天已经讨论过什么于是又提出了已经被否掉的旧方案。这不是上下文窗口大小的问题而是会话断裂的问题。窗口存在时AI 能看到全部对话窗口一关一切归零。真正的项目记忆需要跨越会话边界需要在关键时刻被检索出来而不是靠赌下一次对话刚好还在窗口里。更现实的问题是成本。每次把大量历史对话重新喂进去token 消耗是实打实的。我曾经把三天的对话记录拼接成一份“项目背景说明”塞进新会话结果上下文里全是流水账真正有用的决策点反而被稀释了。与其把所有历史都塞进去不如只提取其中的关键结论、参数约定、被否决的方案和原因这些才是值得长期记住的东西。1.2 记忆不应该是奢侈品而应该是基础设施做工程的都知道代码写久了最重要的不是“代码本身”而是“代码为什么变成现在这样”。需求变更的原因、性能瓶颈的定位过程、某段逻辑为什么用了看上去很绕的写法——这些信息全在对话里。如果记录不下来两个月后你回头看代码只看到结果看不到来路。人的应对方式是写文档、写评论、写设计文档但说实话程序员普遍不爱写文档尤其是项目中途的决策记录。而 AI 对话天然包含了大量这类信息只是被丢弃了。claude-mem 的定位就是把对话历史变成项目资产它自动保留每一次讨论的关键内容在新会话开始前把相关记忆注入上下文让 AI 助手带着“前世记忆”重新上场。这套思路本质上是在给 AI 助手装一个“长期记忆皮层”而对话窗口只负责当次任务的“工作记忆”。工作记忆负责专注长期记忆负责连续二者配合才能干成有跨度的项目。后面我会详细拆解我是怎么设计这个记忆层的包括存什么、怎么存、怎么召回、怎么回放以及这一路上踩过的各种坑。2. 拆解 claude-mem 的设计决策先想清楚要存什么动手写第一行代码之前我强迫自己先回答一个问题到底什么样的信息才配进记忆库直接存全量对话当然最简单但那只是把问题从“上下文装不下”变成了“数据库里躺着垃圾”。没有取舍的记忆系统本质上是另一个垃圾场。我花了不少时间做信息建模最终把记忆分成了三层每一层的有效期、写入方式和被消费的方式都不一样。2.1 三层记忆模型会话级、项目级、长期知识级我把记忆分成三个层级这是整个工具的地基。会话级记忆对应一次完整对话的压缩快照包括这次会话的目标、最终结论、产出物清单。它的有效期是“这个项目周期内”核心作用是被后续会话快速引用。比如某天我和 AI 助手完成了用户鉴权模块的接口定义那么会话级记忆就应该保存“接口路径、请求参数、返回格式、已确认的签名方案”。项目级记忆是跨多个会话沉淀下来的稳定事实比如项目技术栈约定、模块边界、已否决的方案及原因、常见陷阱。这类记忆通常从多段会话级记忆中归纳而来不一定每次会话都写入而是需要某种“沉淀”机制。我在设计时让它支持手动确认和自动抽取两种路径自动抽取负责把高频出现的术语和结论标记出来手动确认则允许我直接输入一条项目约定例如“后端统一用 UTC 时间禁止本地时间入参”。长期知识级记忆更像个人知识库和具体项目无关比如“我对某类架构模式的一贯偏好”“我常用的错误处理风格”。这一层我做得比较轻因为它的价值密度高但复用频率低过度膨胀反而会干扰项目级检索。我建议看到这篇文章的你自己评估如果只是给单个项目用前两层就足够了长期知识层可以后置。这三层记忆必须分开存储否则检索时会互相污染。我最开始偷懒把三层混在一个表里后果是查项目约定时经常翻出无关的闲聊内容后来老老实实加了类型标签和两个独立的索引空间。2.2 存储引擎选型的对比与取舍存储层我先后试过三种方案纯 JSON 文件、SQLite、嵌入式向量库。每种方案都有它的适用位置最终我做的是“组合而非单选”。方案优点缺点我用在哪个层JSON Lines 文件可读、可手动编辑、方便备份查询能力弱、不适合频繁更新会话级原始快照SQLite事务可靠、SQL 检索成熟、单文件部署需要自己管理表结构项目级结构化记忆嵌入式向量库语义检索能力强需要额外依赖、索引有膨胀问题长期知识层和语义召回先说 JSON Lines。每次会话结束时我把原始对话按时间顺序写入一个 .jsonl 文件按会话 ID 作为文件名。这么做的好处是调试极其方便我可以直接打开文件看某次会话到底记录了什么排查写入 bug 时不用连数据库。缺点当然是没法高效查询所以它只作为“原始层”真正的检索走后面的索引。SQLite 用来存项目级记忆。我把每条记忆拆成“实体、属性、值、来源会话ID、可信度、最后确认时间”这几个字段。比如“实体鉴权模块属性签名算法值HMAC-SHA256来源会话#12可信度确认”。这种结构化程度足够支持精确匹配也能做很轻量的条件过滤比如“只看最近一周确认过的约定”。向量库是我后来才引入的用来解决千万不能用关键词匹配到的语义问题。早期的测试里我问“登录这块之前怎么定的”如果只做关键词检索可能搜不到任何东西因为会话里根本没有“登录”“定”这些词只有“鉴权”“签名方案确定”。向量化之后这个问题被大幅缓解。2.3 向量化检索为什么没有一开始就上我见过很多同类工具上来就用向量数据库号称“语义记忆”实际效果却非常一般。我自己的体会是向量化解决的是召回率问题而不是精确性问题它应该被放在检索链路的最后一段而不是唯一一段。项目刚起步时我只有两百多条记忆纯 SQLite 的 LIKE 查询已经完全够用。但记忆量超过一千条后关键词检索的缺陷变得很明显同一个概念在不同会话里有不同的说法比如“鉴权”“认证”“登录态”指同一件事关键词检索会把它们当成三个无关的东西。这时候我才决定引入向量化。我用的是一个本地 embedding 模型维度选了 768每次写入记忆时生成向量、存入向量索引。代价是内存占用上升、首次加载有延迟换来的是语义召回的明显改善。但我要提醒一句千万别把所有记忆全部向量化那会同时污染精确查询和语义查询。我的做法是只对“项目级记忆”和“长期知识层”做向量化会话级快照永远走关键词和会话时间索引。3. 核心流程的工程化实现写入、索引、召回、回放设计归设计真正落地时工程细节决定了这个工具是“能用”还是“好用”。我按数据流转的顺序把整个流程拆成四段每一段都改过至少三轮。3.1 会话快照的写入时机与去重策略第一个问题是什么时候写入记忆我在最早版本里用的是“定时任务全部同步”结果发现大部分中间过程毫无价值最后反而把索引搞得很脏。后来改成“事件驱动 会话结束快照”的组合策略。事件驱动负责记录关键节点当对话中出现明显结论性语句时比如“那就这么定”“这个方案可以”我把该段对话连同上下文摘要写进暂存区。会话结束或手动触发时再把暂存区合并成一份完整快照写入 JSON Lines 原始文件并抽取结构化记忆入库。去重是我踩过的最实在的坑。同一结论可能在对话里反复出现AI 助手喜欢换着说法把一句话说三遍。如果不去重项目级记忆会被同一决策的多个变体塞满。我做的去重策略分两层文本相似度去重和语义去重。先计算新记忆和已有记忆的文本相似度超过 0.9 就视为重复如果没有命中再算向量余弦相似度超过 0.95 也会被拦下来。阈值不能设太死设太猛容易把真正的新信息滤掉我调到 0.95 之后误杀率才降到可接受范围。3.2 检索链路从关键词到语义召回再到重排检索模块是 claude-mem 最核心的部分它直接决定了注入给 AI 助手的记忆是否准确。我没有用“问一句然后返回一堆最相似片段”的简单方案而是搭了一条三级链路。第一级是条件过滤根据当前会话的项目 ID、时间范围、记忆类型先把候选集缩小。比如我在调试支付模块时必须先把记忆空间切到支付项目绝不能把别的项目里的接口约定混进来。第二级是关键词精排用 BM25 类算法对候选集打分精确匹配优先。第三级才是语义召回对前两级结果做向量相似度重排补回那些“说法不同但意思相同”的记忆。重排之后我还会做一步“新鲜度加权”。两天前确认的接口约定比两个月的记录可靠得多除非后者的可信度被人为标记为“永久有效”。加权公式很简单但我调了很久才找到合适的衰减系数半衰期设成 30 天超过 90 天的旧记录除非被手动置顶否则权重会低到几乎不影响排序。这三级链路跑完我还会把结果按“结论型记忆优先于过程型记忆”的原则做一次最终排序。过程型记忆适合用来理解来龙去脉但在给 AI 的上下文里结论型记忆的边际价值远高于冗长的推理过程。3.3 回放机制让 AI 带着“前世记忆”重新上场记忆召回到位之后下一步是怎么把结果回放给 AI 助手。这一步看似简单实则非常讲究时机和格式。如果在会话一开始就把十段记忆全塞进去AI 会被大量背景信息带偏甚至把记忆里的旧结论当成当前事实。我的做法是分三种回放时机。会话启动回放只注入三条以内的核心记忆通常是项目名、技术栈约定、上次会话的待办事项。话题触发回放当对话进入某一主题时根据最近一段对话的语义查询记忆库把相关结论实时注入。手动纠正当 AI 的回答明显偏离已确认方案时我可以手动触发一次强制检索把精确记忆原文放进去让它在给出下一次回答前先“看到”那条结论。回放格式也有讲究。我不用纯文本堆砌而是给每条记忆加上元信息前缀比如 [来源会话 #23 | 确认于三天前 | 类型接口约定]这样 AI 能理解它读到的不是用户随口说的内容而是经过确认的历史结论。这种元信息极大提高了回放内容的可信度我实测下来AI 引用历史结论时的语气都变得更确定了。4. 本地部署与日常使用的落地经验工具再精巧不好用就是摆设。我在本地部署和日常使用上花了不少精力最终形成了一套一套非常顺手的用法这里分享最关键的几个落地经验。4.1 最小可用环境的目录与配置我的部署环境不依赖任何云端服务所有数据存在本地目录里。最小目录结构大概是这样的claude-mem/ ├── raw/ │ └── 会话快照/ │ ├── 2025-06-01_接口改造.jsonl │ └── 2025-06-02_鉴权重构.jsonl ├── indexes/ │ ├── project_mem.sqlite │ └── vector_index/ ├── config.yaml └── logs/config.yaml 里最重要的几个配置项我列成表格供你参考配置项我的取值说明storage.raw_dir./raw原始对话快照目录storage.enable_sqlitetrue是否启用结构化记忆recall.top_k5单次检索最大返回条数recall.min_score0.72低于该分数不纳入回放index.embedding_dim768embedding 维度memory.shelf_life_days90新鲜度半衰期参数这些配置都能在运行中热加载不需要重启服务。我建议你一定保留 raw 目录它看起来最占空间但所有排查问题的起点都是它。4.2 三种我实测好用的用法claude-mem 我做了三种使用方式覆盖了大多数场景。第一种是CLI 查询。在终端里跑mem query 鉴权方案最终怎么定的它会直接返回相关记忆片段和对应的原始会话来源。这个用法适合我正在写代码、不想切到 AI 对话框时的快速确认。第二条命令mem inject --project payment会把项目最新记忆整理成一段上下文我直接复制粘贴给 AI 助手即可。第二种是自动注入脚本。我把mem inject --top 3的输出接到我自己常用的那个 AI 客户端配置里每次新会话启动时自动带入项目核心记忆。这个方案需要一点脚本能力但一次配好之后非常省心相当于给 AI 助手装了个“开机记忆加载器”。第三种是会话侧边栏。我在单独一个终端窗口跑mem watch监听当前项目目录每次和 AI 助手对话结束后它会自动检测新的记录文件并更新索引。这样我不用手动触发任何操作记忆库一直在后台静默生长。需要提醒的是watch 模式依赖文件系统事件接口在非本地文件系统上会失效所以我的部署一直坚持本地目录。4.3 多用户场景下的隔离与权限如果你只是自己用权限问题几乎不用考虑。但我后来把它分享给了项目组的几个同事问题就来了不同人的对话记录如果混在一起A 的接口约定可能被 B 的查询召回导致 AI 给出错误结论。我做了两层隔离。第一层是项目隔离每个项目一个独立命名空间检索时强制带上 project_id 条件。第二层是用户隔离每个用户有自己的读写入权限同事之间默认只能看到被标记为“共享”的记忆。这个设计参考了 Git 的分支思路记忆库不是一个大池子而是既共享又隔离的家族库。共享机制也很关键。几个人一起开发时最重要的共识是“哪些记忆可以被共享”。我约定接口定义、架构决策、技术栈约定这三个类别默认共享个人偏好、临时讨论、未确认想法默认私有。这样既保证团队信息流动又避免污染的噪音进到别人的记忆库里。5. 数据隐私、误召回与性能膨胀的坑工具用起来之后问题并不在“能不能记住”而在“记住的东西是否安全、是否准确、是否拖慢系统”。这一章是我最想写的因为这几个坑都是文档里不会告诉你的。5.1 隐私边界哪些内容不该进记忆库记忆库装的是敏感内容时隐私问题就绕不过去。我一开始满脑子都是“尽量多记”后来有一次实测发现对话里不小心包含了某条内部系统的完整访问口令而它正躺在明文 JSONL 文件里我心里立刻咯噔一下。从那以后我加了一条硬规则**默认不记录敏感字段只有显式标记的内容才允许入库存。**实现上我维护了一个敏感词和模式清单写入前先做脱敏检查。匹配到的内容不会被存进记忆库而是在快照文件里被替换成占位符。脱敏逻辑很简单口令、token、密钥、身份证号这类字段一旦出现高置信度模式就触发屏蔽。宁可漏存一条普通记忆也不能让敏感信息悄悄沉淀下来。另外我建议分类存放权限。SQLite 里只放脱敏后的结构化记忆原始 JSONL 文件单独设读权限只允许本机管理员读取。这类文件不需要同步到任何地方更不能放到云盘同步目录里因为那是明文备份一旦泄漏你所有的“记忆”都等于公之于众。5.2 误召回比不召回更麻烦的排查经历我以为“召回不到记忆”是最烦的直到我在一个支付模块的会话里被错误记忆带偏了整整一下午才发现误召回才是更隐蔽的杀手。当时的情况是我三周前在另一个项目的对话里讨论过一个“订单号重复”的临时排查方案结论是该方案只适用于旧订单表。结果这个结论被错误关联到了当前支付项目的命名空间下AI 助手在新会话里把它当成既定事实引用差点改坏了新订单表的索引逻辑。源头其实是写入时项目上下文的判定问题那段对话发生在“通用技术讨论”会话里没有绑定任何项目 ID入库时被我标记成了默认项目结果污染了支付项目的记忆空间。这个事件之后我加强了写入时的项目上下文绑定逻辑并且给“未绑定项目的记忆”单独建了一个待归档池。这类记忆不会自动进入任何项目的检索范围除非我手动确认它归属于哪个项目。结论型记忆入库前还会经过一次“反向校验”如果它和已有记忆冲突系统不会直接覆盖而是把冲突标记出来让我决定谁优先。5.3 索引膨胀与清理策略向量索引会随记忆量增长而膨胀这是我一开始没想到的。我用本地向量索引存储 768 维向量每条记忆大约占几千字节看起来很小但积少成多一个月后索引文件竟然膨胀到了好几百兆启动加载时间从一秒涨到将近十秒。在分析膨胀原因时我发现问题不在于条数多而在于大量“过时记忆”没有被淘汰。AI 助手的对话里充满了变体表述同一个结论产出六七次“版本”每一次都生成了新向量。为了控制膨胀我最终做了三件事第一定期归档。超过 180 天且没有被手动更新的低相关记忆自动从向量索引移入冷存储只在需要时手动解冻。第二去重时合并向量。前面提到的语义去重命中后保留最早版本的向量同时把新版本里的附加信息补充到元数据里不额外生成新向量。第三冷启动优化。初始加载只载入最近 30 天的高优先级记忆向量其他在后台按需加载。这三招组合之后索引体积回落到最初的 20% 左右启动时间也回到了两秒以内。6. 再往后走从“记住对话”到“理解意图”工具稳定跑了两个多月之后我开始觉得“记住对话”还不够。真正的长期记忆应该从“记录发生了什么”升级为“理解为什么发生”再到“预判接下来需要什么”。这个方向我一变再变最终收敛成了几个可以实际操作的扩展点。6.1 事件订阅与自定义摘要的扩展点最早 claude-mem 只有两个内置动作写入和召回。后来我发现很多高价值操作都发生在“写入之后”。比如某次会话结束后如果自动生成一份周报式的摘要后续项目复盘会省非常多时间。所以我加了一个简单的事件总线每次记忆写入、更新、召回都会发出事件允许我挂自己的回调。我现在挂了三个回调一个负责把每日的高频关键词汇总成“今日主题”一个负责在项目记忆变化超过 5% 时提醒我“该项目近期讨论活跃”另一个负责把新增记忆同步生成 Markdown 周报。这个事件总线的扩展成本非常低但它把工具从“记忆库”变成了“项目活动的数据基础设施”。如果你也要做类似设计我建议把事件结构定义成纯 JSON并且不绑定任何内部实现细节这样以后想接别的系统时只需要写一层适配。6.2 记忆库与外部知识库的边界我一度想把项目的设计文档、会议纪要、代码注释全部导入 claude-mem最后被自己劝退了。原因是这类“正式文档”有它们自己的生命周期和权威性和“对话记忆”的性质完全不同。对话记忆是动态的、口语化的、可能带猜测成分的正式文档是静态的、权威的、需要评审后才能修改的。混在一起只会让 AI 助手分不清哪句是正经结论、哪句只是我说说的想法。我现在采用的边界是正式知识库负责“标准答案”claude-mem 负责“推演轨迹”。AI 助手查询时如果二者冲突以知识库的版本为准。如果知识库里还没有对应内容但记忆中已经出现稳定的结论我会手动把它升级到知识库去而不是让记忆库长期承担“标准答案”的角色。这样记忆库始终是没那么严肃但信息量很大的“工作底稿”知识库则是干净可信的“正式档案”。6.3 给打算自己写记忆层的人三个建议如果你看完这篇文章打算也给自己做一套类似的记忆层我给你三个最实在的建议。第一先写清楚三层记忆模型再写代码。存什么比怎么存重要一万倍。我见过太多项目把全部对话倒进向量库结果语义召回一团浆糊因为噪音太多。先想清楚哪一层解决什么问题后面每一步都会简单很多。第二不要追求一次到位先做能落地的最小闭环。先用 JSONL 文件存原始快照、用 SQLite 做基础查询哪怕没有向量化也能解决 70% 的问题。我真正引入向量库是在记忆量超过一千条之后在此之前它只会增加复杂度。第三一定要给每条记忆留下可追溯的来源。没有来源的记忆是不可信的也会在冲突发生时无法仲裁。我所有的记忆都带着会话 ID 和确认时间这使我能在误召回发生后快速定位污染源而不是对着整库数据发呆。claude-mem 到现在已经迭代了好几版它让我和 AI 助手的协作方式发生了根本变化从“每次重新认识”变成“越聊越熟”。如果你也被 AI 助手的“金鱼记忆”折磨过不妨按照上面的思路自己动手搭一套轻量记忆层。先别设计得太大从保存第一次会话快照开始你会发现后面的一切都是水到渠成。
