为Claude装上长期记忆：claude-mem方案从原理到代码落地

写AI应用的人都有个绕不开的坎：对话一长，模型就“失忆”。前面聊的用户偏好、项目背景、技术选型，过了几轮之后它全忘光了，你只能一遍又一遍把上下文塞回提示词里，token成本越来越高，效果却越来越差。我在给一个内部客服机器人做多轮优化时，被这个问题折磨了很久，最后整理出来一套围绕Claude的长期记忆方案，也就是圈子里常说的 claude-mem 思路。这篇文章就是这套方案的完整拆解，从设计原理到代码落地，再到我踩过的坑，一次性讲清楚。适合正在做AI助手、Agent工作流，或者被上下文长度和成本搞得头疼的开发者参考。

1. claude-mem是什么：一个给Claude装“长期记忆”的实践方案

1.1 先搞清楚：Claude本身有没有记忆

很多第一次接触这个问题的同学，会下意识问一句：Claude不是自带记忆吗？答案很明确：不带。准确地说，Claude模型的每一次调用都是无状态的，它不记得你上一轮说过什么，也不知道这一轮和你对话的是谁。它唯一能看到的内容，就是你这次请求里携带的整个上下文。

所以在官方API里，多轮对话的实现方式就是反复把历史消息拼接起来，连同新的用户输入一起发给模型。这种机制下，记忆的表象是存在的，但本质上它只是一次性副本：上一轮的聊天记录作为文本被塞进了本轮请求，一旦请求结束，这段文本就被丢弃了。换句话说，Claude的“记忆”是临时的，是每次调用时你手动提供给它的一个现场快照。

这个设计带来的直接后果就是：上下文长度受限于模型窗口，成本随着历史长度线性上涨。Claude 3.5/3.7这类模型虽然有长窗口，但窗口不等于记忆，窗口只是给你暂时摆放信息的地方，你怎么把关键信息从一堆历史里挑出来、存下来，下次再用，这才是记忆层要做的事。

1.2 claude-mem要解决的四个典型痛点

我说几个场景，大家看看是不是似曾相识。

第一个是客服场景。用户第一轮说“我是Plus会员，上个月账单有问题”，第五轮可能就变成“我刚才不是说过了吗，我是Plus会员啊”。模型不是不想记，而是历史消息里信息太多，或者你根本没有把那个关键信息放到当前上下文里，它就是想用也没得用。

第二个是内容创作辅助。用户告诉AI自己偏好某种文风、某个行业术语规范，多轮修改后AI风格漂移了，因为每位用户的偏好散落在十几轮对话里，模型根本抓不住重点。

第三个是Agent任务场景。Agent在执行多步任务时，中间结果、已经完成的状态、还没执行的计划，这些都需要跨步骤保留。如果你每步都重新从完整历史里取，token会爆炸，而且容易互相干扰。

第四个是数据隐私和成本控制。有些对话内容涉及个人敏感信息，你其实不想每次都把整段历史发过去，只需要提取必要信息、用完即丢即可。这也是记忆层的一个隐藏价值：信息收窄之后，暴露面反而更小。

claude-mem要做的，就是把“对话历史”升级为“可长期复用的记忆资产”。它不仅仅是存字符串，而是从对话里提炼出事实、偏好、状态、约束，再用结构化方式存进外部存储，在需要时精准召回。

1.3 核心能力拆解：一次调用变成一个记忆闭环

我来画一下这个闭环，实际项目里每个环节都要有对应的实现：

• 对话发生：用户和Claude进行一轮或多轮交互，产生原始文本流。
• 记忆提取：异步调用Claude，用专门的提示词把本轮对话里的“可记忆信息”提取出来，比如用户姓名、偏好、决定、未完成事项。
• 记忆写入：提取结果经过清洗和结构化，写入向量数据库，同时保留一个可读的文本记录。
• 记忆检索：下一轮对话开始前，系统拿着当前用户问题去向量库做相似度检索，找回相关记忆片段。
• 上下文重组：把检索到的记忆、最近的少量对话、系统提示词一起拼成当前请求的上下文，发给Claude。
• 记忆更新：新对话产生新信息后，覆盖或追加旧记忆。

这个闭环跑起来之后，Claude表面上还是无状态的，但你的应用层已经拥有了跨会话、跨会话组的长期记忆能力。用户下个月再来，它依然能记得人家的姓名、偏好和上次聊到一半的事项。

2. 记忆机制的设计逻辑：为什么不能简单拼接历史消息

2.1 从token成本说起

最简单粗暴的方案，是把所有历史消息永远塞给Claude。在对话量小的时候没问题，但一涨起来就顶不住了。我给你们算笔账：假设一条消息平均200 token，一次咨询大概20轮，那么一次调用光历史就有4000 token。每轮都这么做，一次完整咨询累计消耗差不多8万token。到了第21轮，你发的历史还是4000 token，但前面20轮已经被你烧掉了。如果做的是长期助手，用户聊了一百轮，你还把一百轮全带上，一次请求可能直接打爆窗口，费用更是直线上升。

关键还不只是成本。历史越长，模型对最近话题的注意力就越分散。相关论文和实测都指向一个结论：中间位置的信息容易被模型忽略。你把一条关键信息埋在90轮的日志里，还不如单独把它拎出来放在系统提示词里来得管用。所以记忆层的核心价值，不是备份历史，而是把历史里的高价值信息提取成精炼摘要，按需发放。

2.2 记忆分层的思路：短期、工作、长期

我落地时参考了认知科学里常见的三级记忆模型，对应到工程上非常顺。

短期记忆就是最近几轮对话的原文，一般保持在窗口内不用额外操作，最多做个滑动截断。工作记忆是当前任务进行中的状态数据，比如Agent已经执行到第几步、当前待确认参数，这些需要跨几个步骤有效。长期记忆是跨会话保留的稳定信息，比如用户身份偏好、项目背景、长期目标。

三种记忆的存储方式不同：短期直接用内存或Redis，过期即弃；工作记忆用结构化的JSON存状态，任务结束就归档；长期记忆进向量库，做去重和覆盖。这种分层的核心好处，是把成本花在真正重要的事情上：不是为了记住而记住，而是为了下一次决策更准而记住。

2.3 关键技术选型：向量库加混合检索

长期记忆的检索，我只靠关键词匹配是远远不够的。用户的表述每次都不一样，第一轮说“我习惯喝冰美式”，第五轮说“老规矩”，这种语义关联靠关键词根本抓不到，此时向量的优势就体现出来了。把记忆片段用嵌入模型转成向量，用户新问题也转成向量，算一下余弦相似度，语义相近的老记忆就被捞回来了。

但我用到中期发现，纯向量检索也有翻车时刻。比如用户说“帮我改回之前的风格”，向量检索可能返回一堆关于风格泛泛而谈的旧记忆，却漏掉了那条“第二版用了活泼风格”这种精确事实。所以后来我改成了混合检索：向量召回候选集，再用关键词过滤精排，或者用BM25和向量分数做一个加权融合。这样做的好处是，语义匹配负责“找得着”，关键词匹配负责“找得准”。

存储选型上，小项目用Chroma、LanceDB这类轻量库就够了，不用专门搭服务。规模上去以后，再考虑pgvector或Qdrant。我自己的经验是，前期别在基础设施上过度设计，先让流程跑通，再按真实数据量升级。

2.4 记忆写入策略：什么时候记、记什么

比存储更重要的是“记什么”。这是claude-mem这类方案里最容易被低估的部分。很多初学者会把整个对话原文塞进记忆库，结果检索出来的全是废话。记忆写入需要设置一道筛选逻辑，让Claude提取下面这几类信息：

• 用户明确陈述的个人信息：姓名、职业、所在城市、联系方式。
• 偏好与习惯：喜欢的语气、常用的工具、对某个方案的态度。
• 正在进行的事项：答应过要做的事、未完成的请求、待确认的选项。
• 关键决策与结论：选定某个技术栈、确定截止时间、否掉某个方案并说明理由。

提取用Claude来做最合适，因为直接写正则和规则根本扛不住人类的自由表达。我的做法是准备一段提取提示词，要求模型输出JSON结构：`{memory_type, content, importance, timestamp}``。importance字段很重要，它决定了这条记忆后续检索时的权重。高重要度的比如“用户明确要求不用Java”，低重要度的比如“用户随口提了一句今天热”，可以更快被淘汰。

写入频率也要控制，不能每条消息都写，否则记忆库全是噪声。我实践下来是每轮对话结束时提取一次，且只有当提取结果与已有记忆的相似度低于阈值时才写入，相似度高的就走覆盖或跳过。

3. 从零搭建：完整实操流程

3.1 准备工作与依赖

我下面给出一套完整可复现的搭建流程，基于Python生态，用到的是市面上比较主流的轻量组件。整个方案可以跑在本地，不必依赖重型服务。

需要准备的组件清单如下：

• anthropicPython SDK，用于调用Claude。
• 一个嵌入模型，我用的是text-embedding-3-small，也可以换成其他兼容OpenAI格式的嵌入服务，或者开源模型。
• 向量库，我用LanceDB，因为它是嵌入式、零配置，对小型项目非常友好。
• 一个内存存储用于短期会话，直接用redis或者干脆用Python字典先顶着。
• pydantic做记忆结构的校验。

安装依赖的命令很简单，我直接放在这里：

pip install anthropic lancedb openai pydantic

注意openai库这一步只是为了复用它的Embedding接口，如果你用的嵌入服务也走OpenAI兼容格式，可以统一用一个客户端。

3.2 记忆提取的实现与参数选择

记忆提取是整个方案里门槛最高的一步。我调试了很多版提示词，最终稳定运行的是下面这个结构：

extract_prompt = """你是一个记忆提取器。请从用户与AI助手的对话中，提取出值得长期保存的信息。 判断标准： 1. 用户明确陈述的个人信息（姓名、职业、联系方式等） 2. 偏好与习惯（语气、工具、方案倾向） 3. 正在进行的事项（未完成的请求、承诺过的事情） 4. 关键决策与结论（选型、截止时间、否决项） 要求： - 忽略寒暄、临时情绪、无关闲聊 - 如果某条信息与已有记忆重复，不要输出 - 输出JSON列表，字段为 memory_type, content, importance(1-5), timestamp 对话内容： {conversation} 已有记忆： {existing_memories} 只输出JSON，不要解释。 """

这里有一个关键参数：提取时要不要带上已有记忆。我在实测定中发现，不带已有记忆容易产生大量重复写入，带了已有记忆可以大幅减少冗余，但同时也会增加输入token。所以我做了一个折中：提取时只带上与当前对话最相关的前5条已有记忆，用一个轻量向量检索先查出来，再拼进提取提示词里。

温度参数也要注意，提取任务属于信息抽取，温度我设置在0到0.2之间，温度太高模型会自由发挥，输出结构不稳定，温度设0时输出质量最稳。importance字段的约束我写进提示词，并且在后处理时做规则兜底：包含“绝对”“必须”“不要”“禁止”这类强约束词的，强制把importance提到4以上。

3.3 向量存储与检索的代码骨架

写入方面，我定义了一个简单的记忆数据类，然后直接落进LanceDB：

import lancedb import pyarrow as pa db = lancedb.connect("./memory_db") table = db.open_table("memories") def write_memory(memory: dict, embedding: list): data = [{ "content": memory["content"], "memory_type": memory["memory_type"], "importance": memory["importance"], "timestamp": memory["timestamp"], "vector": embedding, }] table.add(data)

检索方面，当前用户问题先转成向量，然后做一次带过滤的查询：

def recall_memories(query: str, top_k: int = 5): query_vec = embed(query) results = table.search(query_vec).limit(top_k * 2).to_list() # 混合精排：把importance权重与向量相似度相乘 results.sort(key=lambda x: x["_distance"] * (1.5 / x["importance"])) return results[:top_k]

这个精排公式是我自己调出来的，核心思路是让高重要度记忆在距离差不多时优先被选中。你可以根据自己的数据调整权重系数。需要注意的是，LanceDB早期版本的search方法返回结果里的_distance字段，越小表示越相似，所以在排序时距离值乘以一个小于1的权重才会排到前面，这里用1.5/importance做调整就是让高importance记忆看似“距离更短”。

3.4 集成到Claude调用链：一个最小可运行示例

到这里，我把记忆层和Claude的主调用链拼起来。下面这个示例是一个带记忆的聊天函数：

import anthropic client = anthropic.Anthropic(api_key="your-api-key") system_prompt_base = "你是一个智能助手，请根据提供的记忆和对话上下文回答用户问题。" def chat_with_memory(user_message: str, session_id: str): # 1. 召回记忆 memories = recall_memories(user_message, top_k=5) memory_block = "\n".join(f"- {m['content']}" for m in memories) # 2. 组装系统提示词 full_system = system_prompt_base + f"\n\n## 用户已知信息\n{memory_block}" # 3. 取最近10轮短期历史（简化实现直接放列表里） history = get_short_term_history(session_id) # 返回openai-style消息列表 # 4. 调用Claude response = client.messages.create( model="claude-sonnet-4-0", max_tokens=1024, temperature=0.7, system=full_system, messages=history + [{"role": "user", "content": user_message}], ) # 5. 更新短期与长期记忆 append_short_term_history(session_id, user_message, response.content[0].text) extract_and_store_memory(history + [{"role": "user", "content": user_message}]) return response.content[0].text

这个最小闭环已经能跑通了。之后再考虑异步化、批量提取、去重等优化，核心链路保持不变。

4. 真实使用场景与效果分析

4.1 多轮长对话助手：从“复读机”到“记住你”

我第一个把claude-mem接进去的项目是一个内部知识库问答机器人。没接记忆层之前，用户问过的问题、点过的赞、表示过不感兴趣的内容，下一次全部归零。接完之后，体验提升最明显的地方在于：用户第二次进来说“之前那个方案我看了，有点问题”，机器人真的知道“那个方案”指的是什么。

实现逻辑并不复杂，就是把用户与机器人的交互历史全部走记忆提取流程，尤其是用户结尾留下的“建议”“意见”“待办”类内容，全部存入长期记忆。下一次同一会话组进来，系统自动召回与当前问题相关的旧结论，拼进提示词。效果上的直接体现，是用户不用再重复自己说过的话，满意度明显上升。

4.2 Agent工作流中的上下文持久化

Agent场景比纯对话更复杂，因为Agent内部会有多步工具调用，每一步都产生中间状态。如果把中间状态全部堆在上下文里，窗口迟早爆掉。我的做法是给Agent定义一个“工作记忆区域”，每一步执行后把关键状态更新到结构化JSON里，下一步只携带精简后的状态，不携带原始历史。

举个例子，一个做竞品调研的Agent，需要依次访问多个页面并汇总信息。每一步会产生一堆原始页面内容，这些不需要全量保留，真正要记住的是“已经访问了哪些页面”“各自的核心结论”“下一步准备访问谁”。这个状态我就走记忆层持久化，同时把原始页面文本丢进向量库备查。这样Agent执行一百步，每一步的上下文占用基本恒定，不会越跑越慢、越跑越贵。

4.3 与RAG方案的边界与配合

很多人会混淆claude-mem和RAG，这里我多写几句。RAG解决的是“外部知识怎么进入模型”的问题，它的素材通常是文档、手册、网页，是相对静态的知识库。claude-mem解决的是“用户状态与对话历史怎么复用”的问题，它的素材是动态产生的个性化交互记录。

两者在工程实现上有不少重叠，都用向量检索，都可能用到嵌入模型和向量库，但数据来源和更新频率完全不同。我在项目里把两者放在了一起：RAG提供公共知识，claude-mem提供用户个性化记忆，两者分别检索，再拼接进入上下文。打个比方，RAG是图书馆，记忆层是用户随手带进来的私人笔记本，Claude每次做决策之前，既查图书管也翻笔记本，回答自然更贴切。

5. 踩坑记录与常见问题排查

5.1 记忆污染：最隐蔽的坑

接入一周后，我开始发现模型出现了“张冠李戴”的现象，A用户的偏好跑到了B用户的回答里。查了半天，问题出在向量检索时我没有隔离用户维度。LanceDB的查询接口里有一个where过滤条件，可以按字段过滤，但我在初期没有把user_id作为过滤条件加进去。修复方式很简单：每次检索时强制加上user_id过滤。

table.search(query_vec).where(f"user_id = '{user_id}'", prefilter=True)

另外一类污染来自提取层本身。Claude提取信息时偶尔会脑补，用户没说过的事它也提取出来了。这需要你在后处理时加一道校验：只接受与原文高度重叠的内容，或者把提取提示词里加上“只提取用户原话里明确出现的信息”。我在实践中多次遇到模型把“用户可能喜欢简约风格”这种猜测性内容写成事实记忆，这类记忆一旦入库，后续每次都会被当成用户偏好来用，误导性很强。

5.2 检索质量差：语义匹配的边界

向量检索在纯语义场景表现不错，但碰到数字、型号、否定词就很容易翻车。用户说“不要Java”，你把这句话编码进向量库，下次用户问“有哪些后端语言适合我们”，模型可能召回了“不要Java”这条记忆，但只把它当成一条普通的备选信息，没有意识到这是一条否决性约束。

我的解法有两层。第一层是给记忆打标签，否决性内容单独建一个constraint类型，在检索时把这类记忆放在提示词的“用户明确禁忌”区域；第二层是关键词兜底，如果当前用户输入里出现技术名词，先做一轮精确匹配，把包含该名词的记忆置顶。这套组合下来，检索准确率提升非常明显。

5.3 写入性能瓶颈与异步化改造

早期版本里，记忆提取和Claude的主响应串行执行，用户每发一条消息，需要等待额外一次Claude调用才能返回。这个延迟加到主路径上，体感非常差。后来我把记忆提取全部改成了异步任务。

主对话只管生成回复，生成结束后把对话内容丢进一个消息队列，由后台worker去执行提取、嵌入、写入。用户感知不到记忆层的存在，只有数据最终一致性有一点延迟。线上验证下来，用户刚说完一句话马上发起下一句，偶尔会召回到不到刚说的内容，但绝大多数场景下，一两秒的延迟无伤大雅。如果你做的是强实时场景，可以把记忆提取改成定时批量，而不是每轮都触发。

5.4 常见问题速查表

我整理了一份速查表，都是实际排查过程中沉淀下来的经验：

还有一个不起眼但很实用的点：每周把importance低于某个阈值的记忆做一次清理，或者用一个大模型跑一次离线压缩，把几十条零星偏好合并成一条概括性记忆。这个操作能让记忆库的“信噪比”长期保持在健康区间。

最后说点个人体会。claude-mem这套方案，核心价值不在于它用了多先进的技术，而在于它把“模型无状态”这个限制通过工程手段绕了过去。我做完之后最大的感受是：记忆不是存得越多越好，而是要让模型在正确的时间，只看到最需要的那几条信息。这个度的把握，远比写几行调用代码更考验人。后续可以继续扩展的方向包括多模态记忆、记忆的自动遗忘机制、以及让用户直接编辑和删除自己的记忆条目，让记忆层真正变得透明、可控。