OpenViking Memory for DeepSeek Harness
An installable DeepSeek Harness bundle that adds OpenViking auto-recall, session capture, viking:// URI protection, and model-invocable memory tools.
Requirements
@deepseek-ai/dsh 0.1.0-rc.6- Node.js
^22.19.0 or >=24
- A reachable OpenViking server
The bundle has no runtime npm dependencies. Its tool and message structures
come from the DSH constructors (defineTool from @deepseek-ai/dsh-tools,
createUserMessage from @deepseek-ai/dsh-llm) behind exact-pinned
peerDependencies that DSH exposes through its profile fallback at boot time, so
the definitions track DSH's contracts instead of hand-built object shapes.
It is tested against 0.1.0-rc.6; install that exact DSH release because
prerelease package dist-tags are not synchronized across the package family.
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', … }).
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.
Install
From the OpenViking repository:
dsh plugin --profile default add ./examples/dsh-memory-plugin
Or install the published package:
dsh plugin --profile default add @ajchemist/openviking-dsh-memory-plugin
Confirm that the profile includes the bundle:
dsh --profile default --dump-config
The package patch mounts the runtime inside a Cordis group with an isolated openvikingMemory service.
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_AGENT | Agent namespace identity sent as X-OpenViking-Agent |
OPENVIKING_PEER_ID | Explicit actor peer |
OPENVIKING_WORKSPACE_PEER | Derive a peer from each DSH session workspace by default |
OPENVIKING_RECALL_PEER_SCOPE | all for cross-workspace recall or actor for isolation |
The patch can also carry plugin config:
- insert:
- id: openviking-memory
name: '@deepseek-ai/cordis-plugin-group'
group: true
isolate:
openvikingMemory: true
config:
- id: openviking-memory-runtime
name: '@ajchemist/openviking-dsh-memory-plugin'
config:
endpoint: http://127.0.0.1:1933
agent: dsh
recallTokenBudget: 2000
scoreThreshold: 0.35
captureToolResults: false
commitTokenThreshold: 20000
Behavior
agent/session-start injects the OpenViking profile and available-memory index through agent.inject().agent/pre-step retrieves with the current step input and appends a durable plugin message to that same step.session/event captures user, assistant, and optionally tool-result messages without scraping a transcript.turn/end checks the OpenViking pending-token threshold and commits when required.- Failed writes enter the shared OpenViking pending queue for replay at the next session start.
tools/pre-execute blocks DSH filesystem and shell tools from treating viking:// URIs as local paths.
Each DSH session maps to dsh-<session-id> in OpenViking. Workspace-derived actor peers are resolved per session and sent on every session-specific request.
Tools
The bundle registers:
viking_searchviking_readviking_browseviking_rememberviking_forgetviking_add_resourceviking_archive_expand
viking_forget performs permanent deletion. The calling model should use it only when the user explicitly requests deletion.
Testing
npm ci # installs the exact-pinned dsh devDependencies the tests exercise
npm run check # manifest, bundle contract, module syntax, agent-header smoke check
npm test # behavioral tests — runs in the repo's PR workflow
npm run verify # check + test + npm pack --dry-run; required before publishing
The release workflow runs npm run verify before it can publish. It then uses npm
Trusted Publishing from GitHub Actions (OIDC) and only publishes versions absent
from the registry.
Updating a local DSH profile from a verified release
After a release is published, update the local profile with the version you intend
to install:
node scripts/update-dsh-profile.mjs 0.1.1
The updater verifies that the exact version is in npm's registry, has integrity
metadata and npm provenance, backs up the profile manifest, installs the exact
version, and verifies the installed package version. It never installs an
unpublished local checkout.
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).
