Agent Zero Memory 插件实战基于 FAISS 的持久向量记忆、知识预加载与自动策展体系【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zeroAgent Zero 的_memory插件为 Agent 提供持久化、基于向量的长期记忆它将记忆与知识片段以嵌入embedding形式存入 FAISS 向量数据库暴露memory_save/memory_load等工具并通过扩展点在每轮对话中自动召回相关记忆、自动沉淀新的持久信息再配合 Web 仪表盘完成人工浏览、编辑与删除。读完本文你将理解该插件的存储模型与目录隔离机制、全部配置参数的含义与默认值、五大记忆工具的使用方式以及“自动记忆 → 整合 → 召回”这条完整链路的源码实现从而能自主调优 Agent Zero 的长期记忆行为。插件定位与整体能力插件元数据定义了该插件的身份name: _memory title: Memory description: Provides persistent memory capabilities to Agent Zero agents. version: 1.0.0 settings_sections: - agent per_project_config: true per_agent_config: true几个关键点配置归属agent设置区所有记忆相关开关都出现在 Agent 设置中支持按项目、按 Agent 覆盖配置per_project_config: true、per_agent_config: true这意味着同一个部署里不同 Agent 或不同项目可以拥有完全不同的记忆策略例如一个研究型 Agent 开启激进记忆、一个轻量 Agent 关闭自动记忆。从 README 的 “Main Behavior” 一节可以归纳出插件的六大能力后文逐一展开持久化向量存储FAISS 索引 嵌入元数据知识预加载Knowledge preloading记忆工具保存/加载/删除/遗忘/行为调整自动对话记忆过滤瞬态信息后沉淀持久信息仪表盘 API搜索、删除、批量删除、更新、子目录列表作用域存储按子目录隔离不同上下文或 Agent 的记忆。存储引擎FAISS 索引、嵌入缓存与索引自愈核心引擎在 helpers/memory.py。Memory类以memory_subdir记忆子目录为键维护一个进程内索引缓存Memory.index: dict[str, MyFaiss]每个子目录对应一个独立的 FAISS 库。目录与文件布局usr/memory/subdir/每个记忆子目录一个 FAISS 库目录内含index.faiss、embedding.json等tmp/memory/embeddings/嵌入结果的缓存存储LocalFileStore源码注释明确写着 “just caching, no need to parameterize”即该缓存可以安全重建项目场景下projects/name子目录会被abs_db_dir()重定向到项目元数据目录内的memory/子目录这是项目记忆隔离的物理基础见后文。初始化与嵌入模型绑定Memory.initialize()的初始化流程值得拆解通过models.get_embedding_model()构建嵌入模型并用CacheBackedEmbeddings.from_bytes_store()包一层本地字节缓存缓存命名空间为provider_model的安全化文件名——相同文本不会重复调用嵌入 API若库目录已存在index.faiss先做哈希校验_write_index_hash()每次保存索引时都会写一份index.faiss.sha256加载时_verify_index_hash()比对不一致则打印警告并触发整库重建防止加载损坏索引读取embedding.json元文件核对其中的model_provider与model_name是否与当前配置一致只要嵌入模型发生过变更旧文档就会被取出get_all_docs()后用新模型整库重新索引——这就是 README 所说 “Stores embedding metadata so the index can be rebuilt if the embedding model changes” 的底层实现新建索引使用faiss.IndexFlatIP内积配合DistanceStrategy.COSINE与自定义_cosine_normalizer将余弦相似度归一到0~1区间并夹取浮点误差如1.0000000596046448到[0, 1]。此外还有一组扩展点配合自愈embedding_model_changed/_10_memory_reload.py 在检测到嵌入模型变更时清空Memory.index强制所有库重新加载。安全过滤filter 表达式的白名单求值向量检索支持按 metadata 过滤如areamain其实现_get_comparator()是一个安全敏感点过滤条件长度上限 512且必须先通过一个字符白名单正则只允许字母、数字、下划线、点、引号、比较/逻辑符号等否则直接拒绝并返回恒假比较器通过白名单后使用simpleeval.simple_eval在metadata字典的命名空间上求值不开放任何函数functions{}。这意味着 Agent 调用memory_load时传入的filter无法执行任意 Python属于仓库内置的注入防护。记忆分区Area与知识预加载Memory.Area枚举定义了三个分区分区用途main一般性记忆与知识未显式指定 area 时默认落入此处fragments自动记忆管线沉淀的对话碎片solutions问题解决方案召回阶段会按分区分别检索见“自动召回”一节删除与替换逻辑也按分区过滤避免误伤。知识目录的加载规则preload_knowledge()在数据库初始化时执行memory.py#L259-L335读取db_dir/knowledge_import.json增量索引每个知识文件对应的文档 ID 列表对每个知识子目录根目录下的文件直接归入main分区非递归fragments/、solutions/等子目录则归入同名分区递归依据索引中的state字段做增量维护状态为changed的文件先删除旧 ID 再插入新文档状态为removed的文件只删除旧 ID维护完成后把state、documents等临时字段从索引中剥离再落盘使索引长期保持轻量。知识导入的解析逻辑由 helpers/knowledge_import.py 承担而api/import_knowledge.py与api/knowledge_reindex.py提供从 Web 端触发导入与重建索引的入口。作用域隔离子目录、项目与 Agenthelpers/memory.py 中的get_agent_memory_subdir()决定了 Agent 实际使用哪个记忆库优先级如下若插件配置project_memory_isolation为真默认true且当前上下文处于某个项目中返回projects/项目名否则回退到agent_memory_subdir配置项默认default。物理路径映射abs_db_dir()/abs_knowledge_dir()标准子目录 →usr/memory/subdir记忆、knowledge/default或usr/knowledge/subdir自定义projects/name前缀 → 项目元数据目录下的memory/与knowledge/从而项目记忆与全局记忆在文件层面完全隔离。get_existing_memory_subdirs()会同时枚举usr/memory/下的子目录和所有含memory/index.faiss的项目目录供仪表盘的 “Memory Directory” 下拉框使用。这种设计使“按上下文/Agent 拆分记忆”README 的 Scoped storage 条目成为开箱即用能力你只需为不同 Agent 配置不同的agent_memory_subdir。五大记忆工具工具实现集中在 plugins/_memory/tools/其行为说明由提示词 agent.system.tool.memory.md 注入系统提示。各工具签名与语义如下memory_save — 保存记忆tools/memory_save.pyexecute(self, text, area, **kwargs)。未指定area时默认main其余 kwargs 全部并入文档 metadata 一并存储。返回fw.memory_saved.md模板并附带memory_idAgent 可以据此后续精确操作该条记忆。memory_load — 相似度检索tools/memory_load.py参数默认值说明query必填检索语句threshold0.7余弦相似度阈值0~1limit10返回条数上限filtermetadata 过滤表达式如areamain一个值得注意的细节threshold与limit接受原生数字或数字字符串工具内部会强制float()/int()转换后再进入向量检索——这是对 LLM 工具调用经常传出字符串参数的防御性处理在 AGENTS.md 的 Local Contracts 一节也有明确约定。无结果时返回fw.memories_not_found.md模板而非报错。memory_delete — 按 ID 删除级联tools/memory_delete.py 接收逗号分隔的ids调用delete_documents_by_ids(ids, cascadeTrue)。cascadeTrue会触发_find_related_docs_by_ids()扫描全库 metadata凡引用了被删 ID 的文档如整合派生的碎片/方案记录一并删除保证删除是“干净”的。memory_forget — 按语义“遗忘”tools/memory_forget.py 按querythreshold默认0.7filter删除对应底层delete_documents_by_query()以k100分批做相似度搜索直到命中数小于批大小为止避免一次删除被 k 截断include_exactTrue会额外做精确文本匹配兜底把 query 归一化小写、压空白后在全文metadata JSON 中做子串扫描要求 query 长度 ≥ 3 字符清除向量检索可能漏掉的完全重复项cascadeTrue同memory_delete清理派生记录。系统提示词还给出了使用纪律不要仅因记忆“老”就遗忘它只有在当前证据表明它过时、错误、被取代、重复或 unwanted 时才遗忘对可变事实如偏好更新应先 load 相关旧记忆 → forget/delete 被取代版本 → 保存唯一的新版本而不是追加第二条。behaviour_adjustment — 行为规则持久化tools/behaviour_adjustment.py 是一个特殊工具它不操作向量库而是维护记忆目录下的behaviour.md规则文件读取当前规则集无behaviour.md时回退到默认模板agent.system.behaviour_default.md用工具模型utility model把“现有规则 用户要求的调整”合并成新规则集并流式记录到日志normalize_ruleset()做文本规整剥掉代码围栏、统一换行、去重结构行、压缩连续空行写回get_custom_rules_file()指向的记忆目录内behavior.md。与之配套system_prompt/_20_behaviour_prompt.py 扩展点会把该规则文件注入系统提示实现“用户说一次Agent 永久改变行为习惯”的闭环。自动记忆管线从对话到碎片再到整合README 的 “Automatic conversation memory” 能力由extensions/python/下的扩展点串成一条流水线。召回message_loop_prompts_after/_50_recall_memories.pyRecallMemories 扩展在提示词组装后介入逻辑如下受memory_recall_enabled总开关控制按memory_recall_interval默认 3控制触发频率每 N 个循环迭代触发一次第一次也触发查询构造有两条路径memory_recall_query_preptrue时调用工具模型基于“最近memory_recall_history_len默认 10000字符的对话历史 当前用户消息”生成一段精炼检索查询失败则跳过本次检索关闭时直接拼接用户消息与对话历史作为查询检索设置 30 秒超时asyncio.wait_for且把任务句柄放进 agent data_recall_memories_task供 _91_recall_wait.py 在需要时等待完成分区检索mainfragments按memory_recall_memories_max_search默认 12取solutions按memory_recall_solutions_max_search默认 8取均受memory_recall_similarity_threshold默认 0.7约束memory_recall_post_filtertrue时再调用一次工具模型对候选做二次筛选输出 JSON 下标列表经dirty_json.try_parse解析剔除相关性不足的条目最终截断到memory_recall_memories_max_result默认 5与memory_recall_solutions_max_result默认 3分别渲染进 agent.system.memories.md 与 agent.system.solutions.md 两个系统提示片段完成“记忆进上下文”。沉淀monologue_end/_50_memorize_fragments.pyMemorizeMemories 扩展在独白monologue结束时运行受memory_memorize_enabled控制且整个流程放到后台线程DeferredTask执行不阻塞主循环取对话历史截断到最近 80000 字符以防工具模型上下文溢出用工具模型按 memory.memories_sum.sys.md 提示词抽取“持久信息”输出经DirtyJson容错解析关键质量关口filter_auto_memory_fragments()实现于 helpers/memory_quality.py在入库前过滤瞬态的行动历史碎片——这正是 README “filtering transient action-history fragments before insertion” 与 AGENTS 文档 “Avoid storing transient action-history noise as durable memory” 契约的代码落点入库策略分两种memory_memorize_consolidationtrue默认走 memory_consolidation.py 的智能整合。create_memory_consolidator()以相似度阈值 0.7、最多 8 条相似记忆、LLM 上下文最多 4 条记忆为参数对每条新碎片先检索近邻再决定是替换、合并还是新增从而让碎片库有界、去重关闭整合时若memory_memorize_replace_threshold 0默认 0.9先按该阈值删除 fragments 分区中的高相似旧碎片再插入新碎片——即用一条新记忆直接顶替旧记忆。另有 _51_memorize_solutions.py 以同样机制把“问题 → 解决方案”沉淀到solutions分区。初始化monologue_start/_10_memory_init.pyMemoryInit 扩展在独白开始时调用Memory.get(agent)确保该 Agent 对应的向量库已加载并完成知识预加载之后所有工具与扩展才能安全使用。配置参数全解default_config.yaml 给出全部默认值配合 plugin.yaml 的settings_sections: [agent]与两个 per-config 开关可在 全局 / 项目 / Agent 三层覆盖。# 作用域 project_memory_isolation: true # 项目内记忆隔离到 projects/name 库 agent_memory_subdir: default # 非项目场景使用的记忆子目录 # 自动召回recall memory_recall_enabled: true # 自动召回总开关 memory_recall_delayed: false # 召回任务是否延迟等待 memory_recall_interval: 3 # 每 N 个循环迭代触发一次召回 memory_recall_history_len: 10000 # 参与召回的历史字符数上限 memory_recall_memories_max_search: 12 # mainfragments 检索候选上限 memory_recall_solutions_max_search: 8 # solutions 检索候选上限 memory_recall_memories_max_result: 5 # 注入提示词的记忆条数上限 memory_recall_solutions_max_result: 3 # 注入提示词的方案条数上限 memory_recall_similarity_threshold: 0.7 # 相似度阈值余弦0~1 memory_recall_query_prep: false # 是否用工具模型生成精炼检索查询 memory_recall_post_filter: false # 是否用工具模型对候选做二次筛选 # 自动沉淀memorize memory_memorize_enabled: true # 自动记忆总开关 memory_memorize_consolidation: true # 智能整合替换/合并/新增 memory_memorize_replace_threshold: 0.9 # 非整合模式下替换旧碎片的相似度阈值调参建议基于实现行为想降低召回噪音提高memory_recall_similarity_threshold或调小两个max_result开启query_prep会多花一次工具模型调用但查询更聚焦想控制记忆库膨胀保持consolidationtrue整合器会把碎片归并关闭整合时把memory_memorize_replace_threshold设为接近 1 的值如 0.9可自动顶替高度重复的碎片多 Agent 协作场景给不同 Agent 配置不同agent_memory_subdir在文件层面实现记忆互不干扰。仪表盘 API 与 Web 界面api/memory_dashboard.py 的MemoryDashboard处理器按action字段分派六个动作action说明search按memory_subdir/area/search/limit默认 100/threshold默认 0.6检索无查询词时返回按时间倒序的全量受 limit 截断并统计知识条目与对话记忆条目数delete按memory_id单条删除bulk_delete按 ID 列表批量删除返回成功/失败计数update以原文档 ID 为键执行“删旧插新”update_documents支持编辑内容与 metadataget_memory_subdirs列出所有可用记忆子目录含项目库get_current_memory_subdir解析当前上下文的记忆子目录无上下文回退default每条记忆返回给前端的结构_format_memory_for_dashboard包含id、area、timestamp经本地化时区转换、完整内容、knowledge_source/source_file/file_type知识来源信息、consolidation_action与完整 metadatamemory-dashboard.html 等 Web 组件据此渲染行列表、详情弹窗memory-detail-modal.html与批量操作。日常使用像园艺一样管理记忆记忆系统再自动也需要人工策展——官方使用指南 docs/guides/memory.md 给出了完整的操作建议值得作为实践清单保留保留什么稳定的用户偏好、项目约定、验证过仍有效的命令、需要跨会话持久的决策、重复问题的已知解法删除什么过时的环境参数旧路径/端口/命令、被当成事实保存的失败猜测、临时实验、从混乱对话里复制的记忆、不应被记住的隐私数据行为异常时的排查回路先按反复出现的短语或命令搜索记忆 → 打开可疑条目通读 → 有用但不准的编辑修正纯粹错误的直接删除 → 在聊天里给出明确纠正后重试批量清理要克制先导出备份、用窄范围检索代替按大类删除、优先删明显垃圾、保留仍然有效的老解法。从源码结构看编辑与删除最终都走update_documents()/delete_documents_by_ids()级联清理派生记录且删除后_save_db()立即持久化并刷新index.faiss.sha256哈希因此仪表盘操作与实际向量库状态是强一致的。小结_memory插件的设计可以用三层来概括存储层用“每子目录一个 FAISS 库 嵌入元数据 SHA256 校验”保证可重建、可换模型、防损坏自动化层用扩展点在对话循环的召回/沉淀两端挂接工具模型把“检索—筛选—注入”与“抽取—过滤—整合—入库”做成无需人工触发的闭环治理层用五个工具加仪表盘 API 提供精确的增删改查与级联清理配合项目隔离与分区main/fragments/solutions控制记忆的作用域与质量。理解并调好 default_config.yaml 里的阈值与开关是让 Agent Zero 的长期记忆从“能记住”走向“记得对”的关键。【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考