From 6fb4e9aa8a42967a5c25e53ad3c969e81e6da4f4 Mon Sep 17 00:00:00 2001
From: Naveen Fernando <90832919+NPFernando@users.noreply.github.com>
Date: Tue, 2 Jun 2026 15:28:04 +0530
Subject: [PATCH] docs: clarify OpenViking local setup

(cherry picked from commit a6807170f109dfaab19bc2023ddb5bb33fcb2852)
---
 plugins/memory/openviking/README.md           | 43 ++++++++++++++++---
 .../user-guide/features/memory-providers.md   | 28 +++++++++---
 2 files changed, 60 insertions(+), 11 deletions(-)

diff --git a/plugins/memory/openviking/README.md b/plugins/memory/openviking/README.md
index 4c98e3d0a096..af3ed9b8a16d 100644
--- a/plugins/memory/openviking/README.md
+++ b/plugins/memory/openviking/README.md
@@ -4,12 +4,23 @@ Context database by Volcengine (ByteDance) with filesystem-style knowledge hiera
 
 ## Requirements
 
-- `pip install openviking`
-- OpenViking server running (`openviking-server`)
-- Embedding + VLM model configured in `~/.openviking/ov.conf`
+- OpenViking installed with the `openviking-server` command available
+- OpenViking server config initialized and validated (`openviking-server init`,
+  then `openviking-server doctor`)
+- OpenViking server running and reachable from Hermes
 
 ## Setup
 
+Prepare OpenViking first:
+
+```bash
+openviking-server init
+openviking-server doctor
+openviking-server
+```
+
+Then configure Hermes:
+
 ```bash
 hermes memory setup    # select "openviking"
 ```
@@ -19,14 +30,36 @@ connection values into Hermes, or create a minimal `ovcli.conf` when one does
 not exist.
 
 Or manually:
+
 ```bash
 hermes config set memory.provider openviking
-echo "OPENVIKING_ENDPOINT=http://localhost:1933" >> ~/.hermes/.env
+```
+
+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`.
+
+```text
+OPENVIKING_ENDPOINT=http://127.0.0.1:1933
+# OPENVIKING_API_KEY=...
+# OPENVIKING_ACCOUNT=default
+# OPENVIKING_USER=default
+# OPENVIKING_AGENT=hermes
 ```
 
 ## Config
 
-All config via environment variables in `.env`:
+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-side provider config is read from environment variables in the active
+profile's `.env`:
 
 | Env Var | Default | Description |
 |---------|---------|-------------|
diff --git a/website/docs/user-guide/features/memory-providers.md b/website/docs/user-guide/features/memory-providers.md
index a2f5352e621c..440764f49d10 100644
--- a/website/docs/user-guide/features/memory-providers.md
+++ b/website/docs/user-guide/features/memory-providers.md
@@ -284,7 +284,7 @@ Context database by Volcengine (ByteDance) with filesystem-style knowledge hiera
 | | |
 |---|---|
 | **Best for** | Self-hosted knowledge management with structured browsing |
-| **Requires** | `pip install openviking` + running server |
+| **Requires** | OpenViking initialized, validated, and running |
 | **Data storage** | Self-hosted (local or cloud) |
 | **Cost** | Free (open-source, AGPL-3.0) |
 
@@ -292,19 +292,35 @@ Context database by Volcengine (ByteDance) with filesystem-style knowledge hiera
 
 **Setup:**
 ```bash
-# Start the OpenViking server first
-pip install openviking
+# 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
-echo "OPENVIKING_ENDPOINT=http://localhost:1933" >> ~/.hermes/.env
-# Authenticated servers should use a user/admin API key:
-echo "OPENVIKING_API_KEY=..." >> ~/.hermes/.env
 ```
 
+`hermes memory setup` can reuse or copy connection values from
+`~/.openviking/ovcli.conf`. Manual setup uses the active profile's `.env` file;
+for the default profile that is `~/.hermes/.env`, and 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_AGENT=hermes
+```
+
+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`).
+
 **Key features:**
 - Tiered context loading: L0 (~100 tokens) → L1 (~2k) → L2 (full)
 - Automatic memory extraction on session commit (profile, preferences, entities, events, cases, patterns)