你有没有遇到过这种情况把一段项目的来龙去脉仔仔细细讲给 Claude 听聊了两个小时方案都快成型了。第二天打开新会话想接着继续结果它一脸茫然完全不记得我们昨天讨论过什么。更气人的是同一个问题换个说法再问一遍它又能给出和之前矛盾的结论。这不是 Claude 变笨了而是它的对话本质上是无状态的每次 API 调用都是一次全新的开始聊天界面里那些“历史记录”只是前端帮你把消息原样回传而已。只要会话一关模型内部不会留下任何持久化痕迹。我做的 claude-mem 这个工具说白了就是给 Claude 装一个“外置记忆层”每次对话结束后自动提炼实体、决定、偏好和待办事项存进本地持久化存储下次发起新会话前把和当前问题最相关的旧记忆检索出来拼进系统提示词里让模型带着“昨天聊过什么”继续干活。这篇文章会把 claude-mem 从设计思路到具体实现完整拆开讲包括记忆怎么抽取、怎么存、怎么检索、怎么注入以及实测下来哪些场景效果惊艳、哪些场景容易翻车。适合两类人看一是觉得“和 AI 对话每次都要重新交代背景”很浪费时间的深度用户二是想给自己的 Agent 或自动化流程加长期记忆的开发者。看完你不仅能跑起来一个可用的记忆工具还能知道它背后的取舍逻辑。1. 会话清零的根源无状态接口与上下文窗口的局限1.1 为什么 Claude 自己“记不住”事先搞清楚一个底层事实Claude 这类大语言模型在 API 层面就是无状态的。你调用接口时传过去的是什么消息它看到的就是什么消息。所谓的“多轮对话”其实是调用方把之前的用户消息和助手回复全部拼接在 messages 数组里一遍遍重新发送。也就是说聊得越久每次请求里携带的历史消息就越长费用也越高。这个机制带来的直接后果是离线存储彻底不存在。如果你在 Web 端用 Claude前端确实会把聊天记录存进浏览器或服务端但那是“界面帮你存的”不是模型自己的记忆。一旦开启新会话没有历史消息可传模型就回到了“失忆状态”。更麻烦的是上下文窗口有限。哪怕你把旧消息都拼接进去窗口也就那么大。聊到后面前面的细节会被“挤”出窗口——模型不是主动遗忘而是物理上再也看不到那些 token 了。1.2 长期记忆真正需要解决的是什么很多人的第一反应是“把历史全塞进上下文不就行了”。但仔细算一笔账就明白这条路走不通成本假设一次深度讨论产生了 5 万字历史新会话每次请求都要带上这 5 万字token 费用直接翻好几倍。效率无关紧要的寒暄、中间过程的试探性回答都会占用宝贵的上下文窗口真正重要的核心约定反而被淹没。准确性人类总结对话时也会“抓重点”模型同样需要从冗长历史中定位关键信息。但在窗口被塞满的情况下它的注意力会被大量噪音分散检索关键事实的能力显著下降。所以长期记忆工具的核心不是“保存一切”而是“保存高价值信息并在需要时精确找回”。这本质上就是一个带抽取、索引、检索的迷你知识库系统。claude-mem 的整套设计都是围绕这个目标展开的不是让 Claude 自己记得而是让外部系统帮它记得。2. 整体架构拆解一条从对话到记忆再到上下文的流水线2.1 五个核心模块各司其职claude-mem 的运行链路可以分成五个环节模块职责关键点对话采集层拿到每轮完整对话文本需要能接入 API 请求前后的包装器记忆抽取层从对话中提炼结构化记忆条目用 Claude 自身做信息抽取输出 JSON存储索引层记忆落库并生成向量索引轻量用 JSON 文件重量级再用向量库检索相关层根据新问题召回相关旧记忆相似度计算加阈值过滤注入拼接层把记忆格式化成系统提示词需要控制长度防止撑爆上下文这个设计和 RAG检索增强生成的经典套路很像但区别在于RAG 检索的是文档片段claude-mem 检索的是对话中提炼出的“原子事实”比如“用户使用 Python 3.11”“项目决定弃用 MySQL 改用 PostgreSQL”“用户偏好简洁的技术方案”。2.2 为什么记忆必须落本地而不是只靠提示词有人可能问直接在系统提示词里写一句“你要记住我们之前的对话”不也能让模型在会话内保持风格一致吗问题是这行提示词只管得了一轮会话。会话结束后提示词也随之消失。要让记忆跨会话存活必须把抽取结果写进某种持久化介质——文件、数据库、向量库都行。claude-mem 的设计哲学里有一条很重要的原则记忆要被显式保存而不是埋在对话历史里碰运气。显式保存意味着你可以查看、修改、删除任何一条记忆也可以把记忆迁移到另一台机器甚至可以把记忆导出给别的 Agent 用。这是靠“无限重发消息”做不到的。2.3 两个存储方案先文件后向量在实际落地时我推荐按数据量分两档处理第一档轻量把记忆条目追加写入一个 JSONL 文件每条记录包含时间戳、内容、类型、来源对话 ID。适合个人使用一天几十上百条记忆读取全量文件也就几百 KB完全够用。第二档重量当记忆条目超过几千条后线性扫描全部记忆会明显变慢这时候再引入本地向量库把每条记忆的嵌入向量存进去用近似最近邻检索召回。这是我认为最合理的演进路线一开始不要给自己上重型基础设施先把链路跑通、把数据格式打磨好。等到检索速度真的成为瓶颈时再迁移到向量库也不迟。迁移过程也不复杂因为 JSONL 本身就是导入导出的通用格式。3. 关键实现细节抽取提示词、数据格式与嵌入模型选型3.1 让 Claude 自己当“记忆整理员”记忆抽取是整个 claude-mem 的引擎。每次对话结束后我们会把完整的对话文本发给模型要求它按固定格式提炼记忆。这相当于让 Claude 兼任对话者和书记员两个角色。这一步的实现思路是用一个专门的抽取提示词要求输出 JSONimport anthropic import json from datetime import datetime client anthropic.Anthropic(api_keyyour_key) EXTRACT_PROMPT 你是记忆整理员。请从下面的对话中提取值得长期记住的信息 包括但不限于 - 用户明确表达过的偏好或决策 - 项目相关的技术选型、进度、待办 - 反复出现的实体人名、工具名、代码库名 - 对后续会有影响的事实性信息 要求 1. 只输出 JSON 数组不要输出任何解释 2. 每条记忆包含三个字段type(偏好/决策/实体/事实/待办)、content(简洁完整的描述)、importance(0-1之间的数值) 3. 忽略寒暄语句、一次性问题和无效讨论 4. content 必须完整表达一个独立事实不能依赖上下文才能看懂 conversation {conversation} /conversation def extract_memories(conversation_text): response client.messages.create( modelclaude-3-5-sonnet-latest, max_tokens2000, system你是一个严谨的信息抽取器。, messages[{role: user, content: EXTRACT_PROMPT.format( conversationconversation_text )}] ) raw response.content[0].text try: memories json.loads(raw) except json.JSONDecodeError: # 偶尔输出会混入解释简单清洗 start raw.find([) end raw.rfind(]) 1 memories json.loads(raw[start:end]) return memories这段代码的核心在于提示词约束。我试过很多版本最开始只写“提炼重要信息”结果模型会提取出一堆废话比如“用户说了一句你好”。后来把 type 和 importance 字段都结构化规定之后输出质量明显提升。3.2 数据格式设计每条记忆都自带身份证记忆条目最终落库的格式我建议长这样{ id: m_20250121_163032, created_at: 2025-01-21T16:30:32, source: conversation_8f3e, type: decision, content: 项目决定弃用 MySQL改用 PostgreSQL原因是需要更好的 JSON 查询支持, importance: 0.9, last_accessed: 2025-01-21T16:30:32, access_count: 0 }id 用于排序和去重created_at 用于判断记忆是否过期source 可以追溯这条记忆来自哪次对话last_accessed 和 access_count 则服务于后面要讲的“遗忘机制”。这里有个容易被忽略的细节content 字段必须能脱离上下文独立理解。比如“改用 PostgreSQL”这种表述就不好正确写法是“项目决定弃用 MySQL改用 PostgreSQL原因是需要更好的 JSON 查询支持”。因为模型在后续对话中看到这条记忆时它没有任何 context 可以补充必须靠 content 字面信息做联想。这也是 claude-mem 和普通日志系统的本质区别日志记录的是“发生了什么”记忆记录的是“未来还需要知道什么”。3.3 嵌入模型与索引什么时候认真对待向量当记忆量超过几千条后每次要遍历全文做关键词匹配就太慢了。这里可以把记忆内容转成向量然后做相似度检索。我做的方案是本地加载一个开源嵌入模型把每条记忆的 content 字段转成 384 维向量存进本地向量库。每次新会话开始时拿到用户消息同样转成向量检索 Top N 条相关记忆。选型上有两个取舍需要说明为什么不用付费的远程嵌入接口因为个人项目里记忆内容可能比较私密在本地跑嵌入模型不涉及任何数据外发而且向量化速度足够快普通 CPU 也能在几十毫秒内完成。为什么推荐 384 维的轻量模型而不是更大的模型因为记忆条目是短文本通常只有一两句话轻量模型在短文本相似度上的表现并不比大模型差太多但资源占用低一个数量级。如果你暂时不想引入向量库也可以先退回关键词索引或 SQLite 的 LIKE 查询。对个人使用来说两千条记忆以内的全量扫描其实也就几十毫秒完全感知不到延迟。4. 检索与注入让记忆在后续对话里真正发挥作用4.1 检索流程不是把所有记忆都塞给模型很多第一次接触记忆系统的人容易犯一个错误把全部记忆原封不动拼进系统提示词。这跟“把全部历史塞进上下文”没有本质区别窗口照样会爆。正确的做法是相关性优先。在新用户消息进来时先对这条消息做一次检索只召回和它相关的记忆。相关度判断就是向量距离阈值加 Top N 截断def retrieve_memories(query, top_k8): query_vec embed(query) results memory_store.search(query_vec, top_ktop_k) # 阈值过滤相似度低于 0.45 的不要 return [r for r in results if r.score 0.45]检索结果再经过一次长度控制。假设每一步对话平均注入 200 到 300 字记忆8 条合起来大约有 2000 字这个量级对上下文窗口的压力很小但已经足够覆盖“用户是谁、正在做什么项目、上一步定过什么方案”这类关键背景。4.2 注入格式用“记忆卡片”而不是生硬拼贴检索到相关记忆后直接拼接文本效果并不好。我试过两种写法差异非常明显。先看笨办法用户的记忆项目决定弃用 MySQL改用 PostgreSQL。用户偏好简洁技术方案。用户正在做数据迁移工具。再看优化后的写法以下是关于用户和项目的长期记忆请结合这些信息回应用户 memories memo typedecision created_at2025-01-21 项目决定弃用 MySQL改用 PostgreSQL原因是需要更好的 JSON 查询支持 /memo memo typepreference 用户明确表示更偏好简洁的技术方案不喜欢过度设计 /memo /memories第二种写法加上了类型标签和时间戳模型能更清楚地知道每条记忆的置信度和来源时点。实测下来带标签的记忆比裸文本的记忆在后续回答中命中率高不少因为模型可以区分“这是当时随口一提的偏好”和“这是经过讨论确定的决策”。4.3 注入时机与动态控制注入不是只在对话最开始时做一次。多轮对话中用户的关注点会发生偏移所以 claude-mem 的机制是每一轮新请求都重新执行一次检索和注入。换句话说记忆系统不是埋在静态系统提示词里而是作为请求处理管道的一环动态参与每一轮生成。实现上就是在一个拦截器里做三件事def build_request_payload(user_message, history): memories retrieve_memories(user_message) memory_block format_memory_block(memories) system_prompt DEFAULT_SYSTEM_PROMPT \n\n memory_block return { system: system_prompt, messages: build_messages(history, user_message) }这里有个性能提醒每次请求都做一次向量检索会带来几十毫秒的额外延迟。个人使用完全无感但如果做高并发的服务端接入建议加一层缓存同一用户短时间内重复提交相似内容时直接命中缓存。5. 实测里的真实体验什么场景惊艳什么场景翻车5.1 效果惊艳的场景在我的实际使用中效果最好的是三类场景。第一类是跨会话的项目开发。比如我做一个数据迁移工具第一天聊定了整体架构和模块划分第二天继续时Claude 直接就能说出“你决定用双写策略先切读流量再切写流量”不用我再解释任何背景对话衔接得非常顺滑。第二类是写作风格的长期保持。我之前用它写一份技术手册每次会话开始前注入记忆“用户偏好步骤式说明、避免形容词堆砌、每个章节末尾要有常见问题”写出来的内容风格确实更统一不再出现上一章还像文档、下一章忽然变成营销文案的割裂感。第三类是个人知识库问答。我持续往记忆里喂一些平时收集的技术决策和踩坑记录后面再提问“之前遇到过事件循环阻塞的问题怎么解决的”它能直接从记忆条文中把原始方案捞出来这比翻聊天记录快多了。5.2 翻车场景和失败原因但 claude-mem 不是万能的下面几个翻车场景值得说道。场景失败表现原因快速闲聊式对话提炼出一堆无意义记忆对话本身没有足够事实密度连续多次纠偏记忆库里堆满冲突的决策不了解旧记忆的覆盖逻辑非常长的一次性讨论抽取结果过于概括丢了操作细节模型在长文本抽取时容易丢掉细粒度信息跨语言对话中文对话提取出的记忆在英文提问时召不回向量空间里中英文内容距离较远最难受的是第二个。在一次技术选型讨论里我先说了“优先考虑用 Redis”过了 20 分钟改成“还是用 MySQL 吧”这两条都会被抽成决策记忆后者并不能自动覆盖前者。之后模型在回答时可能同时看到两条矛盾记忆输出就会摇摆。后来我加了一个处理规则当新提取出来的记忆和已有记忆在向量距离上非常接近且类型相同时默认用新记忆覆盖旧记忆。但这只是很粗糙的兜底策略真正要做好冲突消解还得靠更细的语义分析和人工审核。5.3 token 成本和延迟的代价每次对话结束后的抽取任务意味着几乎每一轮对话都会额外消耗一次模型调用的 token。我实测下来抽取成本大约是正常回复 token 的 10% 到 20%。一天高强度使用下来增加的费用是不可忽略的。延迟方面抽取任务一般在 1 到 3 秒之间。这个延迟发生在用户结束对话之后不会直接阻塞回复体验但如果做成实时记忆就要注意不要卡在对话响应主路径上。我现在的做法是采用“异步抽取”对话进行时不做任何记忆处理等用户结束当前会话或在后台空闲时再统一抽取。这样主流程零感知后台慢慢算就行。5.4 记忆噪音带来的污染问题这是所有记忆系统都绕不开的难题。哪怕抽取提示词写得再好总会有一些应该是“临时内容”却被固化进记忆库的信息。比如“用户今天心情不太好希望方案更稳妥一点”这种临时情绪被记成长期偏好后会持续干扰后续所有回答。解决噪音的基本功是给记忆增加两条生命线时间衰减设置记忆有效期超过 30 天未被访问的记忆自动标记为低优先级检索时排在最后。手动修剪提供一个简单的命令行交互列出所有记忆条目支持删除和修改。别小看这个笨办法它能让记忆库长期保持干净。6. 后续增强方向与个人实践心得6.1 多用户与多项目隔离如果 claude-mem 只服务于单机单用户简单记住对话内容就够了。但只要想把它用于团队协作或多项目并行就必须在记忆条目上增加命名空间字段比如 project_id 和 user_id。检索时先按命名空间过滤再做相似度排序。这个隔离层要在数据模型设计阶段就加进去否则后面补会非常痛苦。我见过有人把三个项目的记忆混在同一个库里的后果聊 A 项目时检索出的记忆一半是 B 项目的模型经常张冠李戴。别问我怎么知道的。6.2 记忆的自动摘要与压缩对话特别长时抽取出来的记忆条目可能非常多。这时可以引入另一层整理任务每周或每满 100 条记忆让模型做一次“记忆归档”——把属于同一主题的零散记忆合并成一条综述并生成一条高层摘要。这样既保留了细节入口又有了一个快速浏览的概览层。这个思路有点像人的长期记忆分层海马体负责短期细节大脑皮层负责长期概括。claude-mem 也可以模仿这个机制把最近一周的记忆作为“细节层”完整保留把更早的记录压缩成“概要层”只在需要历史追溯时才展开。6.3 对存储结构的最终建议如果你打算自己动手实现一个类似工具我的建议是别一上来就搞向量库。先用 JSONL 加全量扫描跑通整个流程感受一下记忆抽取和注入的核心逻辑。等确实出现性能瓶颈了再引入向量索引。多数个人使用场景下几千条记忆根本不需要向量库。真正制约效果的不是存储引擎而是抽取质量。你可以花更多时间打磨抽取提示词添加更多约束字段甚至针对不同对话类型采用不同的抽取模板。这一步比任何数据库选型都值得投入因为后续所有检索、注入的效果上限都由抽取质量决定。6.4 关于“遗忘”设计的个人体会最后分享一个反直觉的经验记忆系统最重要的能力不是“记住”而是“遗忘”。我一开始疯狂追求把所有细节都存下来结果记忆库迅速膨胀到几千条反而不利于检索正确。后来特意加上了重要度阈值和衰减机制效果立刻变好。原因是 Claude 的注意力也是有限的注入 20 条记忆和注入 5 条高质量记忆后者在回答准确率上反而更高。记住记忆的价值不在于数量而在于关键时刻能不能被正确唤醒。你以为你在给模型增强记忆其实你是在帮它做注意力分配。还有一点小技巧每次对话结尾顺手用一句话总结“本次对话留下最重要的三个结论”让模型写进记忆里。这个小动作比任何自动抽取机制都管用因为它强迫模型在讨论结束后做一次主动的收束和确认。别小看这一步实测下来它能显著减少后续对话的认知错位——因为模型在生成结尾总结时其实是在把整个讨论重新做一遍高密度压缩。
