OpenViking/examples/dsh-memory-plugin

一句话定位

为 DeepSeek Harness 接入 OpenViking 上下文数据库：在每一步前自动检索相关记忆，整段对话异步落盘，并向模型暴露 mcp__openviking__* 工具集与一份 openviking-memory 技能指导。

核心能力

• 在 agent/pre-step 钩子用当前步骤的输入做语义检索，把命中结果追加为带来源标注的 user message，作为后续回答的背景
• 监听 session/event 自动采集用户、助手与（可选）工具结果消息并写入 OpenViking session，达到 token 阈值时自动 commit
• 注册一套桥接后的模型工具：mcp__openviking__search / read / list / tree / grep / glob / remember / write / edit / forget / add_resource 等（随服务端广告自动同步）
• 在 tools/pre-execute 拦截 DSH 本地工具对 viking:// URI 的错误调用，让模型改走桥接的 OpenViking 工具
• 单独挂一个 openviking 技能 provider，只服务内置的 openviking-memory 技能，与 DSH 自带的文件系统 provider 互不干扰
• 服务端临时不可达时自动回落到本地待写队列（~/.openviking/pending/），下个会话启动时 replay
• 每个 DSH session 映射为 dsh-<session-id>；actor peer 默认从工作目录派生，可显式覆盖

技术实现

• 语言: JavaScript（Node.js ESM，纯 *.mjs）
• 关键依赖: @deepseek-ai/dsh-llm（createUserMessage 构造注入消息）、@deepseek-ai/dsh-mcp-client（挂 MCP 桥接）、@deepseek-ai/dsh-skill-filesystem（挂技能 provider）
• 架构模式: Cordis 插件组（@deepseek-ai/cordis-plugin-group），apply(ctx, input) 内部订阅 agent/session-start / agent/pre-step / session/event / session/flush / tools/pre-execute 五个生命周期事件；MCP 桥接以 stdio 子进程拉起 servers/mcp-proxy.mjs，避免直接连 /mcp 时的连接卡死
• 入口文件: examples/dsh-memory-plugin/index.mjs，由 cordis.patch.yml 声明装载

适用场景

需要让 DSH 在多会话、多工作区里复用过往项目知识与用户偏好的开发者：模型每轮会自动从历史决策、文档里检索上下文，同时把对话异步落到 OpenViking 服务端，避免下次又得重新交代；你也可以通过 add_resource 把远程仓库或文档一次性灌进 viking:// 虚拟文件系统。

前置依赖与兼容性

安装方式

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

配置项

凭证查找顺序：环境变量（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 → 内置默认（http://127.0.0.1:1933）。 待写队列环境变量：OPENVIKING_PENDING_DIR（默认 ~/.openviking/pending/，目录权限 0o700、文件 0o600）、OPENVIKING_PENDING_MAX_RETRIES（默认 3）、OPENVIKING_PENDING_TTL_DAYS（默认 7）、OPENVIKING_PENDING_REPLAY_LIMIT（默认 50）。

常见问题

Q: 安装后默认连接哪个 OpenViking 服务？

A: 默认连本机的 http://127.0.0.1:1933。可通过 OPENVIKING_URL 环境变量、~/.openviking/ovcli.conf 配置文件，或在 cordis.patch.yml 的 config.endpoint 字段显式覆盖。

Q: 需要 DSH 哪个版本？

A: 需要 DSH 0.1.0-rc.6 及以上的 0.1.x。package.json 把核心 peer 包锁在 >=0.1.0-rc.6 <0.2.0，跨到 0.2.x 会因 peerDependencies 不匹配而装载失败。

Q: 离线时对话会不会丢？

A: 不会。OpenViking 服务不可达或写失败时（HTTP 408 / 429 / 5xx，或返回 retryable: true），消息会被序列化进 ~/.openviking/pending/（目录权限 0o700、文件 0o600），下个会话启动自动 replay；最多重试 3 次或 7 天后清理。

Q: viking:// 是什么？DSH 自带的 read 工具能直接打开吗？

A: viking:// 是 OpenViking 的虚拟数据库 URI，不是本地文件路径。插件在 tools/pre-execute 阶段会拦截 DSH 的 read / glob / grep / bash / edit / write / str_replace_editor 对 viking:// 的错误调用，把模型引导到 mcp__openviking__read / mcp__openviking__list / mcp__openviking__grep 等桥接工具。

Q: 卸载插件后记忆会被清掉吗？

A: 不会。记忆保存在 OpenViking 服务端，卸载插件只会停止自动召回与采集，不会删除已落盘的数据；要彻底删除，调 mcp__openviking__forget 并传准确的 viking:// URI。

Q: 需要安装 OpenViking 服务端吗？

A: 是的。插件只是客户端桥，必须有一个可达的 OpenViking 服务端才能完成召回与写入；服务端不可达时所有写操作都会回落到本地待写队列。

Q: 是否需要配置 API Key？

A: 不强制。本地默认配置下空 key 也能连到本地服务；接入远程服务或 trusted-mode 部署时，需设置 OPENVIKING_API_KEY（或 OPENVIKING_BEARER_TOKEN），并按需配上 OPENVIKING_ACCOUNT / OPENVIKING_USER。

上手难度

进阶 — 安装只是单条 dsh plugin add 命令，但要真正用起来得先在本地或远端跑一个可达的 OpenViking 服务端，再理解 viking:// URI、actor peer 隔离、召回预算等概念；如果只是看 README 就调配置项而不实际联调服务端，会被本地默认的 127.0.0.1:1933 拦在门外。

已知问题与限制

• 强绑定 DSH 0.1.x：peerDependencies 把 dsh-llm / dsh-mcp-client / dsh-skill-filesystem 全部锁在 >=0.1.0-rc.6 <0.2.0，overrides 进一步把整个 dsh 家族固定到 0.1.0-rc.6，DSH 升级到 0.2.x 后本插件会因 peer 不匹配而无法装载。
• 强绑定 Node 引擎：engines.node 写死 ^22.19.0 || >=24，更早的 Node 会直接拒绝安装。
• actor peer 的作用域仅限进程级：MCP 工具调用携带的是进程启动时解析的 peer，而不是每次请求重新解析；当一个进程服务多个 workspace 时，需要用 OPENVIKING_PEER_ID 显式覆盖。
• mcp__openviking__remember 不绑定当前 DSH 会话：服务端把 remember 写到自己的短期 session，而不是 dsh-<session-id> 实时流；自动采集仍然会落盘这条对话本身。
• 注入位置是 agent/pre-step 而非系统提示：设计本意是规避 complete: true preset 抹掉其它 prompt section 的问题；如果未来 DSH 在 pre-step 之后加入 strip-plugin-source 过滤器，召回上下文会被一并剥掉。
• mcp__openviking__forget 是不可逆的硬删除，README 明确要求模型只在用户明确请求时调用。
• 离线待写队列没有后台 worker：replay 只在下一次 session-start 触发，且单次最多 replay 50 条；如果服务长时间不可达，TTL（默认 7 天）或重试上限（默认 3 次）达到后条目会被清理。
• live-recall.test.mjs 端到端用例默认跳过：只有设置 OPENVIKING_E2E=1 且提供真实服务端凭证才会运行，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