From a6807170f109dfaab19bc2023ddb5bb33fcb2852 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 --- plugins/memory/openviking/README.md | 98 +++++++++++++++++-- .../user-guide/features/memory-providers.md | 39 +++++++- 2 files changed, 129 insertions(+), 8 deletions(-) diff --git a/plugins/memory/openviking/README.md b/plugins/memory/openviking/README.md index 07e9484d4ddb..3444ae3968cc 100644 --- a/plugins/memory/openviking/README.md +++ b/plugins/memory/openviking/README.md @@ -4,9 +4,11 @@ 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 and server running (`openviking-server`) +- Embedding model configured in the OpenViking config file +- Optional VLM/chat model configured in OpenViking if you want automatic long-term extraction beyond session/resource storage + +For local-first labs, Ollama's `nomic-embed-text` model is a lightweight embedding-only starting point. ## Setup @@ -15,19 +17,101 @@ hermes memory setup # select "openviking" ``` 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//.env`. + +```text +OPENVIKING_ENDPOINT=http://127.0.0.1:1933 +OPENVIKING_API_KEY= +OPENVIKING_ACCOUNT=default +OPENVIKING_USER=default +OPENVIKING_AGENT=hermes +``` + +`OPENVIKING_API_KEY` can be blank for local dev servers that do not require authentication. Authenticated or multi-tenant servers should set the key and tenant IDs explicitly. + ## Config -All config via environment variables in `.env`: +All Hermes-side provider config is read from environment variables in the active profile's `.env`: | Env Var | Default | Description | |---------|---------|-------------| -| `OPENVIKING_ENDPOINT` | `http://127.0.0.1:1933` | Server URL | -| `OPENVIKING_API_KEY` | (none) | API key (optional) | +| `OPENVIKING_ENDPOINT` | `http://127.0.0.1:1933` | OpenViking server URL. This is the only required Hermes availability flag. | +| `OPENVIKING_API_KEY` | (none) | API key. Optional for local dev mode. | +| `OPENVIKING_ACCOUNT` | `default` | Tenant account ID. Send explicitly when using ROOT/API-key authenticated servers. | +| `OPENVIKING_USER` | `default` | Tenant user ID. Used in memory URIs such as `viking://user/default/...`. | +| `OPENVIKING_AGENT` | `hermes` | Agent ID. Useful for profile or multi-agent isolation. | + +OpenViking's own server config is separate from Hermes. If you use a custom config file, point OpenViking at it when validating or starting the server: + +```bash +OPENVIKING_CONFIG_FILE=/path/to/ov.conf uvx --from openviking ov config validate +OPENVIKING_CONFIG_FILE=/path/to/ov.conf \ + uvx --from openviking openviking-server \ + --config /path/to/ov.conf \ + --host 127.0.0.1 \ + --port 1933 +``` + +## Local Ollama embeddings + +Ollama can provide local embeddings for OpenViking without changing Hermes' chat model provider. + +```bash +ollama pull nomic-embed-text +curl -fsS http://localhost:11434/v1/embeddings \ + -H 'Content-Type: application/json' \ + -d '{"model":"nomic-embed-text","input":"OpenViking embedding probe"}' \ + -o /tmp/openviking-ollama-embed-probe.json +``` + +`nomic-embed-text` returns 768-dimensional vectors. OpenViking should use Ollama's OpenAI-compatible `/v1` base URL, not the native Ollama root URL: + +```json +"embedding": { + "dense": { + "provider": "ollama", + "model": "nomic-embed-text", + "api_base": "http://localhost:11434/v1", + "dimension": 768 + }, + "max_concurrent": 2, + "max_retries": 2, + "text_source": "content_only", + "max_input_tokens": 2048 +} +``` + +Keep concurrency conservative on laptops or WSL instances with limited RAM. Avoid pulling large local chat models unless the machine has enough memory and you explicitly need extraction/model-generation features. + +## Validation + +Check OpenViking first: + +```bash +curl -fsS http://127.0.0.1:1933/health +OPENVIKING_CONFIG_FILE=/path/to/ov.conf uvx --from openviking ov health -o json +``` + +Then check Hermes against the intended profile: + +```bash +hermes memory status +hermes --profile openviking-lab memory status +``` + +The default profile can remain built-in-only while a lab profile uses OpenViking: + +```bash +hermes profile create openviking-lab --clone +hermes --profile openviking-lab config set memory.provider openviking +``` + +For an embedding-only local setup, immediate verification may find data in `viking://session` before it appears as extracted long-term memories under `viking://user//memories`. Long-term extraction may require a configured OpenViking extraction/chat model. ## Tools diff --git a/website/docs/user-guide/features/memory-providers.md b/website/docs/user-guide/features/memory-providers.md index 00f2555d620c..5bbc0958900e 100644 --- a/website/docs/user-guide/features/memory-providers.md +++ b/website/docs/user-guide/features/memory-providers.md @@ -283,7 +283,44 @@ openviking-server hermes memory setup # select "openviking" # Or manually: hermes config set memory.provider openviking -echo "OPENVIKING_ENDPOINT=http://localhost:1933" >> ~/.hermes/.env +``` + +Add the OpenViking connection settings to the active profile's `.env` file. For the default profile that is `~/.hermes/.env`; for named profiles use `~/.hermes/profiles//.env`. + +```text +OPENVIKING_ENDPOINT=http://127.0.0.1:1933 +OPENVIKING_API_KEY= +OPENVIKING_ACCOUNT=default +OPENVIKING_USER=default +OPENVIKING_AGENT=hermes +``` + +`OPENVIKING_API_KEY` can be blank for local dev servers that do not require authentication. Authenticated or multi-tenant servers should set the key and tenant IDs explicitly. + +**Local Ollama embeddings:** OpenViking can use Ollama embeddings without changing Hermes' chat model provider. `nomic-embed-text` returns 768-dimensional vectors; use Ollama's OpenAI-compatible `/v1` base URL in the OpenViking config: + +```json +"embedding": { + "dense": { + "provider": "ollama", + "model": "nomic-embed-text", + "api_base": "http://localhost:11434/v1", + "dimension": 768 + }, + "max_concurrent": 2, + "max_retries": 2, + "text_source": "content_only", + "max_input_tokens": 2048 +} +``` + +Keep concurrency conservative on laptops or WSL instances with limited RAM. Long-term extraction may require a configured OpenViking extraction/chat model; embedding-only setups may verify storage in `viking://session` before extracted memories appear under `viking://user//memories`. + +**Validation:** +```bash +curl -fsS http://127.0.0.1:1933/health +hermes memory status +hermes --profile openviking-lab memory status ``` **Key features:**