给Claude API装上长期记忆：claude-mem记忆增强层全解析

我刚开始把 Claude 接入自己的项目时，最折磨我的不是提示词写不好，而是它实实在在的“失忆”。同一个用户，同一个话题，隔天回来再问一次，它完全不记得之前聊过什么、确认过什么，甚至连用户偏好都要重新讲一遍。这种体验放在问答机器人上还能忍，一旦要做一个真正“陪伴式”的助手或者带上下文的业务系统，基本就是不可用的状态。后来我花了两周时间做了个记忆增强层，代号就叫 claude-mem，核心就一句话：给无状态的 Claude API 套上一层可持久化的记忆系统，让它在每次对话之前自动加载与当前话题相关的历史记忆。这篇文章把我从方案选型、架构设计、代码实现到参数调优的全过程都翻出来，踩过的坑也一并记录，适合正在做 AI 助手、客服机器人、个人知识助理，并且受够了“每次对话都从零开始”的开发者和产品负责人。

1. 先搞明白：为什么 Claude 需要额外加一层记忆

1.1 无状态 API 的“失忆”根源

用过 Claude API 的人都清楚，它本质上是无状态的。你每次调接口，传一组 messages 过去，模型基于这组 messages 生成回答，然后这个上下文就没了。服务器端不会替你保存任何会话历史，更不会在下次请求时自动“想起来”上次说过什么。这跟你在网页端跟 Claude 对话的感受完全不同，网页端有官方帮你维护会话，而 API 端把这个责任完全交给了开发者。

这个设计本身没有错，它让接口变得简单、可横向扩展，也方便做各种自定义。但它带来一个很现实的问题：所有需要“连续性”的场景——比如长期跟进的客服工单、跨多天的学习规划、需要记住用户偏好的内容推荐——开发者都得自己想办法把历史信息捎带上。刚开始我试过最简单粗暴的办法：把完整的对话历史拼成一个长长的 messages 数组，每次请求都整体发给 Claude。结果很快就稳定了，但代价也很快显现：对话超过十几轮，token 数量飞速上涨；话题一多，历史里无关的内容占大头，不仅费钱，模型的注意力也被干扰，回答质量反而下降。

所以做 claude-mem 的第一步，不是去“教”模型记住，而是在 API 和模型中间加一道闸门：只把真正相关的历史记忆挑出来，放到每次请求的上下文里。这道闸门既要会“写”，也就是把有价值的信息沉淀下来；又要会“读”，也就是在合适的时机把记忆精准地捞回来。

1.2 会话短记与长期记忆：为什么必须分开管理

刚开始做记忆的时候，我误以为把所有历史都做成“长期记忆”就行。后来发现这是个严重的误区。对话历史里其实有两类完全不同的信息：一类是当前会话内的上下文线索，比如用户刚才提到“我在上海出差”，这属于短时信息，五分钟之后可能就过期了；另一类是跨会话仍然成立的事实，比如“用户是产品经理，常用 MacBook，希望回复简洁”，这才是值得长期保存的东西。

如果混在一起存，要么长期记忆被大量过期的对话噪音污染，要么短期上下文被过度压缩导致当前话题丢失。所以我最后采用了分层结构：临时层保存最近几轮会话的完整消息，按会话 ID 隔离，超额就截断；持久层只保存提炼过的、带有语义索引的长期记忆，写入向量数据库。会话短记负责“上下文连贯”，长期记忆负责“人格一致”，两者职责清楚，效果才会稳。

2. claude-mem 的整体架构与工作链路

2.1 方案选型：为什么是向量检索而不是全量拼接或关键词搜索

对我来说，最需要想清楚的问题不是“要不要记忆”，而是“记忆怎么取”。早期的两个备选方案都被我否了。方案一是全量拼接，逻辑简单但 token 成本和噪声问题无解；方案二是用 SQL 按关键词搜索历史记录，实现不难，但召回效果很差，因为用户很少会用完全一致的关键词去重复提问。比如用户第一次说“帮我把周报格式改得清爽一点”，隔几天回来说“那个周报样式的事”，关键词搜索很难把这两段关联起来。

最后我选了向量检索。方法就是把每条记忆嵌入成一个高维向量，存入支持近似最近邻搜索的数据库。查询的时候，把用户当前的问题也嵌入成向量，从库里找出语义最相近的若干条记忆。这样即使表述完全不同，只要意思接近，就能被召回。我在测试里遇到过这样的场景：用户曾经说“每天上午九点提醒我站会”，两周后问“我的晨会提醒还在吗”，关键词搜索直接抓瞎，而向量检索能稳定地把那条记忆捞出来。这个差异，就是 claude-mem 值得做的基础。

2.2 核心链路：记忆写入、语义检索、上下文注入

claude-mem 的运行链路可以分为三个环节，所有记忆能力都围绕它们展开。第一个环节是写入。每次对话结束或者积累到一定轮数之后，系统会用一个小模型或者 Claude 自己，从对话中提取“值得长期记住的信息”，生成若干条结构化记忆，例如用户偏好、已确认事实、待办事项、项目决策，再加上时间戳、来源会话 ID 和情感倾向等元数据。每条记忆经过嵌入模型生成向量，写入向量数据库。

第二个环节是检索。在新请求进来时，把用户最近的一条消息或者整个当前上下文摘要做成查询向量，到记忆库里做相似度搜索。检索结果会经过一个过滤和重排的步骤，筛掉过期的、置信度低的和与当前意图冲突的记忆，保留最相关的 N 条。

第三个环节是注入。检索到的记忆会被拼装成一段固定的提示词模板，放进 system prompt 里，和原有的系统指令一起发给 Claude。这里的执行顺序是固定的：先取回记忆，再组装上下文，最后调用 API。三层各司其职，写入管沉淀，检索管召回，注入管使用。整个设计难度不大，但每一步都有细节，下面我逐个拆开讲。

2.3 embedding 模型与向量数据库怎么搭配

选型的时候，我对比过几组方案，最后选择的搭配是：本地用 bge-small-zh-v1.5 做嵌入，向量库用 Chroma，理由很简单——三件都是开源且部署体积小，适合个人项目和中小团队快速跑起来。如果你的应用完全面向英文或者多语言，也可以换 OpenAI 的 text-embedding-3-small，维度更低、语义能力更好，但需要付费调用。向量数据库方面，Chroma 适合单机、数据量在百万条以内的场景；如果预期会扩展到千万级或者需要高并发线上服务，Qdrant 或者 Milvus 会更可靠。记住一个核心原则：embedding 模型决定召回的天花板，向量数据库决定检索的性能下限。前期建议把精力花在 embedding 模型的选择和记忆文本的写法规整上，数据库用最简单能跑的就可以。

3. 手把手实现一个可用的 claude-mem

3.1 环境准备与基础依赖

这个项目我建议用 Python 来搭建，生态最顺手。基础依赖就四个：anthropic 官方 SDK 用来调用 Claude，chromadb 做向量库，sentence-transformers 加载本地 embedding 模型，另外加一个 pydantic 或 dataclass 做结构化记忆的数据模型。推荐在项目根目录建一个 venv，避免依赖污染。以下是可以直接用的安装命令：

pip install anthropic chromadb sentence-transformers

这里有个小提醒：sentence-transformers 首次加载模型时会在线下载权重，国内网络环境下极易失败。我踩过这个坑，建议用 huggingface-cli 预先下载 bge-small-zh-v1.5，然后通过本地路径加载，这样后面对外提供服务时才不会出现启动超时或卡在下载环节的问题。另外，Claude 的 API key 不要写死在代码里，用环境变量管理，比如放到项目目录下的 .env 文件中，并在 .gitignore 里忽略它。

3.2 记忆写入流程：从对话里提炼值得记住的信息

写入是三个环节里最容易做滥的一环。如果你把每句话都存下来，记忆库会迅速变成一个没法用的垃圾桶。我的做法是：让 Claude 自己充当“记忆提炼器”，每次对话达到三到五轮后，把刚才的对话记录丢给模型，让它按固定的 JSON 结构输出值得长期保存的信息。提示词模板我贴到这里，你可以直接参考：

MEMORY_EXTRACT_PROMPT = """ 你是记忆抽取引擎。请从下面的对话中提取值得长期记住的信息。 只提取满足以下条件的内容： 1. 用户的稳定偏好、身份或习惯 2. 已经确认的事实、决定或承诺 3. 后续还会被提及的任务、项目或目标 不要提取临时性、一次性或情绪化的表述。 请以 JSON array 格式输出，每个元素包含： - content: 简练的陈述句，主语明确 - category: preference / fact / task / decision - expires_at: 如果没有过期时间则置为 null 对话内容: {conversation_text} """

我实际使用中发现，这个抽取环节用 Claude 本身跑效果好于用小模型，因为它对“哪些值得留”的判断更接近人类。但代价是每次抽取会多花一些 token，所以我做了一个触发策略：只有当前会话累积超过三分钟、或者产生了超过五轮对话时，才执行抽取；同时每次抽取后把已处理的消息从临时缓冲区清掉，避免重复抽取同一段内容。

拿到 JSON 结果后，逐条写入 Chroma。每条记忆的 metadata 里一定要带三样东西：时间戳、会话 ID、抽取来源。时间戳用来做后来的时间衰减排序，会话 ID 用来追溯这条记忆的来历，来源则方便你排查“是不是抽取模型自己编出来的”。向量就是调用 embedding 模型对 content 字段编码的结果。整个写入函数大概长这样：

import chromadb from sentence_transformers import SentenceTransformer client = chromadb.PersistentClient(path="./claude_mem_store") col = client.get_or_create_collection("memories") encoder = SentenceTransformer("./models/bge-small-zh-v1.5") def write_memories(memories: list[dict], session_id: str): if not memories: return docs = [m["content"] for m in memories] vecs = encoder.encode(docs).tolist() ids = [f"mem_{session_id}_{i}" for i in range(len(memories))] metas = [{ "category": m["category"], "created_at": m.get("created_at", ""), "session_id": session_id } for m in memories] col.upsert(ids=ids, documents=docs, embeddings=vecs, metadatas=metas)

这里有一个容易忽略的点：如果你判断某条旧记忆已经被推翻，不能直接让它继续躺在记忆库里。一个是给新记忆写入同一条来源，另一个是把旧的 id 从集合里 delete 掉。我一开始偷懒只做新增，结果用户明明改了偏好，系统还在给用户推荐旧口味的咖啡，后来才加上冲突检测和旧记忆删除逻辑。

3.3 记忆检索与上下文注入：调用 API 前的关键两步

检索环节的核心问题是：拿什么去做查询向量？我最早拿“用户的最新消息”直接去查，效果不稳定，因为一条短消息的信息量不够。后来改成一个更实用的做法：把当前会话的最近几轮消息拼成一段短摘要，再用摘要去生成查询向量。这样语境更完整，召回的相关性明显提升。

检索参数我一般设置为返回 top_k = 8，相似度阈值 0.3 左右。阈值这个值不是拍脑袋定的，我用了一组历史对话标本进行测试，把“召回的相关性人工打分”作为标准，找出误召回和漏召回的交点，最终才确定。不同领域、不同 embedding 模型的阈值差异会很大，最好自己做一次标注测试，别直接抄别人的参数。检索之后把结果按 category 简单分组，优先展示 task 和 preference 类记忆，因为这两类对当前回答的影响最大。

注入环节我采用的模板固定如下，会放在 system prompt 的开头：

def build_system_prompt(base_system: str, memories: list[str]) -> str: memory_section = "\n".join(f"- {m}" for m in memories) return f"""{base_system} # 你对用户的长期记忆 以下信息来自历史对话，如果与当前对话相关，请自然地使用它们；如果无关，请忽略。不要主动提及“根据记忆”。相关确定性不够时，可以询问用户确认。 {memory_section} """

注意 prompt 里那句“如果无关请忽略”非常关键。没有这句话，模型会把记忆当成必须执行的任务，哪怕检索回来的记忆和当前话题无关，它也会硬生生扯进去，回答就显得莫名其妙。加了这句话之后，模型对记忆的使用就变得克制了许多。

3.4 关键参数配置参考表

这里把我调过一圈之后的推荐参数列出来，方便你做初始配置，但我建议每项都按自己的场景再微调一轮。

表格里我特别想强调记忆库最大条目这个参数。很多人一开始不做限制，越存越多，最后向量检索的速度慢下来，而且“新记忆和旧记忆撞车”的情况会越来越多。我后来给每个用户设置了独立集合，并定期把超过 30 天、category 为 preference 且被重复更新的旧条目归档，这样能有效控制库的规模。

4. 记忆质量优化：记住该记的，忘掉该忘的

4.1 记忆类型与提取质量的平衡

记忆系统里，提取质量直接决定整体体验。存多了，检索噪声大；存少了，跨会话的连续性做不起来。我在提取策略上做过多次迭代，最终把记忆分成五类，分别制定规则。第一类是用户画像，比如职业、城市、偏好，这类稳定性最高，几乎不会变，要完整保留。第二类是任务进度，比如“正在迁移公司官网到新服务器”，这类有时效性，任务完成后就要标记完成或删除。第三类是决策记录，比如“定价方案定了 199 元和 399 元两档”，这类需要精确，提取时尽量保留原文数字。第四类是临时偏好，比如“最近在戒糖”，这类可能随时变化，要打上低置信度标签。第五类是情绪和状态，比如“用户今天很焦虑”，这类我只保留当天会话内使用，绝不进入长期记忆，否则一旦过期，很可能会误导后续交互。

这里的取舍标准可以总结成一句话：如果一条信息在三天后仍然对这个用户有影响，才值得进入长期记忆；否则就留在短记层即可。

4.2 记忆冲突、过期与用户删除权

做记忆系统最怕的就是“记错了还坚持用”。我遇到过不少例子，用户在某次对话里说“周末去露营，所以这周不加班”，结果抽取模型把“不加班”当成一种长期工作习惯写进了偏好里，导致后续所有排期建议都变得很奇怪。发生这种问题以后，我给写入环节加了一道校验：抽取出的每条记忆，都要求模型给出 it 是从哪句原话推导出来的，并且用另一个校验调用对“这条信息是否具有长期性质”做二次判断。虽然多花了一点 token，但误写率明显下降了。另一个教训是删除权。用户一旦表示“我之前说的那个爱好现在没有了”，或者干脆要求“忘掉之前的所有内容”，记忆库必须能说清就清，不能只在逻辑上标记无效。我用了 Chroma 的集合删除接口，配合用户级 ID 做批量清理，实测效果很好，也避免了很多嘴上说改实际上还在用的尴尬。

4.3 安全隐私视角下的记忆最小化

做长期记忆天然会涉及用户隐私，这一点躲不开。我在设计 claude-mem 的时候就把安全原则定为“记忆最小化”：能少存就少存，能存匿名化的就绝不存明文。比如用户提到自己公司内部项目的名字，我会设置一个敏感词规则，记忆提取时把这个词替换成“[内部项目]”。比如涉及密码、token、身份证号这类信息，匹配到后直接阻止写入，并且丢弃该轮抽取结果。这个规则写起来不难，却能从源头防止大多数隐私风险。另外，所有记忆数据在我这边是加密存储的，数据库文件放在独立目录，备份时也会从常规备份中排除。安全这块做扎实一点，后面产品要上线、要过审、要跟用户交代，都会省很多麻烦。

5. 常见问题与排查实录

5.1 检索召回的相关性很差，怎么办

如果你发现用户明明聊过某件事，claude-mem 却没能把对应记忆捞回来，先别急着改模型，按顺序排查四件事。第一，查询摘要是不是太短，如果只有一句话，信息量可能不够；第二，记忆的原文是不是太口语化，比如“我不太喜欢太甜的”和“少糖”这样的表述差异，会影响向量距离；第三，embedding 模型跟你的领域语言是否匹配，如果文本以中文为主，用纯英文模型效果会打折扣；第四，阈值是不是卡太严了。我用一个小技巧来快速判断问题出在哪：写一个脚本，把某条记忆和某个查询的向量余弦相似度单独打印出来，如果相似度本身低于 0.2，说明是语义表征的问题，不是召回逻辑的问题。

5.2 注入记忆后回答反而变得更混乱

这个问题的根因通常是两条：一是记忆条目太多，挤占了主对话的上下文空间，模型处理不过来；二是记忆里有互相矛盾的事实，模型没法判断以哪个为准。解决办法是严格控制注入条目数，并且对检索结果做“去冲突”处理。我现在的做法是，检索回来后按类别分组，同类别最多保留两条，并且如果两条内容语义上相对立，就取时间戳更新的那一条。另外，注入量过大时，可以启用一个简单的压缩策略：用 Claude 把多条记忆先合并成一段概括性描述，再把这段描述注入 system prompt。这样的压缩虽然会损失细节，但是能让模型注意力更集中，在大多数业务场景下收益是正的。

5.3 记忆库膨胀导致检索变慢

Chroma 在几十万条记录以内，单机检索基本都在毫秒级，真正让检索变慢的往往是 metadata 过滤条件用得过多，或者每个用户都建独立集合导致文件句柄过多。如果你发现检索耗时越来越长，先检查过滤条件和集合数量。我的经验是，单用户单集合、metadata 只用时间戳和类别两个过滤键，就能保证长期稳定。如果数据量真的到了上千万级别，建议迁移到 Qdrant 并开启 HNSW 索引，但这是后话了。

5.4 费用控制：每次对话到底要花多少钱

记忆系统带来的额外成本主要有三块：抽取记忆时调用模型的 token、生成查询摘要的 token、以及如果在线调用 embedding API 的毫厘费用。我用本地 embedding 之后，最后一块可以忽略。抽取记忆大概是每五轮对话多花一千 token 左右，对大多数应用来说可以接受。真正需要留意的是高频短对话场景，比如用户每分钟发一条消息，如果每两条就触发一次记忆抽取，成本会快速上升。我后来给抽取加了冷却时间：两次抽取之间至少要间隔三分钟，同一会话内两次抽取之前的新消息不足三条就不抽。压缩记忆注入也有一个小技巧：只在 system prompt 里注入优先级最高的四条，剩下的等用户主动追问时再通过联网检索补上。

6. 一些个人体会

做到现在，我对 claude-mem 最深刻的感受是：记忆系统看起来是“给 API 加缓存”，真正做起来是“给对话建档案”。它的技术难点不在向量数据库或 embedding 模型这些单独组件，而在对记忆生命周期的管理——什么时候写、什么时候取、什么时候改、什么时候忘。任何一个环节处理得不仔细，都会直接反映在用户体验的“不对劲”上。如果你也在做类似的事情，我建议先不要追求功能的复杂度，而是花两周把一条“写入-检索-注入”的最小闭环跑通，再依照真实对话日志去调优。要记的东西没有那么玄，最核心的就是那三个字：相关、克制、可忘。这可能就是 claude-mem 这套东西给我上的最重要的一课。