OpenViking/examples/dsh-memory-plugin

One-Line Positioning

Connects OpenViking context database to DeepSeek Harness: automatically retrieves relevant memories before each step, asynchronously persists entire conversation sessions to disk, and exposes the mcp__openviking__* toolset plus an openviking-memory skill guide to the model.

Core Capabilities

• At the agent/pre-step hook, perform semantic search using the current step's input, append hits as user messages with source attribution as background for subsequent responses
• Listen to session/event to automatically collect user, assistant, and (optional) tool result messages and write to the OpenViking session; auto-commit when token threshold is reached
• Register a set of bridged model tools: mcp__openviking__search / read / list / tree / grep / glob / remember / write / edit / forget / add_resource, etc. (automatically synced with server advertisement)
• At tools/pre-execute, intercept DSH local tool's erroneous calls to viking:// URIs, redirecting the model to use the bridged OpenViking tools instead
• Attach a separate openviking skill provider, serving only the built-in openviking-memory skill, non-interfering with DSH's built-in filesystem provider
• When server is temporarily unreachable, automatically fall back to local pending queue (~/.openviking/pending/), replay on next session start
• Each DSH session maps to dsh-<session-id>; actor peer is derived from working directory by default, can be explicitly overridden

Technical Implementation

• Language: JavaScript (Node.js ESM, pure *.mjs)
• Key Dependencies: @deepseek-ai/dsh-llm (createUserMessage for constructing injection messages), @deepseek-ai/dsh-mcp-client (attaching MCP bridge), @deepseek-ai/dsh-skill-filesystem (attaching skill provider)
• Architecture Pattern: Cordis plugin group (@deepseek-ai/cordis-plugin-group), internally subscribes to five lifecycle events within apply(ctx, input): agent/session-start / agent/pre-step / session/event / session/flush / tools/pre-execute; MCP bridge is launched as a stdio child process via servers/mcp-proxy.mjs to avoid connection hangs when directly connecting to /mcp
• Entry Point: examples/dsh-memory-plugin/index.mjs, declared for loading in cordis.patch.yml

Use Cases

Developers who need DSH to reuse past project knowledge and user preferences across multiple sessions and workspaces: the model automatically retrieves context from historical decisions and documents each turn, while asynchronously persisting conversations to the OpenViking server, avoiding the need to re-explain each time; you can also use add_resource to bulk-import remote repositories or documents into the viking:// virtual filesystem.

Prerequisites & Compatibility

Installation

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

Configuration Options

Credential lookup order: environment variables (OPENVIKING_URL / OPENVIKING_API_KEY / OPENVIKING_BEARER_TOKEN / OPENVIKING_ACCOUNT / OPENVIKING_USER / OPENVIKING_PEER_ID / OPENVIKING_CREDENTIAL_SOURCE / OPENVIKING_CONFIG_FILE / OPENVIKING_CLI_CONFIG_FILE) → ~/.openviking/ovcli.conf → ~/.openviking/ov.conf → built-in defaults (http://127.0.0.1:1933). Pending queue environment variables: OPENVIKING_PENDING_DIR (default ~/.openviking/pending/, directory permissions 0o700, files 0o600), OPENVIKING_PENDING_MAX_RETRIES (default 3), OPENVIKING_PENDING_TTL_DAYS (default 7), OPENVIKING_PENDING_REPLAY_LIMIT (default 50).

FAQ

Q: Which OpenViking server does it connect to by default after installation?

A: Connects to localhost http://127.0.0.1:1933 by default. Can be overridden via OPENVIKING_URL environment variable, ~/.openviking/ovcli.conf config file, or explicitly via config.endpoint field in cordis.patch.yml.

Q: Which DSH version is required?

A: Requires DSH 0.1.0-rc.6 or higher within the 0.1.x range. package.json locks core peer packages to >=0.1.0-rc.6 <0.2.0; crossing to 0.2.x will fail to load due to peerDependencies mismatch.

Q: Will conversations be lost when offline?

A: No. When OpenViking server is unreachable or writes fail (HTTP 408 / 429 / 5xx, or returns retryable: true), messages are serialized to ~/.openviking/pending/ (directory permissions 0o700, files 0o600), and automatically replayed on next session start; max 3 retries or cleaned up after 7 days.

Q: What is viking://? Can DSH's built-in read tool open it directly?

A: viking:// is OpenViking's virtual database URI, not a local file path. The plugin intercepts DSH's erroneous calls to viking:// from read / glob / grep / bash / edit / write / str_replace_editor at the tools/pre-execute stage, redirecting the model to bridged tools like mcp__openviking__read / mcp__openviking__list / mcp__openviking__grep.

Q: Will memories be cleared after uninstalling the plugin?

A: No. Memories are stored on the OpenViking server; uninstalling the plugin only stops automatic recall and capture, won't delete persisted data; to fully delete, call mcp__openviking__forget with the accurate viking:// URI.

Q: Do I need to install the OpenViking server?

A: Yes. The plugin is just a client bridge; a reachable OpenViking server is required for recall and writes to work; when the server is unreachable, all writes fall back to the local pending queue.

Q: Is API Key configuration required?

A: Not mandatory. With default local config, empty key can connect to local service; when connecting to remote service or trusted-mode deployment, set OPENVIKING_API_KEY (or OPENVIKING_BEARER_TOKEN), and optionally configure OPENVIKING_ACCOUNT / OPENVIKING_USER.

Difficulty Level

Advanced — installation is just a single dsh plugin add command, but to actually use it you need a reachable OpenViking server running locally or remotely, plus understanding of concepts like viking:// URI, actor peer isolation, and recall budgets; just reading the README and tweaking config items without actually integrating with the server will get you blocked by the default 127.0.0.1:1933.

Known Issues & Limitations

• Strongly bound to DSH 0.1.x: peerDependencies locks dsh-llm / dsh-mcp-client / dsh-skill-filesystem all to >=0.1.0-rc.6 <0.2.0, overrides further fixes the entire dsh family to 0.1.0-rc.6; when DSH upgrades to 0.2.x, this plugin won't load due to peer mismatch.
• Strongly bound to Node engine: engines.node is hardcoded to ^22.19.0 || >=24; earlier Node versions reject installation outright.
• Actor peer scope is process-level only: MCP tool calls carry the peer resolved at process startup, not re-resolved per request; when one process serves multiple workspaces, explicit override via OPENVIKING_PEER_ID is needed.
• mcp__openviking__remember doesn't bind to current DSH session: server writes remember to its own short-term session, not dsh-<session-id> real-time stream; auto-capture will still persist this conversation.
• Injection point is agent/pre-step not system prompt: design intent is to avoid the issue where complete: true preset wipes out other prompt sections; if DSH adds a strip-plugin-source filter after pre-step in the future, recall context will be stripped too.
• mcp__openviking__forget is an irreversible hard delete; README explicitly requires the model to only call it when user explicitly requests.
• Offline pending queue has no background worker: replay only triggers on next session-start, max 50 items per replay; if service is unreachable for extended time, entries are cleaned up after TTL (default 7 days) or retry limit (default 3) is reached.
• live-recall.test.mjs end-to-end test is skipped by default: only runs when OPENVIKE_E2E=1 is set and real server credentials are provided; currently not enabled in CI.

---

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.

The memory evaluation used Doubao 2.0 Pro as the VLM and Doubao-embedding-vision-251215 as the embedding model.

• 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 / TraeCode CLI 2.0
• 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