@openviking/dsh-memory-plugin 0.1.0

package/README.md

@@ -0,0 +1,129 @@
+# 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:
+
+```bash
+dsh plugin --profile default add ./examples/dsh-memory-plugin
+```
+
+Or install the published package:
+
+```bash
+dsh plugin --profile default add @openviking/dsh-memory-plugin
+```
+
+Confirm that the profile includes the bundle:
+
+```bash
+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:
+
+1. `OPENVIKING_*` environment variables
+2. `~/.openviking/ovcli.conf`
+3. `~/.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 |
+| `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:
+
+```yaml
+- insert:
+    - id: openviking-memory
+      name: '@deepseek-ai/cordis-plugin-group'
+      group: true
+      isolate:
+        openvikingMemory: true
+      config:
+        - id: openviking-memory-runtime
+          name: '@openviking/dsh-memory-plugin'
+          config:
+            endpoint: http://127.0.0.1:1933
+            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_search`
+- `viking_read`
+- `viking_browse`
+- `viking_remember`
+- `viking_forget`
+- `viking_add_resource`
+- `viking_archive_expand`
+
+`viking_forget` performs permanent deletion. The calling model should use it only when the user explicitly requests deletion.
+
+## Testing
+
+```bash
+npm ci          # installs the exact-pinned dsh devDependencies the tests exercise
+npm test        # node --test *.test.mjs — runs in the repo's PR workflow
+```
+
+`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).

package/capture.mjs

@@ -0,0 +1,104 @@
+import {
+  extractPartsFromPayload,
+  extractTextFromPayload,
+  shouldCaptureText,
+} from "./shared/capture-utils.mjs";
+
+export const OPENVIKING_PLUGIN_SOURCE = "openviking-memory";
+
+export function captureEvent(event, config, toolNames = new Map()) {
+  if (!event || typeof event !== "object") return null;
+  if (event.type === "tool/call") {
+    if (config.captureToolResults === true) {
+      toolNames.set(String(event.data.callId), event.data.name);
+    }
+    return null;
+  }
+
+  const message = eventMessage(event);
+  if (!message) return null;
+  const toolCallId = event.type === "tool/result"
+    ? String(message.source?.callId || message.content?.[0]?.toolCallId || "")
+    : "";
+  try {
+    return captureMessage(event, message, config, toolNames);
+  } finally {
+    if (toolCallId) toolNames.delete(toolCallId);
+  }
+}
+
+function captureMessage(event, message, config, toolNames) {
+  // Whitelist by source: plugin-injected user messages (this plugin's recall
+  // blocks, time-context snapshots, any other plugin's context) are model
+  // input, not human input — mirroring them would launder synthetic text
+  // into memory as if a person said it.
+  if (message.source?.kind === "plugin") return null;
+  if (message.role === "assistant" && config.captureAssistantTurns === false) {
+    return null;
+  }
+  if (message.source?.kind === "tool" && config.captureToolResults !== true) {
+    return null;
+  }
+
+  const role = message.role === "assistant" ? "assistant" : "user";
+  const toolNameById = Object.fromEntries(toolNames);
+  const rawText = extractTextFromPayload(message, {
+    toolMaxChars: config.captureToolMaxChars,
+  });
+  const parts = extractPartsFromPayload(message, {
+    toolMaxChars: config.captureToolMaxChars,
+    toolNameById,
+  });
+  const decision = shouldCaptureText(rawText, role, config);
+  const structuredParts = parts.filter(part => part?.type !== "text");
+  if (!decision.shouldCapture && structuredParts.length === 0) return null;
+
+  const hasTextPart = parts.some(part => part?.type === "text");
+  const bodyParts = [
+    ...(hasTextPart && decision.shouldCapture && decision.text
+      ? [{ type: "text", text: decision.text }]
+      : []),
+    ...structuredParts,
+  ];
+  const payload = bodyParts.length > 0
+    ? { role, parts: bodyParts }
+    : { role, content: decision.text };
+  const createdAt = eventCreatedAt(event);
+  if (createdAt) payload.created_at = createdAt;
+  if (config.peerId) payload.peer_id = config.peerId;
+  return payload;
+}
+
+export function promptText(messages) {
+  return (messages || [])
+    .filter(message => !(
+      message?.source?.kind === "plugin"
+      && message.source.plugin === OPENVIKING_PLUGIN_SOURCE
+    ))
+    .map(message => extractTextFromPayload(message))
+    .filter(Boolean)
+    .join("\n\n")
+    .trim();
+}
+
+function eventMessage(event) {
+  switch (event.type) {
+    case "user/message":
+      return event.data;
+    case "assistant/message":
+    case "tool/result":
+      return event.data?.message;
+    default:
+      return null;
+  }
+}
+
+function eventCreatedAt(event) {
+  const time = Number(event?.time);
+  if (!Number.isFinite(time) || time < 0) return "";
+  try {
+    return new Date(time).toISOString();
+  } catch {
+    return "";
+  }
+}

package/client.mjs

@@ -0,0 +1,206 @@
+export class OpenVikingClient {
+  constructor(config) {
+    this.config = config;
+    this.connected = false;
+  }
+
+  headers(options = {}) {
+    const headers = { "Content-Type": "application/json" };
+    if (this.config.apiKey) headers.Authorization = `Bearer ${this.config.apiKey}`;
+    if (this.config.account) headers["X-OpenViking-Account"] = this.config.account;
+    if (this.config.user) headers["X-OpenViking-User"] = this.config.user;
+    const actorPeerId = options.actorPeerId ?? this.config.peerId;
+    if (actorPeerId) headers["X-OpenViking-Actor-Peer"] = actorPeerId;
+    if (this.config.userAgent) headers["User-Agent"] = this.config.userAgent;
+    return headers;
+  }
+
+  async fetchJSON(path, init = {}, options = {}) {
+    const timeoutMs = options.timeoutMs ?? this.config.requestTimeoutMs;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+      const response = await fetch(`${this.config.endpoint}${path}`, {
+        ...init,
+        headers: {
+          ...this.headers(options),
+          ...(init.headers || {}),
+        },
+        signal: controller.signal,
+      });
+      const body = await response.json().catch(() => ({}));
+      const traceId = body?.result?.trace_id
+        || body?.error?.trace_id
+        || body?.trace_id
+        || undefined;
+      if (!response.ok || body?.status === "error") {
+        return {
+          ok: false,
+          result: null,
+          status: response.status,
+          error: body?.error || { message: `HTTP ${response.status}` },
+          traceId,
+        };
+      }
+      return {
+        ok: true,
+        result: body?.result ?? body,
+        status: response.status,
+        traceId,
+      };
+    } catch (error) {
+      return {
+        ok: false,
+        result: null,
+        status: 0,
+        error: { message: error instanceof Error ? error.message : String(error) },
+      };
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  async health() {
+    return (await this.healthResult()).ok;
+  }
+
+  async healthResult() {
+    const response = await this.fetchJSON("/health", {}, { timeoutMs: 5000 });
+    this.connected = response.ok;
+    return response;
+  }
+
+  async ensureSession(sessionId, actorPeerId) {
+    const response = await this.ensureSessionResult(sessionId, actorPeerId);
+    return response.ok
+      || (response.status === 409 && response.error?.code === "ALREADY_EXISTS");
+  }
+
+  async ensureSessionResult(sessionId, actorPeerId) {
+    const response = await this.fetchJSON("/api/v1/sessions", {
+      method: "POST",
+      body: JSON.stringify({ session_id: sessionId }),
+    }, { actorPeerId });
+    return response;
+  }
+
+  async getSession(sessionId, actorPeerId) {
+    const response = await this.fetchJSON(
+      `/api/v1/sessions/${encodeURIComponent(sessionId)}`,
+      {},
+      { timeoutMs: 5000, actorPeerId },
+    );
+    return response.ok ? response.result : null;
+  }
+
+  async getSessionArchive(sessionId, archiveId, actorPeerId) {
+    const response = await this.fetchJSON(
+      `/api/v1/sessions/${encodeURIComponent(sessionId)}/archives/${encodeURIComponent(archiveId)}`,
+      {},
+      { actorPeerId },
+    );
+    return response.ok ? response.result : null;
+  }
+
+  async addMessage(sessionId, payload, actorPeerId) {
+    return this.fetchJSON(
+      `/api/v1/sessions/${encodeURIComponent(sessionId)}/messages`,
+      {
+        method: "POST",
+        body: JSON.stringify(payload),
+      },
+      { actorPeerId },
+    );
+  }
+
+  async commitSession(sessionId, actorPeerId, options = {}) {
+    return this.fetchJSON(
+      `/api/v1/sessions/${encodeURIComponent(sessionId)}/commit`,
+      {
+        method: "POST",
+        body: JSON.stringify({ keep_recent_count: this.config.commitKeepRecentCount }),
+      },
+      { timeoutMs: options.timeoutMs ?? 30000, actorPeerId },
+    );
+  }
+
+  async find(query, options = {}) {
+    const body = { query };
+    if (options.targetUri) body.target_uri = options.targetUri;
+    if (options.limit) body.limit = options.limit;
+    if (options.scoreThreshold !== undefined) body.score_threshold = options.scoreThreshold;
+    const response = await this.fetchJSON("/api/v1/search/find", {
+      method: "POST",
+      body: JSON.stringify(body),
+    }, { actorPeerId: options.actorPeerId });
+    if (!response.ok || !response.result) return [];
+
+    const results = [];
+    for (const bucket of ["memories", "resources", "skills"]) {
+      const entries = response.result[bucket];
+      if (!Array.isArray(entries)) continue;
+      for (const entry of entries) {
+        results.push({
+          uri: entry?.uri || "",
+          contextType: entry?.context_type
+            || (bucket === "memories" ? "memory" : bucket === "skills" ? "skill" : "resource"),
+          score: Number(entry?.score || 0),
+          abstract: entry?.abstract || "",
+          overview: entry?.overview || null,
+        });
+      }
+    }
+    return results;
+  }
+
+  async read(uri, level, actorPeerId) {
+    const endpoint = level === "abstract"
+      ? "abstract"
+      : level === "overview"
+        ? "overview"
+        : "read";
+    const response = await this.fetchJSON(
+      `/api/v1/content/${endpoint}?uri=${encodeURIComponent(uri)}`,
+      {},
+      { actorPeerId },
+    );
+    return response.ok ? response.result : null;
+  }
+
+  async list(uri, actorPeerId) {
+    const response = await this.fetchJSON(
+      `/api/v1/fs/ls?uri=${encodeURIComponent(uri)}&output=original`,
+      {},
+      { actorPeerId },
+    );
+    return response.ok && Array.isArray(response.result) ? response.result : [];
+  }
+
+  async stat(uri, actorPeerId) {
+    const response = await this.fetchJSON(
+      `/api/v1/fs/stat?uri=${encodeURIComponent(uri)}`,
+      {},
+      { actorPeerId },
+    );
+    return response.ok ? response.result : null;
+  }
+
+  async forget(uri, recursive = false, actorPeerId) {
+    const response = await this.fetchJSON(
+      `/api/v1/fs?uri=${encodeURIComponent(uri)}&recursive=${recursive}`,
+      { method: "DELETE" },
+      { actorPeerId },
+    );
+    return response.ok;
+  }
+
+  async addResource(path, reason, actorPeerId) {
+    const body = { path };
+    if (reason) body.reason = reason;
+    const response = await this.fetchJSON("/api/v1/resources", {
+      method: "POST",
+      body: JSON.stringify(body),
+    }, { timeoutMs: 30000, actorPeerId });
+    return response.ok ? response.result : null;
+  }
+}

package/config.mjs

@@ -0,0 +1,161 @@
+import { buildUserAgent, resolveOpenVikingCredentials } from "./shared/credentials.mjs";
+import { resolveEffectivePeerId } from "./shared/workspace-peer.mjs";
+
+export const PLUGIN_VERSION = "0.1.0";
+
+const DEFAULT_CONFIG = Object.freeze({
+  endpoint: "http://127.0.0.1:1933",
+  apiKey: "",
+  account: "",
+  user: "",
+  peerId: "",
+  userAgent: "",
+  workspacePeer: true,
+  recallPeerScope: "all",
+  recallQueryExpansion: "auto",
+  recallQueryExpansionConfigured: false,
+  syncTurns: true,
+  recallTokenBudget: 2000,
+  recallMaxContentChars: 500,
+  recallPreferAbstract: true,
+  recallLimit: 10,
+  recallLimitConfigured: false,
+  scoreThreshold: 0.35,
+  minQueryLength: 3,
+  profileTokenBudget: 10000,
+  commitTokenThreshold: 20000,
+  commitKeepRecentCount: 10,
+  captureToolResults: false,
+  captureMode: "semantic",
+  captureMaxLength: 24000,
+  captureToolMaxChars: 1000000,
+  captureAssistantTurns: true,
+  requestTimeoutMs: 10000,
+});
+
+export function resolveConfig(input = {}, env = process.env, cwd = process.cwd()) {
+  const credentials = resolveOpenVikingCredentials(env);
+  const explicitPeerId = input.peerId || credentials.peerId;
+  const config = {
+    ...DEFAULT_CONFIG,
+    ...input,
+    endpoint: input.endpoint || credentials.baseUrl || DEFAULT_CONFIG.endpoint,
+    apiKey: input.apiKey || credentials.apiKey,
+    account: input.account || credentials.account,
+    user: input.user || credentials.user,
+    peerId: explicitPeerId,
+    explicitPeerId,
+    userAgent: buildUserAgent("dsh", PLUGIN_VERSION),
+    recallLimitConfigured: Object.prototype.hasOwnProperty.call(input, "recallLimit"),
+    recallQueryExpansionConfigured: Object.prototype.hasOwnProperty.call(input, "recallQueryExpansion"),
+  };
+
+  if (env.OPENVIKING_WORKSPACE_PEER !== undefined) {
+    config.workspacePeer = environmentBoolean(
+      env.OPENVIKING_WORKSPACE_PEER,
+      config.workspacePeer,
+    );
+  }
+  if (env.OPENVIKING_RECALL_PEER_SCOPE) {
+    config.recallPeerScope = env.OPENVIKING_RECALL_PEER_SCOPE;
+  }
+  if (env.OPENVIKING_RECALL_QUERY_EXPANSION) {
+    config.recallQueryExpansion = env.OPENVIKING_RECALL_QUERY_EXPANSION;
+    config.recallQueryExpansionConfigured = true;
+  }
+  if (env.OPENVIKING_RECALL_LIMIT) {
+    config.recallLimit = env.OPENVIKING_RECALL_LIMIT;
+    config.recallLimitConfigured = true;
+  }
+
+  config.endpoint = String(config.endpoint || DEFAULT_CONFIG.endpoint).replace(/\/+$/, "");
+  config.workspacePeer = config.workspacePeer !== false;
+  config.peerId = resolveEffectivePeerId({ cfg: config, cwd }).peerId;
+  config.recallPeerScope = config.recallPeerScope === "actor" ? "actor" : "all";
+  config.recallQueryExpansion = config.recallQueryExpansion === "off" ? "off" : "auto";
+  config.recallLimit = clampInteger(config.recallLimit, 1, 50, DEFAULT_CONFIG.recallLimit);
+  config.recallMaxContentChars = clampInteger(
+    config.recallMaxContentChars,
+    100,
+    5000,
+    DEFAULT_CONFIG.recallMaxContentChars,
+  );
+  config.recallTokenBudget = clampInteger(
+    config.recallTokenBudget,
+    200,
+    50000,
+    DEFAULT_CONFIG.recallTokenBudget,
+  );
+  config.scoreThreshold = clampNumber(
+    config.scoreThreshold,
+    0,
+    1,
+    DEFAULT_CONFIG.scoreThreshold,
+  );
+  config.minQueryLength = clampInteger(
+    config.minQueryLength,
+    1,
+    64,
+    DEFAULT_CONFIG.minQueryLength,
+  );
+  config.profileTokenBudget = clampInteger(
+    config.profileTokenBudget,
+    500,
+    50000,
+    DEFAULT_CONFIG.profileTokenBudget,
+  );
+  config.commitTokenThreshold = clampInteger(
+    config.commitTokenThreshold,
+    1000,
+    1000000,
+    DEFAULT_CONFIG.commitTokenThreshold,
+  );
+  config.commitKeepRecentCount = clampInteger(
+    config.commitKeepRecentCount,
+    0,
+    1000,
+    DEFAULT_CONFIG.commitKeepRecentCount,
+  );
+  config.captureMaxLength = clampInteger(
+    config.captureMaxLength,
+    200,
+    100000,
+    DEFAULT_CONFIG.captureMaxLength,
+  );
+  config.captureToolMaxChars = clampInteger(
+    config.captureToolMaxChars,
+    200,
+    1000000,
+    DEFAULT_CONFIG.captureToolMaxChars,
+  );
+  config.requestTimeoutMs = clampInteger(
+    config.requestTimeoutMs,
+    1000,
+    120000,
+    DEFAULT_CONFIG.requestTimeoutMs,
+  );
+  config.captureMode = config.captureMode === "keyword" ? "keyword" : "semantic";
+  config.syncTurns = config.syncTurns !== false;
+  config.captureAssistantTurns = config.captureAssistantTurns !== false;
+  config.captureToolResults = config.captureToolResults === true;
+  return config;
+}
+
+function environmentBoolean(value, fallback) {
+  const normalized = String(value || "").trim().toLowerCase();
+  if (["0", "false", "no", "off"].includes(normalized)) return false;
+  if (["1", "true", "yes", "on"].includes(normalized)) return true;
+  return fallback;
+}
+
+function clampInteger(value, minimum, maximum, fallback) {
+  const number = Math.round(Number(value));
+  if (!Number.isFinite(number)) return fallback;
+  return Math.max(minimum, Math.min(maximum, number));
+}
+
+function clampNumber(value, minimum, maximum, fallback) {
+  const number = Number(value);
+  if (!Number.isFinite(number)) return fallback;
+  return Math.max(minimum, Math.min(maximum, number));
+}

package/cordis.patch.yml

@@ -0,0 +1,9 @@
+- insert:
+    - id: openviking-memory
+      name: '@deepseek-ai/cordis-plugin-group'
+      group: true
+      isolate:
+        openvikingMemory: true
+      config:
+        - id: openviking-memory-runtime
+          name: '@openviking/dsh-memory-plugin'

package/index.mjs

@@ -0,0 +1,56 @@
+import { OpenVikingClient } from "./client.mjs";
+import { resolveConfig } from "./config.mjs";
+import { injectStartupProfile } from "./lifecycle.mjs";
+import { OpenVikingRuntime } from "./runtime.mjs";
+import { registerOpenVikingTools } from "./tools.mjs";
+import { guardVikingUri } from "./uri-guard.mjs";
+
+export const name = "openviking-memory";
+export const inject = ["agents", "sessions", "tools"];
+
+export function apply(ctx, input = {}) {
+  const config = resolveConfig(input);
+  const client = new OpenVikingClient(config);
+  const runtime = new OpenVikingRuntime(client, config, ctx.logger);
+  ctx.provide("openvikingMemory", runtime);
+  ctx.effect(
+    () => () => runtime.disposeAll(),
+    "openvikingMemory.disposeAll()",
+  );
+
+  registerOpenVikingTools(ctx, client, runtime);
+
+  ctx.on("agent/session-start", ({ agent }) => {
+    agent.ctx.effect(
+      () => () => runtime.dispose(agent.session),
+      "openvikingMemory.disposeSession()",
+    );
+    return injectStartupProfile(agent, runtime);
+  });
+
+  // prepend: downstream waterfall listeners run first, so this plugin sees
+  // the final claimed batch and appends after every other contributor.
+  ctx.on("agent/pre-step", async ({ agent, messages, signal }, next) => {
+    const decision = await next();
+    if (decision.kind !== "enter" || signal.aborted) return decision;
+    const profile = await runtime.profileMessage(agent);
+    if (signal.aborted) return decision;
+    const recall = await runtime.recallMessage(agent, decision.messages);
+    if (signal.aborted) return decision;
+    const additions = [profile, recall].filter(Boolean);
+    return additions.length > 0
+      ? { kind: "enter", messages: [...decision.messages, ...additions] }
+      : decision;
+  }, { prepend: true });
+
+  ctx.on("session/event", (session, event) => {
+    runtime.capture(session, event);
+    runtime.maybeCommit(session, event);
+  });
+
+  ctx.on("session/flush", async session => {
+    await runtime.flush(session);
+  });
+
+  ctx.on("tools/pre-execute", guardVikingUri);
+}

package/lifecycle.mjs

@@ -0,0 +1,8 @@
+export async function injectStartupProfile(agent, runtime) {
+  await runtime.initialize(agent);
+  if (agent.status !== "idle") return false;
+  const profile = await runtime.profileMessage(agent);
+  if (!profile) return false;
+  agent.inject(profile);
+  return true;
+}