040e18ad90
initialize() snapshots OPENVIKING_* into the provider once, so /reload (which only updates os.environ) leaves viking_* tools running against stale auth — users have to restart hermes to pick up keys added to ~/.hermes/.env after startup (#21130). Add _ensure_client(), which re-resolves the connection settings via the same _resolve_connection_settings/_load_hermes_openviking_config path initialize() uses and rebuilds + health-checks the client only when an OPENVIKING_* value actually changed; otherwise it reuses the cached client (or a cached None for a known-down target) so the hot path stays at one dict comparison with no network calls. Route every live client-gated path through it: system_prompt_block, prefetch (pre-turn recall), sync_turn, on_session_end, on_session_switch (session rotation), on_memory_write and handle_tool_call. The unreachable branch calls _handle_runtime_openviking_unreachable() so a newly-resolved but not-yet-up LOCAL endpoint keeps initialize()'s recovery — (re)start the server and attach in the background — instead of silently disabling memory. Refreshing is gated behind a flag set at the end of initialize() so the baseline is established before any env re-resolution happens — callers that wire up a client directly (e.g. tests) keep it untouched. Refs #21130 |
||
|---|---|---|
| .. | ||
| __init__.py | ||
| plugin.yaml | ||
| README.md | ||
OpenViking Memory Provider
Context database by Volcengine (ByteDance) with filesystem-style knowledge hierarchy, tiered retrieval, and automatic memory extraction.
Requirements
pip install openviking- OpenViking server running (
openviking-server) - Embedding + VLM model configured in
~/.openviking/ov.conf
Setup
hermes memory setup # select "openviking"
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.
Or manually:
hermes config set memory.provider openviking
echo "OPENVIKING_ENDPOINT=http://localhost:1933" >> ~/.hermes/.env
Config
All config via environment variables in .env:
| 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 |
hermes |
Hermes peer ID in OpenViking, used for peer-scoped memories |
When OPENVIKING_API_KEY is set, Hermes lets 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.
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 |
Store a fact directly with OpenViking content/write |
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 writes directly to OpenViking with POST /api/v1/content/write
and mode=create. It creates peer-scoped memory files under
viking://user/peers/${OPENVIKING_AGENT}/memories/...; OpenViking may return a
canonical user-scoped form such as
viking://user/default/peers/${OPENVIKING_AGENT}/memories/... in API-key mode.
Explicit remembers do not depend on session commit extraction.
Hermes built-in memory tool additions are mirrored to OpenViking after the
local memory operation succeeds:
| Hermes action | OpenViking operation |
|---|---|
add |
content/write with mode=create under the configured peer memory namespace |
Built-in replace and remove operations are not mirrored because Hermes
native memory entries do not yet carry stable OpenViking file URIs. Use
viking_forget when the user explicitly asks to delete a specific OpenViking
memory URI.
viking_forget is intentionally narrow. It only accepts concrete user memory
file URIs, such as
viking://user/peers/hermes/memories/preferences/mem_abc123.md or the canonical
viking://user/default/peers/hermes/memories/preferences/mem_abc123.md. 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.