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

Capability	Plane	Scope
Automatic capture — session/event (write-behind) → session/flush (durability checkpoint) → batchAddMessages + async commitSession (server-side LLM distillation into preferences/entities/events)	Host (memory-openviking row)	Every session, every preset
Memory service ctx.memory — write / recall / search / profile / forget / commit / health	Host	Every preset's rows
Thin tools — memory_write / memory_recall / memory_search / memory_profile / memory_forget	Global registration (tool-memory row)	Every agent (visible unless a preset explicitly restricts global tools)
Automatic <memory_profile> prompt injection — session working-memory overview + cross-session recalled preferences/entities/events, 1200-char budget, 5-min cache, sync provider with async refresh (never blocks prompt assembly)	Global (system-prompt section)	Every turn of every session
Experience closed-loop (verified live) — OpenViking Agent Evolution: experiences (reusable insights) / trajectories (operation contracts) / cases extraction, used() reuse reporting (→ active_count retrieval ranking), 5-state outcome distribution	OpenViking server + adapter	Account-wide (hot-reload switch)
Project targeting — strict k=v tags (project=…) via setTags + search {tags}	Adapter	Per-project recall
Session → peer isolation — per-session actorPeerId (X-OpenViking-Actor-Peer) + peerScope recall control	Host	Production multi-tenant mode (dev-mode OpenViking 0.4.13 has no peers — verified)

"Passive tool calls" become "automatic session memory": the model never has to ask to remember — capture happens on the durable flush checkpoint, 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 (v0.3 target)

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 (all 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).
• 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.
• 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.

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

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}, recall.{maxTokens,scoreThreshold,cacheTtlMs,purpose}, timeoutMs.

tool-memory row config: section.{enabled,maxChars,minScore,cacheTtlMs,maxTokens, includeSessionOverview,query}.

Evaluation

scripts/memory-eval/ (in the ADR-linked repo) provides a LoCoMo-style benchmark: synthetic multi-turn dataset → SDK replay with periodic commits → context-mode recall scoring (fact-level recall, same/cross-session/temporal) → session-level token-compression measurement (DSH token-meter heuristic). Measured on this setup: 91.7% overall recall (short sessions), 77.8% (40-turn sessions), 58.9% token compression per long session.

License

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