@openviking/openclaw-plugin 2026.7.11 → 2026.8.6-1

package/openclaw.plugin.json

@@ -3,6 +3,7 @@
   "name": "OpenViking",
   "kind": "context-engine",
   "description": "OpenClaw context-engine plugin for memory management — powered by OpenViking",
+  "icon": "https://raw.githubusercontent.com/volcengine/OpenViking/main/docs/images/ov-logo-icon.png",
   "activation": {
     "onStartup": true,
     "onCapabilities": [
@@ -12,11 +13,14 @@
   },
   "contracts": {
     "tools": [
+      "add_resource",
       "add_skill",
       "ov_search",
       "ov_read",
       "ov_multi_read",
       "ov_list",
+      "search_experience",
+      "read_experience",
       "memory_recall",
       "ov_recall_trace",
       "memory_store",
@@ -96,7 +100,7 @@
       "label": "OpenViking API Key",
       "sensitive": true,
       "placeholder": "${OPENVIKING_API_KEY}",
-      "help": "Optional API key for OpenViking server"
+      "help": "Optional API key for OpenViking server. Accepts a plain string, ${ENV_VAR} interpolation, or a SecretRef object ({source: env/file, id}). Prefer a SecretRef so the key is never stored as plaintext in openclaw.json."
     },
     "headers": {
       "label": "Headers",
@@ -250,7 +254,7 @@
     "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.",
+      "help": "Agent-visible tool allowlist. Accepts tool names or groups: default, all, memory, resource_query, experience, import, recall_trace, archive, tool_result. add_resource also requires enableAddResourceTool=true.",
       "advanced": true
     },
     "disabledTools": {
@@ -290,7 +294,34 @@
         "description": "Deprecated and ignored. Tenant identity headers are controlled by explicit accountId/userId."
       },
       "apiKey": {
-        "type": "string"
+        "oneOf": [
+          {
+            "type": "string",
+            "description": "Plain API key or ${ENV_VAR} interpolation. For secret-manager-managed keys, prefer the SecretRef object shape below."
+          },
+          {
+            "type": "object",
+            "title": "SecretRef (env)",
+            "description": "Read the API key from an environment variable.",
+            "additionalProperties": false,
+            "required": ["source", "id"],
+            "properties": {
+              "source": { "type": "string", "const": "env", "description": "Look up the key in process.env[id] at plugin load time. Equivalent to ${ENV} interpolation but declarative and visible in the UI." },
+              "id": { "type": "string", "description": "Name of the environment variable. Example: OPENVIKING_API_KEY." }
+            }
+          },
+          {
+            "type": "object",
+            "title": "SecretRef (file)",
+            "description": "Read the API key from a file on disk, e.g. a Kubernetes secretKeyRef mount volume or a 0600-permission managed file. ~ is expanded and trailing whitespace is trimmed.",
+            "additionalProperties": false,
+            "required": ["source", "id"],
+            "properties": {
+              "source": { "type": "string", "const": "file" },
+              "id": { "type": "string", "description": "Absolute file path or ~/relative path. Example: /etc/secrets/openviking.key." }
+            }
+          }
+        ]
       },
       "headers": {
         "type": "object",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openviking/openclaw-plugin",
-  "version": "2026.7.11",
+  "version": "2026.8.6-1",
   "displayName": "OpenViking",
   "description": "OpenClaw context-engine plugin — OpenViking AI memory, long-term memory, knowledge base, semantic search, RAG, context engine. 长期记忆 · 知识库 · 语义检索 · 上下文引擎",
   "type": "module",

package/plugin/command-registration.ts

@@ -5,6 +5,8 @@ export type PluginCommandContext = {
   sessionId?: string;
   agentId?: string;
   ovSessionId?: string;
+  senderId?: string;
+  requesterSenderId?: string;
 };
 
 export type CommandResult = {

package/plugin/openviking-archive-tools.ts

@@ -26,7 +26,7 @@ export type OpenVikingArchiveClient = {
   grepSessionArchives: (
     sessionId: string,
     pattern: string,
-    options: { archiveId?: string; caseInsensitive: boolean; agentId?: string },
+    options: { archiveId?: string; caseInsensitive: boolean },
   ) => Promise<{
     count?: number;
     matches?: OpenVikingArchiveMatch[];
@@ -34,7 +34,6 @@ export type OpenVikingArchiveClient = {
   getSessionArchive: (
     sessionId: string,
     archiveId: string,
-    agentId?: string,
   ) => Promise<{
     archive_id: string;
     abstract?: string;
@@ -128,7 +127,6 @@ export function registerOpenVikingArchiveTools(deps: OpenVikingArchiveToolsDeps)
           const result = await client.grepSessionArchives(ovSessionId, escapedQuery, {
             archiveId,
             caseInsensitive: true,
-            agentId,
           });
           const traceResults: RecallTraceResult[] = (result.matches ?? []).slice(0, deps.traceRecallMaxResultsPerSearch).map((match) => ({
             uri: match.uri,
@@ -263,7 +261,6 @@ export function registerOpenVikingArchiveTools(deps: OpenVikingArchiveToolsDeps)
         const detail = await client.getSessionArchive(
           session.ovSessionId,
           archiveId,
-          session.agentId,
         );
 
         const header = [

package/plugin/openviking-command-definitions.ts

@@ -6,6 +6,7 @@ export type OpenVikingCommandSession = {
   sessionKey?: string;
   ovSessionId?: string;
   agentId: string;
+  actorPeerId?: string;
 };
 
 export type OpenVikingCommandToolResult = {
@@ -217,7 +218,7 @@ export function createOpenVikingCommandDefinitions(
           }
           const session = deps.resolvePluginSessionRouting(ctx);
           const input = deps.parseAddResourceCommandArgs(ctx.args ?? "");
-          return toCommandResult(await deps.addResourceOpenViking(input, session.agentId));
+          return toCommandResult(await deps.addResourceOpenViking(input, session.actorPeerId));
         } catch (err) {
           return { text: `OpenViking add resource failed: ${err instanceof Error ? err.message : String(err)}` };
         }
@@ -234,7 +235,7 @@ export function createOpenVikingCommandDefinitions(
           }
           const session = deps.resolvePluginSessionRouting(ctx);
           const input = deps.parseAddSkillCommandArgs(ctx.args ?? "");
-          return toCommandResult(await deps.addSkillOpenViking(input, session.agentId));
+          return toCommandResult(await deps.addSkillOpenViking(input, session.actorPeerId));
         } catch (err) {
           return { text: `OpenViking add skill failed: ${err instanceof Error ? err.message : String(err)}` };
         }
@@ -251,7 +252,7 @@ export function createOpenVikingCommandDefinitions(
           }
           const session = deps.resolvePluginSessionRouting(ctx);
           const input = deps.parseOVSearchCommandArgs(ctx.args ?? "");
-          return toCommandResult(await deps.searchOpenViking(input, session.agentId, session));
+          return toCommandResult(await deps.searchOpenViking(input, session.actorPeerId, session));
         } catch (err) {
           return { text: `OpenViking search failed: ${err instanceof Error ? err.message : String(err)}` };
         }

package/plugin/openviking-experience-tools.ts

@@ -0,0 +1,160 @@
+import { Type } from "@sinclair/typebox";
+
+import type { FindResult } from "../client.js";
+
+const EXPERIENCE_TARGET_URI = "viking://user/memories/experiences/";
+const DEFAULT_LIMIT = 5;
+const MAX_LIMIT = 20;
+const EXPERIENCE_SIDECAR_FILENAMES = new Set([".abstract.md", ".overview.md", ".relations.json"]);
+
+export type OpenVikingExperienceToolContext = {
+  sessionKey?: string;
+  sessionId?: string;
+  agentId?: string;
+  senderId?: string;
+  requesterSenderId?: string;
+};
+
+export type OpenVikingExperienceSession = {
+  sessionId?: string;
+  sessionKey?: string;
+  ovSessionId?: string;
+  agentId: string;
+  actorPeerId?: string;
+};
+
+type OpenVikingExperienceClient = {
+  find: (
+    query: string,
+    options: { targetUri: string; limit: number; scoreThreshold?: number },
+    actorPeerId?: string,
+  ) => Promise<FindResult>;
+  read: (uri: string, actorPeerId?: string) => Promise<unknown>;
+};
+
+export type OpenVikingExperienceToolsDeps = {
+  registerTool: (toolOrFactory: unknown, opts: { name: string }) => void;
+  getClient: () => Promise<OpenVikingExperienceClient>;
+  resolvePluginSessionRouting: (ctx?: OpenVikingExperienceToolContext) => OpenVikingExperienceSession;
+  isBypassedSession: (ctx?: OpenVikingExperienceToolContext) => boolean;
+  makeBypassedToolResult: (toolName: string) => unknown;
+  userId?: string;
+};
+
+function clampLimit(value: unknown): number {
+  const parsed = Number.isFinite(Number(value)) ? Math.trunc(Number(value)) : DEFAULT_LIMIT;
+  return Math.max(1, Math.min(MAX_LIMIT, parsed));
+}
+
+function experienceRelativePath(uri: string): string {
+  return uri.match(/^viking:\/\/user\/[^/]+\/memories\/experiences\/(.+)$/)?.[1] ?? "";
+}
+
+export function isCanonicalExperienceUri(uri: unknown, expectedUserId?: string): uri is string {
+  const value = typeof uri === "string" ? uri.trim() : "";
+  if (!value || value.includes("?") || value.includes("#")) {
+    return false;
+  }
+  const owner = value.match(/^viking:\/\/user\/([^/]+)\//)?.[1] ?? "";
+  if (expectedUserId?.trim() && owner !== expectedUserId.trim()) {
+    return false;
+  }
+  const relative = experienceRelativePath(value);
+  const segments = relative.split("/");
+  const basename = segments.at(-1) ?? "";
+  return Boolean(
+    relative
+    && segments.every((segment) => segment && segment !== "." && segment !== "..")
+    && !EXPERIENCE_SIDECAR_FILENAMES.has(basename)
+  );
+}
+
+function titleFromUri(uri: string): string {
+  const basename = uri.split("/").at(-1) ?? uri;
+  const title = basename.replace(/\.md$/i, "");
+  try {
+    return decodeURIComponent(title);
+  } catch {
+    return title;
+  }
+}
+
+function jsonToolResult(payload: Record<string, unknown>): {
+  content: Array<{ type: "text"; text: string }>;
+} {
+  return {
+    content: [{ type: "text", text: JSON.stringify(payload) }],
+  };
+}
+
+export function registerOpenVikingExperienceTools(deps: OpenVikingExperienceToolsDeps): void {
+  deps.registerTool(
+    (ctx: OpenVikingExperienceToolContext) => ({
+      name: "search_experience",
+      label: "Search Experience (OpenViking)",
+      description:
+        "Search reusable task-execution experiences for the current OpenViking user. " +
+        "Use before executing operational or multi-step tasks, then call read_experience for selected results.",
+      parameters: Type.Object({
+        query: Type.String({ description: "Current task, situation, or execution problem to search for" }),
+        limit: Type.Optional(Type.Integer({
+          description: `Maximum results to return. Default: ${DEFAULT_LIMIT}; maximum: ${MAX_LIMIT}`,
+          minimum: 1,
+          maximum: MAX_LIMIT,
+        })),
+      }, { additionalProperties: false }),
+      async execute(_toolCallId: string, params: Record<string, unknown>) {
+        if (deps.isBypassedSession(ctx)) {
+          return deps.makeBypassedToolResult("search_experience");
+        }
+        const query = typeof params.query === "string" ? params.query.trim() : "";
+        if (!query) {
+          throw new Error("query is required");
+        }
+        const session = deps.resolvePluginSessionRouting(ctx);
+        const client = await deps.getClient();
+        const result = await client.find(query, {
+          targetUri: EXPERIENCE_TARGET_URI,
+          limit: clampLimit(params.limit),
+        }, session.actorPeerId);
+        const results = (result.memories ?? [])
+          .filter((item) => isCanonicalExperienceUri(item.uri, deps.userId))
+          .map((item) => ({
+            uri: item.uri,
+            title: titleFromUri(item.uri),
+            score: typeof item.score === "number" ? item.score : 0,
+            snippet: item.abstract || item.overview || "",
+          }));
+        return jsonToolResult({ results });
+      },
+    }),
+    { name: "search_experience" },
+  );
+
+  deps.registerTool(
+    (ctx: OpenVikingExperienceToolContext) => ({
+      name: "read_experience",
+      label: "Read Experience (OpenViking)",
+      description:
+        "Read the complete Markdown body of one Experience returned by search_experience and use it as execution guidance.",
+      parameters: Type.Object({
+        uri: Type.String({ description: "Exact canonical Experience URI returned by search_experience" }),
+      }, { additionalProperties: false }),
+      async execute(_toolCallId: string, params: Record<string, unknown>) {
+        if (deps.isBypassedSession(ctx)) {
+          return deps.makeBypassedToolResult("read_experience");
+        }
+        const uri = typeof params.uri === "string" ? params.uri.trim() : "";
+        if (!isCanonicalExperienceUri(uri, deps.userId)) {
+          throw new Error("uri must be a canonical OpenViking Experience URI returned by search_experience");
+        }
+        const session = deps.resolvePluginSessionRouting(ctx);
+        const client = await deps.getClient();
+        const content = await client.read(uri, session.actorPeerId);
+        const text = typeof content === "string" ? content : JSON.stringify(content, null, 2);
+        return jsonToolResult({ uri, content: text });
+      },
+    }),
+    { name: "read_experience" },
+  );
+}

package/plugin/openviking-import-tools.ts

@@ -12,6 +12,7 @@ export type OpenVikingImportToolContext = {
   sessionId?: string;
   agentId?: string;
   senderId?: string;
+  requesterSenderId?: string;
 };
 
 export type OpenVikingImportSession = {
@@ -19,6 +20,7 @@ export type OpenVikingImportSession = {
   sessionKey?: string;
   ovSessionId?: string;
   agentId: string;
+  actorPeerId?: string;
 };
 
 export type OpenVikingImportClient = {
@@ -80,7 +82,7 @@ export function registerOpenVikingImportTools(deps: OpenVikingImportToolsDeps):
             instruction: typeof params.instruction === "string" ? params.instruction : undefined,
             wait: typeof params.wait === "boolean" ? params.wait : undefined,
             timeout: typeof params.timeout === "number" ? params.timeout : undefined,
-          }, session.agentId);
+          }, session.actorPeerId);
           return {
             content: [{ type: "text" as const, text: formatResourceImportText(result) }],
             details: {
@@ -118,7 +120,7 @@ export function registerOpenVikingImportTools(deps: OpenVikingImportToolsDeps):
           data: params.data,
           wait: typeof params.wait === "boolean" ? params.wait : undefined,
           timeout: typeof params.timeout === "number" ? params.timeout : undefined,
-        }, session.agentId);
+        }, session.actorPeerId);
         return {
           content: [{ type: "text" as const, text: formatSkillImportText(result) }],
           details: {

package/plugin/openviking-memory-recall-tools.ts

@@ -15,6 +15,7 @@ export type OpenVikingMemoryRecallToolContext = {
   sessionId?: string;
   agentId?: string;
   senderId?: string;
+  requesterSenderId?: string;
 };
 
 export type OpenVikingMemoryRecallSession = {
@@ -22,6 +23,7 @@ export type OpenVikingMemoryRecallSession = {
   sessionKey?: string;
   ovSessionId?: string;
   agentId: string;
+  actorPeerId?: string;
 };
 
 export type OpenVikingMemoryRecallClient = {
@@ -163,7 +165,7 @@ export function registerOpenVikingMemoryRecallTools(
         const recallClient = await deps.getClient();
         if (deps.cfg.logFindRequests) {
           deps.logger.info?.(
-            `openviking: memory_recall X-OpenViking-Actor-Peer="${session.agentId}" ` +
+            `openviking: memory_recall X-OpenViking-Actor-Peer="${session.actorPeerId ?? "none"}" ` +
               `(plugin defaultAgentId="${recallClient.getDefaultAgentId()}" is unused when session context is present)`,
           );
         }
@@ -177,7 +179,7 @@ export function registerOpenVikingMemoryRecallTools(
             targetUri,
             limit: requestLimit,
             scoreThreshold: 0,
-            actorPeerId: session.agentId,
+            actorPeerId: session.actorPeerId,
           },
         );
           const traceResults = [
@@ -207,7 +209,7 @@ export function registerOpenVikingMemoryRecallTools(
                 limit: requestLimit,
                 scoreThreshold: 0,
                 contextType: search.contextType,
-                actorPeerId: session.agentId,
+                actorPeerId: session.actorPeerId,
               },
             ),
           ));
@@ -319,7 +321,7 @@ export function registerOpenVikingMemoryRecallTools(
         }
         const { lines: memoryLines } = await deps.buildMemoryLinesWithBudget(
           memories,
-          (uri) => recallClient.read(uri, session.agentId),
+          (uri) => recallClient.read(uri, session.actorPeerId),
           {
             recallPreferAbstract: false,
             recallMaxInjectedChars: queryConfig.maxInjectedChars,

package/plugin/openviking-memory-tools.ts

@@ -2,6 +2,10 @@ import { Type } from "@sinclair/typebox";
 
 import type { CommitSessionResult, FindResultItem } from "../client.js";
 import { clampScore, postProcessMemories } from "../memory-ranking.js";
+import {
+  resolveOpenVikingMessagePeerId,
+  type OpenVikingPeerRole,
+} from "../routing/identity-routing.js";
 import { isMemoryUri } from "../routing/memory-uri.js";
 
 export type OpenVikingMemoryToolContext = {
@@ -17,6 +21,7 @@ export type OpenVikingMemorySession = {
   sessionKey?: string;
   ovSessionId?: string;
   agentId: string;
+  actorPeerId?: string;
 };
 
 export type OpenVikingMemoryClient = {
@@ -30,7 +35,7 @@ export type OpenVikingMemoryClient = {
   ) => Promise<void>;
   commitSession: (
     sessionId: string,
-    options: { wait: true; agentId: string; keepRecentCount: number },
+    options: { wait: true; agentId?: string; keepRecentCount: number },
   ) => Promise<CommitSessionResult>;
   deleteUri: (uri: string, agentId?: string) => Promise<void>;
   find: (
@@ -45,8 +50,7 @@ export type OpenVikingMemoryToolsDeps = {
   getClient: () => Promise<OpenVikingMemoryClient>;
   normalizeSessionId: (sessionId: string) => string;
   createTempSessionId: () => string;
-  extractSenderId: (ctx?: OpenVikingMemoryToolContext) => string | undefined;
-  toRoleId: (senderId?: string) => string | undefined;
+  peerRole: OpenVikingPeerRole;
   resolvePluginSessionRouting: (ctx?: OpenVikingMemoryToolContext) => OpenVikingMemorySession;
   isBypassedSession: (ctx?: OpenVikingMemoryToolContext) => boolean;
   makeBypassedToolResult: (toolName: string) => unknown;
@@ -107,18 +111,22 @@ export function registerOpenVikingMemoryTools(deps: OpenVikingMemoryToolsDeps):
             sessionId = deps.createTempSessionId();
             usedTempSession = true;
           }
-          const roleId = role === "user" ? deps.toRoleId(deps.extractSenderId(ctx)) : undefined;
+          const peerId = resolveOpenVikingMessagePeerId({
+            peerRole: deps.peerRole,
+            role,
+            personPeerId: session.actorPeerId,
+            assistantPeerId: session.actorPeerId,
+          });
           await client.addSessionMessage(
             sessionId,
             role,
             [{ type: "text", text }],
-            session.agentId,
             undefined,
-            roleId,
+            undefined,
+            peerId,
           );
           const commitResult = await client.commitSession(sessionId, {
             wait: true,
-            agentId: session.agentId,
             keepRecentCount: 0,
           });
           const memoriesCount = totalCommitMemories(commitResult);
@@ -216,7 +224,7 @@ export function registerOpenVikingMemoryTools(deps: OpenVikingMemoryToolsDeps):
               details: { action: "rejected", uri },
             };
           }
-          await client.deleteUri(uri, session.agentId);
+          await client.deleteUri(uri, session.actorPeerId);
           return {
             content: [{ type: "text", text: `Forgotten: ${uri}` }],
             details: { action: "deleted", uri },
@@ -252,7 +260,7 @@ export function registerOpenVikingMemoryTools(deps: OpenVikingMemoryToolsDeps):
             limit: requestLimit,
             scoreThreshold: 0,
           },
-          session.agentId,
+          session.actorPeerId,
         );
         const candidates = postProcessMemories(result.memories ?? [], {
           limit: requestLimit,
@@ -272,7 +280,7 @@ export function registerOpenVikingMemoryTools(deps: OpenVikingMemoryToolsDeps):
         }
         const top = candidates[0];
         if (candidates.length === 1 && clampScore(top.score) >= 0.85) {
-          await client.deleteUri(top.uri, session.agentId);
+          await client.deleteUri(top.uri, session.actorPeerId);
           return {
             content: [{ type: "text", text: `Forgotten: ${top.uri}` }],
             details: { action: "deleted", uri: top.uri, score: top.score ?? 0 },

package/plugin/openviking-query-runtime.ts

@@ -445,7 +445,7 @@ export function createOpenVikingQueryRuntime<TQueryConfigContext>(deps: OpenViki
       sessionId: traceCtx?.sessionId,
       sessionKey: traceCtx?.sessionKey,
       ovSessionId: traceCtx?.ovSessionId,
-      agentId,
+      agentId: traceCtx?.agentId,
       source: "ov_search",
       operationType: "semantic_find",
       resourceTypes: [...new Set(searches.map((search) => search.resourceType).filter((resourceType): resourceType is RecallResourceType => resourceType !== "archive"))],

package/plugin/openviking-query-tools.ts

@@ -5,6 +5,7 @@ export type OpenVikingQueryToolContext = {
   sessionId?: string;
   agentId?: string;
   senderId?: string;
+  requesterSenderId?: string;
 };
 
 export type OpenVikingQuerySession = {
@@ -12,6 +13,7 @@ export type OpenVikingQuerySession = {
   sessionKey?: string;
   ovSessionId?: string;
   agentId: string;
+  actorPeerId?: string;
 };
 
 export type OVSearchInput = {
@@ -74,7 +76,7 @@ export function registerOpenVikingQueryTools(deps: OpenVikingQueryToolsDeps): vo
           query: String((params as { query?: unknown }).query ?? ""),
           uri: typeof params.uri === "string" ? params.uri : undefined,
           limit: typeof params.limit === "number" ? params.limit : undefined,
-        }, session.agentId, session);
+        }, session.actorPeerId, session);
       },
     }),
     { name: "ov_search" },
@@ -99,7 +101,7 @@ export function registerOpenVikingQueryTools(deps: OpenVikingQueryToolsDeps): vo
         const session = deps.resolvePluginSessionRouting(ctx);
         return deps.readOpenVikingContent({
           uri: String((params as { uri?: unknown }).uri ?? ""),
-        }, session.agentId);
+        }, session.actorPeerId);
       },
     }),
     { name: "ov_read" },
@@ -125,7 +127,7 @@ export function registerOpenVikingQueryTools(deps: OpenVikingQueryToolsDeps): vo
         const uris = Array.isArray((params as { uris?: unknown }).uris)
           ? (params as { uris: unknown[] }).uris.map((uri) => String(uri))
           : [];
-        return deps.multiReadOpenVikingContent({ uris }, session.agentId);
+        return deps.multiReadOpenVikingContent({ uris }, session.actorPeerId);
       },
     }),
     { name: "ov_multi_read" },
@@ -153,7 +155,7 @@ export function registerOpenVikingQueryTools(deps: OpenVikingQueryToolsDeps): vo
           recursive: typeof params.recursive === "boolean" ? params.recursive : undefined,
           simple: typeof params.simple === "boolean" ? params.simple : undefined,
           limit: typeof params.limit === "number" ? params.limit : undefined,
-        }, session.agentId);
+        }, session.actorPeerId);
       },
     }),
     { name: "ov_list" },

package/plugin/openviking-recall-trace-runtime.ts

@@ -26,6 +26,7 @@ export type OpenVikingRecallTraceSession = {
   sessionKey?: string;
   ovSessionId?: string;
   agentId: string;
+  actorPeerId?: string;
 };
 
 export type OpenVikingRecallTraceQueryResult = {
@@ -248,11 +249,11 @@ export function createOpenVikingRecallTraceRuntime(deps: OpenVikingRecallTraceRu
       for (const fallbackQuery of fallbackIdentities) {
         const fallback = await deps.traceRecorder.queryWithFallback(fallbackQuery);
         if (fallback.entries.length > 0) {
-          return enrichTraceEntriesWithContent(fallback, shouldIncludeTraceContent(input), session.agentId);
+          return enrichTraceEntriesWithContent(fallback, shouldIncludeTraceContent(input), session.actorPeerId);
         }
       }
     }
-    return enrichTraceEntriesWithContent(base, shouldIncludeTraceContent(input), session.agentId);
+    return enrichTraceEntriesWithContent(base, shouldIncludeTraceContent(input), session.actorPeerId);
   };
 
   const handleUriDetail = async (request?: RecallTraceRouteRequest) => {
@@ -298,7 +299,7 @@ export function createOpenVikingRecallTraceRuntime(deps: OpenVikingRecallTraceRu
     }
     try {
       const client = await deps.getClient();
-      const content = await client.read(uri, toString(query.agentId) ?? session.agentId);
+      const content = await client.read(uri, session.actorPeerId);
       const text = typeof content === "string" ? content : JSON.stringify(content, null, 2);
       const chars = Array.from(text);
       const slice = chars.slice(offset, offset + contentLimit).join("");

package/plugin/openviking-recall-trace-tools.ts

@@ -11,6 +11,7 @@ export type OpenVikingRecallTraceToolContext = {
   sessionId?: string;
   agentId?: string;
   senderId?: string;
+  requesterSenderId?: string;
 };
 
 export type OpenVikingRecallTraceSession = {
@@ -18,6 +19,7 @@ export type OpenVikingRecallTraceSession = {
   sessionKey?: string;
   ovSessionId?: string;
   agentId: string;
+  actorPeerId?: string;
 };
 
 export type RecallTraceToolInput = {

package/plugin/openviking-session-routing-runtime.ts

@@ -2,6 +2,9 @@ import type { QueryConfigContext } from "../query-config.js";
 import {
   createSessionAgentResolver,
   openClawSessionToOvStorageId,
+  resolveOpenVikingActorPeerId,
+  sanitizeOpenVikingPeerId,
+  type OpenVikingPeerRole,
 } from "../routing/identity-routing.js";
 
 type Logger = {
@@ -10,6 +13,8 @@ type Logger = {
 
 export type SessionAgentLookup = {
   agentId?: string;
+  senderId?: string;
+  requesterSenderId?: string;
   sessionId?: string;
   sessionKey?: string;
   ovSessionId?: string;
@@ -20,13 +25,16 @@ export type PluginSessionRouting = {
   sessionKey?: string;
   ovSessionId?: string;
   agentId: string;
+  actorPeerId?: string;
 };
 
 export function createOpenVikingSessionRoutingRuntime(options: {
+  peerRole?: OpenVikingPeerRole;
   peerPrefix: string;
   logFindRequests: boolean;
   logger: Logger;
 }) {
+  const peerRole = options.peerRole ?? "assistant";
   const sessionAgentResolver = createSessionAgentResolver(options.peerPrefix);
 
   const rememberSessionAgentId = (ctx: SessionAgentLookup) => {
@@ -81,11 +89,17 @@ export function createOpenVikingSessionRoutingRuntime(options: {
     };
     rememberSessionAgentId(session);
 
+    const agentId = resolveAgentId(session.sessionId, session.sessionKey, session.ovSessionId);
     return {
       sessionId: session.sessionId,
       sessionKey: session.sessionKey,
       ovSessionId: session.ovSessionId,
-      agentId: resolveAgentId(session.sessionId, session.sessionKey, session.ovSessionId),
+      agentId,
+      actorPeerId: resolveOpenVikingActorPeerId({
+        peerRole,
+        personPeerId: sanitizeOpenVikingPeerId(ctx?.requesterSenderId ?? ctx?.senderId),
+        assistantPeerId: agentId,
+      }),
     };
   };