@openviking/openclaw-plugin 2026.5.8

package/install-manifest.json

@@ -0,0 +1,47 @@
+{
+  "manifestVersion": "1.0",
+  "pluginVersion": "2026.5.8",
+  "plugin": {
+    "id": "openviking",
+    "kind": "context-engine",
+    "slot": "contextEngine"
+  },
+  "files": {
+    "required": [
+      "index.ts",
+      "config.ts",
+      "context-engine.ts",
+      "auto-recall.ts",
+      "client.ts",
+      "process-manager.ts",
+      "memory-ranking.ts",
+      "text-utils.ts",
+      "tool-call-id.ts",
+      "session-transcript-repair.ts",
+      "runtime-utils.ts",
+      "commands/setup.ts",
+      "tsconfig.json",
+      "tsconfig.build.json",
+      "package.json",
+      "openclaw.plugin.json"
+    ],
+    "optional": [
+      "package-lock.json",
+      ".gitignore",
+      "skills/install-openviking-memory/SKILL.md",
+      "INSTALL-AGENT.md"
+    ]
+  },
+  "npm": {
+    "install": true,
+    "omitDev": true,
+    "build": true,
+    "buildMinOpenclawVersion": "2026.5.3",
+    "buildScript": "build",
+    "pruneAfterBuild": true
+  },
+  "compatibility": {
+    "minOpenclawVersion": "2026.4.8",
+    "minOpenvikingVersion": "0.2.9"
+  }
+}

package/memory-ranking.ts

@@ -0,0 +1,267 @@
+import type { FindResultItem } from "./client.js";
+
+export function clampScore(value: number | undefined): number {
+  if (typeof value !== "number" || Number.isNaN(value)) {
+    return 0;
+  }
+  return Math.max(0, Math.min(1, value));
+}
+
+function normalizeDedupeText(text: string): string {
+  return text.toLowerCase().replace(/\s+/g, " ").trim();
+}
+
+function isEventOrCaseMemory(item: FindResultItem): boolean {
+  const category = (item.category ?? "").toLowerCase();
+  const uri = item.uri.toLowerCase();
+  return (
+    category === "events" ||
+    category === "cases" ||
+    uri.includes("/events/") ||
+    uri.includes("/cases/")
+  );
+}
+
+function getMemoryDedupeKey(item: FindResultItem): string {
+  const abstract = normalizeDedupeText(item.abstract ?? item.overview ?? "");
+  const category = (item.category ?? "").toLowerCase() || "unknown";
+  if (abstract && !isEventOrCaseMemory(item)) {
+    return `abstract:${category}:${abstract}`;
+  }
+  return `uri:${item.uri}`;
+}
+
+export function postProcessMemories(
+  items: FindResultItem[],
+  options: {
+    limit: number;
+    scoreThreshold: number;
+    leafOnly?: boolean;
+  },
+): FindResultItem[] {
+  const deduped: FindResultItem[] = [];
+  const seen = new Set<string>();
+  const sorted = [...items].sort((a, b) => clampScore(b.score) - clampScore(a.score));
+  for (const item of sorted) {
+    if (options.leafOnly && item.level !== 2) {
+      continue;
+    }
+    if (clampScore(item.score) < options.scoreThreshold) {
+      continue;
+    }
+    const key = getMemoryDedupeKey(item);
+    if (seen.has(key)) {
+      continue;
+    }
+    seen.add(key);
+    deduped.push(item);
+    if (deduped.length >= options.limit) {
+      break;
+    }
+  }
+  return deduped;
+}
+
+export function formatMemoryLines(items: FindResultItem[]): string {
+  return items
+    .map((item, index) => {
+      const score = clampScore(item.score);
+      const abstract = item.abstract?.trim() || item.overview?.trim() || item.uri;
+      const category = item.category ?? "memory";
+      return `${index + 1}. [${category}] ${abstract} (${(score * 100).toFixed(0)}%)`;
+    })
+    .join("\n");
+}
+
+export function trimForLog(value: string, limit = 260): string {
+  const normalized = value.trim();
+  if (normalized.length <= limit) {
+    return normalized;
+  }
+  return `${normalized.slice(0, limit)}...`;
+}
+
+export function toJsonLog(value: unknown, maxLen = 6000): string {
+  try {
+    const json = JSON.stringify(value);
+    if (json.length <= maxLen) {
+      return json;
+    }
+    return JSON.stringify({
+      truncated: true,
+      length: json.length,
+      preview: `${json.slice(0, maxLen)}...`,
+    });
+  } catch {
+    return JSON.stringify({ error: "stringify_failed" });
+  }
+}
+
+export function summarizeInjectionMemories(items: FindResultItem[]): Array<Record<string, unknown>> {
+  return items.map((item) => ({
+    uri: item.uri,
+    category: item.category ?? null,
+    abstract: trimForLog(item.abstract?.trim() || item.overview?.trim() || item.uri, 180),
+    score: clampScore(item.score),
+    is_leaf: item.level === 2,
+  }));
+}
+
+export function summarizeExtractedMemories(
+  items: Array<Record<string, unknown>>,
+): Array<Record<string, unknown>> {
+  return items.slice(0, 10).map((item) => {
+    const abstractRaw =
+      typeof item.abstract === "string"
+        ? item.abstract
+        : typeof item.overview === "string"
+          ? item.overview
+          : typeof item.title === "string"
+            ? item.title
+            : "";
+    return {
+      uri: typeof item.uri === "string" ? item.uri : null,
+      category: typeof item.category === "string" ? item.category : null,
+      abstract: trimForLog(abstractRaw, 180),
+      is_leaf: item.level === 2,
+    };
+  });
+}
+
+function isPreferencesMemory(item: FindResultItem): boolean {
+  return (
+    item.category === "preferences" ||
+    item.uri.includes("/preferences/") ||
+    item.uri.endsWith("/preferences")
+  );
+}
+
+function isEventMemory(item: FindResultItem): boolean {
+  const category = (item.category ?? "").toLowerCase();
+  return category === "events" || item.uri.includes("/events/");
+}
+
+function isLeafLikeMemory(item: FindResultItem): boolean {
+  return item.level === 2;
+}
+
+const PREFERENCE_QUERY_RE = /prefer|preference|favorite|favourite|like|偏好|喜欢|爱好|更倾向/i;
+const TEMPORAL_QUERY_RE =
+  /when|what time|date|day|month|year|yesterday|today|tomorrow|last|next|什么时候|何时|哪天|几月|几年|昨天|今天|明天|上周|下周|上个月|下个月|去年|明年/i;
+const QUERY_TOKEN_RE = /[a-z0-9]{2,}/gi;
+const QUERY_TOKEN_STOPWORDS = new Set([
+  "what",
+  "when",
+  "where",
+  "which",
+  "who",
+  "whom",
+  "whose",
+  "why",
+  "how",
+  "did",
+  "does",
+  "is",
+  "are",
+  "was",
+  "were",
+  "the",
+  "and",
+  "for",
+  "with",
+  "from",
+  "that",
+  "this",
+  "your",
+  "you",
+]);
+
+type RecallQueryProfile = {
+  tokens: string[];
+  wantsPreference: boolean;
+  wantsTemporal: boolean;
+};
+
+function buildRecallQueryProfile(query: string): RecallQueryProfile {
+  const text = query.trim();
+  const allTokens = text.toLowerCase().match(QUERY_TOKEN_RE) ?? [];
+  const tokens = allTokens.filter((token) => !QUERY_TOKEN_STOPWORDS.has(token));
+  return {
+    tokens,
+    wantsPreference: PREFERENCE_QUERY_RE.test(text),
+    wantsTemporal: TEMPORAL_QUERY_RE.test(text),
+  };
+}
+
+function lexicalOverlapBoost(tokens: string[], text: string): number {
+  if (tokens.length === 0 || !text) {
+    return 0;
+  }
+  const haystack = ` ${text.toLowerCase()} `;
+  let matched = 0;
+  for (const token of tokens.slice(0, 8)) {
+    if (haystack.includes(` ${token} `) || haystack.includes(token)) {
+      matched += 1;
+    }
+  }
+  return Math.min(0.2, (matched / Math.min(tokens.length, 4)) * 0.2);
+}
+
+function rankForInjection(item: FindResultItem, query: RecallQueryProfile): number {
+  // Keep ranking simple and stable: semantic score + light query-aware boosts.
+  const baseScore = clampScore(item.score);
+  const abstract = (item.abstract ?? item.overview ?? "").trim();
+  const leafBoost = isLeafLikeMemory(item) ? 0.12 : 0;
+  const eventBoost = query.wantsTemporal && isEventMemory(item) ? 0.1 : 0;
+  const preferenceBoost = query.wantsPreference && isPreferencesMemory(item) ? 0.08 : 0;
+  const overlapBoost = lexicalOverlapBoost(query.tokens, `${item.uri} ${abstract}`);
+  return baseScore + leafBoost + eventBoost + preferenceBoost + overlapBoost;
+}
+
+export function pickMemoriesForInjection(
+  items: FindResultItem[],
+  limit: number,
+  queryText: string,
+  scoreThreshold: number = 0,
+): FindResultItem[] {
+  if (items.length === 0 || limit <= 0) {
+    return [];
+  }
+
+  const query = buildRecallQueryProfile(queryText);
+  const sorted = [...items].sort((a, b) => rankForInjection(b, query) - rankForInjection(a, query));
+  const deduped: FindResultItem[] = [];
+  const seen = new Set<string>();
+  for (const item of sorted) {
+    const abstractKey = (item.abstract ?? item.overview ?? "").trim().toLowerCase();
+    const key = abstractKey || item.uri;
+    if (seen.has(key)) {
+      continue;
+    }
+    seen.add(key);
+    deduped.push(item);
+  }
+  const leaves = deduped.filter((item) => isLeafLikeMemory(item));
+  if (leaves.length >= limit) {
+    return leaves.slice(0, limit);
+  }
+
+  const picked = [...leaves];
+  const used = new Set(leaves.map((item) => item.uri));
+  for (const item of deduped) {
+    if (picked.length >= limit) {
+      break;
+    }
+    if (used.has(item.uri)) {
+      continue;
+    }
+    // Respect score threshold when supplementing leaf memories with
+    // non-leaf items. Without this check, low-scoring memories bypass
+    // the threshold configured in recallScoreThreshold (see #1106).
+    if (clampScore(item.score) < scoreThreshold) {
+      continue;
+    }
+    picked.push(item);
+  }
+  return picked;
+}

package/openclaw.plugin.json

@@ -0,0 +1,331 @@
+{
+  "id": "openviking",
+  "name": "OpenViking",
+  "kind": "context-engine",
+  "description": "OpenClaw context-engine plugin for memory management — powered by OpenViking",
+  "activation": {
+    "onStartup": true,
+    "onCapabilities": [
+      "hook",
+      "tool"
+    ]
+  },
+  "contracts": {
+    "tools": [
+      "ov_import",
+      "memory_search",
+      "memory_recall",
+      "memory_store",
+      "memory_forget",
+      "ov_archive_search",
+      "ov_archive_expand"
+    ]
+  },
+  "commandAliases": [
+    {
+      "name": "setup",
+      "kind": "runtime-slash",
+      "cliCommand": "openviking"
+    },
+    {
+      "name": "status",
+      "kind": "runtime-slash",
+      "cliCommand": "openviking"
+    }
+  ],
+  "providerAuthEnvVars": {
+    "openviking": [
+      "OPENVIKING_API_KEY",
+      "OPENVIKING_BASE_URL"
+    ]
+  },
+  "skills": [
+    "./skills/install-openviking-memory"
+  ],
+  "setup": {
+    "providers": [
+      {
+        "id": "openviking",
+        "authMethods": [
+          "api_key",
+          "trusted"
+        ],
+        "envVars": [
+          "OPENVIKING_API_KEY",
+          "OPENVIKING_BASE_URL"
+        ],
+        "cliFlags": {
+          "api_key": [
+            "--base-url",
+            "--api-key"
+          ],
+          "trusted": [
+            "--base-url"
+          ]
+        }
+      }
+    ],
+    "requiresRuntime": true,
+    "cliCommand": "openclaw openviking setup"
+  },
+  "uiHints": {
+    "baseUrl": {
+      "label": "OpenViking Base URL",
+      "placeholder": "http://127.0.0.1:1933",
+      "help": "HTTP URL when mode is remote (or ${OPENVIKING_BASE_URL})"
+    },
+    "agent_prefix": {
+      "label": "Agent Prefix",
+      "placeholder": "optional-prefix",
+      "help": "Optional OpenViking agent prefix. Empty: follow OpenClaw ctx.agentId directly. Non-empty: use `<prefix>_<OpenClaw ctx.agentId>` (sanitized to letters/digits/_/-). If OpenClaw ctx.agentId is unavailable, use OpenClaw default agent `main`."
+    },
+    "apiKey": {
+      "label": "OpenViking API Key",
+      "sensitive": true,
+      "placeholder": "${OPENVIKING_API_KEY}",
+      "help": "Optional API key for OpenViking server"
+    },
+    "accountId": {
+      "label": "Account ID",
+      "placeholder": "(derived from API key)",
+      "help": "Advanced option. Tenant account ID. Only needed when explicitly sending identity headers, such as root-key or trusted deployments. With a user key the server derives identity from the key.",
+      "advanced": true
+    },
+    "userId": {
+      "label": "User ID",
+      "placeholder": "(derived from API key)",
+      "help": "Advanced option. Tenant user ID. Only needed when explicitly sending identity headers.",
+      "advanced": true
+    },
+    "isolateUserScopeByAgent": {
+      "label": "Isolate User Scope By Agent",
+      "placeholder": "false",
+      "help": "Canonical namespace policy. false (default): user alias expands to viking://user/<user_id>/... . true: expands to viking://user/<user_id>/agent/<agent_id>/... . Must match the server-side account namespace policy.",
+      "advanced": true
+    },
+    "isolateAgentScopeByUser": {
+      "label": "Isolate Agent Scope By User",
+      "placeholder": "false",
+      "help": "Canonical namespace policy. false (default): agent alias expands to viking://agent/<agent_id>/... . true: expands to viking://agent/<agent_id>/user/<user_id>/... . Must match the server-side account namespace policy.",
+      "advanced": true
+    },
+    "agentScopeMode": {
+      "label": "Deprecated Agent Scope Mode",
+      "placeholder": "agent",
+      "help": "Deprecated compatibility alias for older routing. Prefer isolateUserScopeByAgent / isolateAgentScopeByUser. Explicit user_agent => false/true, explicit agent => false/false. When fully unset, the plugin defaults to false/false to match the current server-side policy.",
+      "advanced": true
+    },
+    "targetUri": {
+      "label": "Search Target URI",
+      "placeholder": "viking://user/memories",
+      "help": "Default OpenViking target URI for memory search"
+    },
+    "timeoutMs": {
+      "label": "Request Timeout (ms)",
+      "placeholder": "15000",
+      "advanced": true
+    },
+    "autoCapture": {
+      "label": "Auto-Capture",
+      "help": "Extract memories from recent conversation messages via OpenViking sessions"
+    },
+    "captureMode": {
+      "label": "Capture Mode",
+      "placeholder": "semantic",
+      "advanced": true,
+      "help": "semantic captures all eligible user text; keyword uses trigger regex first"
+    },
+    "captureMaxLength": {
+      "label": "Capture Max Length",
+      "placeholder": "24000",
+      "advanced": true,
+      "help": "Maximum sanitized user text length allowed for auto-capture"
+    },
+    "autoRecall": {
+      "label": "Auto-Recall",
+      "help": "Inject relevant OpenViking memories into agent context"
+    },
+    "recallResources": {
+      "label": "Recall Resources",
+      "help": "Include resources (viking://resources) in auto-recall and default memory_recall search. Enables account-level shared knowledge retrieval.",
+      "advanced": true
+    },
+    "recallLimit": {
+      "label": "Recall Limit",
+      "placeholder": "6",
+      "advanced": true
+    },
+    "recallScoreThreshold": {
+      "label": "Recall Score Threshold",
+      "placeholder": "0.15",
+      "advanced": true
+    },
+    "recallMaxInjectedChars": {
+      "label": "Recall Max Injected Chars",
+      "placeholder": "4000",
+      "advanced": true,
+      "help": "Maximum total characters for auto-recall memory injection. Complete memories that do not fit are skipped, not truncated."
+    },
+    "recallMaxContentChars": {
+      "label": "Deprecated Recall Max Content Chars",
+      "placeholder": "5000",
+      "advanced": true,
+      "help": "Deprecated compatibility option and will be removed in a future release. Auto-recall now keeps individual memories intact and uses recallMaxInjectedChars."
+    },
+    "recallPreferAbstract": {
+      "label": "Recall Prefer Abstract",
+      "advanced": true,
+      "help": "Use memory abstract instead of fetching full content when available"
+    },
+    "recallTokenBudget": {
+      "label": "Deprecated Recall Token Budget",
+      "placeholder": "4000",
+      "advanced": true,
+      "help": "Deprecated compatibility alias and will be removed in a future release. Use recallMaxInjectedChars."
+    },
+    "bypassSessionPatterns": {
+      "label": "Bypass Session Patterns",
+      "placeholder": "agent:*:cron:**",
+      "help": "Completely bypass OpenViking for matching session keys. Use * within one segment and ** across segments.",
+      "advanced": true
+    },
+    "commitTokenThreshold": {
+      "label": "Commit Token Threshold",
+      "placeholder": "20000",
+      "advanced": true,
+      "help": "Minimum estimated pending tokens before auto-commit triggers. Set to 0 to commit every turn."
+    },
+    "commitKeepRecentCount": {
+      "label": "Commit Keep Recent Count",
+      "placeholder": "10",
+      "advanced": true,
+      "help": "WM v2: number of most-recent messages kept live after an afterTurn commit. Compact path always uses 0."
+    },
+    "emitStandardDiagnostics": {
+      "label": "Standard diagnostics (diag JSON lines)",
+      "advanced": true,
+      "help": "Emit structured openviking: diag {...} for assemble/afterTurn. Set false to disable."
+    },
+    "logFindRequests": {
+      "label": "Log find requests",
+      "help": "Log tenant routing: /search/find + session messages/commit (X-OpenViking-*; not apiKey). Or set env OPENVIKING_LOG_ROUTING=1 or OPENVIKING_DEBUG=1.",
+      "advanced": true
+    }
+  },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "mode": {
+        "type": "string",
+        "description": "Legacy field kept for backward compatibility. Only 'remote' is supported."
+      },
+      "baseUrl": {
+        "type": "string"
+      },
+      "agent_prefix": {
+        "type": "string"
+      },
+      "agentId": {
+        "type": "string",
+        "description": "Deprecated: use agent_prefix instead"
+      },
+      "serverAuthMode": {
+        "type": "string",
+        "description": "Deprecated and ignored. Tenant identity headers are controlled by explicit accountId/userId."
+      },
+      "apiKey": {
+        "type": "string"
+      },
+      "accountId": {
+        "type": "string"
+      },
+      "userId": {
+        "type": "string"
+      },
+      "isolateUserScopeByAgent": {
+        "type": "boolean"
+      },
+      "isolateAgentScopeByUser": {
+        "type": "boolean"
+      },
+      "agentScopeMode": {
+        "type": "string"
+      },
+      "targetUri": {
+        "type": "string"
+      },
+      "timeoutMs": {
+        "type": "number"
+      },
+      "autoCapture": {
+        "type": "boolean"
+      },
+      "captureMode": {
+        "type": "string"
+      },
+      "captureMaxLength": {
+        "type": "number"
+      },
+      "autoRecall": {
+        "type": "boolean"
+      },
+      "recallResources": {
+        "type": "boolean"
+      },
+      "recallLimit": {
+        "type": "number"
+      },
+      "recallScoreThreshold": {
+        "type": "number"
+      },
+      "recallMaxInjectedChars": {
+        "type": "number"
+      },
+      "recallMaxContentChars": {
+        "type": "number"
+      },
+      "recallPreferAbstract": {
+        "type": "boolean"
+      },
+      "recallTokenBudget": {
+        "type": "number"
+      },
+      "commitTokenThreshold": {
+        "type": "number"
+      },
+      "commitKeepRecentCount": {
+        "type": "number",
+        "minimum": 0,
+        "maximum": 1000
+      },
+      "bypassSessionPatterns": {
+        "type": "array",
+        "items": {
+          "type": "string"
+        }
+      },
+      "ingestReplyAssist": {
+        "type": "boolean"
+      },
+      "ingestReplyAssistMinSpeakerTurns": {
+        "type": "number"
+      },
+      "ingestReplyAssistMinChars": {
+        "type": "number"
+      },
+      "ingestReplyAssistIgnoreSessionPatterns": {
+        "type": "array",
+        "items": {
+          "type": "string"
+        }
+      },
+      "emitStandardDiagnostics": {
+        "type": "boolean"
+      },
+      "logFindRequests": {
+        "type": "boolean"
+      }
+    }
+  }
+}