文档中心

向量数据库VikingDB

使用指南

使用经验记忆实现 Agent 进化

Agent 进化方案概述

基于记忆的进化

OpenViking 使用经验记忆的机制，在不改变底层模型权重、也不侵入 Agent harness 主执行逻辑的前提下，基于自身历史执行过程沉淀可复用的执行知识，并在后续任务中被检索、注入和治理，从而持续改善任务完成质量、稳定性、效率和个性化表现。

Experience 不是历史对话的简单摘要，也不是把上一轮答案原样保存。
OpenViking 会结合同类、相似任务中的执行轨迹，提炼出可以迁移到下一次任务的做法：什么时候适用、推荐按什么步骤执行、需要检查什么、哪些路径容易失败。

对象	记录什么	在进化中的作用
Session	原始消息、工具调用、工具结果、Agent 回复与用户反馈。	提供可追溯的原始证据。
Trajectory	从 Session 中还原出的任务目标、执行路径与结果。	回答“这类任务具体是怎么做的，结果怎样”。
Experience	由一条或多条相关 Trajectory 总结出的可复用方法与风险边界。	回答“下一次遇到相似任务，应该复用什么、避免什么”。

离线持续学习：从 Message 到 Experience

持续写入。Agent 执行任务时，把 user / assistant message 和真实 ToolPart 持续写入 OpenViking Session。关键接口是 POST /api/v1/sessions/{session_id}/messages
提交 session 。当一个任务完成、失败后修复完毕、收到用户纠错、即将重置/压缩上下文等节点，调用 POST /api/v1/sessions/{session_id}/commit。
OpenViking 自动抽取。Commit 先同步归档原始消息，再异步分析任务轨迹，生成或更新 Trajectory 与 Experience。
下一次继续学习。后续任务产生的新轨迹会继续为已有 Experience 提供证据，或形成新的 Experience。

要让抽取结果可靠，一个可学习的任务片段至少应包含：清晰的用户目标、Agent 的主要执行过程、关键工具调用及结果、最终回复；如果存在用户纠错、测试结果或旁路 Evaluator 反馈，保留在同一个任务片段中将获得更好的进化效果。

在线复用：检索、读取，再决定是否应用

集成 OpenViking MCP 后，可安装经验记忆检索 skill（skills/ov-experience-memory）完成自动化的经验记忆检索和读取，或直接集成 OpenViking Plugin 自动获取 skill，在线消费经验记忆流程如下：

按需判断是否需要经验。多步骤执行、工具调用、环境变更、部署、文件或数据修改，以及故障恢复任务，优先检索 Experience；简单问答和闲聊可以跳过。
检索 Experience 根目录。通过 OpenViking MCP 的 find 或 search，将范围限定到 viking://user/memories/experiences。
读取正文。从搜索结果中选择最相关的 1～3 条，用 MCP read 读取精确的 Experience 文件 URI。搜索摘要只用于筛选，不能替代正文。
核对后执行。检查经验的任务类型、环境、前置条件与风险边界是否匹配，再把兼容的步骤和检查项用于当前任务。

公开评测中的效果

说明

τ²-bench ｜复杂业务策略与工具流程能否稳定复用
τ²-bench 把业务流程拆成可执行的业务世界：Retail（零售场景）与 Airline （航空票务服务）都包含领域政策、动态数据库状态、工具 API、任务和用户模拟器。用户会在多轮对话中补充需求，Agent 必须一边澄清，一边按政策调用工具并推进订单、账户或行程状态。
经验记忆的价值体现在相似但不相同的请求里，能否复用验证、判断与执行方法，稳定走完正确流程。

经验记忆将 Retail 正确率从 70.94% 提升到 77.81%（+6.87 pp），将 Airline 从 54.38% 提升到 66.25%（+11.87 pp）。在一个“已送达商品换货”案例中，无记忆仅成功 2/8；召回标准流程经验后达到 8/8，说明经验不仅提高平均正确率，也能把特定流程从偶发成功变为稳定完成。

开启 Agent 进化

使用 Agent 经验实现进化能力前，需要在控制台打开 Agent 进化全局开关。该开关决定当前库中的 Session commit 是否允许生产或更新 Agent 经验记忆。关闭开关不会删除已有 Experience，也不影响已有 Experience 的读取与检索，但后续 commit 不再生成或更新 Trajectory / Experience。

进入目标 OpenViking 实例，在左侧导航打开 Agent 进化。该开关控制当前实例是否在 commit 时沉淀新的 Agent 经验记忆。

完成首个有效任务并 commit。第一条轨迹落库前，经验库会保持冷启动空态。

企业版创建 User 时选择记忆模式
经验记忆以 User 维度沉淀（存储至 / memories/ experiences）。企业版一个 OpenViking 库可以创建多个 User。经验记忆始终归属于当前 User，并在不同 Peer 交互中复用；不同 User 的 Trajectory 与 Experience 相互隔离。
在企业版中创建 user 时，可选择不同的记忆策略：

模式	适用场景	Agent 经验如何沉淀
通用策略	目录主体不固定；团队成员维护个人 Agent，或按 Session 灵活覆盖策略。	✅ 适合当前 User 目录代表一个用户和他的专属助手，会在 / memories/ 目录下同时抽取用户的个人记忆（preferences, profile ,events, entities）和Agent 的执行经验（trajectories, experiences）。
Agent 经验记忆	Agent 只需要跨任务、跨终端用户积累执行方法；终端用户个人记忆由各自 user 管理。	✅ 适合当前 User 目录代表一个 Agent，仅在 / memories/ 下抽取Agent可复用的执行经验，可在 /peers/ 目录下抽取 Agent 服务的终端用户的个人记忆。建议将 Agent 服务的所有用户 session 均上传至 Agent 目录，提交 session 后可跨用户、跨 session 抽取可复用的长期经验。
用户个人记忆	user 代表一个自然人，需要跨不同 Agent 积累个性化上下文。	默认不抽取 Agent 执行经验。若希望某个 Agent 跨用户学习，不应把 Agent 经验写入自然人的目录。

Account 全局开关和 User 记忆策略需要同时允许经验记忆。Session 还可以通过 memory_policy 进一步收窄当前会话的抽取范围（见：create_session-创建会话）；Session 配置不能绕过已关闭的 Account 开关。将 experiences 放入 memory_types 时，OpenViking 会自动带上经验学习所需的 Cases 与 Trajectories 依赖。

集成 Agent

选择接入方式

场景	适配 Agent	离线写入与 commit	在线检索与读取
自主开发 Agent 服务 / 纯 MCP Agent	自研的 Agent Runtime使用MCP接入OpenViking 使用 MCP 对接的消费级 Agent 产品：Trae、WorkBuddy、豆包工作	由开发者通过 Session API 自动写入 message，并在可靠任务边界调用 commit。	集成 OpenViking MCP 与 `ov-experience-memory` Skill，由 Skill 指导 `find/search + read`。
带 Hook 的专属 Agent 插件	Codex、Claude Code、Hermes、OpenClaw	插件在宿主生命周期节点自动捕获消息并 commit，无需业务代码逐个调用 Session API。	使用插件内的 MCP/工具面与 Experience Skill；关键任务也可以显式触发检索。

自主开发的 Agent 服务对接

按标准链路写入 Session 并触发抽取

自研 Agent 服务需要把一次任务中的用户输入、Agent 回复和工具调用按真实顺序写入同一个 OpenViking Session。标准链路包含四个调用：创建 Session、写入 Message、Commit Session、观察 Commit 状态。

第 1 步：创建 Session

接口文档：create_session-创建会话
当 Agent 开始处理一个新的、可独立判断结果的任务时创建 Session，并在 Agent Runtime 中维护“宿主会话 ID → OpenViking session_id”的稳定映射。一个目标连续执行、失败后继续修复或用户纠错后重试时，应继续使用同一个 Session；切换到无关目标时再开启新的 Session。

curl -X POST "$OV_ENDPOINT/api/v1/sessions" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $OV_API_KEY" \
  -d '{
    "auto_commit_policy": {
      "pending_token_threshold": 150000,
      "message_count_threshold": 100,
      "idle_timeout_seconds": 86400,
      "keep_recent_count": 0,
      "min_commit_interval_seconds": 0
    }
  }'

保存响应中的 result.session_id。是否已经启用自动 Commit，以响应中的 result.auto_commit_policy 为准；如果返回 null，不要假设服务端会自动 Commit。

第 2 步：写入 Message，并完整拼接 Tool Call

接口文档：add_message-添加消息
用户消息、Agent 的中间说明、Tool Call 和最终回答都应按发生顺序写入。纯文本可以使用 content；涉及工具调用时使用 parts，把工具名、输入、状态和真实输出保存在同一个 assistant message 中。

curl -X POST "$OV_ENDPOINT/api/v1/sessions/$SESSION_ID/messages" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $OV_API_KEY" \
  -d '{
    "role": "assistant",
    "parts": [
      {
        "type": "text",
        "text": "我先查询目标环境的部署状态。"
      },
      {
        "type": "tool",
        "tool_id": "call_123",
        "tool_name": "get_deployment_status",
        "tool_input": {"service": "checkout"},
        "tool_status": "completed",
        "tool_output": "{\"status\":\"degraded\",\"replicas\":2}"
      }
    ]
  }'

同一次工具调用始终使用同一个 tool_id；不要把多次调用合并成一条摘要。
成功时写入 tool_status=completed 和真实结果；失败时写入 tool_status=error，并保留可诊断的错误信息。
失败、重试、修复分别保留 Tool Part，让 OpenViking 能看到“哪里失败—如何调整—最终结果”的完整轨迹。
一次同步多个历史消息或完整任务片段时，可以调用 POST /api/v1/sessions/{session_id}/messages/batch；单批最多 100 条。

第 3 步：Commit Session，并优先选择有意义的任务边界

接口文档：commit_session-提交会话
commit 会先同步归档原始消息，再在后台异步生成摘要并抽取经验记忆。主动 Commit 时，优先判断“这个片段是否已经包含完整的目标、执行过程和可判断的结果”，而不是只看消息数或 Token 数。

curl -X POST "$OV_ENDPOINT/api/v1/sessions/$SESSION_ID/commit" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $OV_API_KEY"

触发时机	建议	判断方式
任务完成或给出最终回答	主动 Commit	目标、执行路径和结果完整，适合总结成功方法与检查项。
任务失败、用户纠错或修复完成	主动 Commit	如果还会继续修复，等新的结果出现后一起提交；如果任务已经终止，则保留失败原因后提交。
切换到无关的新目标	主动 Commit	先提交前一个任务，再开始新的 Session，避免多个无关目标混在一次抽取中。
Reset、Compact 或 Session End	客户端兜底	防止尚未归档的执行轨迹长期停留在 live Session。
Token、消息数或空闲时间达到阈值	OpenViking 兜底	由 `auto_commit_policy` 自动判断，适合 Runtime 难以识别语义边界的场景。

说明

不知道何时 Commit，也可以交给 OpenViking 兜底。
只要 Session 已启用 auto_commit_policy（见：create_session-创建会话），Agent 服务持续写入 Message 即可；OpenViking 会在 pending Token、消息数超过阈值，或 Session 空闲达到设定时间后自动 Commit。自动机制主要用于避免数据长期未归档；能识别任务完成、失败修复或用户纠错等语义边界时，仍建议主动 Commit。

第 4 步：观察 Commit 状态

接口文档：get_task-获取后台任务状态
Commit 返回 status=accepted 时，保存 task_id 并查询后台任务；这只代表异步处理已受理，不代表经验已经抽取完成。返回 status=skipped 且 task_id=null 时，表示没有可归档内容，无需轮询。

curl -X GET "$OV_ENDPOINT/api/v1/tasks/$TASK_ID" \
  -H "X-API-Key: $OV_API_KEY"

Task 状态	Agent 服务处理方式
`pending / running / cancelling`	按退避策略继续查询，不要重复提交同一段 Session。
`completed`	处理完成；可读取 `result.memories_extracted`、`memory_diff_uri` 等结果确认本次抽取。
`failed / cancelled`	记录 `error`，保留 Session 和 `task_id` 便于排查；不要把失败任务记为“已生成经验”。

在 Agent runtime 中集成 MCP + Skill

在线集成的目标，是让 Agent 在开始高价值任务前先检索过去的 Experience，在真正需要时读取少量原文，并把适用的最佳实践和避坑指南用于当前执行。适合编码、配置、调试、故障恢复以及多步骤、工具密集型任务；闲聊和一次性事实问答通常不需要检索。

组件	作用	职责边界
OpenViking MCP	向 Agent 暴露 `find / search / read` 等真实检索工具。	负责连接与执行工具调用；是否使用哪些可选工具，以当前 MCP 实际注册结果为准。
`ov-experience-memory` Skill	指导 Agent 何时检索、如何构造 query、如何筛选和读取 Experience。	Skill 是使用策略，不是自动 Hook；安装 Skill 不等于已经连接 MCP，也不会自动完成 Session Commit。

注册 OpenViking MCP

先在 Agent 中配置 OpenViking MCP Server，并确认当前会话至少注册了 find、search 和 read。如果没有任何 OpenViking 工具，应继续完成当前任务，但不要伪造经验检索结果或退回到未约定的 HTTP 调用。

下载并安装 openviking-memory Skill

从 OpenViking 官方仓库下载 ov-experience-memory Skill，并复制到 Agent 支持的 Skills 目录。

按 Skill 执行在线检索

在编码、配置、调试、故障恢复或其他多步骤任务开始时，先判断历史经验是否可能改变本次执行方式。
用任务目标、关键对象、预期操作和限制条件构造一个简洁 query；故障恢复时加入失败操作和稳定的错误特征。
优先调用 find，初始 limit 建议为 5～10；已知要查经验时，将范围收敛到 viking://~/memories/experiences。
需要更深入的意图分析时使用 search；需要服务端拼装限额上下文时，可以使用 search(mode="context")。
按任务、环境和前置条件筛选真正相关的结果，只对最可能影响执行的 1～3 条调用 read。
把 Experience 当作建议而不是强制指令，并用当前环境重新验证命令、路径、版本和风险。没有相关结果时直接继续任务；只有遇到实质不同的新失败原因时，再做一次聚焦检索。

find({
  "query": "deployment image pull failure private registry",
  "target_uri": "viking://~/memories/experiences",
  "limit": 5
})

read({
  "uri": "find 返回的 Experience URI"
})

使用带 Hook 的专属 Agent 插件

OpenClaw、Codex 等专属插件会挂载宿主的生命周期 Hook：在用户输入、每轮结束、上下文压缩、重置或会话切换等节点自动召回、捕获消息，并按各自策略 commit。开发者无需在业务代码中逐条实现 Session API，但仍需要正确配置 OpenViking 地址、API Key 和目标 User。

插件 / 专属集成	自动化能力	使用建议
OpenClaw	自动捕获对话、任务前召回，并在消息量达到阈值、compact、reset 等边界 commit。	安装后先运行插件状态检查；使用 Experience Skill 处理高价值执行任务与故障恢复。
Claude Code	每轮结束自动捕获；消息量达到阈值、PreCompact、SessionEnd、SubagentStop 时自动 commit。	适合需要完整生命周期 Hook 和子 Agent 隔离的场景；安装后用插件状态页确认 Hook 与 MCP 均已生效。
Codex	通过 Hook 自动召回、增量捕获；消息量达到阈值、上下文压缩及可用的会话结束事件会触发 commit，并在下次启动时补偿未提交会话。	首次启动按宿主要求批准 Hook；TraeCode CLI 2.0 复用 Codex 插件，若宿主未提供 SessionEnd，则依赖下次 SessionStart 补偿。
Cursor	自动捕获每轮对话；累计 8 条消息（约 4 轮问答）或 PreCompact 时自动 commit。	关闭会话或窗口不一定触发有效提交；短会话结束前建议触发 compact，或确认已达到提交阈值。
TRAE / TRAE CN	每次 Stop 都会捕获并立即 commit 当前已完成的一轮，无需累计到阈值。	适合希望每轮及时沉淀经验的场景；需使用支持 SessionStart、UserPromptSubmit、PreToolUse、Stop Hook 的版本。
OpenCode	在会话空闲且消息量达到阈值时 commit；会话删除、错误、插件卸载，以及上下文压缩前后也会强制提交。	建议使用支持 dispose 生命周期的较新版本；退出时间过短时仍需检查最后一批消息是否完成提交。
Hermes（内置 MemoryProvider）	无需另装 OpenViking 插件；在会话结束、切换、分支式压缩或缓存淘汰等边界自动 commit。	先将 OpenViking 设为 Hermes 的 MemoryProvider；原地压缩和异常强退不保证触发提交。

专属插件的 commit 触发点会随宿主能力变化，不建议把某一个插件的阈值照搬给其他 Agent。验收时关注结果：消息是否持续写入、关键边界是否 commit、后台任务是否完成、Experience 是否能被 find/search + read 真实使用。

插件接入后的最小验收

启动 Agent，完成一次带工具调用的任务。
在 OpenViking 中查看对应 Session，确认 user / assistant message 与 ToolPart 顺序完整。
触发插件支持的 commit 边界，例如完成任务、compact 或 reset。
确认后台任务完成，并能查看新 Trajectory 或 Experience 更新。
启动一个相似新任务，确认 Agent 实际调用 find/search 与 read，而不是仅在提示词里声称“已读取经验”。

查看与验证经验记忆

查看 Experience 内容
进入 Agent 进化，查看 Experience 列表与详情。企业版按 User 展示，不聚合不同 User 的数据。可查看：

经验名称与最近更新时间。
适用场景、触发条件、推荐步骤、校验要求与风险边界。
Experience 文件 URI。

沿 Trajectory 追溯到 Session
一条 Experience 应能追溯到一条或多条来源 Trajectory，并继续追溯到原始 Session。可检查：

Trajectory 是否描述了一个完整任务，包含任务目标、关键步骤、工具调用、结果与 outcome 。
Experience 中的建议能否被来源证据支持，是否遗漏关键前置或把一次偶然成功写成通用规则。
如果 Experience 来自失败或纠错任务，是否清楚区分错误路径与最终修复路径。

查看经验复用效果
OpenViking 提供 Experience 被实际读取后所关联的 Trajectory 与结果分布。

查看迭代并测试 Experience
在测试页面可自动展示经验生产的来源轨迹，抽取轨迹的用户意图，并拼接经验原文，可一键复制到您的 agent 测试加入经验的执行效果。

*注：若原始意图包含用户上传的文件，则需要您获取历史文件再次模拟用户使用的输入

最近更新时间：2026.09.13 16:12:31

这个页面对您有帮助吗？

有用

无用

向量数据库VikingDB

基于记忆的进化 #

离线持续学习：从 Message 到 Experience #

在线复用：检索、读取，再决定是否应用 #

公开评测中的效果 #

选择接入方式 #

自主开发的 Agent 服务对接 #

按标准链路写入 Session 并触发抽取 #