# Agent 记忆 > 全部文档的索引见 [llms.txt](https://ark.volcengine.com/llms.txt)；在任一文档页面地址后追加 `.md` 可获取该页的 Markdown 版本。 火山引擎 OpenViking Context 为 Agent Plan Harness 层提供 Agent 记忆服务。OpenViking Context 是基于 [开源 OpenViking](https://github.com/volcengine/OpenViking) 内核构建的全托管云服务，是一款面向 AI Agents 的上下文数据库，以“虚拟文件系统 + 分层上下文 + 目录递归检索 + 可观测与自迭代”为核心思想，通过将 Memory、Resource、Skill 统一抽象为文件的理念，解决 AI Agent 在执行对话和长周期任务时的复杂上下文管理难题，为 AI Agent 开发者提供结构化、可追溯且低成本的上下文工程解决方案。 # 能力介绍 OpenViking Context 适用于需要长程记忆、复杂知识管理和多 Agent 协作的各类 AI 应用场景，核心价值在于提供结构化、可迭代的上下文管理能力。 - **Agent 长期记忆升级**：作为 Agent 产品的记忆插件，为 Agent 提供记忆沉淀、检索和自进化能力，解决长周期任务中常见的遗忘和高昂成本问题。 - **全局知识资产沉淀**：支持将多个代码仓库、文档库等知识源统一导入 OpenViking Context，构建可语义检索的知识库，赋能代码助手与研发场景。 - **多 Agent 协作共享**：多个独立 Agent 可共享同一个 OpenViking Context 实例作为记忆与知识中枢，实现高效协同。 - **多租户安全隔离**：利用多租户共享与隔离能力，为团队或企业构建安全可控的知识与记忆中心，让智能体在可控的上下文环境中执行任务。 # 使用限制 - 仅支持完成了实名认证的企业用户和个人用户使用。 - 仅支持在北京地域使用 Agent Plan 套餐的 AFP 额度抵扣火山引擎 OpenViking Context 资源的使用费用。 - 仅支持 Agent Plan 个人版、OpenViking Context 个人版。 - 如果您是子账号，首次使用时需联系主账号授权 [VikingdbFullAccess](https://console.volcengine.com/iam/policymanage/System/VikingdbFullAccess) 策略。 - 火山引擎官网账号未欠费（账户余额 ≥ 0）。 # 使用 OpenViking Context ## 步骤一：订阅套餐并开通 Agent 记忆 1. 在 [开通管理-Agent Plan](https://ark.volcengine.com/region:cn-beijing/openManagement?LLM=%7B%7D&advancedActiveKey=agentPlan) 页面购买 Agent Plan 个人版套餐。套餐说明参见[套餐概览](/docs/agent-plan-personal-plan-overview)。 2. 在控制台单击**Harness**，开启 Agent 记忆的抵扣开关。 ![memory1.png](https://arkdocs.tos-cn-beijing.volces.com/images/CodingPlan/memory1.png) ## 步骤二：创建数据库 在**Harness**区域，找到 Agent 记忆卡片，单击**配置使用**进入 OpenViking Context 页面，根据页面提示开通服务并创建数据库。 > **说明** > > 创建数据库的页面左下角会展示 AFP 抵扣信息。 ![memory2.png](https://arkdocs.tos-cn-beijing.volces.com/images/CodingPlan/memory2.png) ## 步骤三：接入 Agent OpenViking Context 支持 MCP、CLI、API、SDK 接入您的自研 Agent 框架，同时对主流 Agent 框架进行生态适配。 > **说明** > > 当前文档仅展示了常用 Agent 接入步骤，更多 Agent 的接入步骤可在 [OpenViking Context 控制台](https://console.volcengine.com/vikingdb/openviking/region:openviking+cn-beijing/) 页面单击**接入 Agent**查看。 > ![image-20260619-205438-901.png](https://arkdocs.tos-cn-beijing.volces.com/images/CodingPlan/image-20260619-205438-901.png) ### 认证说明 Agent 接入 OpenViking 时，必须使用 OpenViking 的 API Key 作为唯一认证，并关联到对应的数据。 OpenViking API Key 可在 [OpenViking Context 控制台](https://console.volcengine.com/vikingdb/openviking/region:openviking+cn-beijing/) 的**用户管理**页面查看与复制。 ![image-20260619-205141-807.png](https://arkdocs.tos-cn-beijing.volces.com/images/CodingPlan/image-20260619-205141-807.png) ### 主流 Agent 集成 **选项：Claude Code** > **说明** > > **集成方式**：Plugin 接入，为 Claude Code 添加跨项目、跨会话（session）的长期记忆功能。安装完成后，每轮对话均会自动召回相关记忆并捕获新内容，无需模型主动调用任何工具。 **步骤 1：安装** ```Bash bash <(curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/claude-code-memory-plugin/setup-helper/install.sh) ``` 该脚本将自动检查依赖项、配置 OpenViking 连接并完成插件安装，支持重复运行（幂等操作）。 安装完成后，需在当前终端激活 claude 的封装函数（wrapper），或者直接打开一个新的终端窗口： ```Bash source ~/.openviking/openviking-repo/examples/claude-code-memory-plugin/setup-helper/wrapper.sh ``` > **说明** > > 通过自定义命令启动 Claude Code？例如包装脚本 cc-custom，或“基础命令 + 子命令”形式的多词启动器——在安装时的“Extra launch commands”一步填入（或运行脚本时传入 `OPENVIKING_CC_WRAP_EXTRA='cc-custom'`），即可让它们一并注入凭据。 使用一段时间后，即便在全新的对话中提及过往的话题，Claude Code 也能准确回忆起来。 **步骤 2：验证** ```Bash type claude ``` > **说明** > > 若输出的是一个路径而非 shell function，说明 wrapper 尚未生效，请先 `source` 那行 wrapper（或新开一个终端）再启动；否则 `claude` 会静默连到本地 127.0.0.1 且不带鉴权。 在 type claude 显示为 shell function 的终端中运行 `claude` 启动，随后： * 输入 `/plugins`：在 Installed 列表中应能找到 openviking-memory（其子项openviking MCP 应显示为已连接状态）。 * 输入`/mcp`：OpenViking 对应的条目应显示您的服务器 URL 及有效的认证信息。 * 输入 `/openviking-memory:ov`：查看服务器状态、身份信息、召回/注入的统计数据以及功能开关状态。 若插件未正常工作，可设置环境变量 `OPENVIKING_DEBUG=1`，并查看日志文件 `~/.openviking/logs/cc-hooks.log` 以排查问题。 **选项：OpenClaw** > **说明** > > **集成方式**：Plugin 接入，作为 OpenClaw 的 context engine，支持多 Agent 跨会话记忆与自迭代，通过 npm 安装助手工具一键完成配置。 **前提条件**：您已经在本地或云服务器上部署了 OpenClaw 2026.5.2 或更新版本。 **步骤 1：安装 OpenViking** 在你的 OpenClaw 的机器终端，执行以下命令以安装 OpenViking Plugin。 ```Bash openclaw plugins install clawhub:@openviking/openclaw-plugin && openclaw openviking setup ``` **步骤 2：配置信息** 根据提示配置以下信息: * Base URL：`https://api.vikingdb.cn-beijing.volces.com/openviking` * API Key：在 OpenViking Context 控制台的**用户管理**页面复制 API Key，具体参见 [认证说明](/docs/agent-plan-personal-openviking-memory#81a0c3e9)。 **步骤 3：重启 OpenClaw** 复制以下指令到 Agent 终端以重启 OpenClaw，重启后控制台将自动判断 Agent 接入状态。 ```Bash openclaw gateway restart ``` **选项：Hermes Agent** > **说明** > > **集成方式**：Hermes 官方内置 OpenViking 作为记忆提供方。无需安装插件，直接把 Hermes 指向您的 OpenViking 服务即可，记忆存储、召回和抽取均原生支持。 **步骤1：配置** 运行 Hermes 记忆配置向导： ```Bash hermes memory setup ``` 配置以下信息： * OpenViking 服务 URL： 自托管服务器 或 火山引擎 OpenViking Context * API Key： 火山引擎 OpenViking Context 时填 API Key，具体参见 [认证说明](/docs/agent-plan-personal-openviking-memory#81a0c3e9)。 * 租户 account / user / agent ID：多租户部署时使用 配置保存在 Hermes 的 `config.yaml` 和 `.env` 文件中。 **步骤2：验证** ```Bash hermes memory status ``` 配置完成后，Hermes 自动使用 OpenViking 作为长期记忆——`viking_remember`、`viking_recall` 等记忆工具即刻可用。 **选项：Codex** > **说明** > > **集成方式**：Plugin 接入，为 Codex 提供持久化的跨会话（session）记忆。一次安装即可实现：每次输入前自动召回记忆、每轮对话结束后增量捕获，并在上下文压缩前将记忆提交给抽取器。 **步骤 1：安装** ```Bash bash <(curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/codex-memory-plugin/setup-helper/install.sh) ``` 该脚本会自动检查依赖、配置 OpenViking 连接并注册插件。所有步骤均具有幂等性，可安全地重复执行。 安装完成后，在当前终端激活 codex 封装函数，或重新打开一个终端窗口。 ```Bash source ~/.openviking/openviking-repo/examples/codex-memory-plugin/setup-helper/wrapper.sh # 首次启动需执行 /hooks 进行一次安全审批 codex ``` > **说明** > > 通过自定义命令启动 Codex？例如包装脚本 `codex-custom`，或“基础命令 + 子命令”形式的多词启动器——在安装时的“Extra launch commands”一步填入（或运行脚本时传入 `OPENVIKING_CODEX_WRAP_EXTRA='codex-custom'`），即可让它们一并注入凭据。 **步骤 2：验证** ```Bash type codex ``` > **说明** > > 若上一步输出的是一个路径而非 `shell function`，说明 wrapper 尚未生效，请先 `source` 那行 wrapper（或新开一个终端）再启动；否则 codex 启动时拿不到 `OPENVIKING_API_KEY`，会报 `MCP server is not logged in`。 进入 Codex 后，插件将在每次输入前自动召回记忆。将环境变量 `OPENVIKING_DEBUG` 设置为 1，可将事件日志输出至 `~/.openviking/logs/codex-hooks.log。` ### CLI 接入 **选项：手动终端安装** **步骤1**：安装 OpenViking CLI 并进入配置流程 ```Bash npm i -g @openviking/cli && ov config ``` **步骤2**: 配置信息 按提示填写以下信息： - Base URL：`https://api.vikingdb.cn-beijing.volces.com/openviking` - API Key：在 OpenViking Context 控制台的**用户管理**页面复制 API Key，具体参见 [认证说明](/docs/agent-plan-personal-openviking-memory#81a0c3e9)。 **步骤3**：查看 CLI 用法 ```Bash ov --help ``` **选项：通过 AI Agent 安装** 将下方提示词复制给您的 AI 助手（Claude Code、Codex、Cursor、TraeCode 等），它会自动完成 OpenViking CLI 安装、配置和用法学习： > **说明** > > `` 需替换为 OpenViking Context 控制台的**用户管理**页面的 API Key，具体参见 [认证说明](/docs/agent-plan-personal-openviking-memory#81a0c3e9)。 ```Plain Text 请先向用户询问 OpenViking API Key，并记为 OPENVIKING_API_KEY。 请在 ~/.openviking/ovcli.conf 写入以下内容： { "url": "https://api.vikingdb.cn-beijing.volces.com/openviking", "api_key": "" } 如发现 ~/.openviking/ovcli.conf 已存在且内容冲突，请先询问用户是否备份原文件，并在得到确认后再覆盖。 请安装 OpenViking CLI： npm i -g @openviking/cli 安装完成后，请运行： ov --help 请探索 CLI 用法，并把 OpenViking CLI 的使用方式写入你的长期记忆。 ``` ### MCP 接入 **步骤1：MCP 配置** 以下为 MCP 配置示例，将 `` 替换为 OpenViking API Key，具体参见[认证说明](/docs/agent-plan-personal-openviking-memory#81a0c3e9)。 ```JSON { "mcpServers": { "ov-mcp-server": { "url": "https://api.vikingdb.cn-beijing.volces.com/openviking/mcp", "headers": { "Authorization": "Bearer " } } } } ``` **步骤2：测试 MCP 工具连通性** ```Bash ov health ``` ### SDK 接入 **步骤1：安装 OpenViking** ```Bash pip install openviking --upgrade --force-reinstall ``` **步骤2：初始化客户端** 将控制台用户管理页面中展示的 API Key 复制到你的 Agent 运行环境中，建议通过环境变量或安全配置中心进行注入，而不要直接硬编码在代码里。具体参见[认证说明](/docs/agent-plan-personal-openviking-memory#81a0c3e9)。 ```Bash export OPENVIKING_API_KEY="your-api-key" ``` ```Python import os import openviking as ov client = ov.SyncHTTPClient( url="https://api.vikingdb.cn-beijing.volces.com/openviking", api_key=os.environ["OPENVIKING_API_KEY"], agent_id="your-agent-id", # 自定义 agent_id，用于隔离 Agent 侧上下文 timeout=120.0, ) client.initialize() ``` **步骤3：写入资源** 资源写入用于把外部知识导入 OpenViking Context。SDK 可以直接接收本地文件路径、目录路径或远端 URL，并自动处理上传细节。 ```Python file_path = "your-file-path" resource_to = "your-resource-path" # e.g. viking://resources/demo/api.md reason = "your-reason" # e.g. External API documentation result = client.add_resource( path=file_path, to=resource_to, reason=reason, wait=True, ) print(result) ``` > **说明** > > * to 必须位于 viking://resources/... 作用域下。 > * 如果 path 是本地文件，SDK 会自动先上传再调用服务端接口。 > * 如果 `wait=True`，接口会等待资源处理完成后再返回，更适合导入后马上检索的场景。 > * 如果不希望阻塞，也可以使用默认异步模式，然后显式调用 `client.wait_processed()`。 **步骤4：写入记忆** 记忆写入建议通过会话方式完成。下面示例演示如何将一条用户消息写入会话，并通过提交触发后续记忆提取。 ```Python text = "your-message-text" # e.g. I am a developer session = client.create_session() session_id = session["result"]["session_id"] if "result" in session else session["session_id"] client.add_message( session_id, "user", parts=[{"type": "text", "text": text}], ) result = client.commit_session(session_id) print(result) ``` ### API 接入 如果您希望通过平台网关、工作流引擎、低代码平台直接调用接口，推荐使用 HTTP API 接入。 **步骤1：写入资源** 对于 HTTP 接口，本地文件不能直接作为path传给 `/api/v1/resouces`，需先上传本地文件获取temp_file_id，再调用 `/api/v1/resouces`。 ```Python import json from pathlib import Path import requests url = "https://api.vikingdb.cn-beijing.volces.com/openviking" api_key = "your-api-key" #可在用户管理页面复制 agent_id = "your-agent-id" #自定义agent-id file_path = Path("your-file-path") # e.g. test.txt resource_to = "your-resource-path" # e.g. viking://resources/demo/test.txt reason = "your-reason" # e.g. External API documentation headers = { "Content-Type": "application/json", "Authorization": "Bearer " + api_key, "X-OpenViking-Agent": agent_id, } def post_json(path: str, payload: dict, timeout: float): response = requests.post( f"{url}{path}", headers=headers, json=payload, timeout=timeout, ) response.raise_for_status() return response.json() with file_path.open("rb") as file: result = requests.post( f"{url}/api/v1/resources/temp_upload", headers={ "Authorization": "Bearer " + api_key, "X-OpenViking-Agent": agent_id, }, files={"file": (file_path.name, file, "application/octet-stream")}, timeout=120.0, ) result.raise_for_status() result = result.json() print(json.dumps(result, ensure_ascii=False, indent=2)) temp_file_id = result["result"]["temp_file_id"] result = post_json( "/api/v1/resources", { "temp_file_id": temp_file_id, "source_name": file_path.name, "to": resource_to, "reason": reason, }, 120.0, ) print(json.dumps(result, ensure_ascii=False, indent=2)) ``` **步骤2：写入记忆** 通过 API 写入记忆时，同样遵循“创建会话 - 添加消息 - 提交会话”的流程。 ```Python import json import requests url = "https://api.vikingdb.cn-beijing.volces.com/openviking" api_key = "your-api-key" #可在【用户管理页面】复制 agent_id = "your-agent-id" #自定义agent-id text = "your-message-text" # e.g. I am a developer headers = { "Content-Type": "application/json", "Authorization": "Bearer " + api_key, "X-OpenViking-Agent": agent_id, } def post_json(path: str, payload: dict, timeout: float): response = requests.post( f"{url}{path}", headers=headers, json=payload, timeout=timeout, ) response.raise_for_status() return response.json() session = post_json("/api/v1/sessions", {}, 360.0) session_id = session["result"]["session_id"] post_json( f"/api/v1/sessions/{session_id}/messages", { "role": "user", "parts": [{"type": "text", "text": text}], }, 360.0, ) result = post_json( f"/api/v1/sessions/{session_id}/commit", {"telemetry": False}, 360.0, ) print(json.dumps(result, ensure_ascii=False, indent=2)) ``` # 计费说明 - **未开启超额后付费**：请求调用产生的费用使用套餐内 AFP 进行抵扣，不消耗其他资源包或账户余额。抵扣规则参见 [套餐内 AFP 抵扣规则](/docs/agent-plan-personal-afp-credits-billing-rules#9d6f1c2a)。 - **开启超额后付费**：在套餐周期内额度未用尽时优先抵扣套餐额度；当套餐周期内额度用尽时，无需修改任何配置信息，系统将自动切换至超额后付费模式继续使用，并产生后付费账单。具体规则与操作参见 [超额后付费规则](/docs/agent-plan-personal-over-quota-postpaid-rules#6f4a2d1c) 和 [超额后付费管理](/docs/agent-plan-personal-over-quota-postpaid-management#1a2b3c4d)。 # 实践教程 **[搭建销售团队工作台](https://bytedance.larkoffice.com/wiki/WpXuw57E0i69sHkK9DNcraEPn1c)** 基于 Agent Plan + Codex + AI Native 应用开发底座 + 豆包搜索 + 专业数据集 + Agent 记忆，把散落在飞书会话、云文档里的私域销售资料和外部专业信息，搭成一个能查公司、看档案、问历史的销售团队定制工作台。 ‌ # 常见问题 * 我想保留 OpenViking 服务，仅想从 Agent Plan 抵扣切换到官网付费，要如何操作？ 在 Agent Plan 页面关闭抵扣后，立即进入 [OpenViking Context 控制台](https://console.volcengine.com/vikingdb/openviking/region:openviking+cn-beijing/) 重新开通 OpenViking 商品即可。 * 我想保留 OpenViking 服务，仅想从官网付费切换到 Agent Plan 抵扣，要如何操作？ 下单个人版 Agent Plan 套餐，并在 Agent Plan 页面开启抵扣即可。 * Agent Plan 额度不足且未开通超额后付费，导致服务无法使用，如何恢复？ 开启超额后付费立即恢复，通过官网出账；或升级 Agent Plan 套餐扩充 AFP 额度，待下一个扣费周期扣减成功即可恢复，最长 1 小时；或升级后 oncall 客服人工恢复。 # 服务协议 - [OpenViking Context 专用条款](https://docs.volcengine.com/docs/84313/2485137?lang=zh) - [Harness 能力说明和产品专用条款](/docs/harness-rules)