1. 从“金鱼脑”到“老法师”Agent 记忆系统的设计哲学做 Agent 开发这两年我最大的感受就是模型能力决定下限记忆系统决定上限。你肯定遇到过这种场景——用户跟 Agent 聊了半小时需求结果下一轮对话它突然问“您刚才说的项目背景是什么来着”这种“金鱼脑”表现在 Demo 阶段还能忍一旦上生产环境用户直接流失。Agent 记忆要解决的核心问题就三个存什么、怎么取、何时更新。听起来简单但每个决策背后都是工程权衡。我见过太多团队一上来就堆向量数据库结果检索出来的全是噪音反而干扰了模型推理。这一章我就把记忆系统的分层设计逻辑拆开讲透。1.1 记忆不是单一存储而是分层架构人的记忆分短期和长期Agent 也一样。我在实际项目中会把记忆分成四层每层职责明确记忆层级存储内容生命周期典型实现工作记忆当前对话轮次、临时变量单次会话内存变量、Context Window情景记忆历史对话摘要、任务执行记录数天到数月向量库 元数据过滤语义记忆领域知识、用户偏好、事实规则长期持久结构化存储 知识图谱程序记忆工具调用模式、成功操作序列长期迭代Prompt 模板库、Skill 注册表为什么要分这么细因为不同记忆的检索频率和更新策略完全不同。工作记忆每轮都在变直接放在 Context 里就行语义记忆可能几个月才更新一次但每次检索都要求高准确率。如果混在一起存检索时噪音比例会高得离谱。我踩过的一个坑早期把所有对话历史都塞进向量库结果用户问“帮我查下订单”检索出来的是三天前聊天气的记录。后来加了元数据过滤——按时间戳、会话 ID、意图类型打标签检索准确率直接从 40% 拉到 85% 以上。1.2 记忆写入策略什么时候该记什么时候该忘很多开发者只关心“怎么存”却忽略了“什么时候存”。我的经验是不是所有对话都值得写入长期记忆。无脑全存的结果就是检索时噪音爆炸而且存储成本线性增长。我通常用一套重要性评分机制来决定是否写入def should_write_to_longterm(message, context): score 0 # 包含用户偏好、事实性信息 if contains_preference(message): score 3 # 包含任务关键决策 if contains_decision(message): score 2 # 用户显式要求记住 if user_explicit_remember(message): score 5 # 重复出现的信息说明重要 if is_repeated(message, context): score 2 # 寒暄、确认类信息 if is_smalltalk(message): score - 3 return score 3这套规则不是拍脑袋想的。我观察了上千轮真实对话发现用户偏好和显式指令是最值得记住的而寒暄类信息存了反而干扰检索。阈值设为 3 是经过 A/B 测试的——太低会存入噪音太高会漏掉关键信息。注意写入策略一定要可配置。不同业务场景对记忆的敏感度不同客服场景可能需要记住所有投诉记录而闲聊场景只需要记住用户名字就够了。1.3 记忆检索向量搜索不是万能药说到检索很多人第一反应就是“上向量数据库”。但实测下来纯向量检索在 Agent 场景下召回率并不理想。原因很简单用户 query 往往很短向量表征信息量不足容易匹配到语义相似但实际无关的内容。我现在用的是混合检索策略关键词过滤先用元数据时间、类型、实体缩小范围向量召回在缩小后的集合里做语义搜索重排序用 Cross-Encoder 对 Top-K 结果精排时效性加权近期记忆给更高权重这套组合拳下来检索准确率比纯向量方案提升了 30% 以上。具体参数上我一般设 Top-K20 做召回重排序后取 Top-5 注入 Context。K 值太大会稀释有效信息太小会漏掉关键记忆。还有一个容易被忽略的点记忆检索要考虑 Token 预算。Context Window 就那么大检索回来的记忆太多会挤占推理空间。我的做法是给记忆分配固定预算比如 2000 Token超出部分按相关性截断。2. 上下文工程把对的 Token 放在对的位置Context 工程是 Agent 开发里最“玄学”的部分——同样的信息放在不同位置模型表现可能天差地别。我做过一组对比实验把关键指令放在 System Prompt 开头 vs 放在用户消息末尾任务完成率差了将近 20 个百分点。这一章我重点讲上下文组装的结构化方法以及如何利用“位置偏置”让模型更靠谱。2.1 上下文窗口的黄金分区法则经过大量实验我总结出一个四区段上下文布局在实际项目中效果稳定[System Prompt 区] - 角色定义、核心规则、输出格式 [长期记忆区] - 检索回来的语义记忆、用户偏好 [近期对话区] - 最近 N 轮对话原文 [当前任务区] - 用户最新输入 任务指令为什么这么排因为模型对开头和结尾的信息注意力最集中这就是著名的“Lost in the Middle”现象。所以我把最重要的角色规则放开头把当前任务放结尾中间放辅助性记忆。实测数据这种布局比“记忆放开头、指令放中间”的方案任务准确率高出 15%-25%。尤其是多步推理任务效果差异非常明显。2.2 动态上下文压缩Token 不够用时的取舍艺术Context Window 再大也是有限的。当对话轮次多了必须做压缩。我的压缩策略分三档第一档对话摘要。把超过 10 轮的历史对话用模型生成摘要保留关键决策和事实丢弃寒暄和重复确认。摘要 Prompt 我一般这么写请将以下对话压缩为不超过 200 字的摘要必须保留 1. 用户明确提出的需求和偏好 2. 已达成的决策和结论 3. 未解决的问题 丢弃寒暄、重复确认、无关闲聊第二档实体抽取。把对话中提到的关键实体人名、项目名、时间、数字抽出来存成结构化 JSON比原文节省 80% Token。第三档按需加载。不是所有记忆都要一次性注入而是让 Agent 通过工具调用按需检索。这招最省 Token但会增加一轮交互延迟。实操心得压缩比例不要超过 70%。我试过把 10000 Token 压到 2000结果关键信息丢失严重模型开始胡编。一般压缩到原文的 30%-50% 是比较安全的区间。2.3 上下文污染那些悄悄拖垮 Agent 的隐形杀手上下文污染是我踩过最深的坑之一。什么叫污染就是 Context 里混入了过时、矛盾或无关的信息导致模型推理出错。常见的污染源有三类过时记忆用户上周说“预算 5 万”这周改成“预算 3 万”但旧记忆没清理模型可能按 5 万做方案矛盾指令System Prompt 说“回答要简洁”但 Few-shot 示例全是长篇大论无关检索向量检索召回了语义相似但实际无关的记忆干扰判断我的解决方案是记忆版本管理 冲突检测。每条记忆带时间戳和版本号新记忆写入时检测是否与旧记忆冲突冲突则标记旧记忆为“已失效”。检索时只召回有效记忆。这套机制实现起来不复杂但效果立竿见影。上线后因为“记忆矛盾”导致的错误率下降了 60% 以上。3. Skills 体系让 Agent 从“会聊天”到“能干活”Agent 和 Chatbot 的本质区别就在于能不能调用工具完成实际任务。而 Skills 就是工具调用的组织方式。我见过很多项目工具定义了几十个但 Agent 就是不会用、用错、或者该用的时候不用。问题出在 Skills 的设计和注册机制上。3.1 Skill 的原子化设计原则一个 Skill 应该多细我的经验是一个 Skill 只做一件事且这件事能用一句话描述清楚。反面案例我见过一个“处理订单”的 Skill内部包含查询、修改、取消、退款四个功能靠参数区分。结果模型经常传错参数调用失败率高达 30%。正面案例拆成query_order、update_order、cancel_order、refund_order四个独立 Skill每个的 description 清晰明确调用准确率直接拉到 90% 以上。Skill 定义的黄金模板{ name: query_order, description: 根据订单号查询订单状态和详情。当用户询问订单进度、物流信息时使用。, parameters: { order_id: { type: string, description: 订单号格式为 ORD 开头的 12 位字符串, required: true } }, when_to_use: 用户提到订单物流发货等关键词且提供了订单号, when_not_to_use: 用户只是闲聊购物体验没有具体订单号 }注意when_to_use和when_not_to_use这两个字段——这是我从实际调试中加上的能显著降低误调用率。模型看到“什么时候不该用”判断会谨慎很多。3.2 Skill 注册与发现让 Agent 知道“自己能干什么”Skill 多了之后怎么让 Agent 知道有哪些能力可用全塞进 System Prompt 会爆 Token动态检索又可能漏掉关键 Skill。我的方案是分层注册 语义路由核心 Skill5-10 个高频使用直接写进 System Prompt扩展 Skill几十个按领域分组用向量检索按需加载长尾 Skill上百个只在特定场景激活通过规则触发具体实现上我给每个 Skill 生成 embedding用户 query 来了之后先做语义匹配召回 Top-5 相关 Skill 注入 Context。这样既控制了 Token又保证了召回率。实测下来这套机制在 200 Skill 的场景下Skill 召回准确率能到 88%比全量注入节省 70% Token。3.3 Skill 执行结果的回传与消化Skill 调用完结果怎么回传给模型这里有个细节很多人忽略原始 API 返回的 JSON 往往又长又难懂直接塞给模型会干扰推理。我的做法是加一层结果格式化def format_skill_result(raw_result, skill_name): if skill_name query_order: return f订单 {raw_result[id]} 状态{raw_result[status]}预计送达{raw_result[eta]} elif skill_name search_flight: flights raw_result[flights][:3] # 只取前3条 return \n.join([f{f[no]} {f[depart]}-{f[arrive]} ¥{f[price]} for f in flights]) # ...这层格式化把原始 JSON 压缩成自然语言Token 减少 60% 以上模型理解准确率反而更高。记住模型是读自然语言的不是读 JSON 的。4. Harness 框架Agent 的“操作系统”该怎么搭Harness 这个词在 Agent 圈子里越来越火但很多人理解得比较模糊。我的定义是Harness 是 Agent 的运行时框架负责编排记忆、上下文、Skills、工具调用、错误处理等所有环节。它就像 Agent 的操作系统决定了各个模块怎么协作。4.1 Harness 的核心循环感知-决策-执行-反思一个完整的 Harness 循环包含四个阶段感知接收用户输入检索相关记忆组装 Context决策模型推理决定是直接回答还是调用 Skill执行调用 Skill获取结果格式化回传反思评估执行结果决定是否重试、是否写入记忆很多简易 Agent 只做了前两步缺少反思环节导致错误无法自我纠正。我加上反思环节后任务成功率提升了 20% 以上。反思的具体实现每次 Skill 调用后用一个轻量模型或规则判断结果是否合理。如果不合理触发重试或换策略。比如查询订单返回空就反思“是不是订单号错了”然后重新向用户确认。4.2 错误处理与重试Agent 的“自愈”能力Agent 执行任务时出错是常态——API 超时、参数错误、权限不足各种情况都有。Harness 必须有一套分级错误处理机制错误类型处理策略重试次数网络超时自动重试3 次指数退避参数错误让模型修正参数后重试2 次权限不足告知用户请求授权0 次业务逻辑错误反思后换策略1 次未知错误兜底回复 记录日志0 次这套机制的关键是区分“可重试”和“不可重试”错误。无脑重试会浪费 Token 和时间该放弃的时候要果断放弃。实操心得重试时一定要把错误信息回传给模型让它知道“上次为什么失败”。我试过不回传错误信息直接重试模型会用同样的参数再调一次纯属浪费。4.3 Harness 的可观测性没有日志就没有优化Agent 系统最怕“黑盒”——出了问题不知道哪一步错了。我在 Harness 里强制加了全链路追踪每个环节都记录输入输出 Token 数记忆检索命中了哪些条目Skill 调用的参数和结果每步耗时模型推理的中间状态这些日志不仅用于排查问题更是优化的数据基础。我通过分析日志发现80% 的失败案例都集中在某几个 Skill 上针对性优化后整体成功率大幅提升。日志格式我推荐用结构化 JSON方便后续做聚合分析。关键字段包括trace_id、step、input、output、latency、error。5. 记忆更新与经验沉淀让 Agent 越用越聪明Agent 上线只是开始真正有价值的是运行过程中不断积累经验越用越聪明。这一章讲记忆更新机制和经验沉淀的实操方法。5.1 记忆的时效性管理什么该忘什么该记一辈子记忆不是存得越多越好。我的经验是给每条记忆设衰减因子用户偏好类衰减慢半衰期 90 天任务记录类衰减快半衰期 7 天事实知识类几乎不衰减临时状态类会话结束即失效检索时按“相关性 × 时效性”排序保证既相关又新鲜。这套机制实现起来就是给每条记忆加个decay_score字段定期更新。5.2 从成功案例中提取可复用经验Agent 每次成功完成任务都是一次学习机会。我会把成功的操作序列提取出来存成“经验模板”。下次遇到类似任务直接参考模板成功率更高。比如 Agent 成功处理了一次退款我就把“确认订单 → 检查退款政策 → 发起退款 → 通知用户”这个序列存下来。下次遇到退款请求直接按这个流程走不用模型重新推理。这就是程序记忆的价值——把成功的操作模式固化下来减少重复推理提升效率和稳定性。5.3 记忆冲突的检测与消解前面提到过记忆冲突的问题这里展开讲消解策略。当新记忆与旧记忆矛盾时有三种处理方式时间优先新记忆覆盖旧记忆适用于偏好变更置信度优先保留置信度高的适用于事实性信息人工介入标记冲突等待确认适用于关键决策我一般用“时间优先 置信度加权”的组合策略。新记忆默认置信度更高但如果旧记忆被多次引用过置信度会累积可能反超。这套机制让 Agent 的记忆保持“自洽”不会出现前后矛盾的低级错误。6. 常见问题与排查技巧实录做 Agent 这两年踩过的坑能写一本书。这里挑几个最高频的问题把排查思路和解决方法整理成速查表。6.1 记忆检索不准的排查清单症状可能原因排查方法解决方案召回无关记忆向量模型不匹配检查 embedding 模型是否适合中文换用中文优化模型漏掉关键记忆Top-K 太小统计漏召回案例增大 K 值 重排序检索结果重复去重逻辑缺失检查是否有重复写入加唯一性约束时效性错误未做时间加权检查排序公式加入衰减因子6.2 Skill 调用失败的典型场景场景一模型不调用 Skill。明明该查订单模型却直接编了个答案。排查发现是 Skill description 写得太模糊。改成“当用户询问订单状态时必须调用此工具”后调用率大幅提升。场景二参数传错。模型把订单号传成了用户 ID。解决方法是给参数加格式校验和示例并在 description 里明确说明格式。场景三调用后不消化结果。Skill 返回了数据模型却忽略它继续编。这是 Context 组装问题——Skill 结果要放在显眼位置并加提示“请基于以上工具返回结果回答”。6.3 上下文超长的应急处理Context 快满了怎么办我的应急方案立即触发对话摘要压缩历史清理低相关性的记忆条目把长文档类内容转为按需检索必要时开启新会话把关键信息迁移过去注意不要等到 Context 完全满了才处理要在 80% 使用率时就预警。我一般设 75% 触发压缩留出缓冲空间。7. 一些个人体会这套记忆 上下文 Skills Harness 的架构是我在多个项目中反复迭代出来的。最大的体会是Agent 开发没有银弹每个模块都要根据业务场景调参。别人跑通的方案直接抄过来可能水土不服。我建议新手从最简单的版本开始——先做工作记忆 几个核心 Skill跑通了再逐步加长期记忆、混合检索、反思机制。一上来就搭大框架很容易陷入“什么都想要什么都做不好”的困境。另外日志和可观测性一定要从第一天就做。我早期偷懒没加详细日志出问题只能靠猜排查效率极低。后来补上全链路追踪定位问题的速度快了十倍不止。最后分享一个小技巧定期用真实用户 query 做回归测试看看记忆检索和 Skill 调用的准确率有没有下降。Agent 系统很容易因为记忆积累而“越用越乱”定期体检能及时发现问题。
