ARTICLE DETAIL

资讯详情

深耕网站建设与运营推广的一线实战洞察。

OpenViking Experience Memory 实战指南:用 Agent 运行时通用工具检索并应用历史操作经验

OpenViking Experience Memory 实战指南:用 Agent 运行时通用工具检索并应用历史操作经验 OpenViking Experience Memory 实战指南用 Agent 运行时通用工具检索并应用历史操作经验【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking导读Experience Memory经验记忆是 OpenViking 面向 AI Agent 的三类记忆形态之一用于把历史会话中沉淀下来的可复用操作流程如部署、配置、故障恢复以结构化文件的形式固化下来供后续任务跨会话复用。本指南以仓库中的 ov-experience-memory 技能文档 为主体完整讲解其触发时机、前置条件、运行时工具选择、八步检索工作流、结果应用规则与会话证据机制并结合 OpenViking 的源码实现经验提取、URI 血缘、搜索/读取工具注册说明其底层原理。读完本文你将能在任何接入 OpenViking 的 Agent 运行时中仅凭find/search/read这类通用工具安全、精准地检索并应用历史操作经验同时保证会话提交后经验检索轨迹可追溯。Experience Memory 是什么先看它在 OpenViking 记忆体系中的位置OpenViking 将持久上下文分为记忆memories事实、偏好、决策、资源resources导入的文档、站点、仓库与技能skills三大类。其中记忆目录内部又按类型分文件归档Experience经验是与轨迹trajectory并列的执行类记忆。这一分类在源码中有明确声明见 openviking/session/memory/constants.pyCASE_MEMORY_TYPE cases TRAJECTORY_MEMORY_TYPE trajectories EXPERIENCE_MEMORY_TYPE experiences EVENT_MEMORY_TYPE events EXECUTION_MEMORY_TYPES frozenset({TRAJECTORY_MEMORY_TYPE, EXPERIENCE_MEMORY_TYPE})在检索侧上下文组装器把记忆类别统一建模experiences与events、entities、preferences一起参与召回见 openviking/retrieve/context_assembler/params.py。同时它默认对experiences设置配额为 0不占普通上下文预算、跨 peer 惩罚为0.02这说明 Experience 是按需精准检索的补充型记忆而非每轮会话默认注入的常驻上下文——这正是本文所讲技能文档存在的根本原因经验需要 Agent 在任务执行前主动去检索而不是等它自动出现。经验与轨迹是结论与过程的关系轨迹记录一次执行的事实经过经验则是在轨迹之上提炼出的下次遇到类似情况该怎么做。本技能文档描述的就是这条检索链路的消费端用法。技能定位什么时候该用什么时候不该用技能文档的 frontmatterdescription见 SKILL.md给出了清晰的触发判定应该用可执行的、多步骤的或依赖工具的任务——编码、文件或数据修改、配置、部署、工作流执行、失败恢复且历史操作指导可能提升可靠性时应在执行前或执行中检索经验。不该用随意闲聊、简单的事实问答。这类场景没有可复用的操作流程可借鉴检索纯属浪费。文档同时划定了经验记忆与其它记忆的边界SKILL.md经验检索是对常规上下文检索的补充绝不替代用户记忆用户事实、事件、决策、历史对话与领域资源、Agent Skills。如果你的任务需要的是用户上次说过什么用户偏好如何请走运行时的正常 recall / retrieval 流程而不是经验检索。前置条件三条硬约束使用本技能前必须满足SKILL.md只用当前 Agent 运行时中真实注册的 OpenViking 工具。每个运行时的工具命名不同必须先用实际注册名调用。同时具备两种能力语义搜索能力用于召回候选 精确 URI 读取能力用于读取经验正文。缺一不可。能力缺失时宁可不用如果搜索或读取能力不可用就直接跳过经验检索继续任务——绝不虚构工具调用、不伪造 ToolPart、不用直接 HTTP 或 CLI 调用顶替 Agent 工具调用。这条约束与后文会话证据机制直接相关伪造的调用不会进入已提交会话反而会污染溯源。另外有一条重要的范围纪律不要用宽泛的记忆recall去替代限定在 Experience 根目录的搜索。经验检索必须精确作用域到经验的专属目录这一点在检索工作流中会反复出现。选择运行时工具一张表搞定所有命名变体同一套 OpenViking 能力在不同 Agent 运行时下以不同名称暴露。技能文档给出官方对照SKILL.md运行时搜索工具读取工具OpenViking MCP、Codex、Claude Codefind或searchreadOpenCodeopenviking_find或openviking_searchopenviking_readOpenClawov_searchov_read或ov_multi_read两点实操细节命名空间前缀宿主可能以mcp__openviking__find这样的形式展示 MCP 工具名必须使用运行时实际显示的确切注册名与 schema不要凭记忆猜测。find与search的分工任务起步时的快速查找优先用find快、返回原始命中列表当会话上下文或更深层意图分析有价值时用search。OpenViking 记忆模块中的MemorySearchTool定义即Semantic search with session contextopenviking/session/memory/tools.py支持query与limit参数且底层会通过ctx.default_search_uris注入默认搜索作用域——这正是只搜 Experience 根目录这一约束的实现抓手。从源码看这些工具名变体不是随意罗列的经验血缘收集模块 openviking/session/memory/experience_lineage.py 对读取类工具做了统一归一化映射read/multi_read、openviking_read/openviking_multi_read、ov_read/ov_multi_read全部被识别为读取操作且用正则^mcp__(?:openviking|plugin_._openviking)__(read|multi_read)$兼容带 MCP 命名空间的形态。也就是说无论你用的是哪一列的工具名只要真实完成调用后端都能把它们识别为经验读取并纳入血缘统计。检索工作流八步精读这是技能文档的核心操作部分SKILL.md完整拆解如下。第 1 步判定是否为可执行任务需要经验检索的任务类型规划、工具使用、环境变更、多步骤工作流、失败后的恢复。闲聊与简单知识问答直接跳过。第 2 步构造一条精炼查询查询应包含任务目标 领域对象 预期操作 重要约束。失败恢复场景还要追加失败的操作 稳定的错误特征如错误码、异常摘要。示例Kubernetes deployment image pull failure private registry。第 3 步只搜索当前用户的 Experience 根目录作用域根固定为viking://~/memories/experiencesMCP 风格参数把target_uri设为该根OpenClawov_search把uri设为该根绝不硬编码default、test或其它用户 ID。为什么必须用~/而不是写死用户因为 Experience 是按用户隔离的。后端在血缘校验时要求 URI 严格匹配[user, user_id, memories, experiences]四段前缀experience_lineage.py写死其它用户 ID 会导致检索结果无法通过归属校验。从 OpenViking 目录建模看experiences 正是用户空间下的标准记忆子目录见 openviking/core/directories.py。第 4 步以limit5起步按语义而非标题判断初检用limit5配合工具默认的分数阈值。判断相关性的依据是任务、环境、前置条件、预期效果——光看标题相似远远不够。若无相关结果直接继续任务不要扩大到无关记忆目录如 events、preferences去碰运气。这与技能开头不拿宽泛 recall 替代的纪律一脉相承。第 5 步只挑选 1~3 个可能改变执行走向的经验文件要求精确的文件 URI不带 query 或 fragment即不允许?、#后缀。忽略目录、无关记忆类型、以及.abstract.md、.overview.md这类 sidecar 文件。sidecar 过滤在源码中有精确对应_EXPERIENCE_SIDECAR_FILENAMES {.abstract.md, .overview.md, .relations.json}experience_lineage.py这些是系统生成的摘要/概览/关系文件不是经验本体。同样地搜索结果的 Token 优化逻辑也会主动过滤以.abstract.md、.overview.md结尾的结果tools.py保证 Agent 看到的是经验主体而非摘要层。第 6 步用 read 工具读取每一个选中的经验正文读取规范化的viking://.../memories/experiences/...URI。搜索返回的摘要只用于初筛绝不能替代阅读经验正文——摘要可能过时或偏薄。read工具支持offset/limit参数控制行范围tools.py大文件可分段读取。第 7 步执行任务时应用经验但不复述原文将相关步骤与检查项融入实际执行不要向用户逐字复述经验内容除非其内容直接构成答案的一部分。第 8 步失败后最多做一次聚焦的补充检索若执行因实质性新原因失败允许基于失败证据再做至多一次聚焦搜索然后只读取新相关的经验文件。这是对检索成本的显式约束经验是辅助不能变成无限回溯。应用检索结果四条裁决规则找到经验后如何正确地使用它文档给出四条规则SKILL.md经验是可复用的流程不是用户画像它不是用户意图、安全策略更不能证明某个动作曾经成功过。优先级从高到低系统/开发者指令 → 当前用户请求 → 当前环境与工具证据 → 经验。经验永远垫底。主动校验容忍过期对过时、不兼容、不安全或相互冲突的指导一律忽略命令、路径、API、版本、破坏性操作都必须对照当前任务重新核实。守住确认与权限边界历史上的成功绝不授权当前会话执行破坏性或外部动作多个经验冲突时优先选择前置条件与当前环境匹配的那一个否则保守行事并在影响用户时主动暴露歧义。会话证据让每次检索都可追溯经验检索的价值在于可审计。技能文档要求使用真实的 Agent 工具调用让提交后的 OpenViking 会话保留这些 ToolPartSKILL.md召回记录一次完成的通用find、search或list调用其结果中包含某个经验 URI即记为对该经验的召回recall。注入记录一次完成的通用read或multi_read读取经验 URI即记为注入injection并可把产生的轨迹与该经验关联。失败/取消/未完成的调用不计入。提交会话前不得编辑、摘要化或合成这些 ToolPart。这一机制的源码实现在 experience_lineage.pycollect_read_experience_uris遍历已提交会话的消息仅当ToolPart的tool_status completed时才会收集其中的经验 URI随后通过canonical_experience_uri做规范化 URI 当前用户归属双重校验并将 URI 编码为{uri_key}1形式的检索标签experience_source_tag同文件第 55-58 行用于经验的来源血缘过滤。也就是说你真实完成了哪几次经验读取后端就能精确还原哪些经验影响了哪条轨迹——这正是不要伪造工具调用这条前置条件的底层原因。底层原理经验从哪来——轨迹到经验的两阶段提取作为消费端理解经验的生产机制有助于判断检索结果的形态与质量。经验由 OpenViking 的 agent 级记忆提取管线在后台生成核心是 openviking/session/memory/agent_experience_context_provider.py 实现的Phase 2输入Phase 1 产出的新轨迹摘要 最多SEARCH_TOP_K 5个候选既有经验其中 Top-3 候选还会附带其来源轨迹作为 grounding。输出规则一个用户意图对应一条独立经验experience_namecontent同名则原地更新、新名则新建、设置supersedes则删除旧经验并继承其历史。维护取向拿不准是否合并时拆分优先只有用户意图与工具序列完全相同才合并——这保证了经验文件小而聚焦也解释了为什么检索时经验正文通常比摘要更值得读取。另外仓库还提供了经验→轨迹的图谱能力openviking/session/memory/experience_lineage.py以及服务端查询端点GET /experiences/trajectories、GET /experiences/outcomesopenviking/server/routers/agent_evolution.py可用于事后分析某条经验源自哪些轨迹、其结果分布如何。完整示例修复一次部署失败技能文档以修复部署失败给出端到端演示SKILL.md结合上文规则展开如下判定修复部署失败是可执行、多步骤、依赖工具的任务且历史操作指导能提升可靠性 → 应该检索。构造查询目标部署 对象Kubernetes 私有仓库镜像 操作拉取镜像 约束/错误特征image pull failure、private registry。限定作用域target_uri viking://~/memories/experienceslimit 5不硬编码用户 ID。筛选只保留 1~3 个最可能改变执行走向的经验文件忽略目录、.abstract.md、.overview.mdsidecar。读取正文用read读取选中的规范化viking://.../memories/experiences/...URI确认其 registry、凭证与 rollout 假设。校验环境匹配对照当前集群检查该经验的 registry、凭证、发布策略假设是否与现状一致不一致则按优先级规则丢弃或保守处理。应用与验证执行兼容的诊断步骤验证实时结果继续完成用户任务不向用户复述经验原文。证据留存整个过程中真实的search/read调用会在会话提交后自动保留 ToolPart形成可追溯的经验血缘。常见误区与边界速查别用宽泛 recall 顶替经验检索必须限定在memories/experiences根需要用户事实、事件、决策时走正常召回流程。别硬编码用户viking://~/memories/experiences中的~由运行时解析为当前用户写死default/test会破坏归属校验experience_lineage.py。别只看标题/摘要摘要用于初筛正文才是裁决依据read支持offset/limit分段。别伪造调用工具调用必须真实完成否则会话提交后无法形成有效的 recall/injection 血缘记录。别把经验当授权历史成功不构成当前会话执行破坏性/外部动作的依据。关联文档ov-experience-memory 技能配套的通用记忆技能参见 openviking-memory其中提到该技能的专用工具对search_experience/read_experience在此文档中被泛化为按运行时实际注册名选择find/search/read等通用工具请以你所在运行时的真实工具名为准。【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表