OpenViking
Frameworkvolcengine/OpenViking
Self-evolving context database unifying agent memory, knowledge RAG, and skills.
Overview
OpenViking stores memories, resources, and skills as a virtual filesystem under the viking:// protocol. It processes content into three tiers (L0/L1/L2) and loads context on demand, with observable retrieval trajectories. Built for AI agents to manage long-term memory and knowledge efficiently.
README Preview
\n\n\n \n \n \n\n\n### OpenViking: The Context Database for AI Agents\n\nEnglish / [中文](README_CN.md) / [日本語](README_JA.md)\n\nWebsite · Live Demo · GitHub · Issues · Docs\n\n[](https://github.com/volcengine/OpenViking/releases)\n[](https://github.com/volcengine/OpenViking)\n[](https://github.com/volcengine/OpenViking/issues)\n[](https://github.com/volcengine/OpenViking/graphs/contributors)\n[](https://github.com/volcengine/OpenViking/blob/main/LICENSE)\n[](https://github.com/volcengine/OpenViking/commits/main)\n\n👋 Join our Community\n\n📱 Lark Group · WeChat · Discord · X\n\n\n\n\n\n***\n\n## What is OpenViking\n\nOpenViking is an open-source context database for AI agents. It stores memories, resources, and skills as one virtual filesystem under the `viking://` protocol, so an agent browses its own context with `ls`, `tree`, and `find` instead of querying a black-box vector store. Content is processed into three tiers — L0 abstract, L1 overview, L2 details — and loaded on demand. Every retrieval leaves a trajectory you can watch and debug. Full introduction: [Getting started](https://docs.openviking.ai/en/getting-started/01-introduction).\n\n[](https://openviking.ai/studio)\n\n*The [OpenViking Studio](https://openviking.ai/studio) playground — a live demo you can open in the browser, no installation required.*\n\n## Why OpenViking\n\n- **One filesystem for all context.** Memories, resources, and skills each get a `viking://` URI. Agents locate and manipulate context deterministically, like a developer working with files. → [Viking URI](https://docs.openviking.ai/en/concepts/04-viking-uri) · [Context types](https://docs.openviking.ai/en/concepts/02-context-types)\n- **Tiered loading cuts token spend.** Every entry is processed into L0 (abstract), L1 (overview), and L2 (details) on write, then loaded only as deep as the task requires. → [Context layers](https://docs.openviking.ai/en/concepts/03-context-layers)\n- **Directory recursive retrieval.** Vector sear
FAQ (5)
TroubleshootingHow to fix "complete_tool_result() got an unexpected keyword argument 'preserve_complete'" error in OpenViking ov compile?
This error occurs on OpenViking main (commit 54d4c0fac, v0.5.2.1+38 / 0.5.3.dev40) where ov compile silently skips the final review stage and reports the warning "Final review incomplete; publishing original artifacts" in result.warnings.
**Root cause:** PR #6364 updated AgentLoop in bot/vikingbot/agent/loop.py to call the preview hook with a new keyword argument preserve_complete, but the Compile pipeline's custom hook in bot/vikingbot/compile/pipeline_agent.py (line ~55) still uses the old two-parameter signature, so every preview call raises a TypeError that the pipeline swallows.
**Fix:** Edit bot/vikingbot/compile/pipeline_agent.py and update the hook signature to accept the new flag (Compile keeps child tool results complete unconditionally, so the flag can be ignored):
async def complete_tool_result(result, session_key, preserve_complete: bool = False):
"""Compile keeps child tool results complete unconditionally; the flag is
accepted for signature parity with the AgentLoop preview hook."""
return result
Then restart openviking-server and re-run ov compile. Verified result: task completes with warnings: [] and the final review stage executes normally.
TroubleshootingHow to fix DSH memory plugin showing commit_count 0 and never archiving short sessions?
The plugin sends the shared default keep_recent_count: 10, so sessions with fewer than 10 messages retain all messages in the recent tail during the final dispose() commit and are never archived. For harnesses that manage their own context, such as DSH, set the value to 0 for the end-of-session commit. Temporary workaround: run with OPENVIKING_COMMIT_KEEP_RECENT_COUNT=0. In code, change the DSH final commit in examples/dsh-memory-plugin/runtime.mjs to send keep_recent_count: 0; the same fix applies to the token-threshold commits in Claude Code and Codex auto-capture.mjs. Plugins where OpenViking manages context should keep the configurable tail. Update to a release containing PR "fix(plugins): archive every message on session commit."
TroubleshootingHow to fix the Web Studio Compile page crash: "Cannot read properties of undefined (reading 'length')"?
This affects OpenViking 0.4.23 when a compile task was created without the optional --from flag. The Studio row renderer checks r?.from.length, but does not guard from, so a task with meta.request.from missing crashes the entire /studio/compile route.
Temporary workaround: open the Compile page with a filter that excludes the offending task, for example:
/studio/compile?status=completed
If the broken task itself is completed, use another status filter or a query that matches nothing:
/studio/compile?q=__no_match__
The task API is healthy; the failure is only in Studio rendering.
Permanent fix: upgrade to a release containing the PR fix(studio): normalize missing compile sources, or normalize missing/null source lists at the Studio API boundary:
const from = r?.from ?? [];
from.length ? from.map(/* render source */) : "—";
The minimal frontend-safe guard is:
r?.from?.length ? r.from.map(/* render source */) : "—"TroubleshootingHow to fix the 'declared `on_session_end` hook is not registered' warning for the OpenViking Hermes plugin?
This is a false-positive when OpenViking registers through Hermes' memory-provider lifecycle instead of the generic hook registry. In the OpenViking Hermes plugin manifest, remove on_session_end from the declared hooks list. Do not remove OpenVikingMemoryProvider.on_session_end() or change ctx.register_memory_provider(OpenVikingMemoryProvider()); Hermes still calls session-end commits through the MemoryProvider lifecycle. Reload/reinstall the plugin, then run hermes plugins doctor openviking again. If session commits succeed while using OpenViking plugin 2.0.1 with Hermes 0.21.5, the warning can safely be ignored until the manifest fix is installed.
TroubleshootingHow to fix OpenViking plugin HTTP client returning HTTP 200 with an empty result instead of retrying when the response body times out or the connection resets?
Upgrade to a source revision or release containing plugin PR #5661, which fixes examples/memory-plugin-shared/lib/ov-http.mjs, plus the companion fix for the openclaw and pi-experimental clients. If pinned to commit d9352f2a8bac78cbf4ed08b26543d22adcdd4c93, cherry-pick those changes.
The defect is in the broad catch around response.json(): it converts body-read transport failures into invalid/empty JSON handling. The fix must rethrow abort/network/stream errors so the existing outer handler returns:
{ ok: false, status: 0, result: null }
and isRetryableFailure(result) returns true. For owned timeouts, the original error must keep error.name === "AbortError" and error.aborted === true.
Use a guard conceptually like:
try {
result = await response.json();
} catch (err) {
if (
err?.name === "AbortError" ||
err?.aborted === true ||
err?.cause?.code === "UND_ERR_SOCKET"
) {
throw err; // Let the outer transport handler classify and retry it.
}
// Keep existing handling only for a complete, malformed, or empty JSON body.
}
Do not use requireJsonBody: true as a workaround: strict mode changes the symptom to a non-retryable HTTP 200 empty or invalid JSON response failure. After the patch, normal successful responses, HTTP errors, and complete malformed/empty JSON bodies retain their previous behavior; only stalls, resets, aborts, and broken streams while reading the body become retryable status-0 transport failures.