OpenViking

One-Line Positioning

Injects the OpenViking context database into DeepSeek Harness (DSH): automatically recalls relevant memories and user profiles before each agent step, writes user/assistant/tool messages in real-time to the viking:// virtual filesystem, and blocks viking:// URIs from DSH local tools.

Core Capabilities

• In the agent/pre-step hook, perform semantic search using the current step input, append matched L0/L1/L2 memories as user messages with source: { kind: 'plugin' }
• Listen to session/event to automatically collect user/assistant/tool result messages and write them to the OpenViking session; auto-commit when commitTokenThreshold is reached
• Register 7 model-callable tools: viking_search / viking_read / viking_browse / viking_remember / viking_forget / viking_add_resource / viking_archive_expand
• Intercept incorrect usage of viking:// URIs by local tools like read/glob/grep/bash/edit/write in tools/pre-execute, forcing them to go through OpenViking tools instead
• Asynchronously ingest HTTP(S)/git remote resources via viking_add_resource, automatically deriving L0/L1/L2 hierarchy
• When service is unreachable or write fails, enter the pending write queue in OPENVIKING_PENDING_DIR, with automatic replay on next session start
• Each DSH session maps to dsh-<session-id> on the OpenViking side; defaults to deriving actor peer from workspace, but can be forcibly overridden

Technical Implementation

• Language: JavaScript (Node.js, ESM *.mjs)
• Key Dependencies: @deepseek-ai/dsh-llm (createUserMessage), @deepseek-ai/dsh-tools (defineTool); no third-party npm dependencies at runtime
• Architecture Pattern: Cordis plugin group (@deepseek-ai/cordis-plugin-group) — apply(ctx, input) registers the openvikingMemory service, subscribes to lifecycle events via ctx.on including agent/session-start, agent/pre-step, session/event, session/flush, tools/pre-execute; runtime uses shared submodules like setup-wizard/profile-inject/recall-core/capture-utils/pending-queue
• Entry Point: examples/dsh-memory-plugin/index.mjs (exports name/inject/apply), cordis.patch.yml declares Cordis loading entry

Use Cases

For developers or teams who need DSH to retain project knowledge, user preferences, and historical experience long-term: in multi-session, multi-workspace collaboration, let the agent automatically retrieve context from past decisions, code styles, and project documentation, avoiding repetitive instructions; meanwhile, asynchronously persist each dialogue turn to viking://user/<peer>/memories/ as the recall source for subsequent steps.

Installation

dsh plugin --profile web add github:volcengine/OpenViking

Configuration Options

Environment Variables (in addition to above): OPENVIKING_URL / OPENVIKING_BASE_URL / OPENVIKING_MCP_URL / OPENVIKING_CREDENTIAL_SOURCE / OPENVIKING_CONFIG_FILE / OPENVIKING_CLI_CONFIG_FILE / OPENVIKING_PENDING_DIR / OPENVIKING_PENDING_MAX_RETRIES / OPENVIKING_PENDING_TTL_DAYS / OPENVIKING_PENDING_REPLAY_LIMIT / OPENVIKING_RECALL_QUERY_EXPANSION / OPENVIKING_RECALL_LIMIT / OPENVIKING_RECALL_PEER_SCOPE / OPENVIKING_WORKSPACE_PEER.

Learning Curve

Advanced — requires first running an accessible OpenViking service (openviking-server) locally or remotely, then understanding concepts like viking:// URIs, L0/L1/L2 hierarchy, and actor peers; DSH installation itself is a single command, but tuning recall budgets, commit thresholds, peer isolation, etc. requires reading the configuration section in config.mjs and README.

Known Issues and Limitations

• Strongly tied to DSH version: peerDependencies locks @deepseek-ai/dsh-llm and @deepseek-ai/dsh-tools both to 0.1.0-rc.6; out-of-sync pre-release dist-tags will cause loading failure
• Strongly tied to Node engine: ^22.19.0 || >=24; earlier Node versions will be rejected outright
• If DSH preset marks persona as complete: true, recall/profile injected in pre-step still appends as user message, bypassing system prompt override; however, if DSH has a strip-plugin-source filter after agent/pre-step, recalled context will be stripped along with it
• When OpenViking service is unreachable, all writes fall back to queue in OPENVIKING_PENDING_DIR (default ~/.openviking/dsh-pending/); if queue repeatedly fails to replay and exceeds OPENVIKING_PENDING_MAX_RETRIES (default 3) or OPENVIKING_PENDING_TTL_DAYS, entries will be cleaned up
• live-recall.test.mjs end-to-end test is skipped by default, only runs when OPENVIKING_E2E=1 and real service credentials are available, not covered in CI
• viking_forget is irreversible hard deletion (explicitly noted in README), should only be called by the model when user explicitly requests deletion

---

What is OpenViking

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

The OpenViking Studio playground — a live demo you can open in the browser, no installation required.

Why OpenViking

• 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 · Context types
• 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
• Directory recursive retrieval. Vector search first locates the highest-scoring directory, then drills down layer by layer, so results arrive with their surrounding context intact. → Retrieval
• Observable retrieval. Each query preserves its directory-browsing trajectory. When a result looks wrong, you can see exactly which path produced it. → Retrieval
• Sessions become memory. After a session commits, OpenViking asynchronously extracts user preferences and agent experience into long-term memory. → Session

How the pieces fit together: Architecture. The thinking behind the design: The Database Paradigm for Context Engineering.

viking://
├── resources/              # Resources: project docs, repos, web pages, etc.
│   └── my_project/
│       ├── docs/
│       │   ├── api/
│       │   └── tutorials/
│       └── src/
└── user/
    └── {user_id}/
        ├── memories/
        │   └── preferences/
        │       ├── writing_style
        │       └── coding_habits
        ├── resources/
        │   └── private_project/
        ├── skills/
        │   ├── search_code
        │   └── analyze_data
        └── peers/
            └── web-visitor-alice/

The three loading tiers:

• L0 (Abstract): a one-sentence summary for quick relevance checks.
• L1 (Overview): core information and usage scenarios for planning.
• L2 (Details): the full original data, read only when needed.

Each directory carries its own L0/L1 layers, so relevance can be judged before any full file is read:

viking://resources/my_project/
├── .abstract               # L0: ~100 tokens - quick relevance check
├── .overview               # L1: ~2k tokens - structure and key points
└── docs/
    ├── .abstract
    ├── .overview
    └── api/
        ├── auth.md         # L2: full content, loaded on demand
        └── endpoints.md

Proof it works

OpenViking 0.3.22 has been evaluated on long-conversation user memory (LoCoMo) and multi-turn agent tasks (tau2-bench). Full results and setup details, including knowledge-base QA, are in the benchmark report; reproduction scripts live in ./benchmark.

• User memory (LoCoMo): with OpenViking, all three agent integrations land at 80–83% accuracy — up from 24–57% on their native memory — while input tokens drop by 34.3–91.0% and query latency by 58.45–66.10%.
• Agent experience (tau2-bench): experience memory lifts task success by +6.87pp (retail) and +11.87pp (airline) over the same LLM without memory.

Quick start

💡 Want to see it in action first? Try OpenViking Studio — a live hosted instance with a context playground, semantic search, and a multi-agent hub. No installation required.

Requires Python 3.10 or higher.

pip install openviking --upgrade
openviking-server init      # interactive wizard: providers, models, ov.conf
openviking-server doctor    # validate setup
openviking-server           # start (background: nohup openviking-server > openviking.log 2>&1 &)

init walks you through provider setup and writes ~/.openviking/ov.conf. It supports Volcengine, OpenAI, Codex OAuth, Kimi, GLM, and local Ollama — for Ollama it can detect and install the runtime and pull models suited to your hardware. doctor checks the config file, Python version, provider connectivity, and disk space without a running server. Manual ov.conf templates, per-provider examples, environment variables, and Windows setup: Configuration guide · Quick start docs.

The install already includes the ov client CLI. With the server running:

ov status
ov add-resource https://github.com/volcengine/OpenViking # --wait
ov ls viking://resources/
ov tree viking://resources/volcengine -L 2
# wait some time for semantic processing if not --wait
ov find "what is openviking"
ov grep "openviking" --uri viking://resources/volcengine/OpenViking/docs/en

Next steps:

• Client configuration (ov config), standalone CLI installs (npm / cargo), and advanced usage such as index rebuilding: CLI setup
• Docker and production deployment: Deployment guide

Use it with your agent

Integrations inject OpenViking recall into your agent's context and auto-commit session memory:

• Claude Code
• Codex
• OpenClaw
• Hermes
• Cursor
• TRAE / TRAE CN / TRAE CLI
• OpenCode
• pi
• Agent Plugins 1.0
• MCP clients
• LangChain / LangGraph

Setup instructions for each agent: Agent integrations overview.

OpenViking Helper (Beta)

OpenViking Helper is a desktop console, currently in beta for macOS and Windows x64:

• Visual local agent setup: detects OpenViking CLI, Claude Code, Codex, Cursor, Trae, and OpenCode, then configures supported plugin, MCP, Hook, and CLI integrations.
• Session trace inspection: parses Claude Code, Codex, and Trae sessions to show OpenViking recall, prompt injection, MCP calls, capture, and commit events.
• Local memory and skill management: views local memory / rule files and SKILL.md skills, then syncs them to OpenViking.

Download:

• macOS Apple Silicon (arm64)
• macOS Intel (x64)
• Windows (x64)

VikingBot

VikingBot is an AI agent framework built on top of OpenViking:

pip install "openviking[bot]"
openviking-server --with-bot
ov chat   # in another terminal

The official Docker image bundles VikingBot and starts it by default alongside the server and console UI. Details: VikingBot guide.

Deploy in production

For production, run OpenViking as a standalone HTTP service — see Server deployment and the Deployment guide.

Commercial editions

The open-source edition is not crippled. OpenViking in this repo is fully open source under AGPLv3: no feature gates, no account required, no activation key. Follow Deploy in production above and run it in production yourself — and that will stay true.

The two editions below answer "who operates it and where it runs", not "can I use it".

Just want to run the open-source edition? Go ahead — you don't need to contact anyone. Head to Quick start.

Research

OpenViking open-sources a subset of the core capabilities described in the VikingMem paper:

VikingMem: A Memory Base Management System for Stateful LLM-based Applications Jiajie Fu, Junwen Chen, Mengzhao Wang, Aoxiang He, Maojia Sheng, Xiangyu Ke, Yifan Zhu, and Yunjun Gao. arXiv:2605.29640, 2026. Accepted by VLDB 2026. 📄 Read the paper on arXiv

Partner Projects

OpenViking welcomes collaboration with other open-source projects to build the context data ecosystem. Our confirmed partners include:

• deer-flow - Open-source long-horizon SuperAgent harness
• NoKV - AI native distributed file system
• loopx - Lightweight loop engineering state kernel
• Hermes Agent - The agent that grows with you

Interested in joining our partner list? Please submit an issue to our community to apply.

Community & contributing

OpenViking is still in its early stages, and there is plenty left to build.

• Docs: docs.openviking.ai · FAQ
• Blog: blog.openviking.ai
• Team: About us
• Chat: 📱 Lark Group · 💬 WeChat · 🎮 Discord · 🐦 X
• Contribute: bug fixes and new features are both welcome — see CONTRIBUTING.md

Security and privacy

This project takes security seriously. For vulnerability reporting and supported versions, see SECURITY.md

License

The OpenViking project uses different licenses for different components:

• Main Project: AGPLv3 - see the LICENSE file for details
• crates/ov_cli: Apache 2.0 - see the LICENSE for details
• examples: Apache 2.0 - see the LICENSE for details
• third_party: Respective original licenses of third-party projects