如果你的 Agent 项目已经越过“写 Demo”阶段准备往生产环境走最先卡住你的往往不是模型能力而是记忆。你大概率遇到过这样的场景模型在演示环境里表现得像资深助理能记住用户的偏好、项目进度、历史决定但换到真实对话里三句话之后就“失忆”了。用户十几分钟前刚说出自己的服务器 IP十几分钟后模型就开始一本正经地编造地址。原因大家都知道——大模型的参数里没有业务状态答案只能依赖当前上下文窗口。于是几乎所有做 LLM 应用的人早晚都要回答同一个问题给 Agent 加什么样的记忆系统效果最好这个问题看起来具体实际上非常难回答。市面上的记忆方案太多了有人把整段历史消息拼进上下文有人用向量数据库做语义召回有人把状态写入关系数据库有人把记忆拆成实体图谱。每个方案都有自己的 Demo每个 Demo 都在自己选定的场景里“效果很好”。真到了横向对比的时候任务不同、模型不同、评测口径不同得出来的结论几乎没有可复现性。最近 Hacker News 上出现了一个 Show HN 项目标题很克制但思路很关键A fixed harness for comparing LLM agent memory systems。它要解决的不是“再做一个更好的记忆系统”而是“让不同记忆系统能在同一套固定规则下被公平比较”。这个思路值得所有做 Agent 开发的人认真想一遍。这篇文章会从三个层面展开第一为什么 Agent 记忆系统需要一套固定的 Harness第二一个可落地的固定 Harness 应该怎么设计、包含哪些评测维度第三我会给出一个最小可运行的 Python 示例你可以直接把它扩展成自己的 Agent 记忆评测工具。全文不依赖特定云厂商代码和配置都可以直接复用。1. 这篇文章真正要解决的问题1.1 没有数据支撑的“技术选型”做 Agent 开发时遇到记忆选型最常见的流程是看社区口碑、跑官方 Demo、再在自己的两三个场景里手动试一下。问题在于这三个信息源都不具备可比性。社区口碑描述的是别人的业务你的对话模式、用户画像、数据规模可能完全不同官方 Demo 是精心挑选的脚本通常只覆盖作者想展示的能力自己临时写的测试脚本呢任务定义、提示词、模型版本、上下文预算统统没有固定今天测出的结论明天就复现不了。结果就是你在一堆“看起来都能用”的记忆系统里做决策依据却是感觉而不是数据。这放在数据库选型、缓存选型里是不可想象的但放在 Agent 记忆系统这个新领域里大家居然都习惯了。1.2 固定 Harness 要解决什么这篇文章要讲的核心方案就是用一个固定 Harness在“只替换记忆系统其他所有条件不变”的前提下量化对比不同 LLM Agent 记忆系统的效果。“固定”这两个字是重点。固定的任务集、固定的基础模型、固定的温度参数、固定的上下文预算、固定的评分口径。只有变量被控制住比较才有意义。1.3 谁最需要这套方案做生产级 Agent 的工程师正在纠结选哪套记忆方案技术负责人需要给团队一个可复现的选型依据研究 Agent 架构的开发者想理解记忆系统怎么评测才公平开源框架作者想给自己的记忆模块写一个标准 Benchmark。如果你只是随便玩玩 LLM API暂时不需要完整 Harness但只要你开始把 Agent 当工程来做这套思路迟早要用上。2. 基础概念与核心原理2.1 什么是 LLM AgentLLM Agent 和普通聊天机器人最大的区别是它具备“自主完成任务”的能力拿到目标后可以规划步骤、调用工具、读取外部状态、根据中间结果调整策略。它不再是一次性问答而是一个有循环、有状态、有外部依赖的系统。状态从哪来模型参数里没有。Agent 每一步决策都要依赖之前的信息用户说了什么、自己做了什么、工具返回了什么。这些信息不可能全部塞进上下文窗口于是就需要一个额外组件来管理——这就是记忆系统。2.2 什么是 Agent 的 Memory SystemMemory System 是 Agent 架构中负责“模型参数之外的持久化状态”的组件。它一般承担三个职责写入把对话历史、工具结果、抽取出的关键事实保存下来检索在当前问题到来时找到最相关的历史记忆更新处理信息的过期与冲突比如用户改了邮箱、改了地址。没有记忆系统的 Agent本质上是“每次对话都从零开始”的有了记忆系统Agent 才真正有了连续工作的能力。2.3 用 Cache / DRAM / Disk 理解记忆分层很多团队讨论记忆方案时喜欢把所有东西都叫“记忆”这其实容易混淆。我用计算机体系结构里的一组类比来讲清楚记忆层次计算机体系类比典型实现核心特点工作记忆L1/L2 Cache当前上下文窗口、最近 N 轮消息读取快、容量小、成本随长度上升情景记忆DRAM会话级向量库、Redis、内存索引容量中等、支持语义检索语义记忆Disk/SSD向量数据库、图数据库、文件存储容量大、持久化、适合沉淀知识这个类比非常有用。Cache 快但贵Disk 大但慢真正的系统设计不可能只用一个层次。Agent 记忆系统的核心工程问题就是如何在不同层次之间做缓存、淘汰、回写和一致性同步。你评测一个记忆系统时本质上是在评测它在这组层次上的调度策略。2.4 Harness 到底是什么Harness 这个词在 LLM 评测里一般翻译成“评测框架”或“评测执行器”但它和我们常说的“测试框架”不完全一样。测试框架回答“这个代码有没有 bug”Harness 回答的是“在完全相同的条件下A 和 B 谁的表现更符合预期”。一个固定 Harness 至少包含三部分固定任务集所有参赛系统跑同一个任务固定执行协议模型、温度、上下文预算、调用方式完全一致固定评分规则用同一套指标计算得分输出结构化报告。Harness engineering 的重点不是“跑通一次评测”而是让评测结果可以被任何人随时复现。3. 传统对比方式的三个坑为什么需要固定 Harness在进入设计之前先看传统对比方式为什么不可靠。这里总结三个最常见的坑。3.1 坑一任务集不可比A 系统用电商客服数据测B 系统用论文问答数据测双方都报告自己准确率 95%。这个 95% 没有任何可比性。更隐蔽的问题是任务难度。有些记忆系统只适合短对话有些适合长文档场景如果不给所有系统相同的任务分布结果就是“谁挑的场景和谁的系统能力匹配谁的分数就高”。3.2 坑二计算预算不可比记忆系统的核心成本是 token。一个系统用 50k 上下文硬扛另一个系统用 4k 上下文加检索两者在同等准确率下成本可能差一个数量级。如果不把 token 消耗和延迟纳入评分就会出现“用钱堆出来的高分数”。固定 Harness 必须规定每次回答的预算上限并且在报告中同时给出准确率和成本。3.3 坑三评测口径不可控有的团队用“用户满意度”评测有的用“事实召回率”有的干脆只用一两个直观案例。口径不一致结果就无法复现。这里更麻烦的是“口头结论”今天测完感觉 A 比 B 好下周换了模型版本结论可能完全反过来。下表对比了三种常见对比方式及其盲点对比方式表面信息隐藏问题官方 Demo效果惊艳场景经过挑选参数未必复现社区分享口碑真实业务差异大结论不可迁移自己的临时脚本贴合业务任务、模型、预算不固定结果不可复现固定 Harness 要补的正是这个位置让评测从一个“感觉”变成一个“可导出、可复查、可纳入 CI 的产物”。4. 固定 Harness 的设计原则与评测维度4.1 三条设计原则第一只换一个变量。你要对比记忆系统那就只替换记忆系统模型、任务、提示词、温度、参数全部不变。任何一项不固定结果都无法归因。第二固定计算预算。限制每次回答能看到的记忆条数、上下文 token 上限。否则“记忆效果好”和“上下文塞得多”会混在一起。第三结果可复现、可导出。评测输出必须是 JSON、CSV 这类结构化格式包含每个任务的得分、延迟、token 消耗并保存完整的输入输出日志。这样出了争议可以回头查。4.2 建议评测维度维度说明建议指标事实保持多个无关话题后是否还记得早期事实fact_accuracy冲突更新用户改变信息后是否采用新值new_value_accuracy检索抗噪存在大量干扰信息时能否召回关键记忆recallk稳定性同任务多次运行结果是否波动方差或极差成本完成相同任务消耗的 token 与时间prompt_tokens、latency_sec可扩展性记忆条数增长后指标下降速度记忆量-准确率曲线4.3 任务集应该怎么设计不要一开始就追求大而全。建议从 3 到 5 个基础任务起步每个任务覆盖一个典型能力跨话题事实保持冲突信息更新长对话早期事实保持相同语义不同表述的检索记忆数量压力测试。每个任务都要加入干扰轮次也就是和评测目标无关的正常对话。否则系统只要“记住最近一句话”就能过测不出真实能力。5. 环境准备与前置条件本文示例代码使用 Python 3.10 及以上版本因为用到了dict[str, Any]这类类型注解语法。依赖只有两个pip install requests richrequests用于调用 LLM APIrich可选主要用来让控制台输出更好看不加也不影响。还需要一个可用的 LLM 服务。你只需要它兼容 OpenAI 的/chat/completions协议即可。本地可以用 Ollama、vLLM 等方式启动一个服务也可以在代码里直接填入云厂商 API 的 base_url 和 key。这一步的关键要求是整个评测过程中base_url 和 model 名称不能变。开始之前先用一条命令验证服务连通curl http://localhost:8000/v1/models能返回模型列表说明服务正常。如果这里就失败后面代码跑不通也不用急着排查业务逻辑先看服务地址和网络。6. 核心流程拆解与完整示例代码实现下面用一个最小可运行的 Harness 示例演示从任务定义到结果报告的完整流程。整个工程只有 5 个文件tasks/config.json任务定义memory_interface.py统一内存接口naive_memory.py简单滑动窗口记忆作为对照系统vector_memory.py向量记忆骨架展示扩展方式harness.py和run_eval.py执行器与运行入口。6.1 任务定义文件先定义三个任务跨话题事实保持、冲突信息更新、长对话早期事实保持。第三个任务专门用来暴露“滑动窗口丢弃早期信息”的问题。{ tasks: [ { id: fact_retention, name: 跨话题事实保持, turns: [ { user: 记住我叫张伟生日 1992-08-17就职于云帆科技项目代号是 Alpha。, check_facts: [] }, { user: 最近有什么适合周末看的科幻电影, check_facts: [] }, { user: 下周我要出差你还记得我的公司和生日吗, check_facts: [云帆科技, 8月17日] } ] }, { id: conflict_update, name: 冲突信息更新, turns: [ { user: 我的联系邮箱是 oldexample.com请记住。, check_facts: [] }, { user: 更正以后联系我用 newexample.com旧的不用了。, check_facts: [] }, { user: 现在要给你发资料我的邮箱是什么, check_facts: [newexample.com] } ] }, { id: long_context_fact, name: 长对话早期事实保持, turns: [ { user: 初始信息我的备案号是 ICP-2024-0921请长期记住。, check_facts: [] }, { user: 请帮我总结一下最近的行业新闻。, check_facts: [] }, { user: 再推荐一些 Python 性能优化的技巧。, check_facts: [] }, { user: 今天天气不错聊点别的吧。, check_facts: [] }, { user: 突然想起来了我的备案号是什么, check_facts: [ICP-2024-0921] } ] } ] }每个turn都有两个字段user是模型收到的用户输入check_facts是这轮回答中必须出现的事实片段。这里使用子串匹配作为最简单的评分方式。真正生产环境里你应该换成 LLM-as-Judge 或者规则加正则的组合原因后面会讲。6.2 统一内存接口所有参与对比的记忆系统都必须实现同一个接口。这样才能保证评测执行器只依赖抽象不依赖具体实现。# 文件路径memory_interface.py from abc import ABC, abstractmethod from typing import Any class MemorySystem(ABC): 所有参与对比的记忆系统都需要实现这个统一接口。 abstractmethod def add(self, key: str, content: str, metadata: dict[str, Any] | None None) -