企业官网建设流程全解析

Hermes Agent 接入 OpenViking 记忆提供方：配置向导详解与验证指南

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

本指南讲解如何在 Hermes Agent（Nous Research）中启用 OpenViking 作为记忆提供方（Memory Provider），通过hermes memory setup openviking向导完成云端或自托管服务的配置，并用hermes memory status验证接入状态。读完本文，你将掌握从向导交互、关键配置项含义到故障排查、以及基于 LoCoMo 基准测试验证记忆链路完整性的全套实战能力。

背景：Hermes Agent 原生内置 OpenViking

OpenViking 定位为 AI Agent 的自进化上下文数据库（Self-evolving Context Database），统一了 Agent 记忆（Memory）、知识库检索（Knowledge RAG）与技能（Skills）。Hermes Agent 作为首批原生集成方之一，无需安装任何插件——只要把 Hermes 指向你的 OpenViking 服务，记忆的存储、召回和抽取均由 OpenViking 原生支持（见 docs/zh/agent-integrations/05-hermes.md）。

从仓库的接入方式分类（见 docs/images/agents/zh/index.json）可以看到，Hermes 属于Provider接入类型，与 Claude Code、Codex 等 Plugin 类型不同：它不依赖 Hook 或插件安装脚本，而是通过 Hermes 官方的 memory-provider 体系直接对接 OpenViking HTTP 服务。

环境准备与隔离要求

Hermes 通过 HTTP 连接 OpenViking，因此无需把 OpenViking 安装进 Hermes 的 Python 环境。官方文档明确给出两条建议：

• 在独立的虚拟环境或容器中运行 OpenViking 服务，与 Hermes 环境隔离；
• 不要在已有 Hermes 的环境中用--force-reinstall安装或升级 OpenViking，避免依赖版本被覆盖；如确需同环境共存，应在同一次依赖求解中安装，并在启动任一服务前运行python -m pip check。

接入前请先确认 OpenViking 服务已就绪。本地部署可参考 docs/zh/guides/03-deployment.md：运行openviking-server init初始化~/.openviking/ov.conf，openviking-server doctor校验配置与模型访问，默认监听http://127.0.0.1:1933，健康检查为curl http://localhost:1933/health。远程访问时的 API Key 设置见 docs/zh/guides/04-authentication.md。

步骤 1：运行安装向导

在终端执行如下命令，启动 OpenViking 记忆配置向导：

hermes memory setup openviking

1.1 选择配置来源

向导首先询问配置来源，出现如下选择界面：

OpenViking config source ↑↓ navigate ENTER/SPACE select ESC cancel → (●) Use existing OpenViking profile - choose from detected ovcli.conf profiles (○) Create new OpenViking profile - enter a new URL/API key

选项说明：

1.2 选择连接方式

若选择「Create new OpenViking profile」，将出现连接方式选择界面：

OpenViking connection ↑↓ navigate ENTER/SPACE select ESC cancel → (●) OpenViking Service (VolcEngine Cloud) - use the managed OpenViking endpoint (○) Custom - use a local, VPS, or self-hosted OpenViking server

• OpenViking Service (VolcEngine Cloud)：使用火山引擎托管的 OpenViking 托管端点（默认https://api.vikingdb.cn-beijing.volces.com/openviking），只需粘贴 API Key；
• Custom：使用本地、VPS 或自托管的 OpenViking 服务器，需要填写 URL（自托管默认http://127.0.0.1:1933）和 API Key；本地免鉴权部署（即auth_mode = "dev"，见 docs/zh/guides/04-authentication.md）时 API Key 可留空。

1.3 填入 API KEY

选择云托管后，向导要求输入 API KEY：

{{OPENVIKING_API_KEY}}

云端 Key 从火山引擎控制台获取；自托管场景下，若服务端配置了server.root_api_key或为用户签发了 user key，则在此填入对应密钥。

1.4 设置 Hermes peer ID in OpenViking

填写「Hermes peer ID in OpenViking」：该字段是 Hermes 在 OpenViking 中的 Agent 身份标识，用于区分不同 Agent 产生的记忆。可直接按 Enter 使用默认值hermes，也可自定义填写。

从源码看，peer_id 是 OpenViking 的核心身份字段之一：openviking/core/peer_id.py 通过normalize_identifier_part(peer_id, "peer_id")对其进行规范化，非法值会抛出ValueError（safe_peer_id则在异常时返回None）。这意味着 peer_id 必须符合标识符命名约束，不能包含路径分隔符等非法字符。在 LoCoMo 基准脚本 benchmark/locomo/hermes/import_to_ov.py 中，add_message(..., peer_id=msg.get("peer_id"))会把 peer_id 附着到每条消息上，用于后续按 Agent 维度检索记忆。

1.5 选择配置保存方式

建议选择「Mirror to OpenViking store」：

Save OpenViking config ↑↓ navigate ENTER/SPACE select ESC cancel (○) Keep in Hermes only - write values only to Hermes .env → (●) Mirror to OpenViking store - write ~/.openviking/ovcli.conf.<name> and link it

1.6 填写 OpenViking profile name

填写「OpenViking profile name」：Hermes 的多租户能力可隔离不同 Profile 的模型、记忆、配置及凭据。建议为每个 Hermes Profile 配置独立的 OpenViking 环境或身份，并在此填写一个便于识别的本地配置名称，以区分对应的 OpenViking 配置。该名称仅用于本地标识，不会创建新用户，也不会改变账号身份或权限。

1.7 完成确认

配置完成后将显示如下确认信息：

OpenViking memory is ready Created and linked OpenViking profile. Config file: ~/.openviking/ovcli.conf.hermes Start a new Hermes session to activate.

注意最后一行：需要启动一个新的 Hermes 会话，记忆提供方才会被激活。同时可以看到，生成的配置文件为~/.openviking/ovcli.conf.hermes（ovcli.conf.<profile-name>命名），与 OpenViking CLI 的配置体系（见 docs/zh/guides/03-deployment.md 中 CLI 从ovcli.conf读取连接配置的描述）完全兼容。

步骤 2：验证接入状态

执行以下命令验证记忆插件状态：

hermes memory status

返回如下结果即表示接入成功：

Memory status ──────────────────────────────────────── Built-in (MEMORY.md / USER.md): Memory injection: enabled ✓ User profile: enabled ✓ Memory tool: enabled ✓ Provider: openviking openviking config: use_ovcli_config: True ovcli_config_path: ~/.openviking/ovcli.conf.hermes endpoint: `https://api.vikingdb.cn-beijing.volces.com/openviking` agent: hermes Plugin: installed ✓ Status: available ✓ Installed plugins: • byterover (API key / local) • hindsight (API key / local) • holographic (local) • honcho (API key / local) • mem0 (API key / local) • openviking (API key / local) ← active • retaindb (API key / local) • supermemory (requires API key)

需要关注的验证要点：

• Provider 必须为openviking，说明当前激活的记忆提供方正确；
• use_ovcli_config: True与ovcli_config_path表明配置复用了 OpenViking CLI 的ovcli.conf体系；
• endpoint指向实际连接的 OpenViking 服务（云端托管端点或自托管 URL）；
• agent: hermes即配置的 peer ID；
• Plugin 与 Status 均为 available，且插件列表中openviking ← active，说明记忆链路可用。

故障排查

若使用自托管服务且Status异常，建议同时排查服务端状态：curl http://localhost:1933/health检查存活、curl http://localhost:1933/ready检查 AGFS、VectorDB、Embedding 等就绪情况（见 docs/zh/guides/03-deployment.md）；若配置了鉴权，还需核对 ovcli.conf 中的api_key是否与服务端签发的 key 一致（见 docs/zh/guides/04-authentication.md）。

进阶：用 LoCoMo 基准验证 Hermes × OpenViking 记忆链路

仓库在 benchmark/locomo/hermes/README.md 中提供了面向 Hermes Agent 的 LoCoMo QA 基准，用于验证记忆链路端到端是否真正打通，同时对比三种记忆路径：

运行方式：

cd benchmark/locomo/hermes ./run_full_eval.sh --suite native ./run_full_eval.sh --suite e2e ./run_full_eval.sh --suite preingest

e2e套件在导入前会先执行 preflight 探测：向 Hermes 发起一次带X-Hermes-Session-Id的对话请求，再查询 OpenViking 的/api/v1/sessions/{session_id}，确认会话确实落到了配置的 OpenViking 目标上（见 run_full_eval.sh 中的verify_hermes_openviking_target）。这实际上就是对「Hermes → OpenViking 记忆链路」的自动化冒烟验证，可作为接入后更深一层的正确性检查手段。

导入侧，import_to_ov.py 演示了 Python 异步 SDK 的标准写入流程：AsyncHTTPClient(url, api_key, account, user)→create_session→add_message→commit_session(telemetry=True)→ 轮询get_task等待后台抽取完成。其中 account/user 命名空间与 docs/zh/guides/04-authentication.md 中的多租户身份模型一一对应，可用于理解 peer_id 之外的账号维度隔离。

总结

接入 Hermes Agent 与 OpenViking 记忆提供方只需三步：运行hermes memory setup openviking向导完成配置、启动新会话激活、用hermes memory status验证状态。向导完整覆盖了「复用现有 ovcli.conf / 新建 Profile」「云托管 / 自托管」「peer ID 隔离」「配置镜像保存」等关键决策点，配合仓库中的 05-hermes.md 集成文档、部署指南 与 认证指南，即可在本地或云端快速搭建起稳定的 Agent 长期记忆基础设施。

相关参考：

• 集成文档与能力参考：docs/zh/agent-integrations/05-hermes.md、docs/zh/agent-integrations/16-capability-reference.md
• 服务部署：docs/zh/guides/03-deployment.md
• 鉴权设置：docs/zh/guides/04-authentication.md
• LoCoMo 基准：benchmark/locomo/hermes/README.md

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