claude-mem 实战：构建 AI 持久化记忆系统，解决大模型无状态痛点

1. 从"记忆"这个痛点说起：claude-mem 到底想解决什么问题

做 AI 应用开发的人，大概都经历过这样一种尴尬：你精心调教了一个对话助手，跟它聊了半小时，把项目背景、代码规范、业务约束都交代得清清楚楚，结果关掉窗口再开一个新会话，它就像失忆了一样，一切从头问起。这不是模型笨，而是大语言模型本身是无状态的——每次请求都是一次独立的推理，它不记得你上一句说过什么，更不记得你三天前交代过的偏好。

claude-mem这个项目，从名字就能看出它的野心：给 Claude 这类对话模型装上一套持久化记忆系统。它不是简单地往 prompt 里塞历史记录，而是要做一套有结构、可检索、能进化的记忆层。说白了，就是让 AI 助手从"每次都是陌生人"变成"越用越懂你的老搭档"。

我最初关注这个方向，是因为在实际项目里踩过一个很典型的坑：我们做了一个内部知识问答助手，用户反馈最多的问题不是"答得不准"，而是"它老是忘"。用户上周刚纠正过一个术语的用法，这周再问，它又用回了错误的理解。这种体验上的割裂感，比偶尔答错更让人抓狂。claude-mem这类项目的价值，就在于把"记忆"从一次性的上下文窗口里解放出来，变成一个可以跨会话、跨时间累积的独立模块。

这篇文章适合三类人看：一是正在做 AI 应用、被上下文管理折磨的开发者；二是对 RAG、向量检索有一定了解，想看看记忆系统怎么落地的人；三是纯粹好奇"AI 记忆"这件事到底怎么实现的技术爱好者。我会从整体设计思路讲到具体实现细节，把参数选择、踩坑经验、排查方法都摊开来说，尽量让你看完能自己动手搭一个能用的版本。

2. 整体设计思路：为什么不能只靠"把历史塞进 prompt"

2.1 上下文窗口不是记忆，这是两码事

很多人第一反应是：记忆嘛，把历史对话都拼进 prompt 不就行了？这个思路在小规模下能用，但很快就会撞墙。原因有三层。

第一层是物理限制。哪怕模型支持很长的上下文，token 也是要花钱的，而且越长越贵、越慢。你不可能把用户三个月的对话历史每次都完整塞进去，成本会失控。

第二层是信噪比问题。历史对话里大量内容是寒暄、重复、无关紧要的确认，真正有价值的"记忆点"可能只占百分之几。全塞进去，反而稀释了关键信息，模型更容易被无关内容带偏。

第三层是结构缺失。原始对话是线性的、流水账式的，而真正的记忆应该是有结构的——"用户偏好 X"、"项目约束是 Y"、"上次讨论到 Z 还没结论"。这些是需要提炼和组织的，不是简单堆砌。

claude-mem的设计思路，本质上是在做记忆的抽取、存储、检索、注入这条完整链路。它把"记住什么"和"怎么用"拆开，让记忆成为一个独立于单次对话的持久层。

2.2 记忆系统的四层架构

我理解的claude-mem这类系统，核心可以拆成四层，这个分层方式是我自己在实践中总结的，跟项目本身的模块划分基本能对上：

这四层里，最容易做砸的是抽取层和检索层。抽取做不好，存进去的全是垃圾，后面检索再准也没用；检索做不好，明明存了有用信息却召不回来，等于白存。存储和注入相对标准化，但注入时的 token 预算控制是个细活，后面会专门讲。

2.3 为什么选择"向量 + 结构化"混合存储

纯向量检索有个天然缺陷：它对精确匹配不敏感。比如用户说"我的项目叫 ProjectX"，向量检索可能召回一堆语义相近但项目名不同的记忆。而纯结构化存储又太死板，没法处理"语义相似但表述不同"的查询。

claude-mem这类项目普遍采用混合方案：向量库存语义记忆，结构化库存事实型记忆。语义记忆比如"用户倾向于用简洁的回答"，事实记忆比如"用户的项目使用 Python 3.11"。前者靠向量相似度召回，后者靠精确字段过滤。这个组合是我实测下来最稳的，单一方案都会在某个场景下翻车。

3. 核心细节解析：记忆抽取与存储的实操要点

3.1 什么该记、什么不该记：抽取策略

记忆抽取的第一个难题是判断标准。我的经验是，值得记住的信息通常符合这几个特征之一：跨会话仍然成立（比如用户偏好、项目约束）、被明确强调过（用户说"记住这个"）、反复出现（多次提到的概念）。而一次性的、临时的、寒暄性的内容，直接丢弃。

具体实现上，常见做法是让模型对每轮对话打一个"记忆价值分"，比如 0 到 1 之间。低于阈值的直接不存。这个阈值我建议设在 0.6 左右，太低会存一堆噪音，太高会漏掉有用信息。这个数字不是拍脑袋来的——我做过一轮对比测试，0.5 时噪音明显增多，0.7 时开始漏掉一些用户明确表达但表述平淡的偏好，0.6 是个相对平衡的点。

抽取的 prompt 设计也有讲究。不要问模型"这段对话重要吗"，太开放了。要问得更具体，比如"这段对话中是否包含用户的长期偏好、项目约束、或明确要求记住的信息？如果有，请提取成一句话"。约束越明确，抽取质量越稳定。

注意：抽取环节一定要做去重。用户可能在不同会话里反复提到同一个偏好，如果每次都存一条，检索时会召回一堆重复内容，浪费 token 还干扰判断。去重可以基于向量相似度，相似度超过 0.9 的视为同一条，更新而非新增。

3.2 记忆的存储结构设计

存储结构决定了后面检索的上限。我推荐的结构是这样的，每条记忆至少包含这几个字段：

• content：记忆正文，一句话或一小段
• embedding：向量表示，用于语义检索
• type：记忆类型，如 preference、fact、context
• created_at：创建时间，用于时间衰减
• last_accessed：最后被召回的时间，用于热度排序
• access_count：被召回次数，高频记忆权重更高
• source_session：来源会话 ID，便于追溯

type字段特别有用。检索时可以根据当前问题类型，优先召回对应类型的记忆。比如用户问"我之前说过什么偏好"，就优先召回 preference 类型；问"项目背景是什么"，就优先 fact 和 context。

时间衰减这块，我踩过坑。一开始没做衰减，结果半年前的一条临时记忆一直排在前面，干扰了当前判断。后来加了衰减因子，公式大概是score = similarity * exp(-λ * days_since_created)，λ 取 0.01 左右，意味着大约 70 天后权重衰减到一半。但要注意，事实型记忆不应该衰减，比如"用户的项目用 Python"，这个不会因为时间久了就失效。所以衰减只对 context 类型生效，preference 和 fact 保持权重。

3.3 向量库选型的取舍

向量库的选择上，小规模场景我建议直接用轻量方案，别一上来就上重型分布式库。原因很简单：记忆系统的数据量通常不大，一个用户几千条记忆顶天了，用重型库是杀鸡用牛刀，运维成本还高。

常见的选择有这么几类：本地文件型（适合原型验证）、嵌入式库（适合单机部署）、服务型（适合多用户并发）。我个人的经验是，原型阶段用本地文件型快速跑通，验证逻辑没问题后再迁移到嵌入式库。迁移成本主要在 embedding 的重新生成，如果一开始就把 embedding 逻辑封装好，迁移其实很快。

维度选择上，主流 embedding 模型输出 768 或 1536 维。维度越高表达力越强但存储和检索成本越高。1536 维在记忆场景下是够用的，没必要追求更高。我实测过 768 和 1536 的召回效果，在记忆这种短文本场景下差异不大，768 反而更快。

4. 检索与注入：让记忆真正"用得上"

4.1 混合检索的排序策略

检索层是整个系统里最考验工程能力的地方。纯语义检索的问题前面说了，对精确匹配不敏感。我的做法是三路召回 + 加权融合：

第一路是向量相似度召回，负责语义相近的记忆。第二路是关键词召回，负责精确匹配（比如项目名、专有名词）。第三路是热度召回，把 access_count 高的记忆也捞出来，防止重要但语义不匹配的记忆被漏掉。

三路结果合并后，用一个加权公式排序：

final_score = w1 * vector_sim + w2 * keyword_match + w3 * heat_score - w4 * time_decay

权重怎么定？我的经验值是 w1=0.5、w2=0.3、w3=0.15、w4=0.05。这个比例是我反复调出来的，向量为主、关键词为辅、热度做补充、时间做微调。当然具体场景要微调，比如专有名词多的场景，w2 可以提到 0.4。

提示：检索时一定要设相似度下限。低于某个阈值的记忆，宁可不召回也不要硬塞。我一般设 0.7，低于这个值的召回基本是噪音。宁可让模型说"我不记得相关的事"，也不要给它错误的记忆。

4.2 Token 预算控制：注入环节的精细活

召回了一堆记忆，怎么塞进 prompt 是个技术活。塞太多，挤占正常对话空间还费钱；塞太少，记忆用不上。我的做法是给记忆分配一个固定 token 预算，比如总上下文的 20%，然后按 final_score 从高到低填充，填满为止。

填充时还要做格式压缩。原始记忆可能是完整句子，注入时可以压缩成更紧凑的形式。比如"用户偏好使用简洁的回答，不喜欢冗长的解释"可以压缩成"偏好：简洁回答"。这样同样的 token 能塞更多条记忆。

另外，注入的位置也有讲究。我习惯把记忆放在 system prompt 之后、用户问题之前，用明确的分隔标记包起来，比如：

[相关记忆] - 偏好：简洁回答 - 项目：使用 Python 3.11 - 约束：输出必须是 JSON 格式 [记忆结束]

这样模型能清楚区分哪些是记忆、哪些是当前对话，不容易混淆。

4.3 记忆的更新与遗忘机制

记忆系统不能只增不减，否则会越来越臃肿。需要一套更新和遗忘机制。

更新方面，当新记忆和旧记忆语义相似度很高时，不要新增，而是合并或覆盖。比如用户之前说"喜欢简洁回答"，后来说"回答要短一点"，这两条应该合并成一条，而不是并存。

遗忘方面，除了前面说的时间衰减，还要有主动清理。长期未被召回（比如 90 天没被 access 过）且 access_count 很低的记忆，可以归档或删除。但删除要谨慎，我建议先归档，观察一段时间确认没影响再真删。

这里有个容易忽略的点：记忆冲突的处理。用户可能前后说法不一致，比如先说"用 Python"，后来说"改用 Go 了"。这时候不能两条都留着，否则检索时模型会困惑。我的做法是，检测到冲突时，新记忆覆盖旧记忆，但保留旧记忆的归档记录，便于追溯。

5. 实操过程：从零搭一个可用的记忆系统

5.1 环境准备与依赖安装

先把基础环境搭起来。我用的技术栈是 Python + 一个轻量向量库 + 一个本地结构化存储。这套组合的好处是依赖少、启动快、便于调试。

pip install numpy openai tiktoken

向量库我选的是本地文件型方案，不需要额外服务。结构化存储直接用 SQLite，零配置。embedding 用现成的 API 或者本地模型都行，原型阶段用 API 更快。

环境变量里配好 API key 和模型名。这里提醒一句，embedding 模型和对话模型要分开配置，别混用。embedding 用专门的 embedding 模型，对话用对话模型，各司其职。

5.2 记忆抽取模块的实现

抽取模块的核心是一个函数：输入一轮对话，输出值得记住的记忆列表。我把它拆成两步：先判断有没有值得记的，再提取具体内容。

def extract_memories(conversation_turn): prompt = f""" 分析以下对话，判断是否包含值得长期记住的信息。 值得记住的信息包括：用户偏好、项目约束、明确要求记住的内容。 如果有，提取成简洁的一句话，并标注类型（preference/fact/context）。 如果没有，返回空列表。 对话内容： {conversation_turn} 以 JSON 格式返回：[{{"content": "...", "type": "..."}}] """ result = call_llm(prompt) return parse_json(result)

这个 prompt 我调了好几版。早期版本太开放，模型什么都往记忆里塞。后来加了明确的类型定义和"如果没有就返回空"的指令，抽取质量明显提升。

抽取后要做去重检查。把新记忆的 embedding 和已有记忆比对，相似度超过 0.9 的走更新逻辑，否则新增。

5.3 存储与索引的落地

存储层我用 SQLite 存结构化字段，向量单独存成文件。每次新增记忆时，同时写两处，保证一致。

def store_memory(content, mem_type, embedding): # 写结构化存储 cursor.execute( "INSERT INTO memories (content, type, created_at, access_count) VALUES (?, ?, ?, 0)", (content, mem_type, now()) ) mem_id = cursor.lastrowid # 写向量索引 vector_store.add(mem_id, embedding) conn.commit()

这里有个细节：写入要保证原子性。如果结构化存储写成功但向量索引写失败，就会出现数据不一致。我的做法是先写结构化存储拿到 ID，再写向量索引，如果向量写失败就回滚结构化存储。虽然 SQLite 和文件向量库没法真正事务化，但通过这种补偿逻辑能保证最终一致。

5.4 检索与注入的完整流程

检索流程是这样的：用户提问后，先把问题转成 embedding，然后三路召回，融合排序，取 top-k，最后按 token 预算注入。

def retrieve_and_inject(query, token_budget=500): query_emb = embed(query) # 三路召回 vector_hits = vector_store.search(query_emb, top_k=20) keyword_hits = keyword_search(query, top_k=10) heat_hits = get_high_heat_memories(top_k=5) # 融合排序 merged = merge_and_rank(vector_hits, keyword_hits, heat_hits) # 按预算填充 selected = [] used_tokens = 0 for mem in merged: mem_tokens = count_tokens(mem.content) if used_tokens + mem_tokens > token_budget: break selected.append(mem) used_tokens += mem_tokens update_access(mem.id) # 更新访问记录 return format_memories(selected)

update_access这步别漏了，它负责更新 access_count 和 last_accessed，是热度排序和时间衰减的数据来源。我一开始忘了加，结果热度排序一直是空的，排查了半天才发现。

5.5 参数调优的实测记录

参数调优这块，我记录了一组实测数据，供参考。测试场景是 500 条记忆、100 次查询，看召回准确率。

从数据看，相似度下限 0.7、token 预算 500 是个不错的起点。当然这跟具体数据分布有关，建议你自己跑一遍再定。

6. 常见问题与排查技巧实录

6.1 记忆召不回：先查这三处

"明明存了却召不回"是最常见的问题。排查顺序我总结成三步：先查 embedding 是否正常生成（有时候 API 报错但被吞了，存进去的是空向量）；再查相似度阈值是否设太高（临时调低到 0.5 试试能不能召回）；最后查查询语句本身（用户问"我之前说的那个偏好"，这种指代性查询本身语义就模糊，召回效果差是正常的）。

如果是指代性查询的问题，可以在检索前先做一次查询改写，把"我之前说的那个偏好"改写成"用户的偏好设置"，再检索，效果会好很多。

6.2 记忆污染：错误信息被反复召回

比召不回更麻烦的是召回了错误记忆。一旦错误信息进了记忆库，每次检索都可能被召回，污染模型输出。排查方法是看 access_count，如果某条记忆被高频召回但用户反馈不对，基本就是它了。

处理方式是软删除 + 黑名单。不要直接物理删除，先标记为失效，同时把它的 embedding 加入黑名单，检索时过滤掉。观察一段时间确认没问题再真删。我踩过一次坑，直接删了一条记忆，结果发现它是另一条正确记忆的合并来源，删了之后正确记忆也不完整了。所以删除一定要谨慎。

6.3 性能问题：检索变慢怎么办

记忆条数上去之后，检索会变慢。主要瓶颈在向量检索。优化方向有几个：一是给向量库建索引（很多库支持近似最近邻索引，能大幅提速）；二是做分层检索，先用粗粒度过滤缩小范围，再精排；三是控制单用户记忆总量，超过阈值就触发归档。

我实测下来，建索引的提速最明显，万级数据下能从几百毫秒降到几十毫秒。分层检索适合更大规模，但实现复杂度高，小规模没必要。

6.4 常见问题速查表

实操心得：记忆系统上线后，一定要加监控。记录每次检索召回了哪些记忆、模型是否用上了、用户是否满意。这些数据是后续调优的依据。我一开始没做监控，调参全靠猜，效率极低。后来加了日志，才发现很多问题出在抽取环节而不是检索环节。

7. 记忆系统的扩展方向与个人体会

claude-mem这类项目跑通基础版本后，还有不少可以深挖的方向。比如记忆的层级化，把记忆分成短期、长期、永久三层，不同层级用不同的衰减策略。再比如记忆的主动推理，不只是被动召回，还能根据当前对话主动推断"用户可能需要这条记忆"，提前注入。

还有一个我觉得很有价值的方向是多用户记忆隔离与共享。团队场景下，有些记忆是个人偏好，有些是团队共识，需要区分对待。个人记忆隔离，团队记忆共享，这个在协作工具里会很有用。

我自己在实际操作中的体会是，记忆系统的难点从来不在技术实现，而在判断标准——什么该记、什么该忘、什么该合并。这些判断没有标准答案，只能靠不断观察和调整。技术框架搭起来可能就几天，但把记忆质量调到一个稳定可用的水平，往往需要几周的迭代。所以别指望一次做完美，先跑起来，再慢慢磨。

最后分享一个小技巧：初期可以加一个人工审核开关，所有抽取的记忆先进入待审核队列，人工确认后再入库。等抽取质量稳定了再关掉。这个开关能帮你快速发现抽取环节的系统性问题，比事后排查高效得多。