@openviking/openclaw-plugin 2026.6.2 → 2026.6.17-dev.2

package/install-manifest.json

@@ -1,6 +1,6 @@
 {
   "manifestVersion": "1.0",
-  "pluginVersion": "2026.5.8",
+  "pluginVersion": "2026.6.11",
   "plugin": {
     "id": "openviking",
     "kind": "context-engine",
@@ -20,7 +20,15 @@
       "tool-call-id.ts",
       "session-transcript-repair.ts",
       "runtime-utils.ts",
+      "recall-trace.ts",
+      "query-config.ts",
+      "adapters/",
+      "registries/",
+      "routing/",
+      "plugin/",
+      "services/",
       "commands/setup.ts",
+      "config/feature-gates.json",
       "tsconfig.json",
       "tsconfig.build.json",
       "package.json",
@@ -30,6 +38,7 @@
       "package-lock.json",
       ".gitignore",
       "skills/install-openviking-memory/SKILL.md",
+      "skills/openviking-context-database/SKILL.md",
       "INSTALL-AGENT.md"
     ]
   },

package/memory-ranking.ts

@@ -182,6 +182,28 @@ type RecallQueryProfile = {
   wantsTemporal: boolean;
 };
 
+export type RankingWeights = {
+  baseScore?: number;
+  leaf?: number;
+  event?: number;
+  preference?: number;
+  lexicalOverlapMax?: number;
+};
+
+export type RankingOptions = {
+  weights?: RankingWeights;
+  categoryWeights?: Record<string, number>;
+  resourceTypeWeights?: Record<string, number>;
+};
+
+const DEFAULT_RANKING_WEIGHTS = {
+  baseScore: 1,
+  leaf: 0.12,
+  event: 0.1,
+  preference: 0.08,
+  lexicalOverlapMax: 0.2,
+};
+
 function buildRecallQueryProfile(query: string): RecallQueryProfile {
   const text = query.trim();
   const allTokens = text.toLowerCase().match(QUERY_TOKEN_RE) ?? [];
@@ -193,7 +215,7 @@ function buildRecallQueryProfile(query: string): RecallQueryProfile {
   };
 }
 
-function lexicalOverlapBoost(tokens: string[], text: string): number {
+function lexicalOverlapBoost(tokens: string[], text: string, maxBoost = DEFAULT_RANKING_WEIGHTS.lexicalOverlapMax): number {
   if (tokens.length === 0 || !text) {
     return 0;
   }
@@ -204,18 +226,31 @@ function lexicalOverlapBoost(tokens: string[], text: string): number {
       matched += 1;
     }
   }
-  return Math.min(0.2, (matched / Math.min(tokens.length, 4)) * 0.2);
+  return Math.min(maxBoost, (matched / Math.min(tokens.length, 4)) * maxBoost);
+}
+
+function inferResourceType(item: FindResultItem): string | undefined {
+  if (item.uri.startsWith("viking://resources")) return "resource";
+  if (item.uri.startsWith("viking://session/")) return "session";
+  if (item.uri.startsWith("viking://user/skills") || item.uri.startsWith("viking://skills")) return "agent";
+  if (item.uri.startsWith("viking://user/")) return "user";
+  return undefined;
 }
 
-function rankForInjection(item: FindResultItem, query: RecallQueryProfile): number {
+function rankForInjection(item: FindResultItem, query: RecallQueryProfile, options?: RankingOptions): number {
   // Keep ranking simple and stable: semantic score + light query-aware boosts.
-  const baseScore = clampScore(item.score);
+  const weights = { ...DEFAULT_RANKING_WEIGHTS, ...(options?.weights ?? {}) };
+  const baseScore = clampScore(item.score) * weights.baseScore;
   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;
+  const leafBoost = isLeafLikeMemory(item) ? weights.leaf : 0;
+  const eventBoost = query.wantsTemporal && isEventMemory(item) ? weights.event : 0;
+  const preferenceBoost = query.wantsPreference && isPreferencesMemory(item) ? weights.preference : 0;
+  const overlapBoost = lexicalOverlapBoost(query.tokens, `${item.uri} ${abstract}`, weights.lexicalOverlapMax);
+  const category = (item.category ?? "").toLowerCase();
+  const categoryBoost = category ? (options?.categoryWeights?.[category] ?? options?.categoryWeights?.[item.category ?? ""] ?? 0) : 0;
+  const resourceType = inferResourceType(item);
+  const resourceTypeBoost = resourceType ? (options?.resourceTypeWeights?.[resourceType] ?? 0) : 0;
+  return baseScore + leafBoost + eventBoost + preferenceBoost + overlapBoost + categoryBoost + resourceTypeBoost;
 }
 
 export function pickMemoriesForInjection(
@@ -223,13 +258,14 @@ export function pickMemoriesForInjection(
   limit: number,
   queryText: string,
   scoreThreshold: number = 0,
+  rankingOptions?: RankingOptions,
 ): 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 sorted = [...items].sort((a, b) => rankForInjection(b, query, rankingOptions) - rankForInjection(a, query, rankingOptions));
   const deduped: FindResultItem[] = [];
   const seen = new Set<string>();
   for (const item of sorted) {

package/openclaw.plugin.json

@@ -12,10 +12,13 @@
   },
   "contracts": {
     "tools": [
-      "add_resource",
       "add_skill",
       "ov_search",
+      "ov_read",
+      "ov_multi_read",
+      "ov_list",
       "memory_recall",
+      "ov_recall_trace",
       "memory_store",
       "memory_forget",
       "ov_archive_search",
@@ -44,7 +47,8 @@
     ]
   },
   "skills": [
-    "./skills/install-openviking-memory"
+    "./skills/install-openviking-memory",
+    "./skills/openviking-context-database"
   ],
   "setup": {
     "providers": [
@@ -78,10 +82,15 @@
       "placeholder": "http://127.0.0.1:1933",
       "help": "HTTP URL when mode is remote (or ${OPENVIKING_BASE_URL})"
     },
-    "agent_prefix": {
-      "label": "Agent Prefix",
+    "peer_role": {
+      "label": "Peer Role",
+      "placeholder": "assistant",
+      "help": "Controls which messages include peer_id: none, assistant, or person. New installs default to assistant."
+    },
+    "peer_prefix": {
+      "label": "Peer 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`."
+      "help": "Optional prefix for assistant peer_id values derived from OpenClaw runtime agent IDs."
     },
     "apiKey": {
       "label": "OpenViking API Key",
@@ -101,24 +110,6 @@
       "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",
@@ -149,11 +140,23 @@
       "label": "Auto-Recall",
       "help": "Inject relevant OpenViking memories into agent context"
     },
+    "autoRecallTimeoutMs": {
+      "label": "Auto-Recall Timeout (ms)",
+      "placeholder": "5000",
+      "advanced": true,
+      "help": "Outer time budget for the whole auto-recall flow, including search, ranking, and memory reads."
+    },
     "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
     },
+    "recallTargetTypes": {
+      "label": "Recall Target Types",
+      "placeholder": "user,agent",
+      "help": "Comma-separated auto-recall and default memory_recall targets: user, agent, resource. Session history is available through ov_archive_search and ov_archive_expand.",
+      "advanced": true
+    },
     "recallLimit": {
       "label": "Recall Limit",
       "placeholder": "6",
@@ -214,6 +217,42 @@
       "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
+    },
+    "traceRecall": {
+      "label": "Trace Recall",
+      "placeholder": "false",
+      "help": "Enable best-effort recall trace recording for debugging recall and search decisions.",
+      "advanced": true
+    },
+    "traceRecallPersist": {
+      "label": "Persist Recall Trace",
+      "placeholder": "false",
+      "help": "Persist recall traces to local JSONL files. Disabled by default.",
+      "advanced": true
+    },
+    "traceRecallDir": {
+      "label": "Recall Trace Directory",
+      "placeholder": "~/.openclaw/openviking/recall-traces",
+      "help": "Directory for persisted recall trace JSONL files.",
+      "advanced": true
+    },
+    "enableAddResourceTool": {
+      "label": "Enable Add Resource Tool",
+      "placeholder": "false",
+      "help": "Disabled by default so search and read flows cannot call add_resource. Set true only when agents should import resources; manual /add-resource remains available.",
+      "advanced": true
+    },
+    "enabledTools": {
+      "label": "Enabled Tools",
+      "placeholder": "default",
+      "help": "Agent-visible tool allowlist. Accepts tool names or groups: default, all, memory, resource_query, import, recall_trace, archive, tool_result. add_resource also requires enableAddResourceTool=true.",
+      "advanced": true
+    },
+    "disabledTools": {
+      "label": "Disabled Tools",
+      "placeholder": "memory",
+      "help": "Agent-visible tool blocklist applied after enabledTools. Accepts the same tool names or groups.",
+      "advanced": true
     }
   },
   "configSchema": {
@@ -227,12 +266,19 @@
       "baseUrl": {
         "type": "string"
       },
-      "agent_prefix": {
-        "type": "string"
+      "peer_role": {
+        "type": "string",
+        "enum": [
+          "none",
+          "assistant",
+          "person"
+        ],
+        "default": "assistant",
+        "description": "Controls which session messages include peer_id."
       },
-      "agentId": {
+      "peer_prefix": {
         "type": "string",
-        "description": "Deprecated: use agent_prefix instead"
+        "description": "Optional prefix for assistant peer_id values."
       },
       "serverAuthMode": {
         "type": "string",
@@ -247,15 +293,6 @@
       "userId": {
         "type": "string"
       },
-      "isolateUserScopeByAgent": {
-        "type": "boolean"
-      },
-      "isolateAgentScopeByUser": {
-        "type": "boolean"
-      },
-      "agentScopeMode": {
-        "type": "string"
-      },
       "targetUri": {
         "type": "string"
       },
@@ -274,9 +311,32 @@
       "autoRecall": {
         "type": "boolean"
       },
+      "autoRecallTimeoutMs": {
+        "type": "number",
+        "minimum": 1000,
+        "maximum": 300000
+      },
       "recallResources": {
         "type": "boolean"
       },
+      "recallTargetTypes": {
+        "oneOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "enum": [
+                "resource",
+                "user",
+                "agent"
+              ]
+            }
+          }
+        ]
+      },
       "recallLimit": {
         "type": "number"
       },
@@ -329,6 +389,108 @@
       },
       "logFindRequests": {
         "type": "boolean"
+      },
+      "traceRecall": {
+        "type": "boolean"
+      },
+      "traceRecallPersist": {
+        "type": "boolean"
+      },
+      "traceRecallDir": {
+        "type": "string"
+      },
+      "traceRecallRetentionDays": {
+        "type": "number",
+        "minimum": 1,
+        "maximum": 3650
+      },
+      "traceRecallLoadRecentDays": {
+        "type": "number",
+        "minimum": 0,
+        "maximum": 3650
+      },
+      "traceRecallMaxEntries": {
+        "type": "number",
+        "minimum": 1,
+        "maximum": 1000000
+      },
+      "traceRecallMaxResultsPerSearch": {
+        "type": "number",
+        "minimum": 1,
+        "maximum": 1000
+      },
+      "traceRecallPreviewChars": {
+        "type": "number",
+        "minimum": 20,
+        "maximum": 10000
+      },
+      "traceRecallQueryMaxChars": {
+        "type": "number",
+        "minimum": 200,
+        "maximum": 200000
+      },
+      "traceRecallQueryMaxDays": {
+        "type": "number",
+        "minimum": 1,
+        "maximum": 3650
+      },
+      "traceRecallIncludeContentByDefault": {
+        "type": "boolean"
+      },
+      "traceRecallIncludeRawUserPreview": {
+        "type": "boolean"
+      },
+      "enableAddResourceTool": {
+        "type": "boolean"
+      },
+      "enabledTools": {
+        "oneOf": [
+          {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          {
+            "type": "string"
+          }
+        ]
+      },
+      "disabledTools": {
+        "oneOf": [
+          {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          {
+            "type": "string"
+          }
+        ]
+      },
+      "agentExperience": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "enabled": {
+            "type": "boolean",
+            "default": false,
+            "description": "Enable agent experience memory recall. Default is false for conservative rollout."
+          },
+          "recallLimit": {
+            "type": "number"
+          },
+          "scoreThreshold": {
+            "type": "number"
+          },
+          "maxInjectedChars": {
+            "type": "number"
+          },
+          "minQueryChars": {
+            "type": "number"
+          }
+        }
       }
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openviking/openclaw-plugin",
-  "version": "2026.6.2",
+  "version": "2026.6.17-dev.2",
   "displayName": "OpenViking",
   "description": "OpenClaw context-engine plugin — OpenViking AI memory, long-term memory, knowledge base, semantic search, RAG, context engine. 长期记忆 · 知识库 · 语义检索 · 上下文引擎",
   "type": "module",
@@ -21,7 +21,13 @@
   "files": [
     "dist/",
     "*.ts",
+    "adapters/",
     "commands/setup.ts",
+    "config/feature-gates.json",
+    "registries/",
+    "routing/",
+    "plugin/",
+    "services/",
     "!vitest.config.ts",
     "install-manifest.json",
     "openclaw.plugin.json",
@@ -34,7 +40,7 @@
     "skills/"
   ],
   "scripts": {
-    "build": "tsc -p tsconfig.build.json",
+    "build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.build.json",
     "prepack": "npm run build",
     "test": "vitest run",
     "typecheck": "tsc -p tsconfig.json",
@@ -51,14 +57,17 @@
     "type": "git",
     "url": "https://github.com/volcengine/OpenViking"
   },
+  "overrides": {
+    "axios": "^1.16.1"
+  },
   "homepage": "https://github.com/volcengine/OpenViking/tree/main/examples/openclaw-plugin",
   "license": "MIT",
   "author": "OpenViking Contributors",
   "openclaw": {
     "extensions": [
-      "./index.ts"
+      "./dist/index.js"
     ],
-    "setupEntry": "./commands/setup.ts",
+    "setupEntry": "./dist/commands/setup.js",
     "compat": {
       "pluginApi": ">=2026.4.8",
       "minGatewayVersion": "2026.4.8"
@@ -70,6 +79,7 @@
   },
   "devDependencies": {
     "@types/node": "^25.3.5",
+    "@volcengine/tos-sdk": "^2.9.1",
     "typescript": "^5.8.0",
     "vitest": "^4.1.0"
   }

package/plugin/command-registration.ts

@@ -0,0 +1,34 @@
+export type PluginCommandContext = {
+  args?: string;
+  commandBody?: string;
+  sessionKey?: string;
+  sessionId?: string;
+  agentId?: string;
+  ovSessionId?: string;
+};
+
+export type CommandResult = {
+  text: string;
+  details?: Record<string, unknown>;
+};
+
+export type CommandDefinition = {
+  name: string;
+  description: string;
+  acceptsArgs?: boolean;
+  requireAuth?: boolean;
+  handler: (ctx: PluginCommandContext) => CommandResult | Promise<CommandResult>;
+};
+
+export type OpenVikingCommandRegistrationApi = {
+  registerCommand?: (command: CommandDefinition) => void;
+};
+
+export function registerOpenVikingCommands(
+  api: OpenVikingCommandRegistrationApi,
+  commands: CommandDefinition[],
+): void {
+  for (const command of commands) {
+    api.registerCommand?.(command);
+  }
+}