文档中心

向量数据库VikingDB

使用 OpenViking 接管 Agent 记忆

定制开发 Agent 记忆接入

如果你正在开发企业助手、团队机器人或 Coding Agent，可以将 OpenViking 作为 Agent 的长期记忆服务：在后台从真实交互中积累记忆，在用户发起新任务时检索相关记忆，让 Agent 延续之前的偏好、项目背景和处理经验。
如果您是个人用户，使用消费级的 Agent（如 Codex，Claude Code，Hermes agent）在个人办公和coding场景使用，可参考使用 OpenViking 个人版快速接入记忆。

接入前准备

开始前，准备目标库的服务地址和访问凭证，并确认记忆抽取能力已经启用。企业版需要使用目标数据空间（Account）和 User 对应的访问配置；不要让模型根据聊天内容自行选择账号或凭证。
记忆接入的 2 条链路：

链路	要完成的工作	推荐方式
离线：积累记忆	创建 Session，回流真实消息，Commit 后跟踪抽取结果	应用后台调用 Session OpenAPI
在线：使用记忆	按当前任务检索、读取记忆，再交给模型使用	可使用 MCP；或您需要确定性流程或精细控制时可使用 OpenAPI 开发自定义工具。

您可以阅读了解 OpenViking 的记忆机制熟悉记忆写入和使用的基础流程概念。
区分 User 和 Peer
一个 User 是一个 OpenViking 目录的访问主体，user 下可以使用不同的 peer 来区分不同对象和主题的记忆。您可以参考 User 和 Peer：实现目录下的记忆和资产隔离来深入了解 Peer 的概念。

离线链路接入：从会话中积累记忆

为了让 OpenViking 能获取 Agent 和用户交互的对话和执行信息，使用 Session 接口完成 “创建 Session → 回流 Message → Commit → 检查结果” 的链路。

创建 Session

用途：为一次业务任务建立会话容器，并设置本次要抽取的记忆范围。建议以连续任务划分 Session。
接口文档：create_session-创建会话

POST {BASE_URL}/api/v1/sessions
Authorization: Bearer {API_KEY}
Content-Type: application/json

{
  "memory_policy": {
    "self": {"enabled": true},
    "peer": {"enabled": true}
  }
}

创建 session 会基于您传入的鉴权 Key 自动路由至 User 目录创建 Session。可指定或让接口返回自动生成的 SessionID，后续上传消息时使用 SessionID 确定会话归属：

{
  "status": "ok",
  "result": {
    "session_id": "session_demo_001",
    "uri": "viking://user/team_assistant/sessions/session_demo_001"
  }
}

创建 Session 时也可以指定当前 Session 开启的记忆策略（是否写入 Peer 和 User 目录下的记忆、使用哪些记忆类型），相关配置可参考 create_session-创建会话。

回流 Message：将交互记录映射为 Part

用途：把真实发生的输入、回复、引用内容和工具执行记录，转换为 OpenViking 能理解的消息结构，并写入暂存至 user 的 session 目录。
接口详见：add_message-添加消息
一条 Message 包含外层的 role、peer_id 等信息，以及按顺序排列的 parts 数组。role 表示谁发出的消息，peer_id 标记关联的人或项目；Part 表示这条消息里有哪些内容。

{
  "role": "user",
  "peer_id": "person_alice",
  "parts": [
    {"type": "text", "text": "我使用 macOS，请先给出简短的排障步骤。"}
  ]
}

OpenViking 要求将 Agent 的原始trace信息转化为不同的 Part（文本内容、引用的OpenViking记忆和资源、工具调用等），并将这些 Part 按顺序排列，组成一条完整的 Message：

业务中的内容	OV Part 类型	主要字段与映射方式
用户原始输入、Agent 实际回复	Text Part：text	将文本写入 text；保留外层 user / assistant 角色
本次交互实际引用的记忆、资源或技能	Context Part：context	uri 标记已有内容，context_type 标记类别，abstract 保存必要摘要
工具调用及其真实返回	Tool Part：tool	按调用 ID 配对输入与结果，填入 tool_id、tool_name、tool_input、tool_output、tool_status
用户提供的图片	Image Part：image_url	使用 image_url.url 指向图片

每个 part 的传输格式：

Text Part：保存真实表达

用户的原始输入表达，以及 Agent 实际给出的说明和最终回复。不建议把系统 Prompt、自动注入的旧记忆传入。

{
  "messages": [
    {
      "role": "user",
      "peer_id": "person_alice",
      "parts": [{"type": "text", "text": "我的 VPN 连不上，请先给简短步骤。"}]
    },
    {
      "role": "assistant",
      "parts": [{"type": "text", "text": "我先检查连接状态，再给出对应步骤。"}]
    }
  ]
}

Context Part：记录本次引用了什么

当本次消息引用了从 OpenViking 召回的记忆、知识等上下文信息，可用 Context Part 指向本次实际使用的已有内容。
context_type 可为 memory、resource 或 skill；uri 使用实际存在、当前身份可访问的 Viking URI，abstract 填写必要摘要。这些信息在召回时 OpenViking 的接口均会返回。

{
  "role": "assistant",
  "parts": [
    {"type": "text", "text": "下面的步骤参考了团队 VPN 排障手册。"},
    {
      "type": "context",
      "context_type": "resource",
      "uri": "viking://user/team_assistant/resources/vpn-guide.md",
      "abstract": "VPN 配置过期时，应获取有效配置并重新连接。"
    }
  ]
}

Tool Part：将调用与结果配成一条执行记录

许多 Agent 框架将工具调用放在 assistant 消息中，将结果放在独立的 tool / toolResult 消息中。
回流时，通过调用 ID 找到对应关系，把调用名称、参数、返回值和状态组织到同一个 Tool Part，外层使用 role=assistant。
在进行记忆抽取时，用户的个性化记忆（events，profile，preference，entities）不会参考工具调用，经验记忆（trajectories，experiences）依赖工具调用来完整分析 agent 执行过程，从而沉淀执行经验。
详细内容可参考：使用经验记忆实现 Agent 进化

一个 OpenClaw 风格的工具调用日志：

[
  {
    "role": "assistant",
    "content": [
      {"type": "toolCall", "id": "call_001", "name": "check_vpn", "arguments": {"profile": "office"}}
    ]
  },
  {
    "role": "toolResult",
    "toolCallId": "call_001",
    "toolName": "check_vpn",
    "isError": false,
    "content": [{"type": "text", "text": "网络正常，VPN 配置已过期。"}]
  }
]

转化为 OpenViking 的导入格式：

{
  "role": "assistant",
  "parts": [
    {
      "type": "tool",
      "tool_id": "call_001",
      "tool_name": "check_vpn",
      "tool_input": {"profile": "office"},
      "tool_output": "网络正常，VPN 配置已过期。",
      "tool_status": "completed"
    }
  ]
}

原始 agent 日志字段或事件	OpenViking message 字段	转换规则
调用 id 与结果 toolCallId / tool_call_id	tool_id	用同一个调用 ID 配对；不能仅按工具名称配对
工具名称	tool_name	保留实际名称；每次重试仍使用新的调用 ID
arguments / input	tool_input	传 JSON 对象。
工具返回内容	tool_output	传字符串；对象结果可序列化为 JSON 字符串
执行结果状态	tool_status	按实际状态填写；可传入 completed，error，或running。建议可以仅传入失败和执行完成的状态，以节省抽取记忆的token消耗

Commit：提交已完成的片段

用途：归档本次待处理的消息，并触发后台记忆抽取。先确认要提交的消息已全部上传，再调用 Commit。

POST {BASE_URL}/api/v1/sessions/{session_id}/commit
X-API-Key: {API_KEY}
Content-Type: application/json

{"keep_recent_count": 0}

commit 后返回本次提交的任务 ID，可轮询任务状态判断记忆抽取任务的执行情况（get_task-获取后台任务状态）

{
  "status": "ok",
  "result": {
    "session_id": "session_demo_001",
    "status": "accepted",
    "task_id": "task_demo_001",
    "archive_uri": "viking://user/team_assistant/sessions/session_demo_001/history/archive_001",
    "archived": true
  }
}

Commit 时可定义是否留出不抽取的近期消息数，以及为抽取的事件记忆打上标签等操作，详情可见：commit_session-提交会话。
您可以开发您的 agent 客户端或服务端，定义 Commit 的触发时机：

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

说明

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

提交任务完成后，在目标 session 将生成一个归档文件夹，可查看本次归档的所有消息，以及本次抽取都造成了哪些记忆的改动，可通过读取返回的 archive_uri 来查看：

在线接入：让 Agent 检索并使用记忆

收到新问题后，应用先确定本次允许读取的数据范围，再通过 MCP 或 OpenAPI 查找相关内容；当前任务的新记录继续交给离线链路处理。

推荐方式：通过 MCP 提供记忆工具

如果 Agent 框架已经支持 MCP，可以直接注册 OpenViking 的 MCP 服务，将 find、search、read 等工具接入现有工具循环，不必为每个检索接口单独编写工具适配。

注册工具。完成 MCP 连接与工具发现，确认 Agent 可以调用检索和读取工具。
约定调用时机。新任务开始时检查已召回内容，不足时调用 find；复杂问题需要进一步查找时使用 search，重要细节通过 read 读取原文。建议可直接安装通用 MCP 记忆 Skill 来指引记忆的检索和读取。

自定义方式：使用 OpenAPI 封装工具或固定流程

需要统一控制检索时机、返回数量、上下文长度，或严格限定多人服务中的读取范围时，可在应用后端封装记忆检索和读取工具。例如，模型只传入 query，后端根据当前登录用户确定目标目录，不接受模型任意指定 user_id 或 peer_id。
下面以读取 Alice 的记忆为例。target_uri 必须由业务系统确定；实际访问仍受凭证权限约束。

POST {BASE_URL}/api/v1/search/find
Authorization:Bearer {API_KEY}
Content-Type: application/json

{
  "query": "Alice 使用的设备和排障回复偏好",
  "target_uri": "viking://user/team_assistant/peers/person_alice/memories/",
  "limit": 5
}

find 返回相关结果及其 URI。可选择性读取记忆：

GET {BASE_URL}/api/v1/content/read?uri={URL 编码后的结果 URI}
Authorization:Bearer {API_KEY}

将记忆拼接至本轮的输入上下文，例如：

相关记忆（参考信息）
  经筛选的事实或经验＋来源 URI

近期对话
  完成本次任务仍需要的 user / assistant / 工具记录

当前用户请求
  用户本轮原始输入；若近期对话已包含，不再追加一遍

最近更新时间：2026.09.17 17:49:16

这个页面对您有帮助吗？

有用

无用

向量数据库VikingDB

创建 Session #

回流 Message：将交互记录映射为 Part #

Text Part：保存真实表达 #

Context Part：记录本次引用了什么 #

Tool Part：将调用与结果配成一条执行记录 #

Commit：提交已完成的片段 #

推荐方式：通过 MCP 提供记忆工具 #

自定义方式：使用 OpenAPI 封装工具或固定流程 #