Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
feat(hermes): update Quick Local releases during setup (#5710)
z1gon9f150ece247a
diff --git a/docs/en/agent-integrations/01-overview.md b/docs/en/agent-integrations/01-overview.mdindex 753e2a391..6d6498f80 100644--- a/docs/en/agent-integrations/01-overview.md+++ b/docs/en/agent-integrations/01-overview.md@@ -12,7 +12,7 @@ OpenViking can act as the long-term memory and context backend for many agent ru| **Cursor** | [Cursor Memory Integration](./12-cursor.md) — one command installs lifecycle hooks, MCP tools, rules, and skills || **TRAE / TRAE CN** | [TRAE Memory Integration](./13-trae.md) — one installer configures prompt-time recall, turn capture, and OpenViking tools || **DeepSeek Harness (`dsh`)** | [DeepSeek Harness Memory Bundle](./17-dsh.md) — in-process Cordis plugin with pre-step recall, event capture, and the OpenViking MCP tools |-| **Hermes Agent** | [Hermes Agent](./05-hermes.md) — built-in OpenViking memory provider, no plugin install needed |+| **Hermes Agent** | [Hermes Agent](./05-hermes.md). Memory plugin with automatic capture and recall. Older releases include a built-in provider. || **OpenCode** | [OpenCode Plugin](./10-opencode.md) — MCP tools plus lifecycle hooks for repo context, auto-recall, and capture || **pi** | [pi Coding Agent Extension](./11-pi.md) — native extension with auto-recall, turn capture, threshold commit, and the server's MCP tools registered as native pi tools || **LangChain / LangGraph** | [LangChain and LangGraph](./07-langchain-langgraph.md) — retriever, tools, context backend, store, and middleware |diff --git a/docs/en/agent-integrations/05-hermes.md b/docs/en/agent-integrations/05-hermes.mdindex f915c1440..485bc0d91 100644--- a/docs/en/agent-integrations/05-hermes.md+++ b/docs/en/agent-integrations/05-hermes.md@@ -1,40 +1,75 @@# Hermes-[Hermes Agent](https://hermes-agent.nousresearch.com/) by Nous Research has a first-class OpenViking memory provider built in. No plugin to install — just point Hermes at your OpenViking server and it handles memory storage, recall, and extraction natively.+Use OpenViking for long-term memory in [Hermes Agent](https://hermes-agent.nousresearch.com/).-## Keep the Python environments separate+## Get started-Hermes connects to OpenViking over HTTP, so OpenViking does not need to be-installed in the Hermes Python environment. Run the OpenViking server in its-own virtual environment or container. Do not use `--force-reinstall` to add or-upgrade OpenViking in an existing Hermes environment: a Hermes release may pin-dependency versions that differ from OpenViking's supported, security-patched-versions. If you intentionally combine both applications in one environment,-resolve them together and run `python -m pip check` before starting either-service.--## Setup+Run these commands in the Hermes profile you want to use:```bash+hermes plugins install openviking --enablehermes memory setup openviking+hermes```-- Cloud: keep **OpenViking Service (VolcEngine Cloud)**, paste the API key-- Custom: URL (default `http://127.0.0.1:1933`) and API key; leave the key empty for local dev-- Reuse an existing `ovcli.conf` profile if the wizard offers one+Accept the dependency prompt during installation. If your Hermes release still+includes OpenViking, skip the install command. That release uses its built-in+copy and does not provide Quick Local.++Hermes uses conversation history to follow the current chat. OpenViking saves+useful facts as long-term memory for later chats. Common memory is not linked+to a sender.++Choose **Personal Agent** to recall common memory and the current sender's+memory while keeping your conversation history settings. Choose **Shared Agent**+to share history within each group or thread and recall all senders' memories+under the same OpenViking user. Shared Agent asks for confirmation.++Then choose a connection:++- **Quick Local** installs a local server and embedding model. It reuses your+ supported Hermes language model for extraction, which can use a remote API.+- **OpenViking Service (VolcEngine Cloud)** connects to VolcEngine's+ [managed OpenViking cloud service](https://www.volcengine.com/product/openviking-service)+ with a service API key. You do not need to install a server or configure+ local models.+- **Custom** connects to your own server with its URL and credentials. Setup+ can also reuse a saved `ovcli.conf`.++After setup, chat as usual. The plugin requests a commit at 20,000 pending+tokens by default, at session end and when switching sessions. Memories become+available after OpenViking finishes extraction. Existing server data is kept.++Quick Local keeps its server running after Hermes exits. See the+[plugin guide](https://hermes-agent.nousresearch.com/docs/plugins/openviking)+for model support, server controls and the known local embedding issue.-## Verify+## Check status```bashhermes memory status```-`available` means that the provider is configured. It does not check server-connectivity or confirm memory extraction.+`available` means the provider is configured. It does not confirm server+health or successful memory extraction.++## Update++```bash+hermes plugins update openviking+```++Restart Hermes or the gateway afterward. Your connection settings and data+are kept. To update a Quick Local server, run setup again and choose Quick+Local. Normal chat uses the installed server without checking for updates.++When a Hermes update removes the built-in provider, it attempts to install+the catalog plugin for profiles already using OpenViking. If that fails,+run the install command above in that profile.-## See also+## More information-- [Capability Reference](./16-capability-reference.md)-- [Hermes — OpenViking memory provider docs](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory-providers#openviking) — full setup guide and configuration options-- [Deployment Guide](../guides/03-deployment.md) — setting up your OpenViking server-- [Authentication](../guides/04-authentication.md) — API key setup for remote access+- [Plugin guide](https://hermes-agent.nousresearch.com/docs/plugins/openviking)+- [Capability reference](./16-capability-reference.md)+- [Server deployment](../guides/03-deployment.md)+- [API keys](../guides/04-authentication.md)diff --git a/docs/en/agent-integrations/16-capability-reference.md b/docs/en/agent-integrations/16-capability-reference.mdindex ef9502383..803507846 100644--- a/docs/en/agent-integrations/16-capability-reference.md+++ b/docs/en/agent-integrations/16-capability-reference.md@@ -60,6 +60,10 @@ Long-term memories are extracted from a session only after a **commit**. Capture| Hermes (bundled) | Yes, session-aware with a fallback | Profile and memory listings | No; only at session boundaries | Yes, if pending uploads finish within 10 seconds | Commits at fork-style compaction || ov CLI | No | No | Only `ov session commit` | Not applicable | Not applicable |+Rows labeled **Hermes (bundled)** describe the pinned in-tree provider+from earlier Hermes releases. Catalog-based releases use the external plugin.+Its different lifecycle behavior is listed in [Hermes](#hermes).+How to read this table:- **Session-aware recall** sends the session ID so the server can use the conversation to interpret the query. The shared plugins’ context mode also expands the query and tracks recently injected memories to avoid repeating them. Hermes uses list mode, which has no injection ledger. OpenClaw uses context search with the session ID but turns deduplication off, because its injected context is rebuilt every turn and never stored in the history. See [How recall reaches the server](#how-recall-reaches-the-server) for the request paths and fallbacks.@@ -666,28 +670,40 @@ Each note covers what is specific to one integration. Shared behavior is in the### Hermes-[Hermes Agent](./05-hermes.md). Two OpenViking memory providers exist for Hermes, and both register under the provider name `openviking`:+[Hermes Agent](./05-hermes.md). Depending on its version, Hermes uses the catalog+plugin or the built-in provider named `openviking`:++- The **catalog plugin** is maintained in this repository under+ [`examples/hermes-plugin`](https://github.com/volcengine/OpenViking/tree/main/examples/hermes-plugin).+ Install it with `hermes plugins install openviking --enable`, then run+ `hermes memory setup openviking`.+- The **bundled provider** exists in earlier Hermes releases under+ `plugins/memory/openviking` and needs no installation. The Hermes rows on this+ page describe that provider at+ [Hermes commit `989798c`](https://github.com/NousResearch/hermes-agent/tree/989798cd5e691230b54b2ea72e5937b68133014c/plugins/memory/openviking).-- The **bundled provider** ships inside Hermes under `plugins/memory/openviking` and needs no installation; `hermes memory setup openviking` configures it. The Hermes rows on this page describe the bundled provider as of [Hermes commit `989798c`](https://github.com/NousResearch/hermes-agent/tree/989798cd5e691230b54b2ea72e5937b68133014c/plugins/memory/openviking).-- The **external plugin** is maintained in this repository under [`examples/hermes-plugin`](https://github.com/volcengine/OpenViking/tree/main/examples/hermes-plugin) and installed with `hermes plugins install`. According to its README, a Hermes release that still bundles the provider loads the bundled copy, and the external plugin becomes active only after the bundled copy is removed. Configuration and stored data carry over.+A release that still includes the bundled provider loads it first. When an+update removes the bundle from a profile already configured for OpenViking,+Hermes attempts to install the catalog plugin automatically. The provider name,+configuration, and stored data do not change.The two are separate code bases. Where their behavior differs:| | Bundled provider (Hermes `989798c`) | External plugin (this repository) ||---|---|---|-| Commits during a session | None; only at session boundaries | A background commit at 20,000 pending tokens (`commit_token_threshold`) |+| Commits during a session | Only at session boundaries | A background commit at 20,000 pending tokens (`commit_token_threshold`) || Recall digests | Not supported | Optional server digest (`recall_compress`) || Mirroring Hermes's built-in memory | Additions only | Additions, replacements, and removals, tracked in a URI registry || `viking_forget` | User memory files with an explicit user ID | Also accepts `viking://~/`, rejects user-ID-less layouts, and checks ownership before deleting |-| Cron, subagent, and flush contexts | Not documented at that commit | Recall works; automatic writes and mirroring are skipped |+| Cron, subagent, and flush contexts | Not documented at that commit | Recall works. Automatic writes and mirroring are skipped |-Behavior of the bundled provider:+Behavior of the pinned bundled provider:- Recall runs before every model call, through session-aware `search/search`, with `/find` as a fallback. Defaults: 6 results, score threshold 0.15, 4,000 characters, 4 seconds in total and 3 seconds per request.-- `viking_remember` sends the fact unchanged through its own session and commits it; it returns `status: submitted`.+- `viking_remember` sends the fact unchanged through its own session and commits it. It returns `status: submitted`.- Commits leave no live messages (`keep_recent_count` 0). Uploads are not durable, but pending-commit markers let a later start commit sessions from a dead run on POSIX.- Memories are written under `viking://user/<uid>/memories/`, or `viking://user/<uid>/peers/<peer>/memories/` when a peer is set.-- Linking an OpenViking `ovcli.conf` profile clears the five connection variables from the Hermes `.env`. `hermes backup` includes the default or environment-selected `ovcli.conf` under `$HOME`; back up a YAML-linked file separately.+- Linking an OpenViking `ovcli.conf` profile clears the five connection variables from the Hermes `.env`. `hermes backup` includes the default or environment-selected `ovcli.conf` under `$HOME`. Back up a YAML-linked file separately.<a id="_5-ov-cli-command-reference"></a><a id="_5-1-command-tree"></a><a id="_5-2-global-options-and-unique-mechanisms"></a><a id="_5-3-capabilities-only-the-cli-has"></a>@@ -787,7 +803,9 @@ The comparisons above were checked against these locations. They help when you n- Hook hosts: `examples/agent-hook-plugin/hosts/` for Cursor, TRAE, ZCode, and Kimi Code.- pi takeover: `examples/pi-coding-agent-extension/lib/takeover-core.mjs`.- OpenClaw tools and lifecycle hooks: `examples/openclaw-plugin/registries/openviking-tools.ts` and `examples/openclaw-plugin/plugin/openviking-lifecycle-hooks.ts`.-- Hermes: the bundled provider at the pinned Hermes commit linked in [Hermes](#hermes), and the external plugin's [README](https://github.com/volcengine/OpenViking/blob/main/examples/hermes-plugin/README.md).+- Hermes: the bundled provider from earlier releases at the pinned commit linked+ in [Hermes](#hermes), and the catalog plugin's+ [README](https://github.com/volcengine/OpenViking/blob/main/examples/hermes-plugin/README.md).## See alsodiff --git a/docs/images/agents/en/hermes.md b/docs/images/agents/en/hermes.mdindex 2b2b1f13d..fab7ae0c4 100644--- a/docs/images/agents/en/hermes.md+++ b/docs/images/agents/en/hermes.md@@ -1,103 +1,69 @@-## Step 1: Install+# OpenViking Service for Hermes-1. Run the following command to start the OpenViking memory setup wizard:+[OpenViking Service](https://www.volcengine.com/product/openviking-service) is+OpenViking hosted and operated by VolcEngine. You do not need to install a server+or configure local models. Activate the service and create an API key in the+[OpenViking console](https://console.volcengine.com/vikingdb/openviking/region:openviking+cn-beijing).+Open **User Management**, then **API Key**.- ```bash- hermes memory setup openviking- ```+## Set up-2. If local `ovcli.conf` profiles exist, the wizard asks for the configuration- source. Otherwise, it starts creating a new configuration:+Run these commands in the Hermes profile you want to use:- ```text- 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- ```+```bash+hermes plugins install openviking --enable+hermes memory setup openviking+```- Options:+Accept the dependency prompt during installation. Skip the install command+if your Hermes release already includes OpenViking.- - Reuse an existing Profile: read the OpenViking URL and secret from a local `ovcli.conf`, with no need to enter them again.- - Create a new Profile: manually provide the OpenViking service endpoint and credentials. Use this for first-time setup or when connecting to a new instance.+In the wizard:-3. If you choose **Create new OpenViking profile**, select **OpenViking Service (VolcEngine Cloud)** when asked for the connection type:+1. Choose **Personal Agent** to recall common memory and the current sender's+ memory while keeping history settings. Choose **Shared Agent** to share+ history within each group or thread and recall all senders' memories under+ the same OpenViking user. Shared Agent asks for confirmation.+2. If prompted, choose **Create new OpenViking profile**. You can also reuse+ a saved `ovcli.conf`.+3. Choose **OpenViking Service (VolcEngine Cloud)**.+4. Enter your service API key.+5. Choose where to save the connection. **Keep in Hermes only** saves it in+ the Hermes `.env`. **Mirror to OpenViking store** saves a local+ `ovcli.conf.<name>` and links Hermes to it. Both save credentials on this+ computer.+6. For a saved OpenViking profile, enter a name such as `hermes`. This is a+ local config name. It does not create a user or change access rights.- ```text- OpenViking connection- ↑↓ navigate ENTER/SPACE select ESC cancel+Then start a new Hermes session:- → (●) OpenViking Service (VolcEngine Cloud) - use the managed OpenViking endpoint- (○) Custom - use a local, VPS, or self-hosted OpenViking server- ```+```bash+hermes+```-4. Enter the API KEY:+For a local server, the external plugin also offers **Quick Local**. It reuses+a supported Hermes language model and installs a local server and embedding model.+See the [plugin guide](https://hermes-agent.nousresearch.com/docs/plugins/openviking)+for requirements and known issues.- ```text- {{OPENVIKING_API_KEY}}- ```+## Check status-5. Choose how to save the configuration. We recommend **Mirror to OpenViking store**:+```bash+hermes memory status+```- ```text- 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- ```--6. Fill in **OpenViking profile name**, for example `hermes`. Hermes' multi-tenant capabilities can isolate models, memories, configuration, and credentials across Profiles. We recommend configuring an independent OpenViking environment or identity for each Hermes Profile, and using an easy-to-recognize local name here. This name is local only; it does not create a new user or change account identity or permissions.-7. When setup completes, Hermes shows:-- ```text- OpenViking memory is ready- Created and linked OpenViking profile.- Config file: ~/.openviking/ovcli.conf.hermes- Start a new Hermes session to activate.- ```--New connections use user memory without an assistant peer. Setup does not ask-for a peer ID. To separate assistant context, set `memory.openviking.agent` in-the active Hermes profile's `config.yaml`. Existing peer memories are not moved.--## Step 2: Verify--1. Check the memory plugin status:-- ```bash- hermes memory status- ```--2. Confirm that OpenViking is selected and configured. `available` does not- check server connectivity or confirm memory extraction:-- ```text- 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-- Plugin: installed ✓- Status: available ✓-- ```+Confirm that the provider is `openviking` and its status is `available`.+This confirms saved configuration, not server health or successful extraction.## Troubleshoot-| Problem | Fix |-|---|---|-| Provider is not openviking | Re-run `hermes memory setup openviking` |-| Status is not available | Check the configured endpoint and linked OpenViking config file |+| Problem | What to do |+|---------|------------|+| Plugin is missing | Run `hermes plugins install openviking --enable` in this profile. |+| Another provider is selected | Run `hermes memory setup openviking` again. |+| Status is not available | Check the saved connection settings and any linked `ovcli.conf`. |-## Reference+## More information-- Docs on Manual Settings: [Hermes](https://docs.openviking.net/en/agent-integrations/05-hermes)-- Blog about how it works: [OpenViking memory provider](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory-providers#openviking)+- [Hermes integration](https://docs.openviking.net/en/agent-integrations/05-hermes)+- [Plugin guide](https://hermes-agent.nousresearch.com/docs/plugins/openviking)diff --git a/docs/images/agents/en/index.json b/docs/images/agents/en/index.jsonindex 1cd56b0ca..666cf401b 100644--- a/docs/images/agents/en/index.json+++ b/docs/images/agents/en/index.json@@ -101,7 +101,7 @@"name": "Hermes Agent","tags": ["Provider"],"logo": "https://lf3-static.bytednsdoc.com/obj/eden-cn/lm_sth/ljhwZthlaukjlkulzlp/agent_logo/Hermes-Agent.png",- "summary": "Hermes includes OpenViking as a native memory provider. Run hermes memory setup openviking, keep VolcEngine Cloud, and paste the API key.",+ "summary": "Long-term memory for Hermes with automatic capture and recall. Connect to OpenViking Service or your own server, or use Quick Local with the external plugin.","detailPath": "https://docs.openviking.net/agents/en/hermes.md"},{diff --git a/docs/images/agents/zh/hermes.md b/docs/images/agents/zh/hermes.mdindex e2b996577..94016dbca 100644--- a/docs/images/agents/zh/hermes.md+++ b/docs/images/agents/zh/hermes.md@@ -1,101 +1,63 @@-## 步骤1:安装+# 为 Hermes 配置 OpenViking Service-1. 在终端执行如下命令,启动 OpenViking 记忆配置向导:+[OpenViking Service](https://www.volcengine.com/product/openviking-service) 是+火山引擎托管和运营的 OpenViking 云服务,无需安装服务端或配置本地模型。+在 [OpenViking 控制台](https://console.volcengine.com/vikingdb/openviking/region:openviking+cn-beijing)+开通服务,然后从**用户管理**的 **API Key** 中创建密钥。- ```bash- hermes memory setup openviking- ```+## 安装和配置-2. 如果本地已有 `ovcli.conf` 配置,向导会询问配置来源;否则会直接开始创建新配置:+在要使用的 Hermes profile 中运行:- ```text- 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- ```+```bash+hermes plugins install openviking --enable+hermes memory setup openviking+```- 选项说明:+安装时接受依赖安装提示。如果当前 Hermes 版本已内置 OpenViking,请跳过安装命令。- - 复用现有 Profile:直接读取本地已有的 `ovcli.conf` 中的 OpenViking 地址和密钥,无需重复填写。- - 新建 Profile:需手动输入 OpenViking 服务的访问 URL 和 API 密钥,适合首次配置或连接新实例的场景。+在向导中:-3. 若选择「Create new OpenViking profile」,将出现连接方式选择,请选择「OpenViking Service (VolcEngine Cloud)」:+1. 选择 **Personal Agent** 可召回公共记忆和当前发送者的记忆,并保留现有历史设置。+ 选择 **Shared Agent** 可在每个群组或话题内共享历史,召回同一 OpenViking 用户+ 下所有发送者的记忆。Shared Agent 会要求确认。+2. 若出现配置来源选项,选择 **Create new OpenViking profile**。也可以复用已保存的+ `ovcli.conf`。+3. 选择 **OpenViking Service (VolcEngine Cloud)**。+4. 输入服务 API Key。+5. 选择保存位置。**Keep in Hermes only** 保存到 Hermes 的 `.env`。+ **Mirror to OpenViking store** 保存到本地 `ovcli.conf.<name>` 并关联到 Hermes。+ 两种方式都会将凭据保存在当前电脑。+6. 保存 OpenViking profile 时,填写名称,例如 `hermes`。这只是本地配置名称,+ 不会创建用户或改变访问权限。- ```text- OpenViking connection- ↑↓ navigate ENTER/SPACE select ESC cancel+然后启动新的 Hermes 会话:- → (●) OpenViking Service (VolcEngine Cloud) - use the managed OpenViking endpoint- (○) Custom - use a local, VPS, or self-hosted OpenViking server- ```+```bash+hermes+```-4. 填入 API KEY:+外部插件还提供 **Quick Local**,可复用受支持的 Hermes LLM,安装本地服务和+embedding 模型。要求和已知问题见[插件指南](https://hermes-agent.nousresearch.com/docs/plugins/openviking)。- ```text- {{OPENVIKING_API_KEY}}- ```+## 查看状态-5. 选择配置保存方式,建议选择「Mirror to OpenViking store」:+```bash+hermes memory status+```- ```text- 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- ```--6. 填写「OpenViking profile name」,例如 `hermes`:Hermes 的多租户能力可隔离不同 Profile 的模型、记忆、配置及凭据。建议为每个 Hermes Profile 配置独立的 OpenViking 环境或身份,并在此填写一个便于识别的本地配置名称,以区分对应的 OpenViking 配置。该名称仅用于本地标识,不会创建新用户,也不会改变账号身份或权限。-7. 配置完成后将显示如下确认信息:-- ```text- OpenViking memory is ready- Created and linked OpenViking profile.- Config file: ~/.openviking/ovcli.conf.hermes- Start a new Hermes session to activate.- ```--新连接默认使用用户记忆,不设置助手 peer;向导不再询问 peer ID。如需隔离助手-上下文,可在当前 Hermes profile 的 `config.yaml` 中设置 `memory.openviking.agent`。-已有的 peer 记忆不会迁移。--## 步骤2:验证--1. 执行以下命令验证记忆插件状态:-- ```bash- hermes memory status- ```--2. 确认已选择并配置 OpenViking。`available` 不会检查服务端连通性,也不代表记忆已完成抽取:-- ```text- 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-- Plugin: installed ✓- Status: available ✓-- ```+确认 provider 为 `openviking`,状态为 `available`。这只表示配置已保存,+不代表服务健康或记忆抽取成功。## 故障排查| 问题 | 处理 |-|---|---|-| Provider 不是 openviking | 重跑 `hermes memory setup openviking` |-| Status 不是 available | 检查 endpoint 配置和关联的 OpenViking 配置文件 |+|------|------|+| 插件未安装 | 在该 profile 中运行 `hermes plugins install openviking --enable`。 |+| 使用了其他 provider | 重新运行 `hermes memory setup openviking`。 |+| 状态不是 available | 检查保存的连接设置和关联的 `ovcli.conf`。 |-## 参考+## 更多信息-- 手动配置文档:[Hermes](https://docs.openviking.net/zh/agent-integrations/05-hermes)-- 原理说明:[OpenViking memory provider](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory-providers#openviking)+- [Hermes 集成](https://docs.openviking.net/zh/agent-integrations/05-hermes)+- [插件指南](https://hermes-agent.nousresearch.com/docs/plugins/openviking)diff --git a/docs/images/agents/zh/index.json b/docs/images/agents/zh/index.jsonindex e68260aff..e857ab148 100644--- a/docs/images/agents/zh/index.json+++ b/docs/images/agents/zh/index.json@@ -101,7 +101,7 @@"name": "Hermes Agent","tags": ["Provider"],"logo": "https://lf3-static.bytednsdoc.com/obj/eden-cn/lm_sth/ljhwZthlaukjlkulzlp/agent_logo/Hermes-Agent.png",- "summary": "Hermes 官方内置 OpenViking。跑 hermes memory setup openviking,默认选火山云,再贴上 API Key 即可",+ "summary": "为 Hermes 提供长期记忆,自动捕获和召回。连接 OpenViking Service 或自有服务,也可通过外部插件使用 Quick Local。","detailPath": "https://docs.openviking.net/agents/zh/hermes.md"},{diff --git a/docs/zh/agent-integrations/01-overview.md b/docs/zh/agent-integrations/01-overview.mdindex 4f55245d4..d28cd52a8 100644--- a/docs/zh/agent-integrations/01-overview.md+++ b/docs/zh/agent-integrations/01-overview.md@@ -12,7 +12,7 @@ OpenViking 可以作为多种 Agent 运行时的长期记忆与上下文后端| **Cursor** | [Cursor 记忆集成](./12-cursor.md) — 一条命令安装生命周期 Hook、MCP 工具、Rules 与 Skills || **TRAE / TRAE CN** | [TRAE 记忆集成](./13-trae.md) — 一个安装器完成 prompt 召回、回合捕获与 OpenViking 工具接入 || **DeepSeek Harness(`dsh`)** | [DeepSeek Harness 记忆插件](./17-dsh.md) — 进程内 Cordis 插件,pre-step 召回、事件捕获与 OpenViking MCP 工具 |-| **Hermes Agent** | [Hermes Agent](./05-hermes.md) — 内置 OpenViking 记忆提供方,无需安装插件 |+| **Hermes Agent** | [Hermes Agent](./05-hermes.md)。自动捕获和召回记忆,旧版本使用内置提供方。 || **OpenCode** | [OpenCode 插件](./10-opencode.md) — MCP 工具 + 生命周期 hooks,覆盖仓库上下文、自动召回与捕获 || **pi** | [pi Coding Agent 扩展](./11-pi.md) — 原生扩展,自动召回、逐轮捕获、阈值 commit,并把服务端的 MCP 工具注册为 pi 原生工具 || **LangChain / LangGraph** | [LangChain 和 LangGraph](./07-langchain-langgraph.md) — retriever、tools、context backend、store 和 middleware |diff --git a/docs/zh/agent-integrations/05-hermes.md b/docs/zh/agent-integrations/05-hermes.mdindex e9cc84696..47d6927e4 100644--- a/docs/zh/agent-integrations/05-hermes.md+++ b/docs/zh/agent-integrations/05-hermes.md@@ -1,37 +1,65 @@# Hermes-[Hermes Agent](https://hermes-agent.nousresearch.com/) (Nous Research) 内置 OpenViking 记忆提供方。无需安装插件——把 Hermes 指向你的 OpenViking 服务即可,记忆存储、召回和抽取均原生支持。+为 [Hermes Agent](https://hermes-agent.nousresearch.com/) 配置 OpenViking 长期记忆。-## 隔离 Python 环境+## 开始使用-Hermes 通过 HTTP 连接 OpenViking,因此无需把 OpenViking 安装到 Hermes 的-Python 环境中。请在独立的虚拟环境或容器中运行 OpenViking 服务。不要在-已有 Hermes 的环境中使用 `--force-reinstall` 安装或升级 OpenViking:Hermes-版本可能会固定与 OpenViking 已支持、已修复安全问题的版本不同的依赖。如果确实要将-两个应用放在同一环境中,请在同一次依赖求解中安装它们,并在启动任一服务前运行-`python -m pip check`。--## 配置+在要使用的 Hermes profile 中运行:```bash+hermes plugins install openviking --enablehermes memory setup openviking+hermes```-- 云:保持 **OpenViking Service (VolcEngine Cloud)**,粘贴 API Key-- 自托管:填 URL(默认 `http://127.0.0.1:1933`)和 API Key;本地免鉴权可留空-- 向导若发现已有 `ovcli.conf`,直接复用即可+安装时接受依赖安装提示。如果当前 Hermes 版本仍内置 OpenViking,请跳过安装命令。+该版本会使用内置副本,不提供 Quick Local。++对话历史用于理解当前聊天。长期记忆保存有用的信息,供后续聊天使用。+公共记忆是不属于某个发送者的记忆。++选择 **Personal Agent** 可召回公共记忆和当前发送者的记忆,并保留现有对话历史设置。+选择 **Shared Agent** 可在每个群组或话题内共享对话历史,并召回同一 OpenViking 用户+下所有发送者的记忆。Shared Agent 会要求确认。++然后选择连接方式:++- **Quick Local** 安装本地服务和 embedding 模型,复用受支持的 Hermes LLM 抽取记忆。+ LLM 仍可使用远程 API。+- **OpenViking Service (VolcEngine Cloud)** 通过服务 API Key 连接火山引擎的+ [OpenViking 托管云服务](https://www.volcengine.com/product/openviking-service),+ 无需安装服务端或配置本地模型。+- **Custom** 使用 URL 和凭据连接自己的服务,也可以复用已保存的 `ovcli.conf`。++配置后正常聊天即可。插件默认在待提交内容达到 20,000 tokens、会话结束或切换时+请求提交。OpenViking 完成抽取后,记忆才能被召回。已有服务端数据会保留。++Quick Local 服务在 Hermes 退出后仍会运行。支持的模型、服务控制命令和已知本地+embedding 问题见[插件指南](https://hermes-agent.nousresearch.com/docs/plugins/openviking)。-## 验证+## 查看状态```bashhermes memory status```-`available` 表示 provider 已配置,不会检查服务端连通性,也不代表记忆已完成抽取。+`available` 表示 provider 已配置,不代表服务健康,也不代表记忆抽取成功。++## 更新++```bash+hermes plugins update openviking+```++更新后重启 Hermes 或 gateway。连接设置和数据会保留。更新 Quick Local 服务时,+重新运行配置向导并选择 Quick Local。正常聊天使用已安装的服务,不会检查更新。++Hermes 更新移除内置副本时,会为已使用 OpenViking 的 profile 尝试安装目录插件。+如果失败,请在该 profile 中运行上面的安装命令。-## 参见+## 更多信息+- [插件指南](https://hermes-agent.nousresearch.com/docs/plugins/openviking)- [集成能力参考](./16-capability-reference.md)-- [Hermes — OpenViking memory provider 文档](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory-providers#openviking) — 完整配置指南-- [部署指南](../guides/03-deployment.md) — 搭建 OpenViking 服务-- [鉴权](../guides/04-authentication.md) — 远程访问的 API Key 设置+- [服务部署](../guides/03-deployment.md)+- [API Key](../guides/04-authentication.md)diff --git a/docs/zh/agent-integrations/16-capability-reference.md b/docs/zh/agent-integrations/16-capability-reference.mdindex ba949aad2..be2492c09 100644--- a/docs/zh/agent-integrations/16-capability-reference.md+++ b/docs/zh/agent-integrations/16-capability-reference.md@@ -60,6 +60,9 @@| Hermes(内置) | 是,带会话,有回退路径 | profile 与记忆清单 | 否;只在会话边界 | 是,前提是待上传内容在 10 秒内完成 | fork 型压缩时提交 || ov CLI | 否 | 否 | 只有 `ov session commit` | 不适用 | 不适用 |+标为 **Hermes(内置)** 的行描述旧版 Hermes 中固定提交的内置 provider。+使用目录插件的版本会加载外部插件,其不同的生命周期行为见 [Hermes](#hermes)。+表格说明:- **带会话的召回**会发送会话 ID,服务端借助对话内容理解查询。共享插件的 context 模式还会扩写查询,并记录最近注入过的记忆,避免重复注入。Hermes 用 list 模式,没有注入台账。OpenClaw 用 context search 并发送会话 ID,但关闭去重,因为它注入的上下文每轮重建,不写入历史。请求路径和回退见[召回请求如何到达服务端](#召回请求如何到达服务端)。@@ -666,10 +669,20 @@ Claude Code、Codex、Cursor、TRAE、ZCode、Kimi Code、DSH 和 pi 还会安### Hermes-[Hermes](./05-hermes.md)。Hermes 有两个 OpenViking memory provider,都以 provider 名 `openviking` 注册:+[Hermes](./05-hermes.md)。Hermes 通过两种分发方式提供名为 `openviking` 的+memory provider:++- **目录插件**在本仓库的+ [`examples/hermes-plugin`](https://github.com/volcengine/OpenViking/tree/main/examples/hermes-plugin)+ 中维护。先运行 `hermes plugins install openviking --enable`,再运行+ `hermes memory setup openviking`。+- **内置 provider** 存在于旧版 Hermes 的 `plugins/memory/openviking` 中,+ 无需安装。本页的 Hermes 行描述+ [Hermes 提交 `989798c`](https://github.com/NousResearch/hermes-agent/tree/989798cd5e691230b54b2ea72e5937b68133014c/plugins/memory/openviking)+ 时的内置 provider。-- **内置 provider** 位于 Hermes 的 `plugins/memory/openviking`,无需安装,用 `hermes memory setup openviking` 配置。本页的 Hermes 行描述的是 [Hermes 提交 `989798c`](https://github.com/NousResearch/hermes-agent/tree/989798cd5e691230b54b2ea72e5937b68133014c/plugins/memory/openviking) 时的内置 provider。-- **外部插件**在本仓库的 [`examples/hermes-plugin`](https://github.com/volcengine/OpenViking/tree/main/examples/hermes-plugin) 维护,用 `hermes plugins install` 安装。据其 README,仍内置该 provider 的 Hermes 版本会加载内置副本,外部插件要在内置副本移除后才生效。配置和已存数据可以沿用。+仍包含内置 provider 的版本会优先加载内置副本。当更新移除内置副本时,已配置+OpenViking 的 profile 会自动尝试安装目录插件。provider 名、配置和已存数据均保持不变。两者是独立的代码库。行为差异如下:@@ -681,7 +694,7 @@ Claude Code、Codex、Cursor、TRAE、ZCode、Kimi Code、DSH 和 pi 还会安| `viking_forget` | 带明确用户 ID 的用户记忆文件 | 还接受 `viking://~/`,拒绝不带用户 ID 的路径,删除前检查归属 || cron、子代理和 flush 上下文 | 该提交中没有说明 | 召回可用;跳过自动写入和镜像 |-内置 provider 的行为:+上述固定提交中内置 provider 的行为:- 每次模型调用前召回,走带会话的 `search/search`,以 `/find` 作为回退。默认值:6 条结果、分数阈值 0.15、4,000 字符、总计 4 秒、单请求 3 秒。- `viking_remember` 把事实原样通过独立会话发送并提交,返回 `status: submitted`。@@ -787,7 +800,8 @@ CLI 提供而插件没有的能力:多个 `ovcli.conf` profile、账户与用- hook 宿主:`examples/agent-hook-plugin/hosts/`,对应 Cursor、TRAE、ZCode 和 Kimi Code。- pi takeover:`examples/pi-coding-agent-extension/lib/takeover-core.mjs`。- OpenClaw 工具和生命周期 hook:`examples/openclaw-plugin/registries/openviking-tools.ts` 和 `examples/openclaw-plugin/plugin/openviking-lifecycle-hooks.ts`。-- Hermes:[Hermes](#hermes) 中链接的固定 Hermes 提交里的内置 provider,以及外部插件的 [README](https://github.com/volcengine/OpenViking/blob/main/examples/hermes-plugin/README.md)。+- Hermes:[Hermes](#hermes) 中链接的旧版内置 provider 固定提交,以及目录插件的+ [README](https://github.com/volcengine/OpenViking/blob/main/examples/hermes-plugin/README.md)。## 参见diff --git a/examples/hermes-plugin/CONFIGURATION.md b/examples/hermes-plugin/CONFIGURATION.mdnew file mode 100644index 000000000..7c7c3bdd1--- /dev/null+++ b/examples/hermes-plugin/CONFIGURATION.md@@ -0,0 +1,358 @@+# Advanced configuration for Hermes++The setup wizard is enough for normal use. Start with the [quick setup](README.md#get-started).+Use this page to change settings or recover a failed memory operation.++## Manual connection setup++Select OpenViking in the active Hermes profile:++```bash+hermes config set memory.provider openviking+```++Add the connection values to that profile's `.env` file:++```text+OPENVIKING_ENDPOINT=http://127.0.0.1:1933+# OPENVIKING_API_KEY=...+# OPENVIKING_ACCOUNT=default+# OPENVIKING_USER=default+```++The default profile uses `~/.hermes/.env`. A named profile uses+`~/.hermes/profiles/<profile>/.env`. Start a new Hermes session after changing it.++## Quick Local model support++Quick Local copies Hermes's language model settings into its own server config.+It supports a static API key or Hermes's local llama.cpp server through an+OpenAI-compatible or Anthropic-compatible API. OAuth logins and credentials+that need a cloud provider's own authentication are not supported. For those+models, use a Custom server with its own model configuration.++Google AI Studio uses its OpenAI-compatible endpoint. Static OpenAI and xAI+keys use Chat Completions, so the model must support that API. Kimi Coding keeps+Hermes's client headers. Anthropic connections that need Bearer authentication,+including MiniMax and Azure Foundry, require a Custom server. The same applies+to proxy keys that OpenViking's LiteLLM backend identifies as OAuth tokens.++Setup sends one short model request before it activates Quick Local. It retries+once for a timeout, HTTP 429 or HTTP 5xx. Other errors stop setup immediately.+Errors and logs do not include the key or the provider's response body.++The local embedding model is `bge-small-zh-v1.5-f16`, with 512 dimensions.+It is trained for Chinese. Use Custom for a server with another embedding model.++## Quick Local files and backups++Files are stored under `$HERMES_HOME/openviking/`. Logs are stored at+`$HERMES_HOME/logs/openviking-server.log`. Each profile has its own server and+port. New setups select a free port from 1934 to 1953. An existing setup keeps+its saved port if it is free, or selects another one if it is occupied.++The server package comes from PyPI. Its download is checked against PyPI's+SHA-256 hash. The native embedding packages use fixed versions and hashes.+Setup asks before building from source on other platforms. Building requires+native development tools and can take several minutes.++An installed server can use more than 1 GB of disk and several hundred MB of+memory per profile. Upgrades keep old runtime directories and downloaded+packages, so disk use can grow.++Hermes backups include files under the profile home. The plugin also adds a+linked `ovcli.conf` outside the profile if it is within your user home directory.+Back up files outside your user home separately. After restoring on another+machine, run setup again to rebuild any runtime missing from the backup.++## Connection settings++OpenViking's server config is separate from Hermes:++- `ov.conf` configures OpenViking storage, embedding/VLM models, authentication and+ server behavior. OpenViking reads it from `--config`,+ `OPENVIKING_CONFIG_FILE`, or `~/.openviking/ov.conf`.+- `ovcli.conf` stores client/CLI connection values such as `url`, `api_key`,+ `account`, and `user`. It is read from `OPENVIKING_CLI_CONFIG_FILE` or+ `~/.openviking/ovcli.conf`.++Hermes reads provider settings from the initialized profile's `config.yaml`,+profile secrets, and linked `ovcli.conf`. Connection values resolve in this order:+profile environment, linked OpenViking config, Hermes YAML, then defaults. API keys+come from profile secrets or the linked OpenViking config, not Hermes YAML.+Quick Local uses its own saved connection and ignores connection environment+overrides. Recall and commit settings still accept their documented overrides.+After initialization, the provider keeps that profile for connection, identity,+and recall settings, including when another profile is active in the same+process. For the launch profile, process-level `OPENVIKING_*` values fill missing+`.env` values. Under multi-profile hosting, Hermes uses the process values frozen+at activation. A messaging gateway without that snapshot does not read them.+Routed profiles never inherit the launch profile's process values.++OpenViking 0.2.14 or newer is required. Older servers with a status-only health+response do not provide the user identity needed by this plugin. The `viking://~`+home address requires OpenViking 0.4.16 or newer for user and admin keys, or+0.4.17 or newer for root keys and local development.++| Environment variable | Default | Description |+|---------|---------|-------------|+| `OPENVIKING_ENDPOINT` | `http://127.0.0.1:1933` | Server URL |+| `OPENVIKING_API_KEY` | (none) | API key for authenticated servers |+| `OPENVIKING_ACCOUNT` | `default` | Tenant account for local/trusted mode |+| `OPENVIKING_USER` | `default` | Tenant user for local/trusted mode |+| `OPENVIKING_AGENT` | (none) | Optional peer ID for separate assistant context |++User and admin API keys let OpenViking derive account/user identity from the key.+In local or trusted deployments without an API key,+Hermes sends `OPENVIKING_ACCOUNT` and `OPENVIKING_USER` as identity headers.+Hermes also sends `User-Agent: openviking-memory-hermes/<version>` on+OpenViking requests. This header contains the Hermes version. It does not+contain a user identifier or require an extra request.++### Optional peer identity++New connections use the OpenViking user's memory directory by default. Setup+does not ask for a peer ID. Without a configured peer, Hermes sends neither+`X-OpenViking-Actor-Peer` nor assistant-message `peer_id`.++For separate assistant context, set the existing `agent` field in the active+profile's `config.yaml`:++```yaml+memory:+ openviking:+ agent: work-assistant+```++Existing non-empty `OPENVIKING_AGENT`, YAML `agent`, and linked OpenViking+`actor_peer_id` or legacy `agent_id` values retain their behavior. Resolution+order remains environment, linked OpenViking config, then Hermes YAML for Service+and Custom connections. Quick Local uses the `hermes` peer. To use+no peer on a Service or Custom connection, remove the peer value from each+configured source and start a new Hermes session.++Upgrades do not move or delete existing memories. Installations that relied+on the old implicit `hermes` peer now use user memory for new writes. Without+a peer ID, default OpenViking search covers user memory and existing peer+memories under the same OpenViking user. Old peer memories stay at their+existing paths and remain searchable. Ranking and result limits determine+which memories are returned. Keep a peer ID if you need the narrower view.++Set `agent: hermes` to restore peer-scoped writes. Memories written at user+scope before this change stay there and remain searchable. This setting+changes future writes, not the location of existing memories.++### Gateway senders and automatic recall++The external provider attaches the current gateway sender to captured user+messages as a peer, for example `telegram.123456`. The OpenViking account and+user stay unchanged. Assistant messages keep the configured `agent` peer.+CLI messages without a gateway sender remain linked to the OpenViking user.+Existing memories are not moved.++The setup presets save the automatic recall scope. You can also set it in the+active profile's `config.yaml`:++```yaml+memory:+ openviking:+ recall_scope: peer+```++| Value | Automatic recall |+|-------|------------------|+| `shared` | Common memory and all peer memories under the same OpenViking user. |+| `peer` | Common memory and the current gateway sender's memory. With no sender, only common memory is recalled. |++With no scope set, the provider preserves the previous requests: normally+shared recall, but an explicitly configured assistant peer can narrow list+recall. Existing compression behavior is also retained. This is compatibility+handling for existing installations, not a third setup mode. Invalid values+warn and preserve that behavior.++`OPENVIKING_RECALL_SCOPE` overrides YAML. On successful setup, the wizard removes+this override from the profile's `.env` so the selected preset takes effect.+An override supplied again by a service or shell still takes precedence.+The configuration schema exposes only `shared` and `peer`. A stable+alternate sender ID is used when Hermes supplies one. Unsafe IDs are encoded+to valid peer IDs. Queued captures retain their own sender when another+participant sends a turn.++The scope applies to automatic query recall, including compression and search+fallbacks. If an older server cannot confirm sender-scoped compression, the+provider uses scoped list recall. Enabled resource recall includes common+resources and, in `peer` mode, the sender's resources.++These recall settings do not change data access rights. They do not hide+shared conversation history or change explicit `viking_*` tools, native memory+mirroring or credentials. Setting `recall_scope` alone does not change gateway+sessions. Shared Agent changes those settings only after confirmation.+Explicit tools keep the configured assistant view. Use separate OpenViking+users and keys when participants need separate access.++## Memory writes and deletes++`viking_remember` creates a separate `hermes-remember-<random>` OpenViking+session, adds the fact as one message and commits all its messages. The session+remains available in OpenViking for audit. OpenViking then+classifies the source and can add, merge, or skip a memory through its normal+extraction pipeline. The tool returns the separate session ID and the+extraction task ID when the server provides one. Extraction continues+asynchronously after the tool returns.++The tool returns `status: submitted` because extraction can add a memory, merge+the fact into an existing memory, or produce no memory operation. It does not+promise that OpenViking created a distinct memory file. The fact is submitted+as an unchanged `user` message so OpenViking owns the final classification.+The legacy `category` argument is still accepted from existing callers but is+not advertised or used. This session is separate from the live Hermes+conversation, so an explicit remember does not commit or rotate the active+conversation session.++If the message request or commit fails, the error includes the exact+session URI, the failed stage, the observed message status, and an `ov session+commit <session-id>` recovery command. Inspect the session first. An archive+means the commit completed. A non-empty live `messages.jsonl` with no archive+means the message was accepted but still needs a commit. An empty live file+without an archive is ambiguous and must not trigger an automatic resubmission.+Use the same OpenViking profile and credentials as Hermes for manual recovery.+OpenViking server auto-commit is disabled by default, so an accepted message+whose explicit commit fails normally remains live without extracted memories+until it is manually committed.++Successful changes through Hermes's built-in `memory` tool are copied to+OpenViking in order. The active profile records each copied entry's exact URI in+`$HERMES_HOME/openviking/memory_mirror_registry.json`:++| Hermes action | OpenViking operation |+|---------------|----------------------|+| `add` | Create a file under user memory or the configured peer, then record its URI |+| `replace` | Match the committed event's full previous content and target, update the same URI, and wait for semantic/vector refresh |+| `remove` | Match the committed event's full previous content and target, delete that exact URI, and wait for semantic cleanup |++Replacing a mapped entry recreates its file if it was deleted directly in+OpenViking, for example with `viking_forget`.++The registry stores the current entry text and a hash that identifies the+connection. It does not store the raw API key. Endpoint, credentials, user,+account and peer changes isolate the new connection from earlier mappings.+New files require a server-confirmed+user identity. Missing or ambiguous mappings block replacement and deletion+with a warning. The plugin never selects a target by semantic similarity.++Replacement and deletion require Hermes to provide the full previous entry+content after its local memory write succeeds. If this data is unavailable,+the plugin skips those mirror operations with a warning. Local memory still+changes. It does not guess which remote entry to change.++Only entries created by this mirror have mappings. Session-extracted memories,+explicit `viking_remember` results, and copies created before this registry are+outside its scope. Use `viking_forget` with an exact URI to remove those copies.++The mirror is asynchronous. Hermes saves its local memory first. Rejected remote+writes leave the registry unchanged and produce a warning. Additions do not wait+for indexing, so the mirror does not report later indexing failures. For `replace`,+if the server reports that the file changed but indexing failed, the registry+retains the new content and exact URI. A warning reports the indexing failure+because search results may be stale. Failed operations are not saved for retry+after a restart. If a remote write succeeds but saving the registry fails, the+registry can differ from the server.+Operations run in order per provider. Instances in the same process share a+registry lock. Separate processes do not share that lock.++Registry files use mode `0600` on POSIX. Protect the profile with normal account+and filesystem permissions on Windows. An unreadable, invalid, or unsupported+registry blocks all mirror writes. Stop Hermes before restoring a valid backup.+For an unsupported version, use a plugin version that supports it. Renaming a+damaged registry starts a new registry but leaves earlier remote copies without+mappings. Those copies need manual cleanup by exact URI.++`viking_forget` is intentionally narrow. It only accepts concrete user memory+file URIs, such as+`viking://user/default/peers/hermes/memories/preferences/mem_abc123.md`, or the+`viking://~/...` self alias. Under `viking://user/...` the user id is required+and must match the calling identity. The `viking://user/memories/...`+and `viking://user/peers/...` paths without a user ID are rejected. Files+directly under `memories/`, such as `viking://user/default/memories/profile.md`,+are also allowed because OpenViking supports them. The tool rejects directories,+resources, skills, sessions, generated summary files, and URIs with query+strings or fragments. Use OpenViking's MCP, CLI, or admin APIs for broader+resource and directory cleanup.+++### Cloud recall compression++Set `OPENVIKING_RECALL_COMPRESS=server` to enable cloud recall compression, or+`auto` to let the server decide whether to rewrite. Both use search+`mode=context`. `server` sends `rewrite=true`, and `auto` sends `rewrite="auto"`.+The server digest takes precedence over the original search results, and `no_relevant`+adds no memory to the prompt. The default is `off`. No local compressor is started.++The Hermes config equivalent is `memory.openviking.recall_compress: server`.+When enabled, the default request timeout and total recall budget become 55 seconds.+Explicit recall timeout settings still take precedence. Older servers fall back+to the existing search path within that deadline.++### Active-session commits++The plugin checks OpenViking's `pending_tokens` after each successful+turn upload. At **20,000 tokens** by default, it requests a background commit+without ending the Hermes session. Memory extraction then runs on the server.+Session-end and session-switch commits still flush messages below this threshold.++Set a different threshold in the active Hermes profile's `config.yaml`:++```yaml+memory:+ openviking:+ commit_token_threshold: 8000+```++`OPENVIKING_COMMIT_TOKEN_THRESHOLD` overrides the YAML value. The setting accepts+integers from 1,000 to 1,000,000. Values outside this range use the nearest limit.+Invalid values use the default of 20,000 tokens. The provider also exposes this+setting through its configuration schema.++This is a client-side commit trigger. It does not set or replace the server's+`auto_commit_policy`. If a server policy is enabled, both triggers operate+independently. Server locking serializes their archive operations, but explicit+client commits do not use the server scheduler's interval or retention settings.+The plugin retains the existing `keep_recent_count: 0` commit behavior.+The threshold is not a hard limit on extraction input: one turn can+exceed it, and the server may include other context during extraction.++### Non-primary contexts++When Hermes initializes the provider with `agent_context` set to `cron`, `subagent`,+or `flush`, recall and profile reads keep working. Automatic turn uploads,+session-end/switch commits, and native memory mirroring are skipped for that+context. Startup recovery can still commit pending messages from earlier sessions.+Explicit `viking_*` tools keep their normal behavior, including writes and deletes.+Interactive sessions (and hosts that predate `agent_context`) keep the previous+automatic write behavior.++## Pinned source installation++Use this flow only when you need a specific reviewed commit instead of the+catalog version. Replace the placeholder with its full 40-character SHA:++```bash+hermes plugins install 'volcengine/OpenViking/examples/hermes-plugin' \+ --ref '<full-40-character-commit-SHA>' --no-enable+hermes plugins enable openviking+hermes memory setup openviking+```++Hermes installs the plugin in `$HERMES_HOME/plugins/openviking/` and resolves+its dependencies under Hermes's constraints when you enable it.++Direct subdirectory installs do not retain a `.git` directory. To update one,+force-reinstall the reviewed commit in the same profile:++```bash+hermes plugins install 'volcengine/OpenViking/examples/hermes-plugin' \+ --force --ref '<full-40-character-commit-SHA>' --enable+```++Connection settings and server data are retained. Restart Hermes or the gateway+after updating.diff --git a/examples/hermes-plugin/DEVELOPMENT.md b/examples/hermes-plugin/DEVELOPMENT.mdindex 4f6b61a40..ae3ce383c 100644--- a/examples/hermes-plugin/DEVELOPMENT.md+++ b/examples/hermes-plugin/DEVELOPMENT.md@@ -14,7 +14,7 @@ Contributions to this directory are provided under its [MIT license](LICENSE).Preserve the existing copyright and permission notice.The distribution name is `hermes-plugin-openviking`. The provider, plugin, and-future Hermes catalog key remain `openviking`. Existing `memory.openviking`+Hermes catalog key remain `openviking`. Existing `memory.openviking`settings, environment variables, linked `ovcli.conf` files, data paths, and`viking_*` tools keep their current behavior.@@ -57,16 +57,18 @@ the PID, creation time, executable and config path before stopping a process.It repairs permissions on plugin-owned private files after backup restoration;no Hermes backup changes are required.-`local_packages.py` selects reviewed OpenViking and llama-cpp-python binaries-with SHA-256 verification before installation. Both PM and pre-PM installers-receive verified local wheel files. Setup records the applied requirements so-that a later pin change updates an existing private runtime. Update pins only after installation,+`local_packages.py` selects compatible OpenViking wheels from PyPI and reviewed+llama-cpp-python binaries, with SHA-256 verification before installation. Both PM+and pre-PM installers receive verified local wheel files. Setup records the applied+requirements so that a newer server release or native package pin updates an+existing private runtime. Change native package pins only after installation,model and service checks pass on the listed platforms. Source builds requireexplicit consent. Platform CI runs real installation, local embedding, capture,restart and port-recovery checks. It uses a static test LLM configuration anddoes not establish live memory extraction; that remains a release check.-The reviewed hashes cover the OpenViking and llama-cpp-python wheels only.-PM/uv resolve the other dependencies; this is not a fully locked server runtime.+The OpenViking hash comes from PyPI at setup time; llama-cpp-python hashes are+fixed in this plugin. PM/uv resolve the other dependencies; this is not a fully+locked server runtime.Source builds use package version pins without reviewed binary hashes. A platformneeds a tested OpenViking/embedding-wheel pair for the prebuilt path.Setup also checks LLM access through the installed OpenViking backend. The CI@@ -74,7 +76,8 @@ fixture must serve an actual completion; an unreachable LLM must fail setup.## Migration coordination-Before the catalog cutover, submit a Hermes catalog entry with:+Hermes publishes this provider through `plugin-catalog/openviking.yaml`. The+entry must contain:- `name: openviking`- `repo: https://github.com/volcengine/OpenViking`@@ -92,16 +95,26 @@ and validate the pinned installation directory:hermes plugins validate /path/to/hermes-profile/plugins/openviking```-Publish the catalog entry and validate migration before Hermes removes its-bundled provider. Hermes PR [#114569](https://github.com/NousResearch/hermes-agent/pull/114569)-adds catalog recovery for configured providers that no longer resolve. The-bundled provider takes precedence while it remains present.+Hermes PR [#131267](https://github.com/NousResearch/hermes-agent/pull/131267)+published the catalog entry. Hermes PR+[#114569](https://github.com/NousResearch/hermes-agent/pull/114569) added catalog+recovery for configured providers that no longer resolve. Keep the reviewed+catalog pin and migration path valid. Hermes PR+[#134350](https://github.com/NousResearch/hermes-agent/pull/134350) removed the+bundled OpenViking provider from main. Older releases still load their bundled+copy first.This plugin does not add a Desktop `config_schema.py`.The wizard uses private helpers from `hermes_cli.memory_setup`; changes tothose helpers require compatibility checks. The plugin uses HTTP. Quick Local installs the server in a separateprofile runtime through Hermes PM, or the earlier Hermes uv installer on thetested release baseline. It does not add server dependencies to Hermes.+Explicit Quick Local setup resolves the latest stable, Python/platform-compatible+OpenViking 0.4 release from PyPI and verifies the wheel against PyPI's download+hash. The native embedding package remains pinned and hash-verified. The resolved+requirements are recorded per profile; unchanged requirements reuse the runtime,+while a new release follows the existing validation and restart path. Chat and+recovery do not resolve or upgrade packages.## Validation@@ -156,9 +169,9 @@ actual Hermes session keys.Provider-specific regression tests belong here and must use the shared externalloader fixture. Generic Hermes framework tests remain in Hermes.-For compatibility checks while Hermes still bundles OpenViking, also run its-provider tests. These load the bundled copy unless explicitly routed through the-external loader; they do not replace this directory's tests:+For compatibility checks against a Hermes release that bundles OpenViking,+also run its provider tests. These load the bundled copy unless explicitly+routed through the external loader; they do not replace this directory's tests:```bashHERMES_TEST_FILE_RETRIES=0 scripts/run_tests.sh \diff --git a/examples/hermes-plugin/README.md b/examples/hermes-plugin/README.mdindex 771fb1785..782231288 100644--- a/examples/hermes-plugin/README.md+++ b/examples/hermes-plugin/README.md@@ -1,137 +1,97 @@-# OpenViking Memory Provider+# OpenViking for Hermes-Context database by Volcengine (ByteDance) with filesystem-style knowledge hierarchy, tiered retrieval, and automatic memory extraction.+OpenViking gives Hermes Agent long-term memory and tools to search your knowledge.+It captures conversations, extracts useful facts and recalls them in later chats.-This plugin connects Hermes to OpenViking for long-term memory and knowledge-retrieval. The installation steps below use a reviewed OpenViking commit.+## Get started-For Hermes releases that still bundle OpenViking, follow the-[Hermes integration guide](../../docs/en/agent-integrations/05-hermes.md) and run-`hermes memory setup openviking`. No external plugin installation is needed.--For development and licensing details, see [DEVELOPMENT.md](DEVELOPMENT.md).--## Install--Validated with Hermes v2026.9.24. CI also checks the reviewed Hermes main-commit pinned in the [test workflow](../../.github/workflows/hermes-plugin-tests.yml).--For a direct installation, replace the placeholder with the reviewed OpenViking-commit's full 40-character SHA:+Run these commands in the Hermes profile you want to use:```bash-hermes plugins install 'https://github.com/volcengine/OpenViking/tree/main/examples/hermes-plugin' \- --ref '<full-40-character-commit-SHA>' --no-enable-hermes plugins enable openviking+hermes plugins install openviking --enablehermes memory setup openviking-hermes memory status+hermes```-The equivalent shorthand is `volcengine/OpenViking/examples/hermes-plugin`.-Hermes installs this directory as `$HERMES_HOME/plugins/openviking/`.-In this two-step flow, Hermes resolves its `pyproject.toml` dependencies under-Hermes's dependency constraints when you enable the plugin.+Accept the dependency prompt during installation. In setup, choose how you+use Hermes, then choose a connection.-If Hermes still includes the bundled OpenViking provider, that copy takes-precedence. The external copy becomes active after the bundled copy is removed.-Keep `memory.provider: openviking` and your existing configuration. No memory-data needs to move.+### Personal or Shared-## Upgrade+Hermes uses conversation history to follow the current chat. OpenViking saves+extracted facts as long-term memory for use in later chats. These are separate.-For a direct subdirectory installation, use force-reinstallation instead of-`hermes plugins update openviking`. Hermes does not retain the repository's-`.git` directory when it installs a subdirectory.+Common memory is not linked to a sender. Sender memory is linked to the person+who sent a message through Telegram, Discord or another messaging platform.+Both modes recall common memory under the same OpenViking user.-Replace the placeholder with the reviewed OpenViking commit's full 40-character-SHA, and run this command in the same Hermes profile as the original installation:+| Usage | What it does |+|-------|--------------|+| **Personal Agent** | Recalls common memory and the current sender's memory. Keeps your existing conversation history settings. |+| **Shared Agent** | Shares conversation history within each group or thread. Recalls common memory and all senders' memories under the same OpenViking user. |-```bash-hermes plugins install 'volcengine/OpenViking/examples/hermes-plugin' \- --force --ref '<full-40-character-commit-SHA>' --enable-```+Choose Personal for an assistant that recalls memory for the current person.+Choose Shared for a team that wants to share recalled memories. Shared Agent+asks for confirmation before changing conversation history settings. Different+groups keep separate histories, even in Shared mode. Restart the gateway if+setup changes its session settings.-Existing connection settings and server data are retained. Restart Hermes or-the gateway after the upgrade. For catalog installations, use-`hermes plugins update openviking`.+Personal does not change existing history settings. If a group already shares+history, choosing Personal leaves that history shared. Neither mode changes+data access rights. Use separate OpenViking users and keys when people need+separate access.-## Requirements+### Choose a connection-- Python 3.11 or newer in the Hermes environment-- A reachable OpenViking server, OpenViking Service credentials, or Quick Local setup-- For a self-hosted server, OpenViking installed in its own environment or container+| Connection | What you need |+|------------|---------------|+| **Quick Local** | A language model already configured in Hermes. Setup installs a local server and embedding model. |+| **OpenViking Service (VolcEngine Cloud)** | A service API key for VolcEngine's [managed OpenViking cloud service](https://www.volcengine.com/product/openviking-service). |+| **Custom** | Your server URL and credentials. Setup can also reuse a saved `ovcli.conf`. |-The plugin connects over HTTP. Keep the server in a separate environment.-Quick Local creates that environment for you. For Custom setup to start a local-server, make `openviking-server` available on `PATH`.+For the cloud service, activate it and create an API key in the+[OpenViking console](https://console.volcengine.com/vikingdb/openviking/region:openviking+cn-beijing).+Open **User Management**, then **API Key**. You do not need to install a server+or configure local models.-OpenViking 0.2.14 or newer is required. Hermes can identify older servers that-expose the legacy status-only health response, but those releases do not provide-the authenticated-user identity contract required by this integration.-The `viking://~` home alias requires OpenViking 0.4.16 or newer for user and-admin credentials, and OpenViking 0.4.17 or newer for root or local development.+After setup, chat as usual. Memories become available after the captured+conversation is committed and OpenViking finishes extraction. The plugin+requests a commit at 20,000 pending tokens by default, at session end and when+switching sessions.-## Setup+The plugin sends conversation turns, tool results and edits to `MEMORY.md`+and `USER.md` to your OpenViking server. Memory extraction can use a remote model.-For a Custom self-hosted deployment, prepare OpenViking in its server environment:+## Quick Local-```bash-openviking-server init-openviking-server doctor-openviking-server-```+Quick Local reuses your Hermes language model for memory extraction. A local+embedding model prepares text for memory search. The language model must use+a supported static API key or Hermes's local llama.cpp server. OAuth logins+are not supported. See [model support](CONFIGURATION.md#quick-local-model-support).-Then configure Hermes:+Setup checks the language model, downloads the embedding model and starts the+server before it finishes. It saves a copy of the model credentials in this+profile's private server configuration. Downloads need access to PyPI, GitHub+and Hugging Face.+The model download is about 46 MB. Other packages add more than 1 GB per profile.-```bash-hermes memory setup openviking-```+Prebuilt packages are available for Apple Silicon with macOS 14 or newer,+Linux x86-64 or ARM64 with glibc 2.31 or newer, and Windows x86-64. On other+platforms, setup asks before building from source. This needs development+tools and can take several minutes. You can use Custom instead.++Each Hermes profile has its own server, data and port. If the saved port is+occupied, Quick Local selects a free port. Run setup again after changing the+Hermes model or API key. Your data and downloaded model are kept.++**Known issue:** OpenViking 0.4.22 and 0.4.23 can crash when local embedding+calls overlap, such as during indexing and recall. This affects Quick Local+and Custom servers using that local backend. It does not affect connections+using remote embedding APIs. The [fix](https://github.com/volcengine/OpenViking/pull/5548)+is merged and is expected in OpenViking 0.4.24. After that release, run Quick+Local setup again to upgrade.-The setup can link to an existing `~/.openviking/ovcli.conf`, copy its current-connection values into Hermes, or create a minimal `ovcli.conf` when one does-not exist.--For a new connection, choose **OpenViking Service**, **Custom**, or **Quick Local**.--Quick Local installs OpenViking 0.4.22 in a private runtime. It uses-`bge-small-zh-v1.5-f16` for local embeddings and copies the configured Hermes LLM-settings for memory extraction. The LLM must use a static API key or Hermes's-local llama.cpp server, with an OpenAI-compatible or Anthropic-compatible API.-OAuth and cloud-native-credentials cannot be copied; use Custom for those deployments.-Google AI Studio uses its OpenAI-compatible endpoint. Static OpenAI and xAI-API keys use Chat Completions; the selected model must support that API.-Kimi Coding retains Hermes's client attribution. Anthropic routes that need-Bearer authentication, including MiniMax and Azure Foundry, and proxy keys-that LiteLLM would treat as OAuth require a separately configured Custom server.-Setup checks the copied LLM with one short completion before activation.-It retries once for a timeout, HTTP 429, or HTTP 5xx. Other errors fail-immediately. The message and server log identify the error without recording-credentials or the provider's response body.--Quick Local stores its runtime, data, model cache, and private configuration in-`$HERMES_HOME/openviking/`. Setup validates it, then leaves its localhost server-running so the first Hermes turn can use memory. On later starts, Hermes starts-the server in the background if it has stopped. The embedding model downloads once, about-46 MiB. The LLM can still use a remote API. Server logs are in-`$HERMES_HOME/logs/openviking-server.log`.-The first installation needs network access. It downloads prebuilt packages-with pinned hashes on macOS 14+ (Apple Silicon), Linux with glibc 2.31+-(x86-64 or ARM64), and Windows x86-64. Setup asks before a source build on-other platforms. A source build needs native development tools and can take-several minutes. You can choose Custom instead and use a separate server.-Downloads require access to PyPI, GitHub and Hugging Face. The local BGE model-is trained for Chinese; use Custom for a server with a different embedding model.--Run setup again after changing the Hermes model or API key. Setup validates-the new settings and restarts this profile's server. Data and the model cache-are retained. Each profile has its own server and port; Quick Local moves to-a free port if another service takes its saved port.-New setups use ports 1934–1953, leaving OpenViking's default port 1933 free.-Existing Quick Local profiles keep their saved port when it is available.--The server stays running after Hermes exits. Use these commands in the same-Hermes profile to control it:+The server keeps running after Hermes exits. These commands are optional:```bashhermes openviking local status@@ -140,332 +100,103 @@ hermes openviking local starthermes openviking local restart```-Stopping the server retains its data. Hermes starts it again when memory is-next used, including from a running gateway. Close those sessions or disable-OpenViking memory for it to stay stopped. While background startup or recovery-is in progress, new turns are not captured until the server is ready.-These commands and Quick Local setup require the external provider-to be active; a bundled copy still takes precedence where present.-Switching to Cloud or Custom stops this profile's managed server and retains-its data. `local start` and `local restart` require Quick Local to be selected;-`local status` and `local stop` remain available for the retained server.-The existing Cloud and Custom connection choices remain available.-Hermes backups include Quick Local files under the profile home; the plugin-adds a linked `ovcli.conf` only when it is outside that home.--Before removing the plugin, close Hermes sessions and stop the gateway for-this profile. Run `hermes openviking local stop`, then select a-different memory provider or disable OpenViking memory. Finally, run-`hermes plugins remove openviking`. The private runtime, model cache and data-remain in `$HERMES_HOME/openviking/`; they can use more than 1 GB per profile.-Plugin removal does not stop a running server.-Each running profile also uses several hundred MB of memory. Package upgrades-retain old runtime generations and wheel files, so disk use can increase.-After restoring a backup on another machine, run setup again to rebuild any-runtime excluded from the backup before using Quick Local.--Setup first asks how the Hermes instance is used:--| Preset | Hermes conversation history | OpenViking long-term recall |-|--------|-----------------------------|-----------------------------|-| **Personal Agent** | Keeps existing group/thread session settings | Common memory and the current sender's memory (`peer`) |-| **Shared Agent** | Shares each group or thread session between its participants | Common memory and all sender memories under the same OpenViking user (`shared`) |--Shared Agent requires confirmation before it sets `group_sessions_per_user` and-`thread_sessions_per_user` to `false`. Different groups still have separate-conversation histories. Restart the gateway to apply changed session settings.-Personal Agent does not make an already shared conversation private.--Both presets retain sender attribution during capture. After commit and-extraction, OpenViking can recall those memories across chats according to the-chosen scope. Upgrading the plugin alone does not apply a preset or change-session settings. Rerunning setup preselects the saved recall choice; a new-setup starts on Personal Agent.--Or manually:+Stopping keeps the data. A running Hermes session or gateway can start the+server again when memory is used. Close those sessions or disable OpenViking+memory if you want it to stay stopped. Turns completed while the server is+starting or recovering are not captured.++Switching to OpenViking Service or Custom stops this profile's Quick Local+server and keeps its data. `local start` and `local restart` work only while+Quick Local is selected.++## Custom server++Run OpenViking in its own Python environment or container. For a new local+server, run these commands there:```bash-hermes config set memory.provider openviking+openviking-server init+openviking-server doctor+openviking-server```-Add the connection settings to the active profile's `.env` file. For the-default profile that is `~/.hermes/.env`; for a named profile use-`~/.hermes/profiles/<profile>/.env`.+Then run `hermes memory setup openviking` and choose Custom. For setup to+start a stopped local server, `openviking-server` must be on `PATH`.++## Check status-```text-OPENVIKING_ENDPOINT=http://127.0.0.1:1933-# OPENVIKING_API_KEY=...-# OPENVIKING_ACCOUNT=default-# OPENVIKING_USER=default+```bash+hermes memory status```-## Config+`available` means the provider is configured. It does not confirm server+health or successful memory extraction. For Quick Local, use+`hermes openviking local status` to check the server.-OpenViking's server config is separate from Hermes:--- `ov.conf` configures OpenViking storage, embedding/VLM models, auth, and- server behavior. OpenViking reads it from `--config`,- `OPENVIKING_CONFIG_FILE`, or `~/.openviking/ov.conf`.-- `ovcli.conf` stores client/CLI connection values such as `url`, `api_key`,- `account`, and `user`. It is read from `OPENVIKING_CLI_CONFIG_FILE` or- `~/.openviking/ovcli.conf`.--Hermes reads provider settings from the initialized profile's `config.yaml`,-profile secrets, and linked `ovcli.conf`. Connection values resolve in this order:-profile environment, linked OpenViking config, Hermes YAML, then defaults. API keys-come from profile secrets or the linked OpenViking config, not Hermes YAML.-Quick Local uses its own saved connection and ignores connection environment-overrides. Recall and commit settings still accept their documented overrides.-After initialization, the provider keeps that profile for connection, identity,-and recall settings, including when another profile is active in the same-process. For the launch profile, process-level `OPENVIKING_*` values fill missing-`.env` values. Under multi-profile hosting, Hermes uses the process values frozen-at activation; a messaging gateway without that snapshot does not read them.-Routed profiles never inherit the launch profile's process values.--| Env Var | Default | Description |-|---------|---------|-------------|-| `OPENVIKING_ENDPOINT` | `http://127.0.0.1:1933` | Server URL |-| `OPENVIKING_API_KEY` | (none) | User/admin API key for authenticated servers |-| `OPENVIKING_ACCOUNT` | `default` | Tenant account for local/trusted mode |-| `OPENVIKING_USER` | `default` | Tenant user for local/trusted mode |-| `OPENVIKING_AGENT` | (none) | Optional peer ID for separate assistant context |--User and admin API keys let OpenViking derive account/user identity from the key.-In local or trusted deployments without an API key,-Hermes sends `OPENVIKING_ACCOUNT` and `OPENVIKING_USER` as identity headers.-Hermes also sends `User-Agent: openviking-memory-hermes/<version>` on-OpenViking requests. This standard harness identifier contains the Hermes-version, but no per-user identifier, and does not add a separate request.--### Optional peer identity--New connections use the OpenViking user's memory directory by default. Setup-does not ask for a peer ID. Without a configured peer, Hermes sends neither-`X-OpenViking-Actor-Peer` nor assistant-message `peer_id`.--For separate assistant context, set the existing `agent` field in the active-profile's `config.yaml`:--```yaml-memory:- openviking:- agent: work-assistant-```+## Update-Existing non-empty `OPENVIKING_AGENT`, YAML `agent`, and linked OpenViking-`actor_peer_id` or legacy `agent_id` values retain their behavior. Resolution-order remains environment, linked OpenViking config, then Hermes YAML for Cloud-and Custom connections. Quick Local uses the `hermes` peer. To use-no peer on a Cloud or Custom connection, remove the peer value from each-configured source and start a new Hermes session.--Upgrades do not move or delete existing memories. Installations that relied-on the old implicit `hermes` peer now use user memory for new writes. Without-a peer ID, default OpenViking search covers user memory and existing peer-memories under the same OpenViking user. Old peer memories stay at their-existing paths and remain searchable. Ranking and result limits determine-which memories are returned. Keep a peer ID if you need the narrower view.--Set `agent: hermes` to restore peer-scoped writes. Memories written at user-scope before this change stay there and remain searchable. This setting-changes future writes, not the location of existing memories.--### Gateway senders and automatic recall--The external provider attaches the current gateway sender to captured user-messages as a peer, for example `telegram.123456`. The OpenViking account and-user stay unchanged. Assistant messages keep the configured `agent` peer.-CLI messages without a gateway sender keep their existing user-level attribution.-Existing memories are not moved.--The setup presets save the automatic recall scope. You can also set it in the-active profile's `config.yaml`:--```yaml-memory:- openviking:- recall_scope: peer+```bash+hermes plugins update openviking```-| Value | Automatic recall |-|-------|------------------|-| `shared` | Common memory and all peer memories under the same OpenViking user. |-| `peer` | Common memory and the current gateway sender's memory. With no sender, only common memory is recalled. |--With no scope set, the provider preserves the previous requests: normally-shared recall, but an explicitly configured assistant peer can narrow list-recall. Existing compression behavior is also retained. This is compatibility-handling for existing installations, not a third setup mode. Invalid values-warn and preserve that behavior.--`OPENVIKING_RECALL_SCOPE` overrides YAML. On successful setup, the wizard removes-this override from the profile's `.env` so the selected preset takes effect.-An override supplied again by a service or shell still takes precedence.-The configuration schema exposes only `shared` and `peer`. A stable-alternate sender ID is used when Hermes supplies one; unsafe IDs are encoded-to valid peer IDs. Queued captures retain their own sender when another-participant sends a turn.--The scope applies to automatic query recall, including compression and search-fallbacks. If an older server cannot confirm sender-scoped compression, the-provider uses scoped list recall. Enabled resource recall includes common-resources and, in `peer` mode, the sender's resources.--This is a retrieval setting, not an access-control boundary. It does not filter-shared conversation history or change explicit `viking_*` tools, native memory-mirroring, or credentials. Setting `recall_scope` alone does not change gateway-sessions; the confirmed Shared Agent setup preset applies those settings.-Explicit tools retain-the configured assistant view. Use separate OpenViking users and credentials-when participants require separate access rights.+Restart Hermes or the gateway afterward. Your connection settings and server+data are kept. Updates use the version reviewed in the Hermes catalog.+For direct source installs, use the [source update command](CONFIGURATION.md#pinned-source-installation).++To update a Quick Local server, run `hermes memory setup openviking` again and+choose Quick Local. Setup selects the latest compatible OpenViking 0.4 release+and restarts the server if needed. Normal chat and recovery use the installed+server without checking for updates.++## Existing users++If a Hermes update removes its built-in OpenViking provider, it attempts to+install the catalog plugin for profiles already using OpenViking. Your settings+and server data are kept. If installation fails, run the install command above+in that profile.++Older Hermes releases load their built-in copy first. On those releases,+keep using `hermes memory setup openviking`. Quick Local and the external+plugin's changes become available when that copy is removed.## Tools-| Tool | Description |-|------|-------------|-| `viking_search` | Semantic search with fast/deep/auto modes |-| `viking_read` | Read content at a viking:// URI (abstract/overview/full) |-| `viking_browse` | Filesystem-style navigation (list/tree/stat) |-| `viking_remember` | Submit a fact through OpenViking session memory extraction |-| `viking_forget` | Delete one exact `viking://` memory file URI |-| `viking_add_resource` | Ingest URLs/docs into the knowledge base |--## Memory Writes And Deletes--`viking_remember` creates a one-shot `hermes-remember-<random>` OpenViking-session, adds the fact as one message, and commits the session with no retained-tail. The session remains available in OpenViking for audit. OpenViking then-classifies the source and can add, merge, or skip a memory through its normal-extraction pipeline. The tool returns the one-shot session ID and the-extraction task ID when the server provides one. Extraction continues-asynchronously after the tool returns.--The tool returns `status: submitted` because extraction can add a memory, merge-the fact into an existing memory, or produce no memory operation. It does not-promise that OpenViking created a distinct memory file. The fact is submitted-as an unchanged `user` message so OpenViking owns the final classification.-The legacy `category` argument is still accepted from existing callers but is-not advertised or used. The one-shot session is separate from the live Hermes-conversation, so an explicit remember does not commit or rotate the active-conversation session.--If the message request or commit fails, the error includes the canonical-session URI, the failed stage, the observed message status, and an `ov session-commit <session-id>` recovery command. Inspect the session first. An archive-means the commit completed. A non-empty live `messages.jsonl` with no archive-means the message was accepted but still needs a commit. An empty live file-without an archive is ambiguous and must not trigger an automatic resubmission.-Use the same OpenViking profile and credentials as Hermes for manual recovery.-OpenViking server auto-commit is disabled by default, so an accepted message-whose explicit commit fails normally remains live and unextracted until it is-manually committed.--Successful Hermes built-in `memory` mutations are mirrored to OpenViking in-order. The active profile records each mirrored entry's exact URI in-`$HERMES_HOME/openviking/memory_mirror_registry.json`:--| Hermes action | OpenViking operation |-|---------------|----------------------|-| `add` | Create a file under user memory or the configured peer, then record its URI |-| `replace` | Match the committed event's full previous content and target, update the same URI, and wait for semantic/vector refresh |-| `remove` | Match the committed event's full previous content and target, delete that exact URI, and wait for semantic cleanup |--Replacing a mapped entry recreates its file if it was deleted directly in-OpenViking, for example with `viking_forget`.--The registry stores the current entry text and a connection fingerprint, not-the raw API key. Endpoint, credentials, user, account, and peer changes isolate-the new connection from earlier mappings. New files require a server-confirmed-user identity. Missing or ambiguous mappings block replacement and deletion-with a warning; the plugin never selects a target by semantic similarity.--Replacement and deletion require Hermes to provide the full previous entry-content after its local memory write succeeds. If this data is unavailable,-the plugin skips those mirror operations with a warning; local memory still-changes. It does not guess which remote entry to change.--Only entries created by this mirror have mappings. Session-extracted memories,-explicit `viking_remember` results, and copies created before this registry are-outside its scope. Use `viking_forget` with an exact URI to remove those copies.--The mirror is asynchronous. Hermes saves its local memory first. Rejected remote-writes leave the registry unchanged and produce a warning. Additions do not wait-for indexing, so the mirror does not report later indexing failures. For `replace`,-if the server reports that the file changed but indexing failed, the registry-retains the new content and exact URI; a warning reports the indexing failure-because search results may be stale. There is no durable replay. A remote mutation-followed by a failed registry save can also cause drift. Operations are ordered-per provider; registry updates are serialized across instances sharing a profile-in one process, not across processes.--Registry files use mode `0600` on POSIX. Protect the profile with normal account-and filesystem permissions on Windows. An unreadable, invalid, or unsupported-registry blocks all mirror writes. Stop Hermes before restoring a valid backup.-For an unsupported version, use a plugin version that supports it. Renaming a-damaged registry starts a new registry but leaves earlier remote copies without-mappings; those copies need manual cleanup by exact URI.--`viking_forget` is intentionally narrow. It only accepts concrete user memory-file URIs, such as-`viking://user/default/peers/hermes/memories/preferences/mem_abc123.md`, or the-`viking://~/...` self alias. Under `viking://user/...` the user id is required-and must match the calling identity; the uid-less `viking://user/memories/...`-and `viking://user/peers/...` shorthands are deprecated and rejected. Files-directly under `memories/`, such as `viking://user/default/memories/profile.md`,-are also allowed because OpenViking supports them. The tool rejects directories,-resources, skills, sessions, generated summary files, and URIs with query-strings or fragments. Use OpenViking's MCP, CLI, or admin APIs for broader-resource and directory cleanup.---### Cloud recall compression--Set `OPENVIKING_RECALL_COMPRESS=server` to enable cloud recall compression, or-`auto` to let the server decide whether to rewrite. Both use search-`mode=context`; `server` sends `rewrite=true`, and `auto` sends `rewrite="auto"`.-The server digest takes precedence over raw rendered context, and `no_relevant`-suppresses injection. The default remains `off`; no local compressor is launched.--The Hermes config equivalent is `memory.openviking.recall_compress: server`.-When enabled, the default request and total recall deadlines become 55 seconds;-explicit recall timeout settings still take precedence. Older servers fall back-to the existing search path within that deadline.--### Active-session commits--The standalone provider checks OpenViking's `pending_tokens` after each successful-turn upload. At **20,000 tokens** by default, it requests a background commit-without ending the Hermes session. Memory extraction then runs on the server.-Session-end and session-switch commits still flush messages below this threshold.--Set a different threshold in the active Hermes profile's `config.yaml`:--```yaml-memory:- openviking:- commit_token_threshold: 8000+Hermes calls these tools when needed. You do not need to run them yourself.++| Tool | What it does |+|------|--------------|+| `viking_search` | Search memories and knowledge. |+| `viking_read` | Read content at a `viking://` address. |+| `viking_browse` | List files and directories. |+| `viking_remember` | Submit a fact for memory extraction. |+| `viking_forget` | Delete one exact memory file. |+| `viking_add_resource` | Add a URL or document to the knowledge base. |++## Remove++Close Hermes sessions and stop the gateway for this profile. For Quick Local,+run `hermes openviking local stop`. Select another memory provider or disable+OpenViking memory, then run:++```bash+hermes plugins remove openviking```-`OPENVIKING_COMMIT_TOKEN_THRESHOLD` overrides the YAML value. The setting accepts-integers from 1,000 to 1,000,000; values outside this range are clamped. Invalid-values use the 20,000-token default. The provider also exposes this setting through-its configuration schema.--This is a client-side commit trigger. It does not set or replace the server's-`auto_commit_policy`. If a server policy is enabled, both triggers operate-independently. Server locking serializes their archive operations, but explicit-client commits do not use the server scheduler's interval or retention settings.-The plugin retains the existing `keep_recent_count: 0` commit behavior.-The threshold is not a hard limit on extraction input: one turn can-exceed it, and the server may include other context during extraction.--### Non-primary contexts--When Hermes initializes the provider with `agent_context` set to `cron`, `subagent`,-or `flush`, recall and profile reads keep working. Automatic turn uploads,-session-end/switch commits, and native memory mirroring are skipped for that-context. Startup recovery can still commit pending messages from earlier sessions.-Explicit `viking_*` tools keep their normal behavior, including writes and deletes.-Interactive sessions (and hosts that predate `agent_context`) keep the previous-automatic write behavior.+Removal does not stop a running server or delete the runtime, model and data+in `$HERMES_HOME/openviking/`.++## Requirements++- Python 3.11 or newer in the Hermes environment.+- OpenViking Service, Quick Local or a reachable OpenViking server.+- OpenViking 0.2.14 or newer for Custom connections.++Tested with Hermes v2026.9.24 and the Hermes main commit used in+[CI](../../.github/workflows/hermes-plugin-tests.yml).++## Config++The wizard saves the connection settings. For optional recall settings,+model support, backups and memory recovery, see [Advanced configuration](CONFIGURATION.md).+For development and migration notes, see [DEVELOPMENT.md](DEVELOPMENT.md).+This directory uses the [MIT license](LICENSE).diff --git a/examples/hermes-plugin/local_packages.py b/examples/hermes-plugin/local_packages.pyindex adc7df461..007d3df52 100644--- a/examples/hermes-plugin/local_packages.py+++ b/examples/hermes-plugin/local_packages.py@@ -1,4 +1,4 @@-"""Reviewed binary packages, verified before either installer receives them."""+"""Resolve the server at setup; retain verified native embedding packages."""from __future__ import annotations@@ -12,34 +12,28 @@ from urllib.parse import parse_qs, urldefrag, urlparseimport httpxfrom packaging.requirements import Requirement-from packaging.version import Version+from packaging.specifiers import SpecifierSet+from packaging.tags import sys_tags+from packaging.utils import InvalidWheelFilename, parse_wheel_filename+from packaging.version import InvalidVersion, Version-_OV = "https://files.pythonhosted.org/packages/"_CPP = "https://github.com/abetlen/llama-cpp-python/releases/download/"# macOS uses the working Metal archive. The same release's CPU macOS archive# fails CRC validation and must not be substituted here._PACKAGES = {("Darwin", "arm64"): (- "5c/f4/222b2eb392a09cf2e13648d4f2f509c6043d16385ebd48a457a453816245/openviking-0.4.22-cp310-abi3-macosx_14_0_arm64.whl",- "ddfa3d23274cbd9afcdfaf1a1542b0a9e5e8286221a96bb7e40bd63e312d5bae","v0.3.30-metal/llama_cpp_python-0.3.30-py3-none-macosx_11_0_arm64.whl","4f5b385f31dbda502d7118aff0c07c9e98961fa0402c025b89ff3250db843eb3",),("Linux", "x86_64"): (- "aa/02/69642eddcbced2d52dc8489a0e8f618b7ae11e6caede9b02fac0f6f54528/openviking-0.4.22-cp310-abi3-manylinux_2_31_x86_64.whl",- "fa508fc9c84a32b3206d2f719c415bad5c50e88c1838fb19349881e087da72c8","v0.3.30/llama_cpp_python-0.3.30-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.whl","591337ea31b6fea25f02da53db136041899a530eda1b2c2611f0bebe7c560a15",),("Linux", "aarch64"): (- "29/ef/8bda981fae06066d2c462d051ceb6038043e776cac7b87f723fe65e34f17/openviking-0.4.22-cp310-abi3-manylinux_2_31_aarch64.whl",- "480070405e5c64c0a7d8d1d2afba7e98a55f151a67c785e4e5d0d54320096afc","v0.3.30/llama_cpp_python-0.3.30-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.whl","0720e1d122a4d1ad46607813bd34018ff46b0f50cd0a38fb93fad650b3b98ade",),("Windows", "x86_64"): (- "3f/26/e0d259f1a9fb53d02b99487f232265f79965fefb9b956563612c7acf5ae5/openviking-0.4.22-cp310-abi3-win_amd64.whl",- "cad1f3e4ea843c47178a8d5056df733b1e3f49d4e902b6f803b9e192320bb89b","v0.3.36/llama_cpp_python-0.3.36-py3-none-win_amd64.whl","ae5e88a2cf464e5a2dde7c8898c2d5c71cc24d03cac6396bf7509456bde0b9fb",),@@ -70,9 +64,9 @@ def install_requirements(*, allow_source_build=False):)requirements = [OPENVIKING_REQUIREMENT, "llama-cpp-python==0.3.30"]else:- ov_path, ov_hash, cpp_path, cpp_hash = packages+ cpp_path, cpp_hash = packagesrequirements = [- f"openviking[local-embed] @ {_OV}{ov_path}#sha256={ov_hash}",+ OPENVIKING_REQUIREMENT,f"llama-cpp-python @ {_CPP}{cpp_path}#sha256={cpp_hash}",]# The PM resolver otherwise chooses a LiteLLM release that excludes Python@@ -80,6 +74,74 @@ def install_requirements(*, allow_source_build=False):return [*requirements, 'litellm==1.83.7; python_version >= "3.14"']+def resolve_server_requirement(*, allow_source_build=False):+ """Select a stable PyPI release only during explicit Quick Local setup."""+ from .quick_local import QuickLocalSetupError++ try:+ response = httpx.get("https://pypi.org/pypi/openviking/json", timeout=30)+ response.raise_for_status()+ return _select_server_requirement(+ response.json()["releases"],+ python_version=platform.python_version(),+ tags=list(sys_tags()),+ allow_source_build=allow_source_build,+ )+ except (httpx.HTTPError, KeyError, TypeError, ValueError) as exc:+ raise QuickLocalSetupError(+ "Could not check OpenViking releases on PyPI. Check network access and retry setup."+ ) from exc+++def _select_server_requirement(releases, *, python_version, tags, allow_source_build=False):+ from .quick_local import OPENVIKING_REQUIREMENT, QuickLocalSetupError++ specifier = Requirement(OPENVIKING_REQUIREMENT).specifier+ ranked_tags = {tag: rank for rank, tag in enumerate(tags)}+ versions = []+ for raw_version, files in releases.items():+ try:+ version = Version(raw_version)+ except InvalidVersion:+ continue+ if version in specifier and not version.is_prerelease and not version.is_devrelease:+ versions.append((version, files))+ for version, files in sorted(versions, key=lambda item: item[0], reverse=True):+ wheels = []+ source_available = False+ for file in files:+ if file.get("yanked") or python_version not in SpecifierSet(+ file.get("requires_python") or ""+ ):+ continue+ if file.get("packagetype") == "sdist":+ source_available = True+ continue+ try:+ name, wheel_version, _build, wheel_tags = parse_wheel_filename(file["filename"])+ except (InvalidWheelFilename, KeyError):+ continue+ matches = wheel_tags.intersection(ranked_tags)+ if name == "openviking" and wheel_version == version and matches:+ wheels.append((min(ranked_tags[tag] for tag in matches), file))+ if wheels:+ file = min(wheels, key=lambda item: item[0])[1]+ url = file["url"]+ if (+ urlparse(url).scheme != "https"+ or urlparse(url).hostname != "files.pythonhosted.org"+ ):+ raise QuickLocalSetupError("OpenViking's release download must come from PyPI.")+ digest = file["digests"]["sha256"]+ return f"openviking[local-embed] @ {url}#sha256={digest}"+ if allow_source_build and source_available:+ return f"openviking[local-embed]=={version}"+ raise QuickLocalSetupError(+ "No compatible OpenViking release is available for this Python and platform. "+ "Use a separate server or explicitly allow a source build in setup."+ )++def verified_requirements(requirements: list[str], cache: Path) -> list[str]:"""Give installers local wheels whose bytes match the reviewed pins.diff --git a/examples/hermes-plugin/plugin.yaml b/examples/hermes-plugin/plugin.yamlindex 89dfb43cb..07fa401f1 100644--- a/examples/hermes-plugin/plugin.yaml+++ b/examples/hermes-plugin/plugin.yaml@@ -1,6 +1,7 @@name: openviking-version: 2.1.0-description: "OpenViking context database — session-managed memory with automatic extraction, tiered retrieval, and filesystem-style knowledge browsing."+version: 2.1.1+description: "Long-term memory for Hermes with automatic capture, recall and tools to search and manage knowledge."pip_dependencies:- httpxrequires_env: []+hooks: []diff --git a/examples/hermes-plugin/pyproject.toml b/examples/hermes-plugin/pyproject.tomlindex 2d987fe48..b78eda7e6 100644--- a/examples/hermes-plugin/pyproject.toml+++ b/examples/hermes-plugin/pyproject.toml@@ -1,6 +1,6 @@[project]name = "hermes-plugin-openviking"-version = "2.1.0"+version = "2.1.1"description = "Hermes Agent memory provider plugin: openviking"requires-python = ">=3.11"license = { text = "MIT" }diff --git a/examples/hermes-plugin/quick_local.py b/examples/hermes-plugin/quick_local.pyindex 4fc6d1714..4bd250b2f 100644--- a/examples/hermes-plugin/quick_local.py+++ b/examples/hermes-plugin/quick_local.py@@ -30,7 +30,8 @@ from utils import atomic_json_writeDEPLOYMENT = "quick_local"EMBEDDING_MODEL = "bge-small-zh-v1.5-f16"EMBEDDING_DIMENSION = 512-OPENVIKING_REQUIREMENT = "openviking[local-embed]==0.4.22"+# Accept new releases in the server API series; resolve only in explicit setup.+OPENVIKING_REQUIREMENT = "openviking[local-embed]>=0.4.22,<0.5"# Later LiteLLM releases exclude Python 3.14. OpenViking supports this version.# This restriction applies only to the private server, never Hermes's dependencies.@@ -470,9 +471,14 @@ class QuickLocalSetup:def _ensure_openviking_installed(self, paths: QuickLocalPaths) -> bool:"""Ensure a compatible runtime, returning whether installation was needed."""- from .local_packages import install_requirements, verified_requirements+ from .local_packages import (+ install_requirements,+ resolve_server_requirement,+ verified_requirements,+ )requirements = install_requirements(allow_source_build=self.allow_source_build)+ requirements[0] = resolve_server_requirement(allow_source_build=self.allow_source_build)receipt = paths.root / "runtime-requirements.json"try:installed_requirements = json.loads(receipt.read_text(encoding="utf-8"))@@ -542,6 +548,8 @@ class QuickLocalSetup:uv,"pip","install",+ "--upgrade-package",+ "openviking","--python",str(paths.runtime_python),*requirements,diff --git a/examples/hermes-plugin/tests/test_local_lifecycle.py b/examples/hermes-plugin/tests/test_local_lifecycle.pyindex 455e027f1..eddae4c13 100644--- a/examples/hermes-plugin/tests/test_local_lifecycle.py+++ b/examples/hermes-plugin/tests/test_local_lifecycle.py@@ -493,16 +493,17 @@ def test_port_probe_rejects_active_listener(modules):"system,machine",[("Darwin", "arm64"), ("Linux", "x86_64"), ("Linux", "aarch64"), ("Windows", "AMD64")],)-def test_supported_binary_requirements_pin_both_archives_by_hash(+def test_supported_binary_requirements_keep_native_embedding_hash(modules, monkeypatch, system, machine):- _home, _p, _m, _ql, _life, packages = modules+ _home, _p, _m, ql, _life, packages = modulesmonkeypatch.setattr(packages.platform, "system", lambda: system)monkeypatch.setattr(packages.platform, "machine", lambda: machine)monkeypatch.setattr(packages.platform, "mac_ver", lambda: ("14.0", (), ""))monkeypatch.setattr(packages.platform, "libc_ver", lambda: ("glibc", "2.31"))requirements = packages.install_requirements()- assert all("#sha256=" in requirement for requirement in requirements[:2])+ assert requirements[0] == ql.OPENVIKING_REQUIREMENT+ assert "#sha256=" in requirements[1]assert "metal" in requirements[1] if system == "Darwin" else "metal" not in requirements[1]@@ -653,11 +654,16 @@ def test_changed_native_pins_reinstall_an_existing_runtime(modules, monkeypatch)monkeypatch.setattr(ql, "openviking_install_satisfies_requirement", lambda _paths: True)monkeypatch.setattr(ql, "_pm_available", lambda: False)monkeypatch.setattr(packages, "verified_requirements", lambda values, _cache: values)+ monkeypatch.setattr(+ packages, "resolve_server_requirement", lambda **_kw: "openviking[local-embed]==0.4.23"+ )engine = ql.QuickLocalSetup(health_check=lambda _url: (False, ""))install = MagicMock()monkeypatch.setattr(engine, "_install_with_uv", install)assert engine._ensure_openviking_installed(paths)- install.assert_called_once_with(paths, packages.install_requirements())+ requirements = packages.install_requirements()+ requirements[0] = packages.resolve_server_requirement()+ install.assert_called_once_with(paths, requirements)assert not engine._ensure_openviking_installed(paths)assert install.call_count == 1diff --git a/examples/hermes-plugin/tests/test_local_packages.py b/examples/hermes-plugin/tests/test_local_packages.pyindex c8fb0da22..87ce9997a 100644--- a/examples/hermes-plugin/tests/test_local_packages.py+++ b/examples/hermes-plugin/tests/test_local_packages.py@@ -9,6 +9,7 @@ from pathlib import Pathfrom urllib.parse import unquote, urlparseimport pytest+from packaging.tags import Tag@pytest.fixture@@ -83,7 +84,12 @@ def test_bad_hash_never_reaches_pm(external_provider, tmp_path, wheel_source, momonkeypatch.setattr(ql, "_pm_available", lambda: True)monkeypatch.setattr(ql, "openviking_install_satisfies_requirement", lambda _paths: False)monkeypatch.setattr(- packages, "install_requirements", lambda **_kw: [f"probe @ {url}#sha256={'0' * 64}"]+ packages,+ "install_requirements",+ lambda **_kw: [ql.OPENVIKING_REQUIREMENT, f"probe @ {url}#sha256={'0' * 64}"],+ )+ monkeypatch.setattr(+ packages, "resolve_server_requirement", lambda **_kw: "openviking[local-embed]==0.4.23")install = MagicMock()monkeypatch.setattr(pm, "ensure_python_tool", install)@@ -92,3 +98,92 @@ def test_bad_hash_never_reaches_pm(external_provider, tmp_path, wheel_source, moengine._ensure_openviking_installed(ql.managed_paths(home))install.assert_not_called()assert not (ql.managed_paths(home).root / "runtime-requirements.json").exists()+++def _distribution(version, *, tag="py3-none-any", **changes):+ filename = f"openviking-{version}-{tag}.whl"+ return {+ "filename": filename,+ "url": f"https://files.pythonhosted.org/packages/{filename}",+ "digests": {"sha256": "a" * 64},+ "packagetype": "bdist_wheel",+ "requires_python": ">=3.11",+ "yanked": False,+ **changes,+ }+++def test_server_selection_uses_latest_compatible_stable_wheel(external_provider):+ _h, _p, module, _s = external_provider("releases")+ packages = importlib.import_module(module.__name__ + ".local_packages")+ releases = {+ "0.4.21": [_distribution("0.4.21")],+ "0.4.22": [_distribution("0.4.22")],+ "0.4.24": [_distribution("0.4.24", tag="cp310-abi3-manylinux_2_31_x86_64")],+ "0.4.25": [_distribution("0.4.25", requires_python="<3.14")],+ "0.4.26": [_distribution("0.4.26", yanked=True)],+ "0.4.27rc1": [_distribution("0.4.27rc1")],+ "0.5.0": [_distribution("0.5.0")],+ }+ selected = packages._select_server_requirement(+ releases,+ python_version="3.14.0",+ tags=[Tag("cp310", "abi3", "manylinux_2_31_x86_64"), Tag("py3", "none", "any")],+ )+ assert selected == (+ "openviking[local-embed] @ https://files.pythonhosted.org/packages/"+ "openviking-0.4.24-cp310-abi3-manylinux_2_31_x86_64.whl#sha256=" + "a" * 64+ )+++def test_source_build_requires_explicit_consent(external_provider):+ _h, _p, module, _s = external_provider("releases")+ packages = importlib.import_module(module.__name__ + ".local_packages")+ ql = importlib.import_module(module.__name__ + ".quick_local")+ releases = {"0.4.24": [_distribution("0.4.24", packagetype="sdist")]}+ with pytest.raises(ql.QuickLocalSetupError, match="No compatible"):+ packages._select_server_requirement(releases, python_version="3.14", tags=[])+ assert (+ packages._select_server_requirement(+ releases, python_version="3.14", tags=[], allow_source_build=True+ )+ == "openviking[local-embed]==0.4.24"+ )+++def test_pypi_failure_is_reported_without_installation(external_provider, monkeypatch):+ import httpx++ _h, _p, module, _s = external_provider("releases")+ packages = importlib.import_module(module.__name__ + ".local_packages")+ ql = importlib.import_module(module.__name__ + ".quick_local")+ monkeypatch.setattr(+ packages.httpx,+ "get",+ lambda *_a, **_kw: httpx.Response(503, request=httpx.Request("GET", "https://pypi.org")),+ )+ with pytest.raises(ql.QuickLocalSetupError, match="check OpenViking releases"):+ packages.resolve_server_requirement()+++def test_each_setup_resolves_new_pypi_release(external_provider, monkeypatch):+ import httpx++ _h, _p, module, _s = external_provider("releases")+ packages = importlib.import_module(module.__name__ + ".local_packages")+ versions = iter(["0.4.23", "0.4.24"])+ requests = []++ def respond(url, **kwargs):+ requests.append((url, kwargs))+ version = next(versions)+ return httpx.Response(+ 200,+ json={"releases": {version: [_distribution(version)]}},+ request=httpx.Request("GET", url),+ )++ monkeypatch.setattr(packages.httpx, "get", respond)+ assert "openviking-0.4.23-" in packages.resolve_server_requirement()+ assert "openviking-0.4.24-" in packages.resolve_server_requirement()+ assert requests == [("https://pypi.org/pypi/openviking/json", {"timeout": 30})] * 2diff --git a/examples/hermes-plugin/tests/test_quick_local.py b/examples/hermes-plugin/tests/test_quick_local.pyindex c15dd2b5e..7afa3b0ab 100644--- a/examples/hermes-plugin/tests/test_quick_local.py+++ b/examples/hermes-plugin/tests/test_quick_local.py@@ -25,6 +25,10 @@ def plugin_modules(external_provider, monkeypatch):monkeypatch.setattr(quick_local.secrets, "token_urlsafe", lambda _size: "local-test-key")monkeypatch.setattr(quick_local, "_validate_local_embedding", MagicMock())monkeypatch.setattr(quick_local, "_validate_vlm", MagicMock())+ packages = importlib.import_module(openviking_module.__name__ + ".local_packages")+ monkeypatch.setattr(+ packages, "resolve_server_requirement", lambda **_kw: "openviking[local-embed]==0.4.23"+ )def _preflight(tmp_path: Path) -> quick_local.QuickLocalPreflight:@@ -961,9 +965,11 @@ def test_current_installer_uses_pm_and_private_root(tmp_path, monkeypatch):)engine = quick_local.QuickLocalSetup(health_check=lambda _url: (False, ""))assert engine._ensure_openviking_installed(paths)+ requirements = packages.install_requirements()+ requirements[0] = packages.resolve_server_requirement()install.assert_called_once_with("openviking-local",- importlib.import_module(quick_local.__package__ + ".local_packages").install_requirements(),+ requirements,"openviking-server",root=paths.runtime,explicit=True,@@ -998,14 +1004,54 @@ def test_compatible_runtime_avoids_installer(tmp_path, monkeypatch):packages = importlib.import_module(quick_local.__package__ + ".local_packages")paths = quick_local.managed_paths(tmp_path)paths.root.mkdir()- (paths.root / "runtime-requirements.json").write_text(- json.dumps(packages.install_requirements())- )+ requirements = packages.install_requirements()+ requirements[0] = packages.resolve_server_requirement()+ (paths.root / "runtime-requirements.json").write_text(json.dumps(requirements))engine = quick_local.QuickLocalSetup(health_check=lambda _url: (False, ""))assert engine._ensure_openviking_installed(quick_local.managed_paths(tmp_path)) is Falserun.assert_not_called()+def test_setup_checks_new_release_even_with_a_compatible_installed_runtime(tmp_path, monkeypatch):+ pm = pytest.importorskip("pm.client")+ packages = importlib.import_module(quick_local.__package__ + ".local_packages")+ paths = quick_local.managed_paths(tmp_path)+ paths.root.mkdir()+ requirements = packages.install_requirements()+ requirements[0] = "openviking[local-embed]==0.4.22"+ (paths.root / "runtime-requirements.json").write_text(json.dumps(requirements))+ monkeypatch.setattr(quick_local, "openviking_install_satisfies_requirement", lambda _p: True)+ monkeypatch.setattr(packages, "verified_requirements", lambda values, _cache: values)+ install = MagicMock()+ monkeypatch.setattr(pm, "ensure_python_tool", install)++ engine = quick_local.QuickLocalSetup(health_check=lambda _url: (False, ""))+ assert engine._ensure_openviking_installed(paths) is True+ assert install.call_args.args[1][0] == "openviking[local-embed]==0.4.23"+ assert json.loads((paths.root / "runtime-requirements.json").read_text())[0] == (+ "openviking[local-embed]==0.4.23"+ )+++def test_release_check_failure_preserves_runtime_receipt(tmp_path, monkeypatch):+ packages = importlib.import_module(quick_local.__package__ + ".local_packages")+ paths = quick_local.managed_paths(tmp_path)+ paths.root.mkdir()+ receipt = paths.root / "runtime-requirements.json"+ receipt.write_text('["previous requirements"]')+ monkeypatch.setattr(+ packages, "resolve_server_requirement",+ MagicMock(side_effect=quick_local.QuickLocalSetupError("PyPI unavailable")),+ )+ run = MagicMock()+ monkeypatch.setattr(quick_local.subprocess, "run", run)+ engine = quick_local.QuickLocalSetup(health_check=lambda _url: (False, ""))+ with pytest.raises(quick_local.QuickLocalSetupError, match="PyPI unavailable"):+ engine._ensure_openviking_installed(paths)+ assert receipt.read_text() == '["previous requirements"]'+ run.assert_not_called()++def test_managed_connection_ignores_foreign_env_and_saved_paths(tmp_path, monkeypatch):paths, _cfg = _saved_local(tmp_path)monkeypatch.setattr(openviking_module, "get_hermes_home", lambda: tmp_path)