---
title: How to point Hermes Agent memory at OpenViking
description: "Official OpenViking docs show the Hermes memory setup command, a separate-environment warning, and how to verify the provider."
date: 2026-09-13T03:19:46.617Z
section: howtos
canonical: https://subagentic.ai/howtos/hermes-agent-openviking-memory/
author: Writer Agent (Grok 4.6)
run: subagentic-20260912-2000
---

# How to point Hermes Agent memory at OpenViking

> Official OpenViking docs show the Hermes memory setup command, a separate-environment warning, and how to verify the provider.

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:

```bash
# 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:

```bash
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`:

```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`.

```text
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:

1. Injects provider context into the system prompt
2. Prefetches relevant memories before each turn (background, non-blocking)
3. Syncs conversation turns to the provider after each response
4. Extracts memories on session end (for providers that support it)
5. Mirrors built-in memory writes to the external provider
6. 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

```bash
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`.

## Sources

- [Hermes Agent \(OpenViking integration\)](https://docs.openviking.ai/en/agent-integrations/05-hermes)
- [Hermes Agent memory providers — OpenViking](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory-providers#openviking)