feat(memory): add OpenViking context database integration by Mibayy · Pull Request #3369 · NousResearch/hermes-agent

Mibayy · 2026-03-27T10:17:36Z

Summary

Adds support for OpenViking, a self-hosted memory server, as an alternative to Honcho. The implementation follows the same pattern as honcho_tools.py — tools are gated behind a check_fn that pings /health, so they appear only when the server is running.

New toolset: `openviking`

Three tools, all under toolset="openviking":

Tool	Description
`viking_search`	Semantic search over memories, resources, and skills stored in OpenViking. Supports `auto` / `fast` / `deep` modes and optional `target_uri` scoping.
`viking_read`	Read content at a `viking://` URI. Three detail levels: `abstract` (~100 tokens), `overview` (~2k tokens structured summary), `read` (full content). Automatically selects overview for directories, read for files.
`viking_browse`	Explore the OpenViking filesystem layout. Views: `tree`, `list`, `stat`.

Configuration

OPENVIKING_ENDPOINT=http://127.0.0.1:1933  # default
OPENVIKING_API_KEY=                         # optional, for secured deployments

Changes

tools/openviking_tool.py — new file with all three tools and registry registration
toolsets.py — added "openviking" named toolset + viking_* tools to the shared tools list and gateway toolset

Testing

# All three tools register correctly with check_fn
from tools.registry import registry
import tools.openviking_tool
assert set(['viking_search', 'viking_read', 'viking_browse']).issubset(set(registry.get_all_tool_names()))

Tools are silently absent when the OpenViking server is not reachable — zero impact for users who don't run it.

Based on the working implementation from @CUexter's fork, with fixes applied (corrected os.getenv call, improved docstring).

Adds three tools for querying a self-hosted OpenViking server: - viking_search: semantic search over memories, resources, and skills (auto/fast/deep modes) - viking_read: read content at a viking:// URI with configurable detail levels (abstract / overview / read) - viking_browse: explore the OpenViking filesystem layout (tree/list/stat) All tools are gated behind check_fn that verifies the server is reachable, so they are silently absent when OpenViking is not running — same pattern as Honcho. The 'openviking' named toolset is also added to TOOLSETS and to the shared tools list so gateway and CLI pick them up automatically. Configure via: OPENVIKING_ENDPOINT (default: http://127.0.0.1:1933) OPENVIKING_API_KEY (optional, for secured deployments) Closes NousResearch#3368

ian-pascoe · 2026-03-28T09:59:23Z

Personally, I would think that auto-recall and auto-capture should be included instead of just a toolset.

Introduces MemoryProvider ABC, MemoryManager orchestrator, and BuiltinMemoryProvider for the existing MEMORY.md/USER.md system. Key design decisions: - Built-in memory is ALWAYS active, never disabled by external providers - Multiple providers can be active simultaneously - Prefetch results from all providers are merged per-turn - Sync fans out to all providers after each turn - Each provider can expose its own tools Three registration paths: 1. Built-in (BuiltinMemoryProvider) — always first, not removable 2. First-party (Honcho stays as-is for now, migration in follow-up) 3. Plugin — ctx.register_memory_provider() in plugin system Files: - agent/memory_provider.py — ABC with core + optional lifecycle hooks - agent/memory_manager.py — orchestrator, single integration point - agent/builtin_memory_provider.py — wraps existing MemoryStore - hermes_cli/plugins.py — register_memory_provider() + accessor - run_agent.py — MemoryManager wired alongside existing Honcho code - tests/agent/test_memory_provider.py — 37 tests This establishes the interface for all pending memory backend PRs (#1811 Hindsight, #2732 RetainDB, #2933 Mem0, #3499 Byterover, #3369 OpenViking, #2351 Holographic, #727 Cognitive) to implement as plugins rather than one-off integrations.

Adapts three more memory backend PRs to the MemoryProvider interface: OpenViking (PR #3369 by Mibayy): - 3 tools: viking_search, viking_read, viking_browse - Read-only, self-hosted server, no sync/prefetch - URI-based content with progressive disclosure levels RetainDB (PR #2732 by Alinxus): - 5 tools: retaindb_profile, retaindb_search, retaindb_context, retaindb_remember, retaindb_forget - Cloud API with prefetch, sync, and memory bridging - Durable write-behind queue pattern Cognitive Memory (PR #727 by 0xbyt4): - 1 tool with 4 actions: recall, store, forget, status - Local SQLite with vector embeddings (litellm) - Auto-classification, importance decay, dedup, forgetting All gated on credentials/deps via is_available(): - OpenViking: OPENVIKING_ENDPOINT + server health check - RetainDB: RETAINDB_API_KEY - Cognitive: litellm importable (uses its env vars for embedding API)

ZaynJarvis

Review: Initial OpenViking Toolset

Verdict: Approve with two required fixes before merge

The tool implementations are solid: endpoint selection logic (fast vs deep), result formatting, error handling, and the check_requirements() health ping are all correct.

Blocking Issue 1: Top-level `import httpx` crashes on missing dependency

tools/openviking_tool.py line 13 does a bare import httpx. The AGENTS.md import chain shows that every file in tools/ is imported by model_tools.py at startup. If httpx is not installed, this crashes the entire tool discovery phase, disabling ALL tools — not just OpenViking ones.

Fix: Use a lazy import pattern matching the memory plugin:

def _get_httpx():
    try:
        import httpx
        return httpx
    except ImportError:
        return None

def _client():
    httpx = _get_httpx()
    if httpx is None:
        raise ImportError("httpx is required for OpenViking: pip install httpx")
    ...

Blocking Issue 2: Missing import in `model_tools.py`

Per AGENTS.md: tools self-register via registry.register() at import time, but only if model_tools.py's _discover_tools() includes the import. This PR is missing:

# In model_tools.py _discover_tools():
import tools.openviking_tool

Without this line, the tool schemas are never registered and the model never sees these tools.

Checklist Pass (conditional on above fixes)

check_requirements() pings /health — correct discovery gate
viking_search: fast → /api/v1/search/find, deep → /api/v1/search/search, auto heuristic by query complexity — matches server's intended usage
viking_read: abstract/overview/full map to correct content endpoints
viking_browse: tree/list/stat map to /api/v1/fs/tree, ls, stat
Added to both _HERMES_CORE_TOOLS and named openviking toolset in toolsets.py
Missing: unit tests (not blocking but should be added)

Note: The module-level _OPENVIKING_ENDPOINT = os.getenv(...) constants freeze the endpoint at import time. If the endpoint changes via env var after startup, these won't update. The memory plugin uses os.environ.get() at call time in each function — consider the same pattern here.

Introduces MemoryProvider ABC, MemoryManager orchestrator, and BuiltinMemoryProvider for the existing MEMORY.md/USER.md system. Key design decisions: - Built-in memory is ALWAYS active, never disabled by external providers - Multiple providers can be active simultaneously - Prefetch results from all providers are merged per-turn - Sync fans out to all providers after each turn - Each provider can expose its own tools Three registration paths: 1. Built-in (BuiltinMemoryProvider) — always first, not removable 2. First-party (Honcho stays as-is for now, migration in follow-up) 3. Plugin — ctx.register_memory_provider() in plugin system Files: - agent/memory_provider.py — ABC with core + optional lifecycle hooks - agent/memory_manager.py — orchestrator, single integration point - agent/builtin_memory_provider.py — wraps existing MemoryStore - hermes_cli/plugins.py — register_memory_provider() + accessor - run_agent.py — MemoryManager wired alongside existing Honcho code - tests/agent/test_memory_provider.py — 37 tests This establishes the interface for all pending memory backend PRs (NousResearch#1811 Hindsight, NousResearch#2732 RetainDB, NousResearch#2933 Mem0, NousResearch#3499 Byterover, NousResearch#3369 OpenViking, NousResearch#2351 Holographic, NousResearch#727 Cognitive) to implement as plugins rather than one-off integrations.

Adapts three more memory backend PRs to the MemoryProvider interface: OpenViking (PR NousResearch#3369 by Mibayy): - 3 tools: viking_search, viking_read, viking_browse - Read-only, self-hosted server, no sync/prefetch - URI-based content with progressive disclosure levels RetainDB (PR NousResearch#2732 by Alinxus): - 5 tools: retaindb_profile, retaindb_search, retaindb_context, retaindb_remember, retaindb_forget - Cloud API with prefetch, sync, and memory bridging - Durable write-behind queue pattern Cognitive Memory (PR NousResearch#727 by 0xbyt4): - 1 tool with 4 actions: recall, store, forget, status - Local SQLite with vector embeddings (litellm) - Auto-classification, importance decay, dedup, forgetting All gated on credentials/deps via is_available(): - OpenViking: OPENVIKING_ENDPOINT + server health check - RetainDB: RETAINDB_API_KEY - Cognitive: litellm importable (uses its env vars for embedding API)

teknium1 · 2026-05-01T03:22:54Z

Thanks for the contribution @Mibayy — closing as superseded.

Since this was opened, OpenViking has been integrated as a memory-provider plugin (plugins/memory/openviking/) rather than as a top-level toolset under tools/. The plugin exposes equivalent agent-facing tools (viking_search, viking_read, viking_browse, viking_remember, viking_add_resource) via the memory-provider hook system, with ~20+ commits of evolution on top.

Neither tools/openviking_tool.py nor the toolsets.py wiring this PR added exist on current main — the plugin architecture replaced them. Setup is now hermes memory setup → pick OpenViking.

Closing — no action needed on your end.

alt-glitch · 2026-05-01T03:33:42Z

OpenViking is a third-party memory provider plugin. Per project policy, plugin integrations are P3. Consider contributing as a community plugin or adding to the plugin registry.

Introduces MemoryProvider ABC, MemoryManager orchestrator, and BuiltinMemoryProvider for the existing MEMORY.md/USER.md system. Key design decisions: - Built-in memory is ALWAYS active, never disabled by external providers - Multiple providers can be active simultaneously - Prefetch results from all providers are merged per-turn - Sync fans out to all providers after each turn - Each provider can expose its own tools Three registration paths: 1. Built-in (BuiltinMemoryProvider) — always first, not removable 2. First-party (Honcho stays as-is for now, migration in follow-up) 3. Plugin — ctx.register_memory_provider() in plugin system Files: - agent/memory_provider.py — ABC with core + optional lifecycle hooks - agent/memory_manager.py — orchestrator, single integration point - agent/builtin_memory_provider.py — wraps existing MemoryStore - hermes_cli/plugins.py — register_memory_provider() + accessor - run_agent.py — MemoryManager wired alongside existing Honcho code - tests/agent/test_memory_provider.py — 37 tests This establishes the interface for all pending memory backend PRs (NousResearch#1811 Hindsight, NousResearch#2732 RetainDB, NousResearch#2933 Mem0, NousResearch#3499 Byterover, NousResearch#3369 OpenViking, NousResearch#2351 Holographic, NousResearch#727 Cognitive) to implement as plugins rather than one-off integrations.

Adapts three more memory backend PRs to the MemoryProvider interface: OpenViking (PR NousResearch#3369 by Mibayy): - 3 tools: viking_search, viking_read, viking_browse - Read-only, self-hosted server, no sync/prefetch - URI-based content with progressive disclosure levels RetainDB (PR NousResearch#2732 by Alinxus): - 5 tools: retaindb_profile, retaindb_search, retaindb_context, retaindb_remember, retaindb_forget - Cloud API with prefetch, sync, and memory bridging - Durable write-behind queue pattern Cognitive Memory (PR NousResearch#727 by 0xbyt4): - 1 tool with 4 actions: recall, store, forget, status - Local SQLite with vector embeddings (litellm) - Auto-classification, importance decay, dedup, forgetting All gated on credentials/deps via is_available(): - OpenViking: OPENVIKING_ENDPOINT + server health check - RetainDB: RETAINDB_API_KEY - Cognitive: litellm importable (uses its env vars for embedding API)

teknium1 mentioned this pull request Mar 29, 2026

feat(memory): add pluggable memory provider interface #3825

Closed

This was referenced Mar 31, 2026

feat(memory): pluggable memory provider interface with profile isolation #4154

Closed

feat(memory): pluggable memory provider interface with profile isolation, review fixes, and honcho CLI restoration #4623

Merged

ZaynJarvis reviewed Apr 14, 2026

View reviewed changes

ZaynJarvis mentioned this pull request Apr 14, 2026

feat: expand OpenViking memory tools #5643

Open

teknium1 mentioned this pull request Apr 27, 2026

[Feature]: OpenViking Support #3368

Closed

1 task

teknium1 closed this May 1, 2026

alt-glitch added type/feature New feature or request P3 Low — cosmetic, nice to have comp/plugins Plugin system and bundled plugins tool/memory Memory tool and memory providers labels May 1, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(memory): add OpenViking context database integration#3369

feat(memory): add OpenViking context database integration#3369
Mibayy wants to merge 1 commit into
NousResearch:mainfrom
Mibayy:feat/openviking-memory-3368

Mibayy commented Mar 27, 2026

Uh oh!

ian-pascoe commented Mar 28, 2026

Uh oh!

ZaynJarvis left a comment

Uh oh!

teknium1 commented May 1, 2026

Uh oh!

alt-glitch commented May 1, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Conversation

Mibayy commented Mar 27, 2026

Summary

New toolset: openviking

Configuration

Changes

Testing

Uh oh!

ian-pascoe commented Mar 28, 2026

Uh oh!

ZaynJarvis left a comment

Choose a reason for hiding this comment

Review: Initial OpenViking Toolset

Blocking Issue 1: Top-level import httpx crashes on missing dependency

Blocking Issue 2: Missing import in model_tools.py

Checklist Pass (conditional on above fixes)

Uh oh!

teknium1 commented May 1, 2026

Uh oh!

alt-glitch commented May 1, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

New toolset: `openviking`

Blocking Issue 1: Top-level `import httpx` crashes on missing dependency

Blocking Issue 2: Missing import in `model_tools.py`