@openviking/openclaw-plugin 2026.7.11 → 2026.8.6

package/plugin/openviking-tool-result-tools.ts

@@ -27,7 +27,6 @@ export type OpenVikingToolResultClient = {
     sessionId: string,
     toolResultId: string,
     options: { offset: number; limit: number; includeMetadata: boolean },
-    agentId?: string,
   ) => Promise<{
     content: string;
     offset: number;
@@ -42,7 +41,6 @@ export type OpenVikingToolResultClient = {
     toolResultId: string,
     query: string,
     options: { limit: number; contextChars: number },
-    agentId?: string,
   ) => Promise<{
     tool_result_id: string;
     matches?: Array<{ offset: number; snippet: string }>;
@@ -50,7 +48,6 @@ export type OpenVikingToolResultClient = {
   listToolResults: (
     sessionId: string,
     options: { toolName?: string; limit: number },
-    agentId?: string,
   ) => Promise<{
     tool_results?: Array<{
       storage_uri?: string;
@@ -180,7 +177,6 @@ export function registerOpenVikingToolResultTools({
             session.ovSessionId,
             parsed.toolResultId,
             { offset, limit, includeMetadata: true },
-            session.agentId,
           );
           const returnedChars = result.content.length;
           const nextOffset = result.offset + returnedChars;
@@ -281,7 +277,6 @@ export function registerOpenVikingToolResultTools({
             parsed.toolResultId,
             query,
             { limit, contextChars },
-            session.agentId,
           );
           const matches = result.matches ?? [];
           const text = matches.length
@@ -354,7 +349,6 @@ export function registerOpenVikingToolResultTools({
           const result = await client.listToolResults(
             session.ovSessionId,
             { toolName, limit },
-            session.agentId,
           );
           const items = result.tool_results ?? [];
           const text = items.length

package/registries/openviking-tools.ts

@@ -1,6 +1,7 @@
 export type OpenVikingToolGroup =
   | "memory"
   | "resource_query"
+  | "experience"
   | "import"
   | "recall_trace"
   | "archive"
@@ -13,6 +14,8 @@ export type OpenVikingToolName =
   | "ov_read"
   | "ov_multi_read"
   | "ov_list"
+  | "search_experience"
+  | "read_experience"
   | "memory_recall"
   | "ov_recall_trace"
   | "memory_store"
@@ -44,6 +47,8 @@ export const OPENVIKING_TOOL_SPECS = [
   { name: "ov_read", group: "resource_query", defaultEnabled: true },
   { name: "ov_multi_read", group: "resource_query", defaultEnabled: true },
   { name: "ov_list", group: "resource_query", defaultEnabled: true },
+  { name: "search_experience", group: "experience", defaultEnabled: true },
+  { name: "read_experience", group: "experience", defaultEnabled: true },
   { name: "memory_recall", group: "memory", defaultEnabled: true },
   { name: "ov_recall_trace", group: "recall_trace", defaultEnabled: true },
   { name: "memory_store", group: "memory", defaultEnabled: true },
@@ -64,6 +69,7 @@ export const OPENVIKING_DEFAULT_ENABLED_TOOL_NAMES = OPENVIKING_TOOL_SPECS
 const OPENVIKING_TOOL_GROUP_ORDER: readonly OpenVikingToolGroup[] = [
   "memory",
   "resource_query",
+  "experience",
   "import",
   "recall_trace",
   "archive",

package/routing/identity-routing.ts

@@ -15,6 +15,47 @@ export type SessionAgentLookup = {
   ovSessionId?: string;
 };
 
+export type OpenVikingPeerRole = "none" | "assistant" | "person";
+
+export function sanitizeOpenVikingPeerId(raw?: string): string | undefined {
+  const normalized = raw
+    ?.trim()
+    .replace(/[^a-zA-Z0-9_-]+/g, "_")
+    .replace(/^_+|_+$/g, "")
+    .replace(/_+/g, "_");
+  return normalized || undefined;
+}
+
+export function resolveOpenVikingMessagePeerId(params: {
+  peerRole: OpenVikingPeerRole;
+  role?: string;
+  personPeerId?: string;
+  assistantPeerId?: string;
+}): string | undefined {
+  if (params.peerRole === "person" && params.role === "user") {
+    return params.personPeerId;
+  }
+  if (params.peerRole === "assistant" && params.role === "assistant") {
+    return params.assistantPeerId;
+  }
+  return undefined;
+}
+
+export function resolveOpenVikingActorPeerId(params: {
+  peerRole: OpenVikingPeerRole;
+  personPeerId?: string;
+  assistantPeerId?: string;
+}): string | undefined {
+  const actorPeerId = resolveOpenVikingMessagePeerId({
+    ...params,
+    role: params.peerRole === "person" ? "user" : "assistant",
+  });
+  if (params.peerRole === "person" && !actorPeerId) {
+    throw new Error("openviking: peer_role=person requires a sender identity");
+  }
+  return actorPeerId;
+}
+
 export type SessionAgentResolveBranch =
   | "session_resolved"
   | "config_only_fallback"

package/routing/memory-uri.ts

@@ -1,5 +1,6 @@
 const MEMORY_URI_PATTERNS = [
   /^viking:\/\/user\/(?:[^/]+(?:\/agent\/[^/]+)?\/)?memories(?:\/|$)/,
+  /^viking:\/\/user\/[^/]+\/peers\/[^/]+\/memories(?:\/|$)/,
   /^viking:\/\/agent\/(?:[^/]+(?:\/user\/[^/]+)?\/)?memories(?:\/|$)/,
 ];
 

package/services/context-lifecycle-service.ts

@@ -3,7 +3,13 @@ import { DEFAULT_PHASE2_POLL_TIMEOUT_MS, type OpenVikingClient, type OVMessage }
 import type { EffectiveQueryConfig } from "../query-config.js";
 import { buildAutoRecallContext, prepareRecallQuery } from "../auto-recall.js";
 import { toJsonLog } from "../memory-ranking.js";
-import { openClawSessionToOvStorageId } from "../routing/identity-routing.js";
+import {
+  openClawSessionToOvStorageId,
+  resolveOpenVikingActorPeerId,
+  resolveOpenVikingMessagePeerId,
+  sanitizeOpenVikingPeerId,
+  type OpenVikingPeerRole,
+} from "../routing/identity-routing.js";
 import { extractNewTurnMessages } from "../text-utils.js";
 import { estimateAgentMessageTokens, estimateTextTokens } from "../token-estimator.js";
 import {
@@ -26,7 +32,6 @@ export type CommitOpenVikingSessionParams = {
   sessionKey?: string;
   getClient: () => Promise<Pick<OpenVikingClient, "commitSession">>;
   logger: ContextEngineLifecycleLogger;
-  resolveAgentId: (sessionId: string, sessionKey?: string, ovSessionId?: string) => string;
   rememberSessionAgentId?: (ctx: {
     agentId?: string;
     sessionId?: string;
@@ -131,6 +136,7 @@ export type AfterTurnOpenVikingSessionParams = {
     commitTokenThresholdRatio: number;
     commitKeepRecentCount: number;
     logFindRequests: boolean;
+    peer_role?: OpenVikingPeerRole;
   };
   getClient: () => Promise<AfterTurnClient>;
   logger: ContextEngineLifecycleLogger;
@@ -177,7 +183,6 @@ function sleep(ms: number): Promise<void> {
 async function pollPhase2ExtractionOutcome(
   client: AfterTurnClient,
   taskId: string,
-  agentId: string,
   logger: ContextEngineLifecycleLogger,
   sessionLabel: string,
 ): Promise<void> {
@@ -185,7 +190,7 @@ async function pollPhase2ExtractionOutcome(
   try {
     while (Date.now() < deadline) {
       await sleep(PHASE2_POLL_INTERVAL_MS);
-      const task = await client.getTask(taskId, agentId).catch((e) => {
+      const task = await client.getTask(taskId).catch((e) => {
         logger.warn?.(`openviking: phase2 getTask failed task_id=${taskId}: ${String(e)}`);
         return null;
       });
@@ -340,7 +345,6 @@ export async function commitOpenVikingSession({
   sessionKey,
   getClient,
   logger,
-  resolveAgentId,
   rememberSessionAgentId,
   isBypassedSession,
 }: CommitOpenVikingSessionParams): Promise<boolean> {
@@ -358,10 +362,8 @@ export async function commitOpenVikingSession({
       sessionKey,
       ovSessionId: ovId,
     });
-    const agentId = resolveAgentId(sessionId, sessionKey, ovId);
     const commitResult = await client.commitSession(ovId, {
       wait: true,
-      agentId,
       keepRecentCount: 0,
     });
     const memCount = totalExtractedMemories(commitResult.memories_extracted);
@@ -492,6 +494,11 @@ export async function assembleOpenVikingSession({
       const client = await getClient();
       const routingRef = sessionId ?? sessionKey ?? ovSessionId;
       const agentId = resolveAgentId(routingRef, sessionKey, ovSessionId);
+      const actorPeerId = resolveOpenVikingActorPeerId({
+        peerRole: cfg.peer_role ?? "assistant",
+        personPeerId: sanitizeOpenVikingPeerId(sender.senderId),
+        assistantPeerId: agentId,
+      });
       const queryConfig = await queryConfigStore?.getEffective({
         agentId,
         sessionId,
@@ -503,6 +510,7 @@ export async function assembleOpenVikingSession({
         queryConfig,
         client,
         agentId,
+        actorPeerId,
         queryText: recallQuery.query,
         logger,
         verbose: (message) => logger.info(message),
@@ -553,9 +561,7 @@ export async function assembleOpenVikingSession({
 
   try {
     const client = await getClient();
-    const routingRef = sessionId ?? sessionKey ?? ovSessionId;
-    const agentId = resolveAgentId(routingRef, sessionKey, ovSessionId);
-    const ctx = await client.getSessionContext(ovSessionId, tokenBudget, agentId);
+    const ctx = await client.getSessionContext(ovSessionId, tokenBudget);
 
     const preAbstracts = ctx?.pre_archive_abstracts ?? [];
     const hasArchives = !!ctx?.latest_archive_overview || preAbstracts.length > 0;
@@ -899,14 +905,19 @@ export async function afterTurnOpenVikingSession({
           ovSessionId,
           msg.role,
           ovParts,
-          agentId,
+          undefined,
           createdAt,
-          msg.role === "user" ? senderRoleId : undefined,
+          resolveOpenVikingMessagePeerId({
+            peerRole: cfg.peer_role ?? "assistant",
+            role: msg.role,
+            personPeerId: senderRoleId,
+            assistantPeerId: agentId,
+          }),
         );
       }
     }
 
-    const session = await client.getSession(ovSessionId, agentId);
+    const session = await client.getSession(ovSessionId);
     const pendingTokens = session.pending_tokens ?? 0;
 
     const commitTokenThreshold = Math.floor(tokenBudget * cfg.commitTokenThresholdRatio);
@@ -926,7 +937,6 @@ export async function afterTurnOpenVikingSession({
 
     const commitResult = await client.commitSession(ovSessionId, {
       wait: false,
-      agentId,
       keepRecentCount: cfg.commitKeepRecentCount,
     });
     logger.info(
@@ -952,7 +962,7 @@ export async function afterTurnOpenVikingSession({
         `openviking: Phase2 memory extraction runs asynchronously on the server (task_id=${commitResult.task_id}). ` +
           "memories_extracted appears only after that task completes — not in this immediate response.",
       );
-      void pollPhase2ExtractionOutcome(client, commitResult.task_id, agentId, logger, ovSessionId);
+      void pollPhase2ExtractionOutcome(client, commitResult.task_id, logger, ovSessionId);
     }
   } catch (err) {
     logger.warn?.(`openviking: afterTurn failed: ${String(err)}`);
@@ -1033,7 +1043,7 @@ export async function compactOpenVikingSession({
   let preCommitEstimatedTokens: number | undefined;
   if (typeof tokensBeforeOriginal !== "number") {
     try {
-      const preCtx = await client.getSessionContext(ovSessionId, tokenBudget, agentId);
+      const preCtx = await client.getSessionContext(ovSessionId, tokenBudget);
       if (typeof preCtx.estimatedTokens === "number" && Number.isFinite(preCtx.estimatedTokens)) {
         preCommitEstimatedTokens = preCtx.estimatedTokens;
       }
@@ -1053,7 +1063,6 @@ export async function compactOpenVikingSession({
     );
     const commitResult = await client.commitSession(ovSessionId, {
       wait: true,
-      agentId,
       keepRecentCount: 0,
     });
     const memCount = totalExtractedMemories(commitResult.memories_extracted);
@@ -1129,7 +1138,7 @@ export async function compactOpenVikingSession({
     let contextFetchError: string | undefined;
 
     try {
-      const ctx = await client.getSessionContext(ovSessionId, tokenBudget, agentId);
+      const ctx = await client.getSessionContext(ovSessionId, tokenBudget);
       logger.info(
         `openviking: compact getSessionContext raw result for ${ovSessionId}: ` +
           JSON.stringify(ctx, null, 2),

package/services/context-message-adapter.ts

@@ -1,4 +1,5 @@
 import type { OVMessage } from "../client.js";
+import { sanitizeOpenVikingPeerId } from "../routing/identity-routing.js";
 import { sanitizeToolUseResultPairing } from "../session-transcript-repair.js";
 
 export type AgentMessage = {
@@ -8,15 +9,7 @@ export type AgentMessage = {
 };
 
 export function toRoleId(senderId: string | undefined): string | undefined {
-  if (!senderId) {
-    return undefined;
-  }
-  const normalized = senderId
-    .trim()
-    .replace(/[^a-zA-Z0-9_-]+/g, "_")
-    .replace(/^_+|_+$/g, "")
-    .replace(/_+/g, "_");
-  return normalized || undefined;
+  return sanitizeOpenVikingPeerId(senderId);
 }
 
 /**

package/skills/ov-experience-memory/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: ov-experience-memory
+description: >
+  Use OpenViking experience memories during task execution. Search relevant
+  experiences with search_experience, read selected experiences with
+  read_experience, and leave standard tool parts in the committed session so
+  OpenViking can report recall and injection usage.
+version: 2026.7.9
+tags:
+  - openviking
+  - experience-memory
+  - agent-memory
+  - usage-reporting
+---
+
+# OpenViking Experience Memory
+
+Use this skill when the current user request starts or continues an executable
+task, especially tasks involving tools, files, code changes, data operations,
+workflow decisions, or multi-step actions.
+
+Do not use this skill for casual chat, pure explanation, or one-off factual Q&A
+that does not require operational guidance.
+
+## Runtime Contract
+
+The agent runtime must expose two tools with these exact names:
+
+- `search_experience`
+- `read_experience`
+
+OpenViking usage reporting recognizes only completed tool parts with these exact
+tool names. Calls to generic `find`, `search`, `read`, `ov_search`, or `ov_read`
+do not count as experience recall or injection events.
+
+## Tool: search_experience
+
+Purpose: search reusable execution experiences from the OpenViking experience
+library before assembling task context.
+
+Input schema:
+
+```json
+{
+  "query": "string",
+  "limit": 5
+}
+```
+
+Output schema:
+
+```json
+{
+  "results": [
+    {
+      "uri": "viking://user/<current_user_id>/memories/experiences/example.md",
+      "title": "example",
+      "score": 0.82,
+      "snippet": "Short summary or matched situation"
+    }
+  ]
+}
+```
+
+Implementation:
+
+The runtime tool calls OpenViking `POST /api/v1/search/find` with `target_uri`
+fixed to the current-user shorthand `viking://user/memories/experiences/`.
+Callers provide only `query` and optional `limit`; they cannot override or pass
+`target_uri`. OpenViking resolves the fixed shorthand against the authenticated
+request user. Return only canonical experience memory URIs for that user; never
+hardcode `default` or another user ID.
+
+Usage reporting:
+
+A completed `search_experience` tool part is counted as an experience recall
+event for every `results[].uri` value.
+
+## Tool: read_experience
+
+Purpose: read the full Markdown body of a selected experience and inject it into
+the agent prompt as task execution guidance.
+
+Input schema:
+
+```json
+{
+  "uri": "viking://user/<current_user_id>/memories/experiences/example.md"
+}
+```
+
+Output schema:
+
+```json
+{
+  "uri": "viking://user/<current_user_id>/memories/experiences/example.md",
+  "content": "Experience Markdown body"
+}
+```
+
+Implementation:
+
+Call OpenViking `GET /api/v1/content/read?uri=<encoded_uri>` for the selected
+experience URI. Always pass the canonical URI returned by `search_experience`;
+do not construct a URI with a hardcoded user ID. The returned content should be
+inserted into the prompt as operational guidance, not as user profile facts.
+
+Usage reporting:
+
+A completed `read_experience` tool part is counted as an experience injection
+event for `tool_input.uri` or `tool_output.uri`. In this design, reading an
+experience through `read_experience` means the experience was injected into the
+prompt.
+
+## Recommended Flow
+
+1. When a task begins, build a short query from the latest user instruction,
+   current plan, active skill name, and important tool/environment context.
+2. Call `search_experience` before final prompt assembly.
+3. Review returned titles/snippets and select only experiences likely to affect
+   execution.
+4. Call `read_experience` for selected experience URIs.
+5. Inject the returned Markdown into the prompt under an explicit experience
+   section.
+6. Continue task execution.
+7. Commit the session normally. The committed session must include the
+   `search_experience` and `read_experience` tool parts so OpenViking can report
+   usage.
+
+## Prompt Injection Format
+
+Use a compact and explicit block:
+
+```text
+<openviking-experience-memory>
+The following guidance was retrieved from prior task execution experience.
+Use it as operational guidance. Do not treat it as user identity or preference.
+
+<experience uri="viking://user/<current_user_id>/memories/experiences/example.md">
+...experience markdown...
+</experience>
+</openviking-experience-memory>
+```
+
+## Commit Requirements
+
+The session committed to OpenViking must preserve tool parts with:
+
+- `tool_name`
+- `tool_status`
+- `tool_input`
+- `tool_output`
+- `tool_id`
+
+Only `tool_status == "completed"` is counted. Failed, cancelled, or skipped tool
+parts are ignored by usage reporting.