Agent Zero 记忆检索未命中反馈：解析 fw.memories_not_found.md 标准消息模板

Agent Zero 记忆检索未命中反馈解析 fw.memories_not_found.md 标准消息模板【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero导读本文聚焦 Agent Zero AI framework 中的fw.memories_not_found.md提示词模板深入剖析其在持久化记忆检索链路中的定位与作用。你将了解到该模板如何在memory_load工具执行向量相似度检索未命中时被触发{{query}}占位符如何被真实查询词替换以及底层 FAISS 检索的相似度阈值机制与相关配置项。读完本文你既能看懂这条消息从触发到渲染的完整调用链也能掌握调整记忆召回灵敏度如threshold与limit的实操方法。一、模板内容与定位prompts/fw.memories_not_found.md是 Agent Zero 框架消息framework message体系中的一员全文如下{ memory: No memories found for specified query: {{query}} }这是一个结构极其精简的 JSON 模板只包含一个memory字段值是一条英文提示语其中{{query}}是待渲染的占位符。它不属于普通对话提示而是供工具tool在执行结果中返回的结构化反馈消息——当 Agent 尝试从记忆库中检索与查询相关的记忆却一无所获时系统使用该模板告知上层调用方“本次检索未命中”。从仓库目录结构看这类fw.*.md文件统一存放在 prompts 目录下与fw.memories_deleted.md记忆删除成功反馈、fw.msg_truncated.md消息截断提示、fw.tool_result.md工具结果包装模板等同属一类均由代码通过read_prompt按文件名动态加载。二、触发场景memory_load 工具的执行路径该模板唯一的生产调用点位于记忆插件_memory的memory_load工具中源码见 plugins/_memory/tools/memory_load.py。MemoryLoad继承自helpers.tool.Tool核心执行逻辑如下DEFAULT_THRESHOLD 0.7 DEFAULT_LIMIT 10 async def execute(self, query, thresholdDEFAULT_THRESHOLD, limitDEFAULT_LIMIT, filter, **kwargs): if threshold is None or threshold : threshold DEFAULT_THRESHOLD if limit is None or limit : limit DEFAULT_LIMIT threshold float(threshold) limit int(limit) db await Memory.get(self.agent) docs await db.search_similarity_threshold(queryquery, limitlimit, thresholdthreshold, filterfilter) if len(docs) 0: result self.agent.read_prompt(fw.memories_not_found.md, queryquery) else: text \n\n.join(Memory.format_docs_plain(docs)) result str(text) return Response(messageresult, break_loopFalse)关键链路可概括为三步参数规整threshold与limit若为空则回退到默认值0.7与10并做类型转换float/int向量检索调用db.search_similarity_threshold(...)执行相似度检索结果分叉命中数len(docs) 0时渲染fw.memories_not_found.md模板命中时则拼接所有文档文本直接返回。值得注意的是read_prompt的调用方式——文件名fw.memories_not_found.md不带路径前缀说明 prompt 加载遵循项目统一的命名解析机制queryquery将用户查询词注入{{query}}占位符从而生成类似No memories found for specified query: how to deploy的最终消息。返回值语义return Response(messageresult, break_loopFalse)break_loopFalse表示检索未命中不会中断 Agent 的主循环——工具正常返回Agent 可以继续后续推理与行动。这保证了“没有记忆”本身也是一种合法、温和的状态反馈而非异常中断。三、底层原理相似度阈值检索如何判定“未命中”未命中判定的核心实现在Memory.search_similarity_threshold见 plugins/_memory/helpers/memory.pyasync def search_similarity_threshold( self, query: str, limit: int, threshold: float, filter: str ): comparator Memory._get_comparator(filter) if filter else None return await self.db.asearch( query, search_typesimilarity_score_threshold, klimit, score_thresholdthreshold, filtercomparator, )可以看到检索方式为similarity_score_threshold即相似度得分必须不低于threshold才返回低于阈值的文档一律被过滤klimit限制最多返回的文档数filter参数会通过Memory._get_comparator(filter)构建元数据比较器用于按子目录等条件收窄检索范围。由此可以推断“未命中”的两种典型成因记忆库为空尚未保存任何记忆或当前记忆子目录下没有内容相似度低于阈值库中虽有记忆但与查询语义距离过远score_threshold0.7将其全部过滤。此外仓库还提供了search_similarity_threshold_with_scoresmemory.py这一带得分返回的检索变体供需要展示相关度的场景使用其过滤逻辑与上述一致。命中时的文本格式化当检索命中时Memory.format_docs_plainmemory.py负责把Document列表转为纯文本staticmethod def format_docs_plain(docs: list[Document]) - list[str]: result [] for doc in docs: text for k, v in doc.metadata.items(): text f{k}: {v}\n text fContent: {doc.page_content} result.append(text) return result每条记忆按元数据键: 值逐行输出最后附上Content: 正文内容多条记忆以空行分隔。这种结构化纯文本正是“未命中”模板所要替代的内容形态——有结果时是若干条格式化记忆无结果时则是统一的未命中提示。四、阈值与限额影响“未命中”频率的配置项未命中是否频繁出现直接受相似度阈值和检索数量影响。相关默认配置集中在 plugins/_memory/default_config.yamlproject_memory_isolation: true memory_recall_enabled: true memory_recall_delayed: false memory_recall_interval: 3 memory_recall_history_len: 10000 memory_recall_memories_max_search: 12 memory_recall_solutions_max_search: 8 memory_recall_memories_max_result: 5 memory_recall_solutions_max_result: 3 memory_recall_similarity_threshold: 0.7 memory_recall_query_prep: false memory_recall_post_filter: false memory_memorize_enabled: true memory_memorize_consolidation: true memory_memorize_replace_threshold: 0.9 agent_memory_subdir: default与本文主题直接相关的调优建议配置项默认值对未命中的影响memory_recall_similarity_threshold0.7阈值越高检索越严格越容易触发未命中反馈memory_recall_memories_max_search12自动回忆时的最大候选搜索数memory_recall_memories_max_result5自动回忆时最终返回的记忆条数上限agent_memory_subdirdefault记忆存储的子目录决定检索范围子目录为空必然未命中其中memory_recall_similarity_threshold: 0.7与memory_load.py中DEFAULT_THRESHOLD 0.7完全一致二者共同构成了“默认 0.7 相似度门槛”的项目级约定。五、同类模板对照未命中、已删除与工具结果为了准确理解fw.memories_not_found.md的“反馈消息”属性可将其与同一体系下的两个兄弟模板对照记忆删除成功——prompts/fw.memories_deleted.md{ memories_deleted: {{memory_count}} }由memory_delete.py与memory_forget.py在批量删除后通过read_prompt(fw.memories_deleted.md, memory_countlen(dels))渲染返回被删除条数。工具结果通用包装——prompts/fw.tool_result.md{ tool_name: {{tool_name}}, tool_result: {{tool_result}} }用于将任意工具的名称与执行结果包装成统一 JSON 结构回传。三者对比可见fw.*模板承载的是框架级、跨工具的标准化反馈契约字段名memory/memories_deleted/tool_name即消息语义的机器可读标识值则为人类可读的文本或计数。fw.memories_not_found.md正是这一契约在“记忆检索空结果”场景下的实现。六、从消息到行为Agent 侧的使用建议在实际使用 Agent Zero 的记忆功能时理解这条未命中消息有助于正确解读 Agent 行为它不是错误break_loopFalse意味着未命中只是正常返回Agent 会继续执行无需将其视为故障排查点它是信号频繁出现该消息往往提示记忆库内容不足或查询与已存记忆语义偏差过大此时可考虑降低memory_recall_similarity_threshold、增加记忆写入频率或检查agent_memory_subdir是否指向了正确的子目录它是可追踪的由于消息中嵌入了原始{{query}}通过日志可以反查“哪些查询在何时未命中”为记忆质量优化提供数据线索。结语fw.memories_not_found.md虽仅有一行 JSON却是 Agent Zero 记忆子系统“空结果语义”的规范化表达它由memory_load工具在向量检索零命中时触发经read_prompt注入真实查询词后返回给 Agent与 FAISS 的similarity_score_threshold检索策略及0.7默认阈值共同构成了完整的未命中判定闭环。理解这条模板就等于理解了 Agent Zero 记忆召回机制中“查无此忆”这一关键分支的行为契约。【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考