dsh-memory-openviking

Native long-term memory for DeepSeek Harness, backed by OpenViking ("Self-evolving Context Database for AI Agents"). Zero self-built plugin frameworks — the integration rides DSH's native Cordis composition planes and OpenViking's HTTP/MCP surface.

dsh-plugin · Global long-term memory: automatic capture, experience/trajectory closed-loop, memory tools and profile injection for every agent preset — no dedicated "memory mode".

What you get

"Passive tool calls" become "automatic session memory": the model never has to ask to remember — capture happens on the flush checkpoint (with retry, so it survives a server restart window), the next session starts with a profile already in its system prompt, and experience reuse is tracked and fed back into retrieval ranking.

Architecture

┌─ DeepSeek Harness (Cordis runtime) ────────────────────────────────┐
│  host composition ($DSH_HOME/cordis.patch.yml)                    │
│    memory-openviking  → `memory` service (capture + recall)       │
│    tool-memory        → memory_* tools + <memory_profile> section │
│  agent plane (ANY preset)  → tools & section inherited globally   │
│  global skill root ~/.dsh/skills/ → memory-guide usage skill      │
└───────────────┬───────────────────────────────────────────────────┘
                │ HTTP (dev mode: no auth)
┌───────────────▼───────────────────────────────────────────────────┐
│ OpenViking server (127.0.0.1:18770)                               │
│  viking://user/default/memories/{preferences,entities,events,     │
│    experiences,trajectories,cases,tools,skills,...}               │
│  viking://user/default/sessions/dsh-<session>/ (archives + tasks) │
└───────────────────────────────────────────────────────────────────┘

Generic direction

The research docs in docs/ lay out the evolution to a backend-agnostic memory hub mirroring DSH's own dsh-storage pattern: a @deepseek-ai/dsh-memory interface package (Memory hub + MemoryBackend contract covering write/read/forget/tracking), with this repo's OpenViking client as one adapter implementation — Mem0/Zep/etc. plug in the same way. See docs/dsh-generic-memory-design.md.

Key implementation facts (verified live against OpenViking 0.4.13 — see docs/sdk-0.1.0-live-notes.md):

• Write path uses the @openviking/sdk sessions API (getSession(autoCreate) → batchAddMessages → commitSession, async server-side extraction ~10-30s). Since v0.4.0 the adapter re-ensures the session before every batch/commit, so a server restart can never orphan a batch on a missing session.
• Recall path uses raw POST /api/v1/search/search {mode:"context"} — the SDK's find/search (list mode) cannot return extracted fact leaves; context mode is the modern equivalent of the deprecated /api/v1/search/recall. Context mode accepts tags filtering (verified live); v0.4.0 fixed the client dropping the tags parameter.
• Commit throttling: commitIntervalMessages (16) or commitIntervalMs (60s) — keeps the server extraction queue from flooding on chatty sessions.

Install

# 1. Copy/install both packages so the DSH loader resolves them (e.g. into the
#    web profile's node_modules), then add two rows to $DSH_HOME/cordis.patch.yml:
- id: memory-openviking
  name: '@deepseek-ai/dsh-memory-openviking'
- id: tool-memory
  name: '@deepseek-ai/dsh-tool-memory'
# 2. OpenViking must be up BEFORE DSH starts (http://127.0.0.1:18770).
# 3. Restart DSH.

The deployment scripts (scripts/dsh-*.ps1) cover install, source-link (junction, so source edits reach the running DSH without re-copying), sync, restart, and OpenViking autostart.

Both packages are plain ESM, zero build step, node --test unit tests with an injected fake fetch (no live server needed) — 72 tests across the two packages:

npm install                 # workspace root
node --test packages/*/test/

Configuration

memory-openviking row config (all optional): baseUrl (default http://127.0.0.1:18770), apiKey/account/user (production multi-tenant), peerPerSession (false; production), peerScope (all|actor), capture.{toolResults,nonUserSources, subagentSessions,flushThresholdBytes,commitIntervalMessages,commitIntervalMs,keepRecentMessages, maxBufferBytes,flushTimeoutMs,retryMaxAttempts,retryBaseDelayMs,retryMaxDelayMs}, recall.{maxTokens,scoreThreshold,cacheTtlMs,purpose}, timeoutMs, deadLetterDir.

tool-memory row config: section.{enabled,maxChars,minScore,cacheTtlMs,maxTokens, includeSessionOverview,query} and dynamic.{enabled,maxTokens,minScore,maxEntries, inputMaxChars,minInputChars,projectTagPrefix}.

Multi-tenant deployments

With no account/user and peerPerSession: false, peerScope: 'all', every DSH session shares one OpenViking actor — memories leak across users. The service logs a warning at startup in that combination. For multi-user deployments set account/user, peerPerSession: true and peerScope: 'actor'.

Evaluation

scripts/memory-eval/ provides a LoCoMo-style benchmark with three layers:

• run-eval.mjs — live OpenViking retrieval quality: synthetic multi-turn dataset (with shared-token cross-session distractors) → SDK replay with periodic commits → context-mode recall scoring. Strict scoring is the headline: a fact hits only when ALL its stable tokens (>= 2 per fact, guaranteed by the dataset) appear in ONE recalled entry; lenient scoring (the old any-token criterion) is reported for comparison. Also MRR and precision@5. This measures the server, not the plugin.
• pipeline-check.mjs — offline, replays the same dataset through the REAL plugin MemoryService (fake transport): write-behind, dedup, byte-threshold drains, session re-ensure, keepRecent commits, retain-on-failure retry, final commit on disposal, state reclamation.
• token-eval.mjs — two separated numbers: archival storage compression (storage-side) and end-to-end per-request prompt overhead (real tool-schema measurement + profile estimate + measured injected-block tokens).

See scripts/memory-eval/README.md and the docs/ evaluation notes for the latest numbers and their exact caveats.

License

MIT (packages). OpenViking server is AGPLv3 — this integration talks to it over HTTP only, never embeds or links server code.