★ FEATURED ARTICLE 做 Agent 开发这半年我踩过最大的坑说起来特别基础模型能力再强它记不住东西。上一轮聊好的用户偏好下一轮就清零重来跟金鱼一样七秒记忆都算好的。早期我靠硬拼 context window把聊天记录全部塞给模型效果是有一点的但 token 费用涨得飞快过了几千轮之后上下文一长模型回答质量直线下降严重的连指令都开始漏。后来我换了一条路不攒原话改攒结论。也就是给 Agent 外挂一套独立的记忆系统把每一次对话里值得留下的信息抽取成结构化记忆存起来下次需要的时候再精准召回拼进当前对话的上下文里。这个思路实现的方案在开源社区里有一个带 M 字母开头的代号方案圈内经常拿它做记忆层的参考实现。我用它改造了自己手上一个跨平台智能助手项目之后效果变化非常明显用户连续三次说“我不吃辣”第四次点餐推荐清单里就彻底没有辣味菜了用户上周改过一次会议安排这周再提起Agent 能直接说出“上次你把它挪到了周五下午三点”。这篇文章我把自己从零集成这套外挂记忆系统期间的完整心得、代码走读和踩过的问题做一个整理。聊清楚三件事这套系统为什么有效核心机制到底是什么以及怎么把它真正接到你自己的项目里。无论你是刚接触 Agent 开发还是已经在做基于大模型的应用这套记忆层的思路应该都能帮到你。1. 先说痛点Agent 的能力想升级卡在了“记不住”上1.1 大模型对话窗口不是记忆是临时工笔记本很多人一上来就不理解为什么大模型什么都懂却记不住三秒钟前说过的话。这里有个概念要拆清楚模型的记忆说白了是存在权重里的。训练结束之后它的“知识”就固化了而对话过程中你传进去的文本只存在于这次请求的上下文窗口里——意思就是这一次请求结束、模型返回结果之后那片上下文就被清空了。除非你每次请求都把历史记录重新传一遍否则模型是“零记忆”的。这个特性你可以理解成临时工笔记本模型每接一单新活就发一个新的本子上家客户说了啥它全看不见。要让它知道上回聊了什么你只能把老客户的原话一个字不落重新念一遍。这带来的第一个问题是成本对话越长每次请求的 token 消耗线性上升做一次长会话光传历史就把预算烧掉一大半。第二个问题是上限上下文窗口再长也有边界当累积的历史超过窗口长度要么截断丢掉早期内容要么改用摘要可摘来摘去必然丢细节。第三个问题更隐蔽历史里的噪声是没有任何过滤的用户一百句话里可能只有一句是偏好剩下九十九句全是寒暄和废话。如果你全塞给模型它很难在一堆凉菜里精准挑出那道真正的硬菜。1.2 外挂记忆到底在解决哪几个具体场景问题把记忆从模型上下文里抽出来单独放到一个系统里管理这就是所谓的“外挂记忆”。它的核心思路是对话不再靠“传原话”而是靠“传要点”。我自己实际改造之后体会到它解决的是下面这几类具体场景问题。第一类是长期偏好跟踪。比如用户在一次长对话里提到“我平时上班比较早八点前就要出门”“我喝咖啡只喝美式不加糖”“家里有一只柯基叫团团”。这些信息散落在不同的时间、不同的会话里传统做法想把它们全部传给模型就必须保留每一个原始句子。外挂记忆的做法是每次对话结束之后把里面的事实型信息抽取出来、结构化存好下一次对话开始前把和当前提问相关的偏好召回出来拼进 system prompt。这样一来模型回答“帮我安排明天早上出门的节奏”时脑子里就已经知道“八点出门、要喝咖啡”这些背景了。第二类是跨会话连续性。用户一天前问过“我们的项目 X 的交付节点是什么时候”今天又来问“帮我看看项目 X 现在还缺哪些事”。没有记忆系统的 Agent 会一头雾水——它不知道“项目 X”是什么。有了记忆层它可以从存储里查到项目 X 的核心信息接着上一轮的认知继续说。长期使用下来你会明显感觉到 Agent 像一个真正跟过项目的助理而不是每句话都要重新解释的机器人。第三类是个性化表达。用户说“我比较喜欢简洁的回答风格”这个偏好抽出来之后后面所有回答都能自动往“短、直接、少寒暄”的方向调。说到底Agent 之间的差距早期拼模型能力后期拼的就是谁能更懂用户而“懂”这个字几乎完全依赖记忆系统能做到多细、多准、多及时更新。2. 记忆系统的核心机制从底层讲清它怎么运转2.1 记忆处理的四段流水线提取-合并-存储-召回外挂记忆系统不是简单地把对话丢进数据库它内部是一条明确的流水线。我在集成过程中把这条流水线拆成了四个阶段提取、合并、存储、召回。理解了这条流水线你就把握住了记忆系统的命门。提取阶段是这个方案最聪明的地方。它不存对话原话而是通过模型“想”出哪些信息值得记。具体来说系统把一段对话发给你指定的大模型可以是主对话模型也可以单独配一个小模型让它输出结构化结果比如“这是一个用户偏好”“这是一个项目事实”“这是一条行动指令”。拿我改造的例子来说用户说“下次记得帮我定靠窗的位置”提取层就会把它转成一条 structured memory字段大概是类型偏好主语用户内容订位时优先选靠窗位置。原文里那些“下次”“记得”这些口语语气词全部被清掉了留下的是干净的逻辑信息。合并阶段解决的是信息冗余和冲突问题。每次新提取出来的记忆不是直接插进库而是先和已知记忆做一次比对如果库里已经有一条特别相似的就考虑合并如果新记忆和旧的矛盾就要判断谁覆盖谁。举个例子用户周一说了“我周一上午都在开会”周二又说“我上午都在开会”合并层应该把这两条整合成“用户上午通常开会”而不是存两条互相重复的记录。存储阶段把记忆落到外部存储里。这套方案的一个特点是支持“无持久化依赖”的快速原型模式——你在本地跑一下不用装任何数据库就能看到效果但只要进入真实环境我强烈建议立刻接一个真正的外部存储否则服务一重启所有记忆全没了那跟大模型本身的失忆没有任何区别。召回阶段发生在 Agent 每次生成回复之前。系统拿到当前用户消息先做语义相似度检索从记忆库里找出和当前话题最相关的记忆片段再把这些片段编排进 prompt。召回的准不准直接影响“外挂记忆”到底像真正的记忆还是像一坨乱塞的便利贴。为了更直观我把这套流水线各自承担的核心动作和产出物整理成了一张表流水线阶段核心动作输入输出提取模型将对话转成结构化记忆点对话原文记忆事实/偏好/ID合并判断新记忆与库内记忆的关系新记忆 已有记忆新增/更新/删除操作存储写入向量库和关系库结构化记忆持久化记录召回根据当前消息语义命中相关记忆用户当前输入相关记忆片段列表2.2 记忆类型拆分哪些该长期留哪些该随手丢在实际运营记忆库的时候我慢慢意识到一味追求“全记住”是误区。所有记忆点一视同仁地存过不了两周库里就会堆满“用户昨天吃了外卖”“用户今天出门带了伞”这种毫无长期价值的信息。真正好用的记忆系统一定做分类管理。我这套方案里默认做了三类拆分我根据自己的项目又调整过一些细节第一类是记忆事实facts。用户主动说出并且稳定的客观信息比如“我在某城市”“我的职位是后端工程师”“家里有两个孩子”。这类记忆最重要变化频率低影响面广必须存到长期记忆层并且每次对话都要优先召回。第二类是偏好与规则preferences。“我喜欢周报用表格形式”“我不接紧急需求变更”“回复语气要专业但不能太生硬”这些可以被归为偏好。它们的优先级也高但和事实的区别在于偏好更偏向“怎么做”事实偏向“是什么”。第三类是临时状态state。比如“这个需求本周五上线”“上一轮我们讨论到一半的方案还没定稿”。状态是会过期的而且很多时候只和当前项目或者最近几天相关。这类信息应该单独放一块定时清理避免它污染长期记忆。分段存储的核心理念是不要把所有记忆点一股脑全扔进一个大池子。一旦池子大了召回时的相关性检索就容易被大量低价值信息干扰。就像你办公桌上堆了一堆文件真要用某一份的时候翻遍整张桌子也找不到。分类做得好Agent 将来“想问题”的时候才能聚焦在真正重要的那几块内容上。2.3 存储后端为什么可插拔向量库负责相似、关系库负责精确这套方案的存储设计是一个典型的“双后端”架构。我一开始觉得没必要觉得一个数据库不就行了嘛实践下来发现真不行——因为两种后端解决的是完全不同的问题。向量数据库负责按语义相似度找记忆。它的底层思路是把一段文本转成一个高维向量然后在向量空间里做最近邻搜索。你问“他想订一个安静的位置”向量库能找到“用户喜欢角落靠窗位”这条记忆哪怕两者字面完全不同。这就是语义检索的价值。但向量库的弱点是精确匹配不行如果你要查“用户的会员等级是什么”按向量检索出来的结果可能是一堆含“等级”“会员”关键词的无关记忆准确性完全看运气。所以需要关系型数据库来兜底。它处理的是结构化精确查询比如“ID XX 的记忆最近一次更新是什么时候”“这个用户有没有存过邮箱”。事实型信息、记忆的元信息创建时间、更新时间、来源会话ID都在关系库里保存得清清楚楚。向量库负责“模糊联想”关系库负责“精确记账”两者配合才是完整的记忆方案。这种可插拔设计还带来一个实际好处你在本地调试时可以先用轻量存储跑通全部逻辑确认记忆提取和召回质量过关之后再接上生产级的外部存储不用改业务代码。我自己就是这么干的先集中精力调 prompt 效果把系统里最难调的“记忆提取质量”解决掉再花钱上更重的存储设施分摊了试错成本。3. 落地实操把记忆模块接进你自己的 Agent 项目3.1 环境准备与最小配置清单真正动手接之前我先列一下我项目里的最小配置清单方便你照着准备。第一样是一套可用的 API。要跑记忆提取必须有能调用大模型的环境本地跑一个小模型其实也行但论提取质量和速度还是云端 API 更省心。配置的时候记得准备一个专门给记忆提取用的 API Key别和主对话模型的 Key 混在一起后面好做单独的成本核算。第二样是记忆组件的 SDK。这套方案的 Python 包是发布在官方包索引上的直接 pip 安装就行。其中带扩展插件的版本会把向量存储等额外依赖一起装好省得后面反复补包。第三样是一个临时存储。快速体验阶段组件自带的内存存储就够用了。当然我前面已经强调过这种模式不能用于生产环境服务重启数据即失只适合拿来验证流程。我非常推荐你新建一个独立目录建一个虚拟环境再来做这一步。不要和主项目共用依赖记忆组件版本升级偶尔会有 API 调整独立环境能避免不少连带问题。3.2 记忆写入流程的代码走读整个流程最核心的一步是对话结束后触发记忆提取。先把代码骨架贴出来from memory_client import MemoryClient # 初始化记忆客户端 client MemoryClient() # 设定当前用户标识 user_id user_alice # 单条对话消息 messages [ {role: user, content: 下周二的评审会帮我挪到周三下午那个会议室记得订大一点的。} ] # 写入记忆组件内部会自动完成提取-合并-存储 result client.add_memory( user_iduser_id, messagesmessages, ) print(result)你注意到没有这里调用接口时传入的是整个消息列表而不是一条你已经整理好的记忆文本。这正是这个方案的核心设计记忆提取完全交给内部流程。这时候组件内部大概发生了这几件事第一步把 messages 发送给配置好的模型让它判断这段对话里有哪些值得长期保留的信息第二步返回的结构化结果里会包含记忆类别、内容、丰富程度评分第三步和现有记忆做相似比对决定新增还是更新第四步把最终结果写入存储后端。它这样设计的潜台词是你不必自己写任何应对“记住特定信息”的规则。用户可能用一百种方式表达“我不吃辣”靠规则匹配要么漏、要么误伤但大模型抽取能力强只要提示词描述得足够清楚就能把这句话从任何表达方式里抓出来。当然不同模型提取效果差异很大我建议你自己准备两三条测试对话分别跑一遍看结果里有没有把寒暄、闲聊误当作事实记下来。配置模型那块有一行很容易被忽略client MemoryClient( memory_config{ llm: { provider: openai, config: { model: 你配置的提取模型名, }, }, embedder: { provider: openai, config: { model: 你配置的向量模型名, }, }, } )这里有个容易犯的小错误记忆提取模型和向量化配置是完全两个东西。记忆提取决定“该记什么”向量化决定“两个文本看起来像不像”。如果向量化模型选得不好词义表达能力弱那么召回阶段很容易出现“看似相关实则四六不靠”的坏结果。比如用户问“会议室空调太冷了”理想的召回应该能关联到“用户对温度敏感”这条记忆但如果向量模型不够强这两者之间可能算不出高相似度。3.3 记忆读取与提示词注入记忆写进去了读取端才是真正提升用户体验的地方。我实现 Agent 的时候是在每次生成回答之前先做一次记忆召回然后把结果注入到系统提示词里。流程大致是这样# 用户发来当前问题 current_query 帮我看看周三下午的会议安排 # 用在用记忆系统中检索 search_results client.search_memory( user_iduser_id, querycurrent_query, ) # 将召回的记忆整理成提示词片段 memory_context \n.join( [f- {item[memory]} for item in search_results[results]] ) # 拼进 system prompt system_prompt f你是一个智能助理。以下是与用户相关的历史记忆片段请参考这些信息回答 {memory_context} 这里最需要拿捏的是召回数量的上限。我把召回条数控制在 5 条以内多了反而容易出问题。原因很直接召回越多超出账号本身相关性的废话也越多模型读到的信息噪音比例上升回答更发散。你可以把这个参数理解成“优先级提示”给模型的不是全部记忆而是它此刻最应该想起来的几件事。就像真人助理不会把交往十年里所有琐事全倒给你听只说眼下这一件相关的就够了。召回的结果不一定要直接用原文塞进提示词。我后来做了一个很小的二次加工先让模型把召回的记忆片段整理成一段“用户背景小传”再注入主对话。这样模型看到的不是几条孤立记忆的简单拼接而是读起来自然的描述。举个例子如果召回结果各是“用户在某城市工作”“用户在周三下午有例会”我可能先让模型把这两条整合成一句“用户在某城市工作每周三下午通常开会”再作为背景信息给主模型效果明显比丢两条笔记进去要好。3.4 两个典型的业务场景改造示例我实际拿两个场景做过完整改造你可以看看“记忆进入业务”之后长什么样。第一个场景是点餐推荐助手。改造之前它每次回答只根据用户当次输入的菜品名做推荐用户要是想说“再来点上次那种不辣的小食”助手只能猜。接上记忆之后系统从历史对话里提取了“用户不吃辣”“用户偏好鸡肉类小食”到第二次用户说“帮我点几个小食”系统就能直接推荐不辣的鸡肉类菜品还会提醒餐厅有相关备注选项。这个体验的提升用户感知非常强。第二个场景是项目群助理。群聊内容里经常出现“需求变更”“时间节点”“负责人指派”这类信息最典型的是用户随口说一句“这个功能周五要能上线”过了几天再问“今天要交付的任务有哪些”如果助手只靠当前对话是不知道“这个功能”指什么的。接上记忆系统之后这类行动型信息会被抽取成短期记忆状态等用户再次问起时助手就能自动把“周五上线任务”捞出来还知道关联到哪个项目模块。你做其他场景也一样先想清楚哪些信息值得沉淀再反推怎么触发记忆写入。不要一股脑把所有对话全记录那是简陋的做法记录质量会越用越差。4. 避坑实录关于记忆系统那些文档里不写的事4.1 记忆污染问题没有评分机制垃圾记忆会拖垮效果记忆系统最大的敌人不是“记不住”而是“记错”和“记垃圾”。我在做测试的前两周经常出现用户明明只是随口吐槽一句“今天路上可真堵”系统却把“用户认为城市交通很堵”当成一条稳定事实存了下来。这种记忆留着吧偶尔还能沾点边但更多的坑是用户随口一句“我又胖了两斤”系统存下来“用户体重 120 斤”等用户三个月后减到 100 斤了它还在按三个月前的事实回答完全没跟上变化。要解决这个我建议做两件事。第一给记忆提取 prompt 加上严格的“重要性门槛”。比如明确告诉模型只有用户陈述的长期偏好、明确的事实、影响后续决策的指令才值得保存一次性的情绪表达、随口寒暄、临时场景描述全部丢弃。第二在写入前加一条人工审核规则。如果记忆类型是“事实”且置信度不足就不写入放到一个待定区。我后来在系统里加了一个很简单的规则置信度评分低于 0.7 的记忆点直接丢弃不再进入存储。效果立竿见影记忆库里“垃圾碎片”的数量少了太多。操作上还建议把提取模型换成比对话模型更“严格”的配置。对话模型为了陪着聊通常更愿意接话、更随和而提取模型需要的是“挑重点”克制一点更好。4.2 冲突与遗忘同一条事实变了旧版本还在顶上记忆合并是这套系统里比较复杂的部分也是我调试时踩得最深的坑。拿最经典的场景说用户今天跟你说“我搬到 B 城市了”明天问 Agent “我在哪里上班”它只要还是按半年前那条旧记忆回答就会闹笑话。原理在于合并阶段对新旧记忆做了相似判定但相似并不等于“同一条”。如果新旧文本之间差异不是特别大合并逻辑大概率能统一成一条新版本但一旦新内容和旧内容在字面上差异巨大比如换了城市名语义向量算出来的相似度可能不够高系统就容易当作两条独立记忆并列存放在库里。这种问题的排查有两条经验。一是历史记忆回看很重要我每隔一段时间就把用户的主要记忆调出来人工抽检一下看看有没有明显矛盾的信息并列存在。二是主动触发覆盖我在写入逻辑里加了一道简单判断如果新记忆的主题对象比如“所在城市”“职位”“家庭情况”与旧记忆一致就强制旧记忆作废而不是放任两条并列。许多人觉得记忆系统是“存”出来的其实是“管”出来的把管理规则理顺系统才会越用越准。4.3 检索质量与长度控制别让录音带变成噪音箱检索是用户无感的部分但问题恰恰都藏在这里。我调试的时候常出现一种情况用户问“这周还有什么会议”召回返回的记忆里却混入“用户上周订过一趟出租车去机场”这种相关性极差的记忆。本质原因是向量检索评分不够精准它可能因为“出行”这个关键词把一条“出行记录”误认为与“会议安排”相关。要压住这种噪音我有几个土办法。第一调高检索返回的相似度阈值。默认阈值偏低把不相关的记忆也带出来我调到 0.75 之后大部分低质量结果能被挡在门外。第二在检索时用文本过滤。比如用户问“会议”时可以只召回类型为“事件”和“偏好”的记忆不召回“出行记录”和“生活琐事”类型。第三围绕搜索结果做去重和按更新时间排序。保证同一条核心信息只出现一次而且尽量是最新版本。还有一点是长度控制。注入到提示词的记忆内容长度要控制我一般把单条记忆压缩成一句话。你直接用原始的长记忆文本召回三条可能就占了五百 token挤占主对话空间还会稀释整体注意力。4.4 成本与性能的平衡每条记忆不是白存的记忆系统本质上是一个多子步骤流程每一步几乎都要调用一次模型接口成本不容小觑。单条对话写入时提取模型要调用一次、合并模型要调用一次、向量化模型要调用一次读取时向量检索也要调用一次。如果所有操作都走云端 API热闹的时候每月费用会非常可观。我的优化经验有三个方向。第一合并操作不用每次都做。只有新提取的记忆和库内某条记忆高度相似时才做一次完整合并判断大部分记忆进入时直接做相似度得分预判低于阈值的直接存储不调用合并模型。第二读取端做缓存。同一用户在一段时间内反复问类似问题时直接复用第一次召回的候选结果不必每次都做向量检索。第三把提取模型和对话模型拆开用更小更快更便宜的模型专门做提取牺牲一点提取细节换取大幅成本下降。这一套组合下来我在保持记忆质量的前提下记忆相关的 API 开销降低了 50% 以上。如果项目早期没有预算做这么细的成本优化我的建议是先把记忆召回条数压制到最小能显著降本。等到确实出现了“该记住的没记住”的情况再一点点放大条数找到你自己的性价比平衡点。5. 我给你留的最后几个建议记忆系统这个方向看起来是一个独立组件实际接入之后会发现它牵动的其实是 Agent 的整体架构。我的亲身感受是不要把记忆系统当成一个“事后加的功能”它应该从第一天就参与你的数据设计。如果你的 Agent 需要长期服务同一个用户或同一个团队记忆能力就不是可选项而是决定体验上限的胜负手。如果你现在正准备接这套方案我建议你按这样的顺序推进先不碰任何复杂配置拿一段测试对话跑通写入和召回然后对照系统记录认真检查每一条被写入的记忆是否符合你的预期确认提取质量没问题了再上外部存储、加缓存、做成本优化。这个过程比你直接照搬一份大而全的配置要踏实得多。最后分享一个我自己的小心得现在每次用户对我说“你怎么记得我说过这件事”我都觉得这个方向做得值。把记忆做对用户是能感受到的。希望这篇文章能让你少踩几个我踩过的坑把 Agent 的记忆能力真正用起来。
阅读完成 · 觉得有帮助？
