How to point Hermes Agent memory at OpenViking

Hermes Agent already has a first-class OpenViking memory provider. There is no extra plugin to install: point Hermes at your OpenViking server and it handles memory storage, recall, and extraction natively over HTTP.

That HTTP boundary is the integration. Keep the two Python environments apart, run the OpenViking setup wizard, then confirm the provider is active. Mixing the installs is the usual way to pin conflicting dependencies; the documented HTTP setup avoids that.

Keep the Python environments separate

Hermes connects to OpenViking over HTTP, so OpenViking does not need to live 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 inside 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.

Prepare OpenViking first

Hermes expects OpenViking to be initialized, validated, and running before you select it as the memory provider. The Hermes memory-provider docs show this sequence:

# Prepare OpenViking first

openviking-server init

openviking-server doctor

openviking-server

# Then configure Hermes

hermes memory setup    # select "openviking"

# Or manually:

hermes config set memory.provider openviking

OpenViking server settings live in ov.conf (--config, OPENVIKING_CONFIG_FILE, or ~/.openviking/ov.conf). Client connection values live in ovcli.conf (OPENVIKING_CLI_CONFIG_FILE or ~/.openviking/ovcli.conf).

Run the setup wizard

OpenViking's Hermes integration page is more direct:

hermes memory setup openviking

The wizard has two paths:

Cloud: keep OpenViking Service (VolcEngine Cloud) and paste the API key.
Custom: a URL (default http://127.0.0.1:1933) and an API key. Leave the key empty for local dev.

Reuse an existing ovcli.conf profile if the wizard offers one. hermes memory setup can also reuse or copy connection values from ~/.openviking/ovcli.conf.

You can pick the provider another way: hermes plugins → Provider Plugins → Memory Provider. Or set it in ~/.hermes/config.yaml:

memory:

  provider: openviking   # or honcho, mem0, hindsight, holographic, retaindb, byterover, supermemory

Hermes ships with several external memory providers. Only one external provider can be active at a time. Built-in memory (MEMORY.md / USER.md) stays on alongside it.

Manual connection values

Manual setup uses the active profile's .env file. For the default profile that is ~/.hermes/.env; for named profiles use ~/.hermes/profiles/<profile>/.env.

OPENVIKING_ENDPOINT=http://127.0.0.1:1933

# OPENVIKING_API_KEY=...

# OPENVIKING_ACCOUNT=default

# OPENVIKING_USER=default

OPENVIKING_ACCOUNT and OPENVIKING_USER are used for local/trusted mode.

What you get once it is active

When a memory provider is active, Hermes automatically:

Injects provider context into the system prompt
Prefetches relevant memories before each turn (background, non-blocking)
Syncs conversation turns to the provider after each response
Extracts memories on session end (for providers that support it)
Mirrors built-in memory writes to the external provider
Adds provider-specific tools so the agent can search, store, and manage memories

The built-in memory continues to work exactly as before. The external provider is additive.

OpenViking is a context database by Volcengine (ByteDance) with a filesystem-style knowledge hierarchy, tiered retrieval, and automatic memory extraction into 6 categories. Hermes lists it as best for self-hosted knowledge management with structured browsing. Data stays self-hosted (local or cloud). Cost is free (open-source, AGPL-3.0).

Key OpenViking features Hermes documents:

Tiered context loading: L0 (~~100 tokens) → L1 (~~2k) → L2 (full)
Automatic memory extraction on session commit (profile, preferences, entities, events, cases, patterns)
viking:// URI scheme for hierarchical knowledge browsing

The agent gets six tools: viking_search (semantic search), viking_read (tiered: abstract/overview/full), viking_browse (filesystem navigation), viking_remember (store facts), viking_forget (delete a memory file by exact viking:// URI), and viking_add_resource (ingest URLs/docs).

Peer identity and write scope

Peer identity is optional. Setup does not ask for a peer ID. By default, Hermes sends no peer ID and writes explicit memories to viking://user/<user>/memories/....

For separate assistant context, set memory.openviking.agent: work-assistant in config.yaml. Existing non-empty peer settings keep their peer-scoped writes and recall. That includes OPENVIKING_AGENT and actor_peer_id or legacy agent_id in a linked OpenViking config. Existing memories are not moved or deleted.

With no peer ID, default search covers user memory and existing peer memories under the same OpenViking user. Old peer memories remain searchable at their existing paths. Ranking and result limits determine which memories are returned. Set memory.openviking.agent: hermes to restore the old peer-scoped writes. Memories written at user scope before that change stay there and remain searchable. The setting changes future writes, not existing memory locations.

Hermes sends User-Agent: openviking-memory-hermes/<version> on OpenViking requests. That harness identifier contains no per-user identifier and does not add a separate request.

Verify

hermes memory status

When you are ready, read the OpenViking Hermes page and the Hermes OpenViking memory-provider section, bring up a server that has already passed openviking-server doctor, then run hermes memory setup openviking and confirm with hermes memory status.