# OpenViking > Provides OpenViking long-term semantic memory, automatic session capture, and viking:// context tools for DeepSeek Harness, enabling DSH sessions to automatically recall and write to persistent memory. ## Metadata - Author: [@volcengine](https://github.com/volcengine) - Repo: - GitHub: [volcengine/OpenViking](https://github.com/volcengine/OpenViking) - Stars: 28,872 - Language: Python - License: [AGPL-3.0](https://spdx.org/licenses/AGPL-3.0.html) - Homepage: - Topics: `agent-memory`, `agent-plugins`, `agentic-rag`, `context-database`, `dsh-plugin`, `self-evolving` - Forks: 2,274 - Open Issues: 453 - Last push: 2026-08-17T14:58:29.000Z - Added: 2026-08-17T00:00:00.000Z ## Install ```bash dsh plugin --profile web add github:volcengine/OpenViking ``` ## Wiki ## 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-` 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//memories/` as the recall source for subsequent steps. ## Installation ```bash dsh plugin --profile web add github:volcengine/OpenViking ``` ## Configuration Options | Config | Type | Description | Default | |---|---|---|---| | `endpoint` | string | OpenViking service address | `http://127.0.0.1:1933` | | `apiKey` | string | Bearer credential (also via `OPENVIKING_API_KEY`/`OPENVIKING_BEARER_TOKEN` or `~/.openviking/ovcli.conf`) | `""` | | `account` | string | trusted-mode account (`X-OpenViking-Account`) | `""` | | `user` | string | trusted-mode user (`X-OpenViking-User`) | `""` | | `peerId` | string | Explicit actor peer (overrides workspace derivation) | `""` | | `workspacePeer` | boolean | Whether to derive actor peer from DSH workspace | `true` | | `recallPeerScope` | `"all"` \| `"actor"` | Whether to recall across workspaces | `all` | | `recallQueryExpansion` | `"auto"` \| `"off"` | Whether to perform query rewriting | `auto` | | `recallTokenBudget` | number (200–50000) | Recall context token limit | `2000` | | `recallMaxContentChars` | number (100–5000) | Recall entry abstract truncation length | `500` | | `recallLimit` | number (1–50) | Number of recall entries | `10` | | `scoreThreshold` | number (0–1) | Recall score threshold | `0.35` | | `minQueryLength` | number (1–64) | Minimum query length to trigger recall | `3` | | `profileTokenBudget` | number (500–50000) | Startup profile injection token limit | `10000` | | `commitTokenThreshold` | number (1000–1000000) | Pending token threshold to trigger session commit | `20000` | | `commitKeepRecentCount` | number (0–1000) | Number of recent messages to keep during commit | `10` | | `captureMode` | `"semantic"` \| `"keyword"` | Capture mode | `semantic` | | `captureAssistantTurns` | boolean | Whether to capture assistant messages | `true` | | `captureToolResults` | boolean | Whether to capture tool results | `false` | | `captureMaxLength` | number (200–100000) | Maximum single capture length | `24000` | | `captureToolMaxChars` | number (200–1000000) | Maximum tool result characters | `1000000` | | `requestTimeoutMs` | number (1000–120000) | HTTP request timeout | `10000` | 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 --- This document is auto-generated by [deepseek-plugin.org](https://deepseek-plugin.org). HTML page: [OpenViking](https://deepseek-plugin.org/plugins/volcengine/OpenViking) Wiki generated by AI (model: `MiniMax-M2.5`)