Agent Zero 记忆后过滤提示词设计memory.memories_filter 模板与召回管线全解【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zeroAgent Zero 的_memory插件在每次对话循环中会自动召回向量库里的相关记忆但相似度检索的候选项里往往混着过期、重复、无信息量的条目。本篇以插件中的用户侧提示词模板 memory.memories_filter.msg.md 为核心完整拆解这套“AI 后过滤post-filter”机制它如何用一份不到 10 行的提示词模板定义一次 LLM 判选任务如何与配套系统提示词约定“纯 JSON 整数索引数组”的输出契约以及 recall 扩展 是如何把检索到的记忆、用户消息与对话历史灌入模板、再把返回的索引拆分为“记忆”和“解决方案”两个列表注入系统提示的。读完后你可以完整理解该插件召回链路的每一段调用关系并能独立调整memory_recall_*系列参数来改变召回行为。一、提示词模板本体一个任务声明与三个占位符plugins/_memory/prompts/memory.memories_filter.msg.md 的全文如下10 行# Provide array of indices of relevant memories and solutions in relation to user message and history: ## Memories and solutions: {{memories}} ## User message: {{message}} ## History for context: {{history}}结构非常克制可分为两部分理解任务声明第 1 行以#开头的单句指令直接要求模型“提供与用户消息和历史相关的、相关记忆与解决方案的索引数组”。注意这里明确把召回结果称为memories and solutions两类合并的候选池——这与代码中把两个检索结果拼接成同一份编号列表的做法一一对应。三个数据插槽{{memories}}被召回的记忆/解决方案候选项的枚举文本模型只能从这份列表里“勾选”索引{{message}}当前这条用户消息原文是判相关性的主依据{{history}}截断后的近期对话历史仅作为上下文辅助。这种“任务句 纯数据区”的写法是该插件提示词文件的统一风格例如 memory.memories_query.msg.md 同样是两段占位符结构。它把“模型该做什么”压缩成一句把“判断依据”完全交给运行时注入的数据从而保证同一模板可以被不同长度、不同数量的候选池复用。二、输出契约纯 JSON 整数索引数组msg 模板只声明了“提供索引数组”而严格的格式约束与筛选规则写在同目录的配套系统提示词 memory.memories_filter.sys.md 中两者构成一次完整调用。sys 提示词的关键约定格式响应必须是“对应记忆索引的整数 JSON 数组没有其他任何文本、前言、解释或格式”sys 文件第 8–9 行。例如官方示例输出就是[0, 2]第 30–33 行。上下文侧重规则第 11–18 行历史靠后的内容更新近、更相关有用户消息时以用户消息为主、历史仅作上下文若记忆含时间戳把“新近”当作软信号——可变事实优先取新值而旧的持久性事实仍可能有用若多条记忆对同一可变事实冲突且能识别出哪条更新则只保留最新那条当存在更完整的当前记忆时排除已被取代、历史性、重复或低细节的片段。Never include 黑名单第 24–28 行及第 35–39 行示例像 “Pet inquiry”“Programming skills” 这种无细节的短语、问候类对话模式、无信息价值的内容一律不选示例中给出了永不相关的反例——“User has greeted me”无信息价值、“Hello world program”只有标题无细节、“Today is Monday”日期信息已过时、“Memory search”仅有标题。选择“返回索引”而非“返回记忆文本”是这套契约的核心工程决策模型不需要复述内容输出 token 极少且可机器解析同时索引天然防幻觉——返回的下标要么落在候选池内、要么无效不存在“编造一条不存在的记忆”的空间。三、召回管线后过滤在流程中的位置提示词不是孤立存在的它由 RecallMemories 扩展挂载在message_loop_prompts_after钩子上驱动。整条链路如下1. 触发闸门与超时保护扩展在每轮循环执行时先检查memory_recall_enabled默认开启见 default_config.yaml 第 2 行随后按loop_data.iteration % memory_recall_interval 0决定是否发起召回第 39 行——默认间隔为 3 轮即并非每轮都召回。检索任务通过asyncio.create_task包装并施加 30 秒超时SEARCH_TIMEOUT 30第 13、47–52 行任务句柄写入agent数据区供后续等待环节取用。2. 检索词生成query prep可选若memory_recall_query_prep为true先用工具模型utility model基于 memory.memories_query.msg.md 模板同样是{{message}}{{history}}两槽从“用户消息 历史”中提炼一条检索 query提炼结果为空或长度 ≤ 3 时直接跳过检索第 112–127 行。若为false默认直接把user_instruction \n\n history拼成 query第 120 行。历史截取逻辑在第 88 行self.agent.history.output_text()[-set[memory_recall_history_len]: ]默认取最近 10000 字符。这份 history 后续正是 msg 模板里{{history}}插槽的内容来源。3. 双路 FAISS 相似度检索检索针对 FAISS 向量库插件 README 说明了 FAISS 持久化索引机制分两路执行第 132–146 行检索路area 过滤条件数量上限参数默认上限记忆memoriesarea main or area fragmentsmemory_recall_memories_max_search12解决方案solutionsarea solutionsmemory_recall_solutions_max_search8两路都使用memory_recall_similarity_threshold默认 0.7作为相似度阈值。若两路均为空扩展直接返回并在日志中记录 “No memories or solutions found”第 148–152 行。4. 后过滤提示词模板在这里被渲染执行当memory_recall_post_filter开启时默认为false进入本文核心环节第 154–199 行# assemble an enumerated dict of memories and solutions for AI validation mems_list {i: memory.page_content for i, memory in enumerate(memories solutions)} # call AI to validate the memories filter await self.agent.call_utility_model( systemself.agent.read_prompt(memory.memories_filter.sys.md), messageself.agent.read_prompt( memory.memories_filter.msg.md, memoriesmems_list, historyhistory, messageuser_instruction, ), ) filter_inds dirty_json.try_parse(filter)对照模板可以看到三个占位符与代码实参的一一对应关系{{memories}}←mems_list把两路检索结果拼接后统一编号memories solutions以“索引: 内容”的枚举字典传给模板——这就是为什么 msg 模板的任务句会说 “memories and solutions”{{message}}←user_instruction本轮用户消息没有则为字符串None见第 86–87 行{{history}}← 第 88 行截断后的对话历史文本。模型响应经 dirty_json.try_parse 容错解析可消化模型输出中夹杂的非 JSON 杂质随后按编号空间拆回两个列表第 172–189 行mem_len len(memories) if isinstance(filter_inds, list): for idx in filter_inds: if isinstance(idx, int): if idx mem_len: filtered_memories.append(memories[idx]) # 落在记忆区 else: sol_idx idx - mem_len if sol_idx len(solutions): # 落在解决方案区 filtered_solutions.append(solutions[sol_idx])拆分逻辑完全由 msg 模板承诺的“统一索引空间”支撑小于mem_len的索引归属记忆其余偏移后归属解决方案越界索引与非整数元素被静默丢弃保证解析永不抛错中断主流程。一个值得注意的边界行为从源码结构看若过滤调用本身抛出异常如工具模型不可用代码会走except分支并把filter_inds置为[]第 195–200 行即过滤失败时本轮召回结果整体被清空fail-closed并记录一条 “Failed to filter relevant memories” 的 warning 日志——宁可本轮不带记忆也不把未经判选的候选塞进系统提示。5. 结果封顶与注入系统提示过滤后的两路列表各自截断到memory_recall_memories_max_result默认 5与memory_recall_solutions_max_result默认 3第 204–205 行日志输出 “N memories and M relevant solutions found”。最终内容通过 agent.system.memories.md 与 agent.system.solutions.md 两个提示词包装成文本块写入loop_data.extras_persistent的memories/solutions键第 222–229 行从而并入下一轮主模型的系统提示——召回结果由此真正“进入”了 Agent 的上下文。四、相关配置参数速查以下参数全部来自 plugins/_memory/default_config.yaml均支持按项目/按 Agent 覆盖见插件 README 的 Configuration Scope 一节。与后过滤链路直接相关的是加粗项参数默认值作用memory_recall_enabledtrue总开关关闭则整条召回链路不执行memory_recall_interval3每隔多少轮循环触发一次召回memory_recall_history_len10000取最近多少字符的对话历史同时作为{{history}}插槽与 query 的历史部分memory_recall_query_prepfalse是否用工具模型先提炼检索 querymemory_recall_post_filterfalse是否启用本文讨论的 AI 后过滤memory_recall_delayedfalse延迟召回模式见下节memory_recall_memories_max_search12记忆路 FAISS 检索条数上限memory_recall_solutions_max_search8解决方案路检索条数上限memory_recall_memories_max_result5过滤后注入的记忆条数上限memory_recall_solutions_max_result3过滤后注入的解决方案条数上限memory_recall_similarity_threshold0.7相似度阈值低于该值的候选直接丢弃后过滤默认关闭意味着默认行为是“检索 阈值 条数封顶”直接注入只有把memory_recall_post_filter设为true时才会额外消耗一次工具模型调用来执行 msg/sys 这对提示词。这是一组典型的成本/精度权衡参数——关闭时省一次 LLM 往返与 token 开销开启时由模型按 sys 提示词的规则剔除低价值、被取代、冲突的记忆代价是增加延迟并引入 fail-closed 风险过滤失败则本轮无记忆。五、延迟召回模式过滤结果的“跨轮注入”召回任务在第 N 轮发起但系统提示在第 N 轮拼装时任务可能尚未完成。RecallWait 扩展同目录、排序号 91 晚于 50负责取回任务句柄默认模式下直接await task等待召回完成再放行若memory_recall_delayed为true且任务是在本轮发起的第 22–27 行则不等待仅向临时 extras 插入一段 memory.recall_delay_msg.md 提示文本召回结果顺延到下一轮才进入系统提示。无论哪种模式后过滤的产出经memories_filter判选后的索引拆分结果最终都走第五节描述的 extras 注入路径。六、工程要点小结提示词即接口msg 模板用一句任务声明 三个命名插槽定义了后过滤的输入契约sys 模板定义输出契约纯 JSON 整数数组两侧代码只做“填充插槽”和“解析数组”提示词承担了几乎全部业务语义相关性判断、新旧冲突取舍、黑名单。索引代替文本让模型输出候选池下标而非复述内容输出短、可机解析、天然防幻觉解析端再用mem_len边界把统一索引空间拆回两路结果。多层防御isinstance(idx, int)校验、越界丢弃、dirty_json容错解析、异常时 fail-closed 清空结果保证工具模型的任何异常输出都不会把脏数据写进主模型的系统提示。可插拔成本后过滤是独立开关默认关闭适合在“响应延迟敏感”与“记忆信噪比”之间按部署场景取舍。以上全部机制可在 plugins/_memory 插件目录内交叉验证提示词位于 prompts/ 目录召回与过滤主逻辑位于 extensions/python/message_loop_prompts_after/默认参数位于 default_config.yaml。【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
