hermes 外部记忆配置openviking，（客户端）

环境
Win11，WSL2，Ubuntu24.04

一、相关文档

记忆提供程序

Memory Providers

openviking简介

openviking快速开始

在线服务

OpenViking Service（火山引擎云）

产品介绍

二、配置hermes

健康检查

uadmin@UD26:~$ curl http://127.0.0.1:1933/health
{"status":"ok","healthy":true,"version":"0.4.10","auth_mode":"dev"}

切换记忆提供者

uadmin@UD26:~$ hermes config set memory.provider openviking
✓ Set memory.provider = openviking in /home/uadmin/.hermes/config.yaml

~/.hermes/config.yaml

memory:
  flush_min_turns: 6
  memory_char_limit: 2200
  memory_enabled: true
  nudge_interval: 10
  provider: openviking
  user_char_limit: 1375
  user_profile_enabled: true

查看记忆状态

hermes memory status

uadmin@UD26:~$ hermes memory status

Memory status
────────────────────────────────────────
  Built-in:  always active
  Provider:  openviking

  Plugin:    installed ✓
  Status:    not available ✗
  Missing:
    ✗ OPENVIKING_ENDPOINT
    ✗ OPENVIKING_API_KEY
    ✗ OPENVIKING_ACCOUNT
    ✗ OPENVIKING_USER
    ✗ OPENVIKING_AGENT
    ✗ OPENVIKING_RECALL_LIMIT
    ✗ OPENVIKING_RECALL_SCORE_THRESHOLD
    ✗ OPENVIKING_RECALL_MAX_INJECTED_CHARS
    ✗ OPENVIKING_RECALL_TIMEOUT_SECONDS
    ✗ OPENVIKING_RECALL_REQUEST_TIMEOUT_SECONDS
    ✗ OPENVIKING_RECALL_FULL_READ_LIMIT
    ✗ OPENVIKING_RECALL_PREFER_ABSTRACT
    ✗ OPENVIKING_RECALL_RESOURCES

  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)

报了一堆Missing，可以忽略，

在~/.hermes/.env中配置OPENVIKING_ENDPOINT，就不报Missing（还是配上吧）

# 外部记忆openviking

# openviking服务端点（需要配置，配了不报Missing）

OPENVIKING_ENDPOINT=http://127.0.0.1:1933

.env更多配置

~/.hermes/.env

# 外部记忆openviking
# openviking服务端点（需要配置，配了不报Missing）
OPENVIKING_ENDPOINT=http://127.0.0.1:1933
# dev 模式（无认证），不需要root_api_key
OPENVIKING_API_KEY=
# OpenViking 里的租户 / 用户 / agent 标识，用来隔离不同用户/助手的记忆空间。
# 租户 account ID
OPENVIKING_ACCOUNT=default
# 用户 ID
OPENVIKING_USER=default
# 这是 Hermes 在 OpenViking 中的对等 ID (peer ID)，可以设置为 hermes
OPENVIKING_AGENT=hermes

# 以下召回相关参数为可选测试，不配有默认值（前期不需要配置）
# 自动召回最多注入的记忆条数
OPENVIKING_RECALL_LIMIT=6
# 召回的最低相关性分数（低于此分数的记忆不注入）
OPENVIKING_RECALL_SCORE_THRESHOLD=0.15
# 单次召回注入的总字符数上限	
OPENVIKING_RECALL_MAX_INJECTED_CHARS=4000
# 召回整体超时（秒）
OPENVIKING_RECALL_TIMEOUT_SECONDS=4.0
# 召回单次 HTTP 请求超时（秒）
OPENVIKING_RECALL_REQUEST_TIMEOUT_SECONDS=3.0
# 每次召回最多读取几篇完整 L2 正文
OPENVIKING_RECALL_FULL_READ_LIMIT=2
#为 true 时只用摘要（L0），不读完整正文
OPENVIKING_RECALL_PREFER_ABSTRACT=false
#为 true 时召回范围包含 resources（知识库资源），默认只召回记忆
OPENVIKING_RECALL_RESOURCES=false

再查看记忆状态

hermes memory status

uadmin@UD26:~$ hermes memory status

Memory status
────────────────────────────────────────
  Built-in:  always active
  Provider:  openviking

  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)

查看日志

tail -f ~/.hermes/logs/gateway.log

hermes logs -f

三、测试

Hermes 聊天框核心测试方法

进入 Hermes 对话界面后，按以下 3 个层级测试，从基础连通到核心长期记忆能力逐步验证。

1. 显式工具调用测试（最快验证连通性）

直接发指令让 Hermes 调用 OpenViking 专属工具，能成功执行就代表链路完全打通。

• 存储记忆测试 发送指令：

  用 viking_remember 保存一条事实：我的测试标记为 openviking-20260723，开发环境是 WSL2 Ubuntu 24.04
  

  正常情况下 Hermes 会调用 viking_remember 工具，返回执行成功的结果，内容会写入 OpenViking 的用户记忆库。

• 语义检索测试 紧接着换表述提问，验证召回能力：

  用 viking_search 搜索和我的开发环境相关的内容
  

  或者直接自然提问：我之前存的测试标记是什么？，能准确返回对应内容，说明语义检索正常。

• 目录浏览测试 验证 OpenViking 文件系统范式是否可用：

  用 viking_browse 浏览 viking:// 根目录
  

  能返回 resources/、user/ 等目录结构，说明文件系统层级功能正常。

2. 自动跨会话记忆测试（验证核心长期记忆能力）

这个测试可以验证 Hermes 是否自动同步对话、会话结束自动提取记忆，以及跨会话召回的核心能力：

a. 在当前对话里说一段独特的、不会出现在内置记忆里的内容，比如：我接下来的开发任务是给 Hermes 记忆OpenViking 配置阿里云百炼模型和本地的模型。
b. 正常结束当前 Hermes 会话（退出 CLI/TUI），等待 10-20 秒，让会话提交后触发 OpenViking 的自动记忆提取
c. 重新打开一个全新的 Hermes 会话，直接提问：我接下来优先级最高的开发任务是什么？
如果新会话能准确召回上一轮的内容，说明 OpenViking 的长期持久化记忆、跨会话自动召回完全生效。

3. 资源导入与分级加载测试（进阶验证 OpenViking 特性）

如果要验证 OpenViking 的核心能力，可以测试资源导入和分层读取：

用 viking_add_resource 导入这个文档：https://hermes-agent.ac.cn/docs/user-guide/features/memory-providers

导入完成后，验证分级加载：

给我这个资源的 L0 摘要

能返回～100 token 的精简摘要，就代表 L0/L1/L2 分层加载功能正常。

三、OpenViking 侧反向验证（确认数据写入外部存储）

如果要确认数据确实写入了 OpenViking，而不是 Hermes 内置的 MEMORY.md/USER.md，可以从 OpenViking 侧反向验证：

1. OpenViking CLI 检索验证（

如果你安装了 openviking 包，直接在终端执行检索：

ov命令需要后续先配置一下

ov find "测试标记"

能搜到你刚才在 Hermes 里存储的内容，就说明数据确实持久化到了 OpenViking 数据库。

2. 本地存储目录验证

本地部署的 OpenViking 数据默认存在 ~/.openviking/data 目录（或你 ov.conf 里配置的 storage.workspace 路径），可以查看目录下是否生成了对应的记忆、资源文件，确认持久化正常。

四、OpenViking CLI（ov命令）

这是OpenViking 的客户端工具

文档

OpenViking CLI 配置指南

远程自定义
只有 root key 的配置需要 --account 和 --user。

本地自定义
本地默认 URL：http://127.0.0.1:1933
本地无鉴权服务通常不需要 API Key。

ov命令之前的提示

uadmin@UD26:~$ ov find "测试标记"
OPENVIKING LANGUAGE
Current: English

? Choose language
  ↑/↓ choose · Enter select · Esc back · Ctrl+C exit

  › English
    简体中文

语言已切换为简体中文。
ov find 测试标记

╭─ 配置错误 ───────────────────────────────────────────────────────────╮
│ 未检测到 ovcli.conf。请先运行 ov config 创建配置，再使用服务器命令。 │
╰──────────────────────────────────────────────────────────────────────╯

下一步：
  ov config  创建配置

可以通过ov config命令配置（稍微麻烦），也可以手动配置~/.openviking/ovcli.conf文件（快捷）

设置语言

uadmin@UD26:~$ ov language zh-CN
语言已切换为简体中文。

uadmin@UD26:~$ ov language en
Language set to English.

这个命令会创建
~/.openviking/ovcli.settings.conf

ov config配置

ov config

uadmin@UD26:~$ ov config

 ██████╗ ██████╗ ███████╗███╗   ██╗██╗   ██╗ ██╗ ██╗  ██╗ ██╗ ███╗   ██╗ ██████╗
██╔═══██╗██╔══██╗██╔════╝████╗  ██║██║   ██║ ██║ ██║ ██╔╝ ██║ ████╗  ██║██╔════╝
██║   ██║██████╔╝█████╗  ██╔██╗ ██║██║   ██║ ██║ █████╔╝  ██║ ██╔██╗ ██║██║  ███╗
██║   ██║██╔═══╝ ██╔══╝  ██║╚██╗██║╚██╗ ██╔╝ ██║ ██╔═██╗  ██║ ██║╚██╗██║██║   ██║
╚██████╔╝██║     ███████╗██║ ╚████║ ╚████╔╝  ██║ ██║  ██╗ ██║ ██║ ╚████║╚██████╔╝
 ╚═════╝ ╚═╝     ╚══════╝╚═╝  ╚═══╝  ╚═══╝   ╚═╝ ╚═╝  ╚═╝ ╚═╝ ╚═╝  ╚═══╝ ╚═════╝


╭──────────────────────────── AI Agent 上下文数据库 ────────────────────────────╮
│                                                                               │
│              ⢻⣶⣄                                                              │
│              ⠈⣿⣿⣟⢦⡀                                                           │
│               ⣿⣿⣿⡌⢻⣦⡀                                                         │
│               ⣿⣿⣿⣧ ⠹⣿⣦⡀        当前配置： none                                │
│              ⢀⣿⣿⣿⣿  ⢹⣿⣷⡀       状态： 未配置                                  │
│              ⣼⣿⣿⣿⡟  ⠈⣿⣿⣷       VLM: 未知                                      │
│            ⢀⣼⣿⣿⣿⣿⣁⣀⣤⣤⣿⣿⣿⡄  ⡀   Embedding: 未知                                │
│           ⢀⣾⡿⠿⠛⢛⣿⣿⣿⣿⣿⣿⣿⣿⡇⢀⣼⠃   已保存配置： 0                                 │
│              ⢀⣰⣿⣿⣿⣿⣿⠿⠟⠛⠋⣡⣿⠇    配置目录： ~/.openviking                       │
│    ⠠⣶⣾⣿⣿⣿⣶⣤⣀ ⠾⠟⠛⠉⠉   ⣀⣤⣾⡿⠃                                                    │
│      ⠙⢿⣿⣿⣿⣿⣿⣿⣷⣶⣶⣶⣶⣶⣿⣿⣿⡿⠟⠁                                                     │
│        ⠈⠛⠿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠿⠛⠉                                                        │
│             ⠈⠉⠉⠉⠁                                                             │
╰──────────────────────────────────────────────────────────── v0.4.11.dev0 ─────╯

◆ 你想配置什么？

? 选择操作
  ↑/↓ 选择 · Enter 确认 · Esc 返回 · Ctrl+C 退出

  › 添加配置
    切换配置
    编辑配置
    删除配置
    用户管理

选择：添加配置
----------------------------------------------------------------------------------------

◆ 创建新的 OpenViking 配置。

? CLI 要连接到哪里？
  ↑/↓ 选择 · Enter 确认 · Esc 返回 · Ctrl+C 退出

  › OpenViking 服务（火山引擎云）
    自定义

选择：自定义
----------------------------------------------------------------------------------------

? 配置名称（可选）
  Enter 继续 · Esc 返回 · Ctrl+C 退出

  留空将自动生成名称。

  >

回车默认
----------------------------------------------------------------------------------------

? 服务器 URL
  Enter 继续 · Esc 返回 · Ctrl+C 退出
  默认值： http://127.0.0.1:1933

  >

回车默认
----------------------------------------------------------------------------------------

? API Key 类型
  ↑/↓ 选择 · Enter 确认 · Esc 返回 · Ctrl+C 退出

  本地服务可不填；如果启用了认证，请填写。

  › 无密钥 / 本地开发
    User API Key
    Root API Key

回车默认
----------------------------------------------------------------------------------------

? 账户 ID
  Enter 继续 · Esc 返回 · Ctrl+C 退出

  本地无密钥身份。
  默认值： default

  >

回车默认
----------------------------------------------------------------------------------------

? 保存本地配置名称
  ↑/↓ 选择 · Enter 确认 · Esc 返回 · Ctrl+C 退出

  选择这个本地 CLI 配置的名称。
  保存为 ovcli.conf.<name>；当前配置为 ovcli.conf。

  › 设置自定义本地名称
    使用生成名称（custom-d01089）
    返回

选择：使用生成名称（custom-d01089）
----------------------------------------------------------------------------------------

? 保存配置？
  ↑/↓ 选择 · Enter 确认 · Esc 返回 · Ctrl+C 退出

  › 保存并设为当前配置
    仅保存
    取消

回车默认
----------------------------------------------------------------------------------------

✓ 已保存配置 'custom-d01089'，并设为当前配置。
保存到： /home/uadmin/.openviking/ovcli.conf.custom-d01089
当前配置： /home/uadmin/.openviking/ovcli.conf
下一步： 运行 ov --help 查看可用命令。

配置文件ovcli.conf

~/.openviking/ovcli.conf

{
  "account": "default",
  "user": "default"
}

手动配置ovcli.conf

创建并配置文件~/.openviking/ovcli.conf

api_key没有可以不写。

{
  "url": "http://127.0.0.1:1933",
  "api_key": "你的服务端密钥",
  "account": "default",
  "user": "default"
}

ov命令测试

ov find "测试标记"

uadmin@UD26:~$ ov find "测试标记"
cmd: ov find --uri= -n 10 "测试标记"
10 results
Ranked by relevance · limit 10 final results

1. memory · Level 2 · score 0.439
   viking://user/default/peers/hermes/memories/preferences/user/开发环境配置.md
   - 开发环境为 WSL2 Ubuntu 24.04 - 当前测试标记为 openviking-20260723

2. memory · Level 2 · score 0.427
   viking://user/default/peers/hermes/memories/preferences/mem_210444957cc5.md
   开发环境是 WSL2 Ubuntu 24.04，测试标记为 openviking-20260723

3. memory · Level 2 · score 0.348
   viking://user/default/memories/cases/viking记忆保存与搜索验证.md
   # viking记忆保存与搜索验证 ## Task Signature
   用户保存开发环境相关事实后，执行语义搜索验证记忆可被正确检索，再浏览viking根目录确认仓库结构...
...

命令帮助

ov --help