dsh-openviking
Verified@logictan/dsh-openviking Β· v0.4.15 Β· Apache-2.0
OpenViking memory and context bundle for DeepSeek Harness
Install
dsh plugin add @logictan/dsh-openviking Confirm the layer applied with dsh --profile default --dump-config β see the install guide.
Source
Published to npm without a public repository. Inspect the package contents before installing.
Tags
Readme
OpenViking Memory for DeepSeek Harness
An installable DeepSeek Harness bundle that adds OpenViking auto-recall, session capture, viking:// URI protection, and the OpenViking MCP tool surface.
Requires an OpenViking server with
viking://~home-alias support. Recall targets the caller's own context space throughviking://~/memoriesandviking://~/skills; the uid-lessviking://user/memoriesshorthand is rejected by newer servers.
Published as @logictan/dsh-openviking.
Install
This is the DSH fork of the upstream OpenViking memory plugin. It ships inside the aggregate bundle, which is the supported way to install it:
dsh plugin --profile web add @logictan/dsh-plugins-all
dsh --profile web --dump-config # should list the openviking-memory row
Adding this package alone also works, but then the rest of the bundle's plugins are absent:
dsh plugin --profile web add @logictan/dsh-openviking
dsh plugin forwards to pnpm inside the profile directory, so the bundle has to
be a real package. Linking a source checkout (dsh plugin --profile web add packages/dsh-openviking) only works when that checkout has its own
node_modules, because Node resolves the bundle's dsh peers from the source
tree's realpath rather than from the profile.
It also needs node packages/dsh-openviking-shared/sync.mjs run first: the
shared/ modules the bundle imports are generated, not committed.
Requirements
@deepseek-ai/dsh0.1.0-rc.6or later, below1.0.0(see DSH version compatibility)- Node.js
^22.19.0or>=24 - A reachable OpenViking server
The bundle has no runtime npm dependencies. Its message structures come from
createUserMessage (@deepseek-ai/dsh-llm), its tool surface from
@deepseek-ai/dsh-mcp-client, and its skill provider from
@deepseek-ai/dsh-skill-filesystem β peerDependencies that DSH itself already
installs. Keep those packages in the host installation rather than adding
individual DSH core packages to the profile. DSH initializes profiles with
nodeLinker: hoisted and autoInstallPeers: false, then makes the host packages
available through its module fallback at boot. A missing-peer warning during
dsh plugin add alone does not prove startup is broken.
The peer range is >=0.1.0-rc.6 <0.2.0 || ^0.1.5-rc.1 || ^0.2.1-rc.2. The
later clauses explicitly admit the release candidates semver does not include in
the first clause merely because they compare above 0.1.0-rc.6. Other
pre-release series need separate verification. Local devDependencies and
overrides stay pinned to the generation the host runs to exercise the real
contract.
Everything under shared/ is generated by
node packages/dsh-openviking-shared/sync.mjs β edit
packages/dsh-openviking-shared/lib/, never the vendored copies.
DSH version compatibility
The peer range is >=0.1.0-rc.6 <1.0.0-0. DSH checks each @deepseek-ai/dsh-*
peer when it loads a plugin, with pre-releases included in the range, so this
admits every 0.x release and pre-release from 0.1.0-rc.6 on, including ones
published after this bundle. The bundle touches a small DSH surface β
createUserMessage and boundContextSummary from @deepseek-ai/dsh-llm and
the plugin entry points of @deepseek-ai/dsh-mcp-client and
@deepseek-ai/dsh-skill-filesystem β so the range is not narrowed to the
releases tested so far.
Verified releases: 0.1.0-rc.6, 0.1.5-rc.1, 0.1.5-rc.2, 0.1.7-rc.2,
0.2.0-rc.2, and 0.2.1-alpha.1. A daily job
(.github/workflows/host-compat.yml) runs the bundle's tests against the
releases DSH's latest, next, and alpha dist-tags point at, installs each
of those releases, adds the packed bundle to a profile and checks
--dump-config lists it, and opens an issue when any of that fails, so a breaking release is usually caught before users
reach it; if the bundle still fails to start on a new release, pin DSH to a
verified one and open an issue. DSH 1.0 and later, pre-releases included, fall outside the
range and DSH refuses to load the bundle; dsh plugin allow-version grants an exact-version
exemption if you accept the risk. Local devDependencies and overrides stay
pinned to rc.6 to exercise the minimum supported contract.
Troubleshooting startup
If startup reports that @deepseek-ai/dsh-llm does not export assertNever,
inspect the affected profile before changing dependencies:
dsh --version
dsh plugin --profile web why @deepseek-ai/dsh-skill
dsh plugin --profile web why @deepseek-ai/dsh-skill-filesystem
dsh plugin --profile web why @deepseek-ai/dsh-llm
Replace web with the affected profile name. Check its package.json,
pnpm-lock.yaml, and pnpm-workspace.yaml under
${DSH_HOME:-$HOME/.dsh}/profiles/<profile>/, including dependency overrides.
[email protected] imports assertNever from the old location. A profile-local
copy can shadow the newer host package and break both DSH's own skill loader
and this plugin. As of 2026-09-14, the skill and skill-filesystem npm latest
tags still point to 0.0.1 release candidates; installing either without a
version is not an upgrade strategy.
If these old packages are direct profile dependencies added only to satisfy this plugin, remove those constraints and let DSH supply its matching packages:
dsh plugin --profile web remove @deepseek-ai/dsh-skill @deepseek-ai/dsh-skill-filesystem
dsh plugin --profile web add @logictan/dsh-openviking@latest
dsh --profile web
If another plugin requires them, update that plugin's constraints instead of
removing them blindly. Keep autoInstallPeers: false and nodeLinker: hoisted
in the profile's pnpm settings. Do not patch the import in node_modules: a
mixed DSH package family can have other incompatible interfaces. Updating this
memory plugin alone does not remove conflicting profile-local packages.
Use dsh --profile <profile> to start a named profile. dsh web is an alias for
the stock web profile, not a subcommand to append after --profile.
Design notes
Why injection uses pre-step user messages, not the system prompt
Recall and profile context enter through the agent/pre-step waterfall as
durable, source-attributed user messages
(source: { kind: 'plugin:openviking-memory', β¦ }). The producer-owned kind is
required by DSH session format v4; the plugin still recognizes legacy
kind: 'plugin' messages while older sessions are replayed.
They are deliberately not added to the system prompt: a DSH preset whose
persona declares complete: true (the stock minimal preset does) restores
that persona as the sole prompt section after assembly, silently discarding
every other contribution β a system-prompt-based memory plugin loses its
context under such presets with no error. Pre-step injection also makes each
injection a session event that replays, is visible to compaction, and never
reaches request/header.
What triggers recall
Recall runs on a pre-step whose entering batch contains user-authored input.
The query is built only from those messages: user-role messages with
source.kind absent or user. Messages that DSH or other plugins inject
(time-context, plugin:* notices, this plugin's own blocks) and tool results
are excluded, using the same rule capture uses. A batch made only of injected
context sends no search request.
How the tool surface is mounted
mcp.mjs mounts @deepseek-ai/dsh-mcp-client straight at the server's /mcp
endpoint over streamable HTTP, so the model gets the server's full tool set
instead of a hand-maintained subset.
It used to start a stdio proxy per mount instead β one Node process per root agent, each ~17 MB of phys_footprint. On a host with 25 live agents that came to 26 processes and 705 MB to reach five distinct peers, which is why the mount speaks the transport itself.
The mount headers come from the same buildOvHeaders the runtime's own HTTP
path uses, so the tool surface and the recall path cannot drift on the actor
header. The protocol headers (content-type, accept, mcp-protocol-version,
mcp-session-id) are left to the transport, which derives them from the
exchange. OPENVIKING_EXTRA_HEADERS reaches the mount too, for deployments
behind an authenticating gateway.
Two consequences follow from the mount being per agent:
- The actor peer is the session's own. The bridge is mounted per root agent
with the peer that session resolved from its workspace, so a tool call carries
the same actor as that session's recall, capture, and commit. A host serving
several repositories no longer attributes every session's tools to the project
it was started in. The root mount remains as the fallback for a session that
has not started yet, and keeps the boot-time peer.
OPENVIKING_PEER_IDstill pins the actor peer explicitly, for every mount at once. rememberis not session-scoped. The server's MCPrememberstores into its own short-lived session rather than the livedsh-<session-id>stream β the same behavior the Claude Code, Codex, and Cursor integrations have. Automatic capture still records the conversation itself.
The bridge and the skill provider are mounted last in apply(), after every
lifecycle registration, so an unreachable server holds up nothing above it. Each
root agent then gets its own bridge when it is announced. Subagents get none,
for the same two reasons they get no recall: the mount list holds only ownerless
agents, and skipSubagentSessions filters them again.
Why the skill gets its own provider
skills.mjs registers a second ctx.skills provider with
includeDefaultRoots: false and bundledSkillDir pointing at skills/. DSH
reads this host-owned bundle directly rather than asking a workspace filesystem
to resolve a path outside its root. Its existing filesystem provider still
owns the project and user skill roots; the bundle does not duplicate that
catalog or override higher-priority project skills.
Configuration
OpenViking credentials use the same resolution order as the other memory plugins:
OPENVIKING_*environment variables~/.openviking/ovcli.conf~/.openviking/ov.conf
Common environment variables:
| Variable | Purpose |
|---|---|
OPENVIKING_URL / OPENVIKING_BASE_URL |
OpenViking server endpoint |
OPENVIKING_API_KEY / OPENVIKING_BEARER_TOKEN |
Bearer credential |
OPENVIKING_ACCOUNT |
Trusted-mode account |
OPENVIKING_USER |
Trusted-mode user |
OPENVIKING_PEER_ID |
Explicit actor peer; pins every mount at once |
OPENVIKING_WORKSPACE_PEER |
Derive a peer from each DSH session workspace's git identity by default; 0 sends no peer |
OPENVIKING_RECALL_PEER_SCOPE |
all for cross-workspace recall or actor for isolation |
The profile's cordis.patch.yml can also carry plugin config:
- insert:
- id: openviking-memory
name: '@logictan/dsh-openviking'
config:
endpoint: http://127.0.0.1:1933
recallTokenBudget: 2000
scoreThreshold: 0.35
captureToolResults: false
skipSubagentSessions: true
commitTokenThreshold: 20000
mcpToolCallTimeoutMs: 60000
Recall normally uses POST /api/v1/search/search with mode: "context".
recallMaxTokens (OPENVIKING_RECALL_MAX_TOKENS) sets this request's
max_tokens budget for server-assembled context. When it is unset, the plugin
omits max_tokens and uses the server's default budget.
recallLimit (OPENVIKING_RECALL_LIMIT) scales the category quotas for context
recall; it is not a strict cap on the final number of entries. When explicitly
set, it allocates at least one slot to each of the six categories: events,
entities, preferences, experiences, resources, and skills. For example,
recallLimit: 4 sends six one-slot quotas, so the result can contain more than
four entries. Lowering it does not expand the set of categories searched.
Actual results still depend on matching content, score filtering, deduplication,
and the token budget. When unset, the server's coding preset supplies the quotas.
The older size settings apply to fallback recall, not the primary context request:
recallTokenBudget(OPENVIKING_RECALL_TOKEN_BUDGET) controls the estimated token budget of the locally rendered block when both server-side context and the legacy/api/v1/search/recallendpoint are unavailable and recall falls back to raw search results.recallMaxContentChars(OPENVIKING_RECALL_MAX_CONTENT_CHARS) limits each item's content in that local fallback. It also sets the legacy/recallrequest'smax_charstomax(1000, recallMaxContentChars * recallLimit).
Behavior
agent/pre-stepretrieves with the current step input and appends a durable plugin message to that same step, including the OpenViking profile, the available-memory index, and the<available-skills>catalog on the first step of a session.agent/createdgives each root agent its own memory bridge, carrying that session's peer.session/eventcaptures user, assistant, and optionally tool-result messages without scraping a transcript.turn/endchecks the OpenViking pending-token threshold and commits when required.skipSubagentSessions: trueexcludes sessions marked withheader.origin: subagentfrom automatic profile, recall, capture, commit, and their own memory bridge; it defaults tofalse.syncTurns: falsestops every new write: no captured messages, no threshold or shutdown commit. Writes queued while the toggle was on are still replayed by the background drainer once the server recovers β they were captured with the toggle on. Profile injection and recall are unaffected; it defaults totrue.skillCatalog(defaulttrue) andskillCatalogTokenBudget(default1200;0also turns the catalog off) govern<available-skills>. The catalog comes from oneGET /api/v1/skills?node_limit=200call: the user's own skills first, then those shared underviking://agent/skillsminus any whose name the user also owns, each description cut to about 40 tokens. Its budget is separate fromprofileTokenBudget. When the descriptions do not fit, the catalog lists names only (with a... +N moretail if even the names do not all fit); when not even one name fits, it shrinks to a one-line count; with no skills, or a server without the endpoint, it is omitted.- Failed writes enter the shared OpenViking pending queue. A background drainer (default every 60s,
OPENVIKING_PENDING_DRAIN_INTERVAL_MS) probes the server health and replays the queue in-process, so a transient write failure recovers without restarting dsh; it does not consume the retry budget that session initialization spends. Those initialization replays keep consuming retries as before. tools/pre-executedenies a DSH filesystem tool (read,glob,grep,edit,write,str_replace_editor) whose path argument is aviking://URI, pointing the model at the bridgedmcp__openviking__*tools instead. Awriteoreditunder a skill directory (viking://~/skills/...,viking://user/<id>/skills/...,viking://agent/skills/...) points atmcp__openviking__add_skillinstead, which creates or replaces a whole skill from itsSKILL.mdtext. Agrepwhose pattern isviking://text still runs.tools/post-executelets abashcommand that carries aviking://URI run unchanged and attaches a notice for the model: use the bridged tools if it meant OpenViking content, or ignore the notice when the URI is intentional data such as anovargument or an HTTP payload.
Each DSH session maps to dsh-<session-id> in OpenViking. IDs that contain Windows-invalid path characters are normalized to a readable underscore form plus a stable hash, so two native IDs cannot collapse onto the same OpenViking session; already-portable IDs keep their existing mapping. Existing sessions whose native IDs require normalization start a new OpenViking session after this upgrade. Workspace-derived actor peers are resolved per session and sent on every session-specific request: the peer is the git identity of the session's workspace β the normalized origin URL ([email protected]:volcengine/OpenViking.git becomes github.com-volcengine-openviking), else the repository root path, that fallback keeping the older rule where every non-letter-or-digit character becomes -. Outside a git repository no peer is sent at all, and what is remembered there goes to the user-level space viking://user/<you>/memories. One repository therefore keeps one peer across subdirectories, worktrees, clones and machines, while a fork's different origin keeps it separate. A peer.id written in the workspace's .openviking/config.json is honored: the peer is resolved against the session's own directory, which is the only place that file can be found. OPENVIKING_PEER_ID overrides it. Memories written under the older path-derived peer stay reachable: the default recallPeerScope: all sweeps every peer under the user.
Tools
The model sees the OpenViking MCP tools under the bridge's server-qualified
names β mcp__openviking__search, mcp__openviking__read,
mcp__openviking__list, mcp__openviking__tree, mcp__openviking__grep,
mcp__openviking__glob, mcp__openviking__remember,
mcp__openviking__write, mcp__openviking__edit,
mcp__openviking__forget, mcp__openviking__add_resource,
mcp__openviking__add_skill, and the rest of whatever the connected server
advertises. The list re-syncs when the server announces a change, so a server
upgrade adds tools without a bundle release.
mcp__openviking__forget performs permanent deletion. The calling model should
use it only when the user explicitly requests deletion.
The bundle also serves the shared openviking-memory and openviking-skills
skills from skills/ through its own isolated ctx.skills provider, so the
model gets the same guidance the other integrations ship: when to search, read,
and write, and how to find, use, create, share, and migrate OpenViking skills.
Testing
npm ci # installs the exact-pinned dsh devDependencies the tests exercise
npm run check # syntax check every shipped module + package/PLUGIN_VERSION agreement
npm test # node --test *.test.mjs β runs in the repo's PR workflow
The 0.3.2 compatibility check installed the packed bundle through
dsh plugin add in isolated profiles and exercised DSH 0.1.0-rc.6,
0.1.5-rc.1, and 0.1.5-rc.2 with matching core packages. It covered Web startup
and browser loading, skill discovery/read, MCP tool calls, profile/recall
injection, user/assistant capture, resume deduplication, threshold commits, and
disposal commits. The check used a local HTTP/MCP fixture and a deterministic
model adapter on macOS with Node.js 26.5.0; it verifies harness integration, not
real-server memory extraction. The rc.2 CLI also exited cleanly on SIGTERM.
The startup failure from issue #4944 was reproduced by adding the reported
old skill packages to an rc.2 profile; removing those direct dependencies and
reinstalling the bundle restored the same integration checks. A clean rc.2
profile with the published 0.3.0 bundle did not reproduce that import error.
live-recall.test.mjs is an opt-in end-to-end gate against a real OpenViking
server: it stores a sentinel memory through a session commit, waits for
extraction, and asserts recall returns that sentinel β the property no stub
can certify. Enable it with OPENVIKING_E2E=1 plus the normal credential
chain; it skips otherwise (including in CI until a server secret exists).