# 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//.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 | | `OPENVIKING_EXTRA_HEADERS` | (none) | JSON object of extra HTTP headers (e.g. gateway service tokens); overrides `extra_headers` from the linked `ovcli.conf` | User and admin API keys let OpenViking derive account/user identity from the key. In trusted deployments, set `OPENVIKING_API_KEY` to the server's root API key; Hermes sends `OPENVIKING_ACCOUNT` and `OPENVIKING_USER` as identity headers. Only local dev mode allows access without an API key. Hermes also sends `User-Agent: openviking-memory-hermes/` on OpenViking requests. This header contains the Hermes version. It does not contain a user identifier or require an extra request. ### Extra HTTP headers (authenticating gateways) A server published behind an authenticating gateway (Cloudflare Access, oauth2-proxy, an mTLS-terminating proxy) needs a client header on every request, including the startup health check. `extra_headers` is the documented client contract: it sits in the linked `ovcli.conf` next to `url`/`api_key` and is what the CLI and the Python/Rust/Go clients read. Hermes consumes the same key, so a deployment that already carries it needs nothing else: ```json { "url": "https://ov.example.com", "api_key": "", "extra_headers": { "CF-Access-Client-Id": "", "CF-Access-Client-Secret": "" } } ``` `OPENVIKING_EXTRA_HEADERS` (a JSON object, read from the profile `.env`) is an explicit override for deployment secrets that should not live in a file. It wins when both are set, so the resolution order is: profile `OPENVIKING_EXTRA_HEADERS` → linked `ovcli.conf` `extra_headers` → none. Values must be scalars. `X-OpenViking-*` names are dropped, so an operator-supplied map can never assert tenant identity, and the plugin's own headers (authentication, tenant, actor) take precedence over the map. The client snapshots the map when it is built, so the headers also cover the startup `/health` probe. ### 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-` 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 ` 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 also skips commits in these contexts. Pending messages remain available for recovery when the next primary context starts. 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 '' --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 '' --enable ``` Connection settings and server data are retained. Restart Hermes or the gateway after updating.