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

OpenViking 是面向 AI Agent 的自进化上下文数据库，其 Experience（经验）记忆类型专门用于沉淀“可复用的操作流程”。本文以仓库中 Claude Code 记忆插件自带的ov-experience-memory技能文档为核心，完整讲解如何在 Agent 运行时中通过通用的 OpenViking 搜索与读取工具检索 Experience，并正确地把经验应用到编码、部署、故障恢复等多步执行类任务中。读完本文，你将掌握 Experience 的检索工作流、运行时工具选型、经验应用优先级以及会话级证据留痕机制，并理解经验从执行轨迹中沉淀出来的底层原理。

Experience 在 OpenViking 记忆体系中的定位

在 OpenViking 的虚拟文件系统中，用户空间下预设了memories目录，其下按类型组织长期记忆。openviking/core/directories.py 定义了预设目录树，其中memories下包含preferences（偏好）、entities（实体）、events（事件）、cases（案例）、patterns（模式）、tools（工具使用）、skills（技能执行）、trajectories（执行轨迹）以及experiences（经验）：

viking://~/memories/experiences

从预设目录定义可以清晰地看出各类记忆的职责边界：

在 openviking/session/memory/constants.py 中，EXPERIENCE_MEMORY_TYPE = "experiences"与TRAJECTORY_MEMORY_TYPE = "trajectories"被归入EXECUTION_MEMORY_TYPES，与CASE_MEMORY_TYPE一起构成 Agent 自进化记忆体系的核心类型。

Experience 与 Trajectory 的生成关系

Experience 并非凭空产生，而是由 Agent 执行轨迹（trajectory）在会话提交后通过记忆抽取流水线提炼而来。仓库中的 openviking/session/memory/agent_experience_context_provider.py 是这条流水线的第二阶段：给定新轨迹摘要后，先做语义检索（SEARCH_TOP_K = 5）找出候选经验，再由 LLM 决定是更新已有经验、新建经验、还是跳过。其抽取指令明确要求：

• 每个不同的用户意图输出一条独立的 Experience 条目；
• 同名experience_name就地更新，新名字则新建，supersedes字段用于“替换并继承旧经验的历史”；
• 经验内容必须是可直接注入 Agent 系统提示词的机器指令。

openviking/prompts/templates/memory/experiences.yaml 定义了 Experience 的存储位置与内容结构。其directory模板为viking://user/{{ user_space }}/memories/experiences，文件名模板为{{ experience_name }}.md，operation_mode为upsert，且标记agent_only: true（仅 Agent 阶段抽取）。内容的正文必须严格采用三段式结构：

## Situation <入口条件：泛化后的上下文、用户意图或整体场景，决定整条规则何时生效> ## Approach <主动执行逻辑（DOs）：一步步的最优执行路径，用直接命令式与显式 IF/THEN/ELSE 表达条件分支> ## Reflect <硬性护栏与原则（DON'Ts）：严格的否定规则、边界条件与防止重蹈覆辙的启发式>

该 schema 对内容质量有一组强约束，值得在实际使用中领会：

• 互斥性：Approach只放积极的可执行步骤，Reflect只放否定边界，两节不重复同一概念；
• 优化执行路径：必须裁剪对话噪音、无效重试循环、错误起点与无关设置动作，只保留必要的高效路径；
• 机器可读：以命令式祈使句直接对未来的 Agent 下指令（如 “Ask the user for X”、“Call tool Y”）；
• 抽象化：去除具体实体、ID、用户名、原始文本，用泛化描述使规则可普遍适用；
• 失败整合：过去的错误必须翻译成严格的否定约束，且只能放在Reflect节；
• 条件分支保留：完整捕获 IF/THEN/ELSE 决策树，绝不把用户驱动的不同分支折叠成单一动作；
• 原子范围：每条经验只覆盖一个用户意图及其工具调用序列，多个意图必须拆分；Approach超过 8 条要点必须停止并拆分。

理解了 Experience 的“身世”，下面的检索实战才有意义——你要检索的不是琐碎的个人信息，而是经过 LLM 提炼、可直接指导执行的操作规程。

前置条件（Preconditions）

使用ov-experience-memory技能前，必须满足以下条件，否则应放弃 Experience 检索而继续正常执行：

1. 只使用当前 Agent 运行时中实际注册的 OpenViking 工具。不要假设某个工具一定存在，以运行时展示的确切工具名与 schema 为准。
2. 必须同时具备语义搜索能力与精确 URI 读取能力。二者缺一不可：先用搜索定位候选，再用精确读取拿到经验全文。
3. 任一能力不可用时，继续执行但跳过 Experience。不得凭空捏造工具调用、伪造 ToolPart，也不得绕过 Agent 工具直接使用 HTTP 或 CLI 访问。
4. 不要用宽泛的recall替代限定在 Experience 根目录下的搜索。当任务同时需要用户事实、事件、决策、历史对话或领域资源时，继续使用运行时的常规 recall 与检索流程。

这些约束的目的在于：Experience 只是上下文检索的补充，它不取代用户记忆、事件、偏好、会话归档、资源或 Agent Skills；同时它也不允许 Agent 用“看起来像”的方式伪造工具调用，破坏会话证据的完整性。

选择运行时工具

不同 Agent 运行时对 OpenViking 工具的命名不同，技能文档给出的对应关系如下：

几点选型与使用要点：

• 宿主可能给 MCP 工具加命名空间前缀，例如mcp__openviking__find。始终使用运行时展示的确切注册名与 schema，不要凭记忆猜测。
• 优先用find做任务开始时的快速查找（轻量、快）；当会话上下文或更深层的意图分析有价值时，改用search。
• 读取时选择精确读取（read）或批量读取（multi_read）。仓库中的 openviking/session/memory/experience_lineage.py 表明，read、multi_read、openviking_read、openviking_multi_read、ov_read、ov_multi_read以及mcp__openviking__read/multi_read等命名变体在底层都会被统一识别为读取操作，用于经验溯源。

检索工作流

技能文档给出了一套完整的 8 步检索工作流，每一步都直接可执行：

1. 判断任务类型：仅当请求是可执行任务（规划、工具使用、环境变更、多步工作流、失败恢复）时才检索 Experience；闲聊与简单知识问答跳过检索。

2. 构造查询：用一句话包含任务目标、领域对象、预期操作与重要约束；失败后重试时，还应加入失败的操作与稳定的错误特征（error signature）。

3. 只搜索当前用户的 Experience 根目录：

   viking://~/memories/experiences

   对使用 MCP 风格参数的工具，把该根目录设为target_uri；对 OpenClaw 的ov_search，把该根目录设为uri。绝不要硬编码default、test或其他用户 ID——在 openviking/core/retrieval_targets.py 中，resolve_retrieval_targets会基于当前RequestContext解析出确切的用户目录，硬编码会直接导致越权或检索错位。

4. 从limit=5与工具默认的分数阈值开始。依据任务、环境、前置条件与可能产生的影响来判断结果相关性，仅凭标题相似度不够。若无相关结果，继续执行但不检索 Experience，也不要扩大搜索到无关的记忆目录。

5. 只挑选一到三个最可能改变执行走向的 Experience 文件。要求使用不含查询参数与片段（fragment）的精确文件 URI；忽略目录、无关记忆类型以及.abstract.md、.overview.md这类旁车文件（sidecar）。

6. 用运行时的 OpenViking 读取工具读取每一个选中的规范 URI（viking://.../memories/experiences/...）。搜索返回的摘要（abstract）只用于辅助选择，不能替代阅读 Experience 正文。

7. 在执行任务的过程中应用相关步骤与检查项。除非答案中确实需要，否则不要把 Experience 原文逐字复述给用户。

8. 失败后的定向补充检索：若执行因实质性新原因失败，最多再做一次聚焦于失败证据的补充搜索，且只读取新相关的 Experience 文件。

为什么限定target_uri如此重要

从服务端实现看，openviking/server/routers/search.py 提供的/api/v1/search端点接收target_uri参数，并经由 openviking/core/retrieval_targets.py 的default_target_directories解析默认检索目录。当显式传入 Experience 根目录时，检索范围被严格收窄到memories/experiences之下，既保证语义检索落在正确的命名空间，也避免混入偏好、事件、资源等无关记忆类型——这正是技能文档要求“绝不扩大搜索到无关目录”的服务端依据。

应用检索到的经验

检索到 Experience 之后，如何正确应用它，决定了经验的最终价值：

• 把 Experience 视为可复用的操作规程，而不是用户画像、用户意图、安全策略或“某操作已经成功过”的证据。
• 优先级顺序：系统与开发者指令 > 当前用户请求 > 当前环境与工具证据 > Experience。经验永远排在最后，只作为补充参考。
• 主动过滤：忽略过时、不兼容、不安全或相互冲突的指导；对命令、路径、API、版本以及破坏性操作，务必对照当前任务逐一核验。
• 守住确认与权限边界：过去的成功绝不授权当前会话执行破坏性或外部动作。
• 冲突处理：当多条 Experience 冲突时，优先选择其前置条件与当前环境最匹配的那一条；否则采取保守策略，并在影响用户时把歧义明确呈现出来。

这套规则对应了 Experience 在生成时的定位——openviking/prompts/templates/memory/experiences.yaml 要求Approach中的步骤“只描述直接的工具调用”，且Reflect中的“NEVER do Z”类硬规则正是为了给未来的执行者画清红线。检索方与应用方遵循同一套纪律，经验才能既高效又不越界。

会话证据（Session Evidence）

Experience 检索与应用必须在会话中留下真实的工具调用痕迹，这样提交后的 OpenViking 会话才能保留对应的 ToolPart 记录。技能文档明确了什么算数、什么不算：

• 一个已完成的通用 OpenVikingfind、search或list结果中包含某个 Experience URI，即记录对该 Experience 的一次召回（recall）；
• 一个已完成的通用 OpenVikingread或multi_read读取了某个 Experience URI，即记录一次注入（injection），并可将由此产生的轨迹与该 Experience 关联；
• 失败、取消或未完成的调用都不计入。

在会话提交之前，不要编辑、摘要化或合成这些 ToolPart。

从源码可以印证这一机制的严谨性。openviking/session/memory/experience_lineage.py 的collect_read_experience_uris会遍历已提交会话的消息集，仅收集满足以下条件的读取记录：工具调用tool_status == "completed"；URI 通过canonical_experience_uri校验（必须是viking://user/{user_id}/memories/experiences/...的规范形态且归属当前用户）；multi_read中单项失败（success: false）或返回(nothing found at ...)、ERROR:标记的读取会被排除。这套“只认真实成功调用”的判定逻辑，正是技能文档“Failed, cancelled, or incomplete calls do not count”的服务端落地。此外，experience_source_tag会为经验 URI 生成{uri}=1形式的检索标签，用于后续把新的轨迹与产生它的经验建立溯源关系。

示例：部署失败修复

技能文档给出了一个完整示例，以“修复一次部署失败”为场景串联整个工作流：

1. 对 Experience 根目录发起搜索，查询词例如：

   Kubernetes deployment image pull failure private registry

2. 读取最相关的精确 Experience URI。

3. 核验该经验中的镜像仓库、凭据与滚动发布（rollout）假设是否与当前集群一致。

4. 应用兼容的诊断步骤，验证实时结果，然后继续完成用户任务。

这个例子直观地展示了“先检索 → 再核验前置条件 → 再应用”的完整闭环：经验不是拿来即用的教条，读取后必须与环境对账，兼容才应用，不兼容就放弃并保守处理。

小结

OpenViking 的 Experience Memory 为 Agent 提供了一条“从执行轨迹中提炼经验、在任务执行前检索经验、在执行中应用经验、在会话中留痕经验”的完整链路：

• 沉淀端：会话提交后，agent_experience_context_provider.py 将轨迹摘要与候选经验交给 LLM，产出Situation/Approach/Reflect三段式、可直接注入系统提示词的机器指令，存入viking://user/{user}/memories/experiences；
• 检索端：运行时通过注册好的find/search/read系列工具，以viking://~/memories/experiences为根做限定域语义检索，再用精确 URI 读取正文；
• 应用端：经验优先级最低，受系统指令、用户请求、环境证据的层层约束，过时与冲突内容一律过滤；
• 证据端：只有真实完成的搜索与读取调用才构成会话中的 ToolPart，experience_lineage.py 据此建立经验与轨迹的溯源关系。

把握住“经验是补充而非替代、检索必须限定在 Experience 根、应用必须核验环境”这三条主线，你就能让 Agent 在每一次多步任务中稳定地复用历史操作经验，实现真正的自进化式执行。

【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking