Agent Zero 记忆固化机制深度解析memory.consolidation.sys.md 如何驱动记忆的自动合并、替换与去重【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero在 Agent Zero 的_memory插件中每一条自动提取的记忆在写入向量库之前都会先经过一个由 LLM 执行的“固化分析”Memory Consolidation决策把新记忆与库中相似记忆放在一起比较然后选择合并、替换、更新、保留独立或跳过。本文以 memory.consolidation.sys.md 这份固化分析系统提示词为主体完整解读它定义的决策模型、分析准则与 JSON 输出契约并结合 memory_consolidation.py 的实现源码说明这些准则在代码中如何被强制执行、失败时如何兜底帮助读者理解 Agent Zero 如何长期保持高质量、不冗余的记忆存储。一、固化分析在记忆流水线中的位置固化分析提示词位于 plugins/_memory/prompts/ 目录下是整个记忆插件提示词族中的一环同目录还有 memory.keyword_extraction.sys.md为检索提取关键词、memory.memories_query.sys.md、memory.memories_filter.sys.md记忆召回查询与过滤等分别服务于“写入”和“召回”两条链路。固化分析属于写入链路的最后一道关口。从源码结构看完整写入流程如下每轮会话monologue结束时扩展 _50_memorize_fragments.py 被触发它把聊天历史交给 utility LLM 抽取候选记忆片段候选片段先经过 memory_quality.py 中的is_auto_fragment_worth_saving正则质量闸门过滤掉动作历史、临时路径、命令输出等“一次性”内容对应测试见 test_memory_quality.py通过闸门的每条记忆交由MemoryConsolidator处理先做相似记忆检索再把“新记忆 相似记忆 元数据”组装成消息配合本文解读的系统提示词调用 LLM得到一个固化的 JSON 决策代码按action字段分派到具体的数据库操作删除/插入/更新。因此memory.consolidation.sys.md不是一份孤立的文案而是“LLM 决策层”的规格说明书代码负责执行与兜底提示词负责决策规则。二、核心决策模型五种固化动作提示词开篇定义了分析专家的职责Your Mission分析一条新记忆及其相似既有记忆判断应采取哪种策略merge把多条记忆合并成一条综合性记忆删除原始条目replace用新版本替换过时的记忆适用于新信息与旧信息直接矛盾或使其作废update把同一主题上已有记忆改写为最新的完整版本不再额外新增一条记忆keep_separate新记忆与既有记忆服务于不同目的时各自独立保留skip没有值得执行的固化操作时直接简单插入新记忆。同时提示词给出了一条关键的默认偏向Default bias对于可变的用户偏好、项目状态、配置选择、名字、位置、活跃任务或关于同一主题的“当前”事实优先选择update或replace而不是再追加一条独立的记忆。这条原则直接针对“同一事实随时间反复堆积”这一 LLM 记忆系统的常见退化问题源码中的_handle_update实现也与之呼应UPDATE 语义是“重填已有主题”而不是“再挂一条同等重要的记忆”见 memory_consolidation.py 中“仅在没有任何既有记忆被更新时才插入新记忆”的逻辑。五种动作与源码中的ConsolidationAction枚举一一对应memory_consolidation.pyLLM 返回的action字符串会被解析为该枚举解析失败时回退为SKIP。三、六项固化分析准则逐条解读提示词的 “Consolidation Analysis Guidelines” 部分是决策规则的核心共六条。这里逐条说明其含义以及源码对它的实现印证。3.1 相似分感知Similarity Score Awareness高相似分0.9内容高度相似适合替换REPLACE中等相似分0.7–0.9相关但独立的内容对 REPLACE 需谨慎低相似分0.7主题相关但内容不同应避免 REPLACE。这条准则给 LLM 一个“证据强度”标尺候选记忆的_consolidation_similarity分数是真实余弦相似度由检索阶段写入doc.metadata见 _find_similar_memories。代码层还叠加了一道硬性安全闸ConsolidationConfig.replace_similarity_threshold默认 0.75_handle_replace执行前会复核待删记忆的相似分低于阈值的 REPLACE 会被自动降级为 KEEP_SEPARATE并在元数据中标记consolidation_action: keep_separate_safety、original_action: replacememory_consolidation.py。也就是说提示词中的“谨慎”在代码里被落实为一个可配置的熔断阈值。需要注意两个阈值的分工0.7similarity_threshold是“发现相似记忆”的检索门槛0.75replace_similarity_threshold是“允许删除旧记忆”的安全门槛。前者在 memory_load.py 中定义为DEFAULT_THRESHOLD 0.7并被复用后者注释说明是“为真实余弦相似度调优过的值”。3.2 时间智能Temporal Intelligence新信息通常取代旧信息时间戳是“软”的新近度信号不是自动 TTL——年代久远本身不会让一条持久记忆失效仅当用户明确需要历史或审计轨迹时才保留历史上下文当新记忆明确给出当前状态时不要将旧偏好保留为同等重要的记忆对可变事实优先考虑新近性仍有用且未被新信息推翻的稳定旧事实应当保留。这一条把“记忆去旧”与“记忆删除”区分开可变事实偏好、端点、配置应收敛为单一“当前版本”而稳定的历史事实不受时间侵蚀。这与 3.5 的知识源意识配合决定了哪些记忆可以安全改写。3.3 内容关系Content Relationships互补信息应合并为更完整的记忆矛盾信息需仔细分析哪个更准确、更当前重复内容应合并去重相关但独立的主题适合分开保留同一主题、数值发生变化时通常应 update 或 replace而不是 keep_separate。最后一条与“Default bias”呼应是防止“同主题多版本并存”的关键判据。3.4 质量评估Quality Assessment保留更详细、更完整的信息模糊或不完整的记忆可以被补充具体细节增强事实准确性优先于推测保持实际可用性。3.5 元数据保留Metadata Preservation时间戳应保留以维持时间上下文来源信息在合并时应被归并重要度分数应反映固化后记忆的价值。源码中_gather_consolidated_metadata正是这条准则的实现它先以新记忆元数据为基底再逐一并入所有被合并/更新记忆的元数据字段字段冲突时保留新记忆的值唯一的特例是tags列表做去重并集memory_consolidation.py。3.6 知识源意识Knowledge Source Awareness区分Knowledge Sources来自导入文件与Conversation Memories来自聊天知识源通常更权威应谨慎保留除非有明确收益避免把知识源与对话记忆合并固化来自不同文件的知识时保留源文件信息知识源承载事实性信息对话记忆承载经验性学习。四、输出契约固化决策 JSON提示词要求 LLM 以严格的 JSON 对象返回分析结果这是 LLM 与代码之间的数据契约{ action: merge|replace|keep_separate|update|skip, memories_to_remove: [id1, id2], memories_to_update: [ { id: memory_id, new_content: updated memory content, metadata: {additional: metadata} } ], new_memory_content: final consolidated memory text, metadata: { consolidated_from: [id1, id2], historical_notes: summary of older information, importance_score: 0.8, consolidation_type: description of consolidation performed }, reasoning: brief explanation of decision and consolidation strategy }各字段在代码中的消费方式_analyze_memory_consolidation值得注意字段代码行为action解析为ConsolidationAction非法值回退为SKIPmemories_to_removeMERGE/REPLACE 时按 ID 删除旧记忆REPLACE 前做相似分安全复核memories_to_updateUPDATE 时逐条“删旧插新”并写入updated_from溯源字段new_memory_contentMERGE/REPLACE 时若为空视为错误不回填原文KEEP_SEPARATE/UPDATE/SKIP 时可回退为新记忆原文metadata与新记忆原始元数据合并冲突时 LLM 元数据优先consolidated_from等溯源信息入库reasoning仅写入日志不存入记忆元数据源码中明确注释“do not include reasoning in memory”LLM 响应通过DirtyJson.parse_string容错解析容忍被包裹、带注释等非严格 JSON整个分析步骤若抛异常回退为SKIP并记录失败原因保证记忆写入永不因固化失败而中断。消息侧的模板为 memory.consolidation.msg.md由代码填充五个占位符{{area}}记忆区域如 FRAGMENTS、{{current_timestamp}}、{{new_memory}}、{{new_memory_metadata}}JSON 序列化的初始元数据以及{{similar_memories}}按“ID Timestamp Content”逐条拼接的相似记忆文本。系统提示词本文主体则原样读取不做模板替换。五、典型固化场景与 REPLACE 安全准则提示词给出了三组示例场景它们同时是理解决策边界的最佳材料场景 1合并相关信息merge新记忆“Alpine.js 表单验证应使用 x-on:submit.prevent 处理表单提交”既有记忆“Alpine.js 表单需要正确的用户交互事件处理”判定merge→ 生成一条更完整的 Alpine.js 表单处理记忆。场景 2替换过时信息replace新记忆“API 端点已更新为 /api/v2/users取代 /api/users”既有记忆“获取用户数据的端点是 /api/users”判定replace→ 更新为新端点并在historical_notes中记录变更。场景 2b更新当前偏好update新记忆“用户现在偏好带示例的简洁技术回答”既有记忆“用户偏好长篇探索式回答”判定update→ 将既有的用户偏好记忆改写为新的当前偏好不要把两者都保留为同等重要的记忆。场景 3不同上下文保持独立keep_separate新记忆“Python async/await 语法用于处理并发操作”既有记忆“Python 列表推导式用于高效数据处理”判定keep_separate→ 同属 Python 但是不同概念。REPLACE 的使用条件与安全问题在提示词中被单独强调REPLACE 条件——满足以下情形时可用 replace高相似分0.9表明内容高度相似新信息直接矛盾既有信息版本更新使旧版本作废Bug 修复或更正取代旧信息官方变更覆盖先前表述。REPLACE 安全——只替换高相似分的记忆中等相似分时优先 MERGE 或 KEEP_SEPARATE以保留独立信息。如前所述代码把这条“安全”要求量化为replace_similarity_threshold默认 0.75越界的替换会被静默降级为带安全标记的独立插入而不是报错。六、源码纵深固化管线的执行细节6.1 配置参数ConsolidationConfigConsolidationConfig 定义了管线的可调参数均可通过 create_memory_consolidator 工厂函数的关键字覆盖参数默认值作用similarity_threshold0.7复用 memory_load 的 DEFAULT_THRESHOLD相似记忆发现门槛max_similar_memories10检索阶段最多发现多少条相似记忆max_llm_context_memories5实际送入 LLM 分析的相似记忆条数上限replace_similarity_threshold0.75REPLACE 安全复核阈值processing_timeout_seconds60整体处理超时超时返回失败而非阻塞consolidation_sys_prompt/consolidation_msg_promptmemory.consolidation.sys.md/memory.consolidation.msg.md系统/消息提示词文件名keyword_extraction_sys_prompt/keyword_extraction_msg_promptmemory.keyword_extraction.sys.md/.msg.md关键词提取提示词文件名6.2 相似记忆检索语义 关键词双通道_find_similar_memories 的检索策略是六步用 memory.keyword_extraction.sys.md 指导 utility LLM 从新记忆中提取 2–4 个搜索关键词该提示词要求聚焦关键概念、实体、动作动词与领域术语输出纯 JSON 字符串数组若提取失败则回退为“取首句/前 200 字符”作为查询以新记忆全文做一次语义检索阈值 0.7过滤条件限定在当前记忆区域area {area}以每个关键词再做一轮检索按记忆 ID 去重同一 ID 保留最高相似分按相似分降序排序截取前max_llm_context_memories条送入 LLM。每条候选记忆的相似分都写入metadata[_consolidation_similarity]这就是提示词“相似分感知”准则的数据来源。6.3 竞态防护与降级路径管线对“分析期间相似记忆被并发删除”的情况做了显式处理LLM 分析前会先用get_by_ids校验候选记忆仍然存在过滤掉已删除项日志中标记race_condition_detected若全部被过滤则直接插入。此外还有两层降级无相似记忆 → 直接插入direct_insertLLM 判定 SKIP 或分析异常 → 直接插入新记忆skip。也就是说固化系统的所有失败模式都收敛为“至少把新记忆安全插入库中”不会出现记忆丢失。6.4 各动作的落库语义_apply_consolidation_result按动作分派memory_consolidation.pyKEEP_SEPARATE插入新记忆不触碰既有记忆MERGE先删memories_to_remove再插入合并文本元数据带consolidated_from溯源列表REPLACE先做相似分安全复核不达标则降级为keep_separate_safety独立插入达标后删旧插新元数据带replaced_memoriesUPDATE对memories_to_update中每条“存在性校验 → 删旧版本 → 插入新版本”元数据带updated_from只有当没有任何既有记忆被更新时才把new_memory_content作为新条目插入——这正是提示词“不追加额外记忆”原则的代码化。所有插入都会带上area、timestamp本地化 ISO 时间与consolidation_action字段使每条入库记忆都可追溯其固化路径。七、上游接入从配置项看固化行为的开关插件的默认配置 default_config.yaml 控制整条写入链memory_memorize_enabled: true # 开启会话结束时的自动记忆提取 memory_memorize_consolidation: true # 开启智能固化关闭后走简单替换模式 memory_memorize_replace_threshold: 0.9 # 关闭固化时的“相似即替换”删除阈值当memory_memorize_consolidation为 true 时_50_memorize_fragments.py 会为每条通过质量闸门的片段创建固化器实际运行参数为similarity_threshold0.7、max_similar_memories8、max_llm_context_memories4并把记忆写入FRAGMENTS区域为 false 时则退化为“简单替换”模式对超过memory_memorize_replace_threshold0.9的旧片段直接删除后插入不使用 LLM 决策。手动写入路径同样存在memory_save工具memory_save.py将指定文本插入指定区域而召回侧的memory_load工具memory_load.py默认以 0.7 阈值、10 条上限做相似度检索——与固化管线共用同一套阈值常量体现了“写入发现”与“读回检索”的一致标准。八、质量原则与工程启示提示词结尾的 “Quality Principles” 归纳了五条总纲Preserve Knowledge固化过程中永不丢失重要信息Improve Organization形成更清晰、更易访问的记忆结构Maintain Context在相关处保留时间与来源信息Enhance Searchability通过固化提升未来记忆检索效果Reduce Redundancy消除不必要的重复同时保留细微差别Keep Current Facts Current对可变事实最终记忆应代表最新可用状态而非人类式地归档每一个旧版本。从工程视角看这份提示词展示了 LLM 记忆系统中一种典型而稳妥的“提示词定规则、代码守底线”的设计语义层面的判断哪些该合并、哪些该替换交给 LLM 并给出可解释的 JSON 契约而删除操作的安全性相似分下限、并发竞态存在性校验、模型输出不可靠DirtyJson 容错、非法动作回退 SKIP、整体超时兜底则由确定性代码硬约束。理解这一分层是复用或改造 Agent Zero 记忆系统例如调整阈值、自定义提示词、扩展动作类型的前提。参考路径固化分析系统提示词本文主体plugins/_memory/prompts/memory.consolidation.sys.md固化分析消息模板plugins/_memory/prompts/memory.consolidation.msg.md关键词提取提示词plugins/_memory/prompts/memory.keyword_extraction.sys.md固化管线实现plugins/_memory/helpers/memory_consolidation.py自动记忆质量闸门plugins/_memory/helpers/memory_quality.py会话结束记忆提取扩展plugins/_memory/extensions/python/monologue_end/_50_memorize_fragments.py插件默认配置plugins/_memory/default_config.yaml记忆读写工具plugins/_memory/tools/memory_save.py、plugins/_memory/tools/memory_load.py质量闸门测试tests/test_memory_quality.py【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考