1. 从"claude-mem"这个名字说起:它到底想解决什么
第一次看到claude-mem这个命名,我的直觉是:这是一个围绕对话记忆做文章的项目。claude指向的是对话式 AI 的交互场景,mem是 memory 的缩写,合在一起,核心命题就非常清晰了——让对话式 AI 拥有跨会话、可检索、可管理的长期记忆能力。
为什么这件事值得单独做一个项目?因为只要你真正长时间用过对话式 AI,就会撞上同一个墙:上下文窗口是有限的,而人的需求是连续的。今天上午你跟它聊了一半的架构方案,下午想接着聊,它已经忘了;上周你告诉过它你的技术栈偏好、代码风格、项目背景,这周开新会话,一切归零。每次都要重新交代一遍背景,这种体验就像每次打电话都要先自我介绍一遍"我是谁、我在做什么、我习惯怎么沟通"。
claude-mem要做的,就是把这层"记忆"从模型内部剥离出来,变成一个外部的、可控的、可持久化的存储层。它不依赖模型本身记住什么,而是通过一套机制,在需要的时候把相关的历史信息"喂"回给模型。这个思路在工程上非常关键,因为它把"记忆"从一个黑盒能力,变成了一个你可以调试、可以清理、可以迁移的白盒系统。
这篇文章适合谁看?如果你正在做对话式 AI 的应用层开发,或者你自己就是一个重度 AI 工具使用者,想搞清楚"长期记忆"到底该怎么落地,那这篇内容会对你有用。我会从记忆的本质问题讲起,拆到存储结构、检索策略、注入时机、去重与衰减这些实操层面的东西,最后给出一套可以照着搭的最小可用方案。全程不堆概念,讲的是我实际踩过、验证过的路子。
需要先说明一点:claude-mem这类项目的具体实现细节,公开资料往往比较零散,所以文中涉及的具体参数、目录结构、检索阈值,有一部分是基于这类记忆系统常见工程实践的合理补全,我会在相应位置标注清楚哪些是通用做法、哪些是需要你按自己场景调整的。
2. 记忆系统的本质:不是"存下来"那么简单
2.1 为什么"把对话存进数据库"是个伪需求
很多人对 AI 记忆的第一反应是:把每轮对话存进数据库,下次检索出来拼进 prompt 不就行了?我一开始也是这么想的,直到实际跑起来才发现,这个方案在真实场景下几乎不可用。
问题出在三个地方。第一是噪声爆炸。一次正常的技术讨论,可能产生几十轮对话,其中真正有长期价值的信息可能只有三五条——比如"我们决定用 PostgreSQL 而不是 MySQL"、"这个项目的部署目标是单机 Docker"。剩下的全是过程性的废话。如果你把整段对话都塞回去,prompt 会被垃圾信息淹没,模型反而抓不住重点。
第二是检索精度。当你用向量检索去匹配"上次我们聊的数据库选型",返回的可能是十段都提到"数据库"的对话,但真正包含决策结论的那一段可能排在第七位。检索不准,记忆就是负资产。
第三是时效与冲突。三个月前你说"我倾向用 REST",上个月你改口说"还是上 GraphQL 吧"。如果两条记忆都被平等地检索出来,模型会陷入精神分裂。记忆系统必须能处理更新、覆盖、失效,而不是只做追加。
所以claude-mem这类项目的真正难点,从来不是"怎么存",而是"存什么、怎么找、什么时候用、旧了怎么办"。这四件事构成了记忆系统的完整闭环,缺一个都会让系统在实际使用中崩掉。
2.2 记忆的分层:工作记忆、情景记忆、语义记忆
要设计好记忆系统,先得给记忆分类。我习惯把它分成三层,这个分法借鉴了认知科学,但在工程上极其好用。
工作记忆(Working Memory)就是当前会话的上下文,也就是模型窗口里那点内容。它的特点是容量小、生命周期短、随会话结束而消失。这一层不需要你额外做什么,模型自带的上下文就是它。
情景记忆(Episodic Memory)是"某次具体交互发生了什么"。比如"2024 年 3 月 15 日那次会话,用户让我重构了一个登录模块,最终采用了 JWT + 刷新令牌的方案"。这类记忆带时间戳、带场景,适合用"最近发生了什么"这类查询召回。
语义记忆(Semantic Memory)是抽离出来的稳定事实。比如"用户偏好用 TypeScript"、"项目使用 pnpm 作为包管理器"、"用户不喜欢过度注释的代码"。这类记忆不带具体场景,是长期沉淀下来的偏好和事实,适合用"用户是谁、偏好什么"这类查询召回。
claude-mem如果只做一层,那它大概率只能做情景记忆,也就是"把历史对话存起来再检索"。但真正好用的系统,一定会在情景记忆之上再抽一层语义记忆——从对话里提炼出稳定事实,单独存一份。这样下次开新会话时,你只需要注入语义记忆那几十条精炼事实,就能让模型"认识你",而不需要把几百轮对话全拖进来。
这个分层是后面所有设计的基础。你如果只记一句话,就记这句:情景记忆负责"回忆细节",语义记忆负责"认识用户",两者存储和检索策略完全不同。
2.3 记忆的写入时机:什么时候该记
存什么的问题解决了,接下来是"什么时候存"。这里有个反直觉的结论:不要每轮对话都写记忆。
我早期做过一个版本,每轮对话结束就调一次模型去判断"这轮有没有值得记的",结果 token 消耗巨大,而且写进去大量低价值内容。后来改成按会话边界写入——一次会话结束(用户关闭、超时、或显式触发)时,统一做一次记忆抽取。这样成本可控,而且抽取时有完整上下文,判断质量更高。
具体来说,写入分两个动作。第一个动作是情景摘要:把整段会话压缩成一段 100 到 200 字的摘要,保留关键决策、结论、未解决的问题。第二个动作是事实抽取:从会话里挑出稳定事实,比如偏好、约束、技术选型,每条独立成条,带一个置信度。
提示:事实抽取这一步,建议用一次独立的模型调用,并且给它一个明确的输出格式(比如 JSON 数组),每条包含
fact、category、confidence三个字段。不要指望模型自由发挥,格式约束越死,后续处理越省事。
写入时机的选择,直接决定了记忆系统的信噪比。我的经验是:宁可少写,不可滥写。一条错误或过时的记忆,比没有记忆更糟糕,因为它会持续污染后续所有会话。
3. 存储结构设计:向量库、关系库还是文件
3.1 三种存储方案的取舍
记忆存哪里,是绕不开的选型问题。我实际用过三种方案,各有适用场景,下面这张表是我踩坑之后总结的对比。
| 方案 | 优势 | 劣势 | 适用场景 |
|---|---|---|---|
| 纯文件(JSON/Markdown) | 零依赖、可读可编辑、易迁移 | 检索靠关键词,语义匹配弱 | 个人使用、记忆量小于几百条 |
| 关系型数据库 | 结构化查询强、事务可靠、易做去重 | 语义检索需要额外扩展 | 需要精确过滤、多用户场景 |
| 向量数据库 | 语义检索天然支持、扩展性好 | 运维成本、需要 embedding 调用 | 记忆量大、检索精度要求高 |
claude-mem这类项目,如果定位是个人或小团队使用,我强烈建议从文件方案起步。原因很简单:记忆量在早期根本不大,几百条记忆用文件存,配合关键词加简单的时间衰减排序,检索效果已经够用。过早引入向量库,你会把大量时间花在运维和 embedding 成本上,而不是记忆逻辑本身。
等到记忆量上千、检索开始不准了,再迁移到向量库也不迟。而且迁移时你会发现,前面用文件方案积累的"哪些记忆真正被用到"的数据,能帮你判断该给哪些记忆建索引。
3.2 一条记忆该长什么样
不管存哪里,记忆的数据结构是核心。我用的结构大概是这样:
{ "id": "mem_20240315_001", "type": "semantic", "content": "用户偏好使用 TypeScript,且倾向于严格模式", "category": "preference", "confidence": 0.9, "created_at": "2024-03-15T10:30:00Z", "last_accessed": "2024-04-02T08:12:00Z", "access_count": 7, "source_session": "sess_20240315_a", "tags": ["language", "coding-style"], "status": "active" }几个字段值得单独说。type区分情景和语义,检索时可以按需过滤。confidence是置信度,抽取时模型给的,后续如果同一条事实被反复确认,可以调高;如果被推翻,直接置为失效。last_accessed和access_count是记忆热度的度量,用来做衰减和排序——经常被用到的记忆应该优先召回,长期没人碰的可以降权甚至归档。status用来做软删除,避免物理删除后无法追溯。
注意:
confidence这个字段千万别省。我见过太多系统把抽取出来的事实当成绝对真理,结果一条错误记忆反复被注入,把模型带偏。有了置信度,你可以在注入时做阈值过滤,比如只注入confidence > 0.7的记忆。
3.3 去重与冲突处理:记忆系统的"免疫机制"
记忆写多了,必然出现重复和冲突。比如"用户用 TypeScript"和"用户偏好 TypeScript 严格模式",这两条高度重叠;再比如"项目用 MySQL"和"项目已迁移到 PostgreSQL",这是直接冲突。
去重我用的方法是写入前先检索。新记忆生成后,先用它的内容去检索已有记忆,如果找到相似度超过阈值(比如 0.85)的,就不新增,而是更新已有记忆的confidence和last_accessed。这样能有效控制记忆总量。
冲突处理更麻烦一点。我的做法是引入时间优先 + 显式覆盖两条规则。如果两条记忆内容矛盾,且都带时间戳,默认新的覆盖旧的,把旧的status置为superseded。但如果新记忆的confidence明显低于旧记忆(比如新的是 0.5,旧的是 0.9),就不自动覆盖,而是标记为"待确认",下次会话时主动向用户澄清。
这套机制听起来复杂,但实现起来就是一个写入前的检索加判断逻辑,几十行代码的事。它的价值在于:让记忆系统具备自我净化能力,而不是一个只进不出的垃圾场。
4. 检索与注入:记忆怎么"想起来"和"用起来"
4.1 检索策略:关键词、向量还是混合
检索是记忆系统的咽喉。检索不准,前面存得再好都白搭。我实测下来,混合检索效果最稳:先用关键词做粗筛,再用向量做精排。
具体流程是这样:用户发起新会话时,系统拿到当前输入,先做关键词提取(可以用简单的分词加停用词过滤,也可以用模型抽关键词),拿这些词去记忆库里做匹配,召回一批候选。然后对候选做向量相似度排序,取 top-K。最后再叠加时间衰减和热度加权,得到最终注入列表。
时间衰减的公式我用的是简单的指数衰减:
score = similarity * exp(-λ * days_since_access) * (1 + log(1 + access_count))其中λ是衰减系数,我一般取 0.01 到 0.03 之间。这个值越大,记忆"过期"越快。对于偏好类语义记忆,衰减应该慢一些(λ 取小);对于情景记忆,衰减可以快一些,因为具体某次对话的细节,时间久了确实没那么重要。
4.2 注入时机与格式:别把记忆当 prompt 垃圾场
检索出来的记忆,怎么塞进 prompt,也是有讲究的。我见过最粗暴的做法是把记忆拼成一大段文字丢在 system prompt 里,结果模型经常忽略,或者被记忆里的细节带偏。
我的做法是结构化注入 + 明确指令。把记忆按类型分组,语义记忆放前面(因为它是"用户是谁"),情景记忆放后面(它是"最近发生了什么"),并且用清晰的标记包起来:
[长期记忆 - 用户偏好] - 偏好 TypeScript 严格模式 - 不喜欢过度注释 [近期记忆 - 相关历史] - 上次讨论过登录模块重构,最终采用 JWT + 刷新令牌然后在 system prompt 里加一句明确的指令:"以上是历史记忆,供参考。如果与当前对话冲突,以当前对话为准。" 这句话很关键,它给了模型一个优先级规则,避免记忆和当前输入打架时模型无所适从。
注入数量也要控制。我的经验是语义记忆不超过 20 条,情景记忆不超过 5 条。超过这个量,边际收益急剧下降,反而增加噪声和 token 成本。
4.3 记忆的"遗忘":主动清理比无限积累更重要
一个健康的记忆系统,必须有遗忘机制。这不是可选项,是必需项。原因很简单:记忆的价值随时间衰减,而噪声永远在累积。
我的遗忘策略分三级。第一级是降权:长期未被访问的记忆,score自然衰减,检索时排到后面,等于软性遗忘。第二级是归档:超过一定时间(比如 90 天)且access_count低于阈值的记忆,status置为archived,不再参与常规检索,但保留可查。第三级是物理删除:归档超过一定时间(比如 180 天)的,直接删掉。
这套机制跑起来之后,记忆库的总量会稳定在一个合理区间,而不是无限膨胀。我实测过一个个人使用场景,跑了半年,活跃记忆稳定在 300 条左右,检索响应一直在毫秒级。
提示:遗忘策略的参数(90 天、180 天这些)一定要可配置。不同场景差异很大,工作项目相关的记忆可能三个月就过时,但个人偏好类记忆可能一年都有效。别写死。
5. 一套可落地的最小实现方案
5.1 目录结构与核心模块
讲了这么多原理,落到代码上,一个最小可用的claude-mem大概需要这几个模块:
claude-mem/ ├── store/ # 记忆存储层 │ ├── memory.json # 记忆数据(起步阶段用文件) │ └── store.py # 读写、去重、冲突处理 ├── extract/ # 记忆抽取 │ └── extractor.py # 会话摘要 + 事实抽取 ├── retrieve/ # 检索 │ └── retriever.py # 关键词 + 向量混合检索 ├── inject/ # 注入 │ └── injector.py # 格式化 + 拼接到 prompt └── config.yaml # 阈值、衰减系数等配置这个结构的好处是职责清晰。存储层只管数据,抽取层只管从对话里挖信息,检索层只管找,注入层只管拼。每一层都可以单独测试、单独替换。比如你后面想把文件存储换成向量库,只需要改store和retrieve,其他层不动。
5.2 关键参数配置与调优
配置项我列几个最关键的,这些值都是我实际调过的起点,你可以在此基础上微调:
memory: dedup_threshold: 0.85 # 去重相似度阈值 conflict_confidence_gap: 0.3 # 冲突时置信度差超过此值则不自动覆盖 inject: max_semantic: 20 # 最多注入语义记忆条数 max_episodic: 5 # 最多注入情景记忆条数 min_confidence: 0.7 # 注入的最低置信度 decay: lambda_semantic: 0.01 # 语义记忆衰减系数 lambda_episodic: 0.03 # 情景记忆衰减系数 forget: archive_days: 90 # 归档阈值 delete_days: 180 # 删除阈值 min_access_count: 2 # 归档前最低访问次数调参的优先级我建议是:先调inject那组,因为它直接影响你每次对话的体验;再调dedup_threshold,控制记忆增长速度;最后调decay和forget,这两个是长期维护用的,短期看不出效果。
5.3 实测中的几个坑
第一个坑是抽取过度。模型很容易把一些临时性的、一次性的信息也当成稳定事实抽出来,比如"用户这次想用 Python 写个脚本",这明显是临时的,但模型可能抽成"用户偏好 Python"。解决办法是在抽取 prompt 里明确区分"临时意图"和"稳定偏好",并且给临时信息一个低置信度。
第二个坑是检索空转。新会话刚开始,用户还没说什么,检索没有有效输入,这时候如果强行检索,会召回一堆不相关的记忆。我的做法是首轮不注入情景记忆,只注入语义记忆(因为语义记忆是"用户是谁",跟当前话题无关也应该带上),等对话进行到第二轮再开始检索情景记忆。
第三个坑是注入顺序。我一开始把记忆放在 system prompt 最前面,结果模型经常把记忆当成当前任务的一部分。后来改成放在 system prompt 末尾、用户输入之前,并且用明确的分隔标记,模型的理解就准确多了。这个顺序问题很微妙,但实测差异明显。
6. 记忆系统的边界:它做不到什么
聊了这么多能做的,也得说清楚它做不到什么,免得你抱有不切实际的期待。
第一,记忆系统不能替代模型的理解能力。它只是把相关信息送到模型面前,至于模型能不能正确使用,取决于模型本身。你可能会遇到记忆明明注入了,模型还是答非所问的情况,这时候要检查的是注入格式和指令,而不是记忆本身。
第二,记忆的准确性有上限。抽取和检索都是概率性的,不可能 100% 准确。所以系统设计上必须容忍错误,靠置信度、去重、冲突处理这些机制把错误的影响降到最低,而不是追求零错误。
第三,跨用户隔离是个硬要求。如果你做的是多用户系统,记忆必须严格按用户隔离,检索时带上用户 ID 过滤。这一点没有任何妥协余地,一旦串了,就是严重的数据问题。
第四,记忆不等于个性化。很多人以为有了记忆,AI 就"懂我"了。实际上记忆只是让 AI 知道了一些事实,真正的个性化还需要在 prompt 层面做风格适配、在交互层面做反馈学习。记忆是基础,不是全部。
我在实际使用中最大的体会是:记忆系统的价值不在于"记住多少",而在于"在对的时候想起对的那一条"。一个只有 50 条精炼记忆、但每次都能精准召回的系统,远胜过一个存了 5000 条、每次召回一堆噪声的系统。所以如果你要动手做,先把抽取和检索这两件事做扎实,存储量反而是最后才需要考虑的。
最后分享一个小技巧:给记忆系统加一个"手动干预"入口。允许你自己查看、编辑、删除记忆。这不仅是兜底手段,更是你理解系统行为的最好方式——当你发现某条记忆总是被错误召回时,手动改一次,比调半天参数来得快。