@openviking/openclaw-plugin 2026.9.4 → 2026.9.8-1

package/dist/services/context-lifecycle-service.js

@@ -243,8 +243,8 @@ export async function assembleOpenVikingSession({ sessionId, sessionKey, message
             const routingRef = sessionId ?? sessionKey ?? ovSessionId;
             const agentId = resolveAgentId(routingRef, sessionKey, ovSessionId);
             const actorPeerId = resolveOpenVikingActorPeerId({
-                peerRole: cfg.peer_role ?? "assistant",
-                personPeerId: sanitizeOpenVikingPeerId(sender.senderId),
+                peerRole: cfg.peer_role ?? "none",
+                senderPeerId: sanitizeOpenVikingPeerId(sender.senderId),
                 assistantPeerId: agentId,
             });
             const queryConfig = await queryConfigStore?.getEffective({
@@ -595,9 +595,9 @@ export async function afterTurnOpenVikingSession({ sessionId, sessionKey, messag
             });
             if (ovParts.length > 0) {
                 await client.addSessionMessage(ovSessionId, msg.role, ovParts, undefined, createdAt, resolveOpenVikingMessagePeerId({
-                    peerRole: cfg.peer_role ?? "assistant",
+                    peerRole: cfg.peer_role ?? "none",
                     role: msg.role,
-                    personPeerId: senderRoleId,
+                    senderPeerId: senderRoleId,
                     assistantPeerId: agentId,
                 }));
             }
@@ -671,7 +671,7 @@ function compactFailureResult(reason, tokensBefore, details) {
         },
     };
 }
-export async function compactOpenVikingSession({ sessionId, sessionKey, tokenBudget, currentTokenCount, force, compactionTarget, customInstructions, getClient, logger, resolveAgentId, isBypassedSession, diag, }) {
+export async function compactOpenVikingSession({ sessionId, sessionKey, tokenBudget, currentTokenCount, force, compactionTarget, customInstructions, getClient, logger, resolveAgentId, isBypassedSession, runtimeCompact, diag, }) {
     const ovSessionId = openClawSessionToOvStorageId(sessionId, sessionKey);
     diag("compact_entry", ovSessionId, {
         tokenBudget,
@@ -682,6 +682,18 @@ export async function compactOpenVikingSession({ sessionId, sessionKey, tokenBud
             customInstructions.trim().length > 0,
     });
     if (isBypassedSession({ sessionId, sessionKey })) {
+        // Bypassed sessions store nothing in OV, but the host still needs a real
+        // compaction (preflight hard-fails on an unknown skip reason), so hand the
+        // request to OpenClaw's native compactor.
+        const delegated = await runtimeCompact?.();
+        if (delegated) {
+            diag("compact_result", ovSessionId, {
+                ok: delegated.ok,
+                compacted: delegated.compacted,
+                reason: delegated.reason ?? "session_bypassed_runtime_compaction",
+            });
+            return delegated;
+        }
         diag("compact_result", ovSessionId, {
             ok: true,
             compacted: false,

package/dist/services/setup/probe-service.js

@@ -0,0 +1,112 @@
+import { resolveOpenVikingRequestHeaders, } from "../../request-headers.js";
+export const defaultSetupNetworkTransport = (url, init) => fetch(url, init);
+export function createSetupNetworkProbes({ pluginVersion, compatRange, checkVersionCompatibility, transport = defaultSetupNetworkTransport, timeoutMs = 10_000, }) {
+    return {
+        async probeApiKeyType(baseUrl, apiKey, configuredHeaders) {
+            if (!apiKey) {
+                return { keyType: "no_key", needsAccountId: false, needsUserId: false, detail: "No API key configured" };
+            }
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+            const sessionsUrl = `${baseUrl.replace(/\/+$/, "")}/api/v1/sessions?limit=1`;
+            try {
+                const configuredRequestHeaders = resolveOpenVikingRequestHeaders({ headers: configuredHeaders });
+                const headers = {};
+                headers["X-API-Key"] = apiKey;
+                Object.assign(headers, configuredRequestHeaders);
+                const response = await transport(sessionsUrl, {
+                    headers,
+                    signal: controller.signal,
+                });
+                if (response.ok) {
+                    return { keyType: "user_key", needsAccountId: false, needsUserId: false, detail: "API key has full user context" };
+                }
+                if ([400, 401, 403, 422].includes(response.status)) {
+                    let body = "";
+                    try {
+                        body = await response.text();
+                    }
+                    catch { /* ignore parse errors */ }
+                    const lower = body.toLowerCase();
+                    const needsAccount = /x-openviking-account|account[_ ]?id|account context|tenant/.test(lower);
+                    const needsUser = /x-openviking-user|user[_ ]?id|user context|user key/.test(lower);
+                    if (needsAccount || needsUser) {
+                        return {
+                            keyType: "root_key",
+                            needsAccountId: needsAccount,
+                            needsUserId: needsUser,
+                            detail: body.slice(0, 200),
+                        };
+                    }
+                    try {
+                        const probeHeaders = {
+                            "X-API-Key": apiKey,
+                            "X-OpenViking-Account": "__probe__",
+                            "X-OpenViking-User": "__probe__",
+                            ...configuredRequestHeaders,
+                        };
+                        const probe2 = await transport(sessionsUrl, {
+                            headers: probeHeaders,
+                            signal: controller.signal,
+                        });
+                        if (probe2.status !== response.status) {
+                            return {
+                                keyType: "root_key",
+                                needsAccountId: true,
+                                needsUserId: true,
+                                detail: body.slice(0, 200) || `HTTP ${response.status} -> ${probe2.status} after adding tenant headers`,
+                            };
+                        }
+                    }
+                    catch { /* ignore probe errors, fall through to unknown */ }
+                    if (response.status === 401 || response.status === 403) {
+                        return { keyType: "unknown", needsAccountId: false, needsUserId: false, detail: `HTTP ${response.status} - authentication failed, verify your API key` };
+                    }
+                    return { keyType: "unknown", needsAccountId: false, needsUserId: false, detail: `HTTP ${response.status}${body ? ` - ${body.slice(0, 160)}` : ""}` };
+                }
+                return { keyType: "unknown", needsAccountId: false, needsUserId: false, detail: `HTTP ${response.status}` };
+            }
+            catch (err) {
+                return { keyType: "unknown", needsAccountId: false, needsUserId: false, detail: String(err instanceof Error ? err.message : err) };
+            }
+            finally {
+                clearTimeout(timeoutId);
+            }
+        },
+        async checkServiceHealth(baseUrl, apiKey, configuredHeaders) {
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+            try {
+                const configuredRequestHeaders = resolveOpenVikingRequestHeaders({ headers: configuredHeaders });
+                const headers = {};
+                if (apiKey) {
+                    headers["X-API-Key"] = apiKey;
+                }
+                Object.assign(headers, configuredRequestHeaders);
+                const response = await transport(`${baseUrl.replace(/\/+$/, "")}/health`, {
+                    headers,
+                    signal: controller.signal,
+                });
+                if (response.ok) {
+                    try {
+                        const data = await response.json();
+                        const result = (data.result ?? data);
+                        const version = String(result.version ?? data.version ?? "");
+                        const compatibility = checkVersionCompatibility(version);
+                        return { ok: true, version, error: "", compatibility, pluginVersion, compatRange };
+                    }
+                    catch {
+                        return { ok: true, version: "", error: "", compatibility: "unknown", pluginVersion, compatRange };
+                    }
+                }
+                return { ok: false, version: "", error: `HTTP ${response.status}`, compatibility: "unknown", pluginVersion, compatRange };
+            }
+            catch (err) {
+                return { ok: false, version: "", error: String(err instanceof Error ? err.message : err), compatibility: "unknown", pluginVersion, compatRange };
+            }
+            finally {
+                clearTimeout(timeoutId);
+            }
+        },
+    };
+}

package/openclaw.plugin.json

@@ -80,14 +80,14 @@
       "help": "HTTP URL when mode is remote (or ${OPENVIKING_BASE_URL})"
     },
     "peer_role": {
-      "label": "Peer Role",
-      "placeholder": "assistant",
-      "help": "Controls which messages include peer_id: none, assistant, or person. New installs default to assistant."
+      "label": "Memory Scope (peer_role)",
+      "placeholder": "none",
+      "help": "Where peer-scoped memories are stored. none (default): viking://user/<user_id>/memories. assistant: viking://user/<user_id>/peers/<assistant_id>/memories. sender: viking://user/<user_id>/peers/<sender_id>/memories. Legacy person is accepted as sender."
     },
     "peer_prefix": {
       "label": "Peer Prefix",
       "placeholder": "optional-prefix",
-      "help": "Optional prefix for assistant peer_id values derived from OpenClaw runtime agent IDs."
+      "help": "Only used when Memory Scope is assistant. Prefix added to the peer id derived from the OpenClaw agent id."
     },
     "apiKey": {
       "label": "OpenViking API Key",
@@ -195,7 +195,7 @@
     "bypassSessionPatterns": {
       "label": "Bypass Session Patterns",
       "placeholder": "agent:*:cron:**",
-      "help": "Completely bypass OpenViking for matching session keys. Use * within one segment and ** across segments.",
+      "help": "Completely bypass OpenViking for matching session keys (no capture, recall, or commit; compaction falls back to OpenClaw's native compactor). Use * within one segment and ** across segments.",
       "advanced": true
     },
     "commitTokenThresholdRatio": {
@@ -279,10 +279,11 @@
         "enum": [
           "none",
           "assistant",
+          "sender",
           "person"
         ],
-        "default": "assistant",
-        "description": "Controls which session messages include peer_id."
+        "default": "none",
+        "description": "Memory scope. none: shared user memory. assistant: peer memory keyed by OpenClaw assistant id. sender: peer memory keyed by sender id. person is a legacy alias for sender. Also controls which session messages include peer_id."
       },
       "peer_prefix": {
         "type": "string",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openviking/openclaw-plugin",
-  "version": "2026.9.4",
+  "version": "2026.9.8-1",
   "displayName": "OpenViking",
   "description": "OpenClaw context-engine plugin — OpenViking AI memory, long-term memory, knowledge base, semantic search, RAG, context engine. 长期记忆 · 知识库 · 语义检索 · 上下文引擎",
   "type": "module",
@@ -77,11 +77,5 @@
       "openclawVersion": "2026.5.27",
       "pluginSdkVersion": "2026.5.27"
     }
-  },
-  "devDependencies": {
-    "@types/node": "^25.3.5",
-    "@volcengine/tos-sdk": "^2.9.1",
-    "typescript": "^5.8.0",
-    "vitest": "^4.1.0"
   }
 }

package/plugin/openclaw-runtime-compaction.ts

@@ -0,0 +1,41 @@
+// Bridge to OpenClaw's built-in compactor for sessions that bypass OpenViking.
+// The host exports `delegateCompactionToRuntime` from `openclaw/plugin-sdk/core`
+// (present since the earliest supported host); it is resolved lazily because the
+// plugin builds without the host SDK installed.
+
+export type RuntimeCompactionResult = {
+  ok: boolean;
+  compacted: boolean;
+  reason?: string;
+  result?: {
+    summary?: string;
+    firstKeptEntryId?: string;
+    tokensBefore: number;
+    tokensAfter?: number;
+    details?: unknown;
+  };
+};
+
+export type RuntimeCompactionDelegate = (
+  params: Record<string, unknown>,
+) => Promise<RuntimeCompactionResult>;
+
+const PLUGIN_SDK_CORE_SPECIFIER = "openclaw/plugin-sdk/core";
+
+let cached: Promise<RuntimeCompactionDelegate | undefined> | undefined;
+
+export function loadRuntimeCompactionDelegate(): Promise<RuntimeCompactionDelegate | undefined> {
+  cached ??= (async () => {
+    try {
+      const mod = (await import(PLUGIN_SDK_CORE_SPECIFIER)) as {
+        delegateCompactionToRuntime?: unknown;
+      };
+      return typeof mod?.delegateCompactionToRuntime === "function"
+        ? (mod.delegateCompactionToRuntime as RuntimeCompactionDelegate)
+        : undefined;
+    } catch {
+      return undefined;
+    }
+  })();
+  return cached;
+}

package/plugin/openviking-client-runtime.ts

@@ -9,7 +9,7 @@ type Logger = {
 type ClientRuntimeConfig = {
   baseUrl: string;
   apiKey: string;
-  peer_role: "none" | "assistant" | "person";
+  peer_role: "none" | "assistant" | "sender";
   peer_prefix: string;
   timeoutMs: number;
   accountId?: string;

package/plugin/openviking-memory-tools.ts

@@ -114,7 +114,7 @@ export function registerOpenVikingMemoryTools(deps: OpenVikingMemoryToolsDeps):
           const peerId = resolveOpenVikingMessagePeerId({
             peerRole: deps.peerRole,
             role,
-            personPeerId: session.actorPeerId,
+            senderPeerId: session.actorPeerId,
             assistantPeerId: session.actorPeerId,
           });
           await client.addSessionMessage(

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

@@ -34,7 +34,7 @@ export function createOpenVikingSessionRoutingRuntime(options: {
   logFindRequests: boolean;
   logger: Logger;
 }) {
-  const peerRole = options.peerRole ?? "assistant";
+  const peerRole = options.peerRole ?? "none";
   const sessionAgentResolver = createSessionAgentResolver(options.peerPrefix);
 
   const rememberSessionAgentId = (ctx: SessionAgentLookup) => {
@@ -97,7 +97,7 @@ export function createOpenVikingSessionRoutingRuntime(options: {
       agentId,
       actorPeerId: resolveOpenVikingActorPeerId({
         peerRole,
-        personPeerId: sanitizeOpenVikingPeerId(ctx?.requesterSenderId ?? ctx?.senderId),
+        senderPeerId: sanitizeOpenVikingPeerId(ctx?.requesterSenderId ?? ctx?.senderId),
         assistantPeerId: agentId,
       }),
     };

package/routing/identity-routing.ts

@@ -15,7 +15,7 @@ export type SessionAgentLookup = {
   ovSessionId?: string;
 };
 
-export type OpenVikingPeerRole = "none" | "assistant" | "person";
+export type OpenVikingPeerRole = "none" | "assistant" | "sender";
 
 export function sanitizeOpenVikingPeerId(raw?: string): string | undefined {
   const normalized = raw
@@ -29,11 +29,11 @@ export function sanitizeOpenVikingPeerId(raw?: string): string | undefined {
 export function resolveOpenVikingMessagePeerId(params: {
   peerRole: OpenVikingPeerRole;
   role?: string;
-  personPeerId?: string;
+  senderPeerId?: string;
   assistantPeerId?: string;
 }): string | undefined {
-  if (params.peerRole === "person" && params.role === "user") {
-    return params.personPeerId;
+  if (params.peerRole === "sender" && params.role === "user") {
+    return params.senderPeerId;
   }
   if (params.peerRole === "assistant" && params.role === "assistant") {
     return params.assistantPeerId;
@@ -43,15 +43,15 @@ export function resolveOpenVikingMessagePeerId(params: {
 
 export function resolveOpenVikingActorPeerId(params: {
   peerRole: OpenVikingPeerRole;
-  personPeerId?: string;
+  senderPeerId?: string;
   assistantPeerId?: string;
 }): string | undefined {
   const actorPeerId = resolveOpenVikingMessagePeerId({
     ...params,
-    role: params.peerRole === "person" ? "user" : "assistant",
+    role: params.peerRole === "sender" ? "user" : "assistant",
   });
-  if (params.peerRole === "person" && !actorPeerId) {
-    throw new Error("openviking: peer_role=person requires a sender identity");
+  if (params.peerRole === "sender" && !actorPeerId) {
+    throw new Error("openviking: peer_role=sender requires a sender identity");
   }
   return actorPeerId;
 }

package/services/context-lifecycle-service.ts

@@ -117,6 +117,8 @@ export type CompactOpenVikingSessionParams = {
   logger: ContextEngineLifecycleLogger;
   resolveAgentId: (sessionId: string, sessionKey?: string, ovSessionId?: string) => string;
   isBypassedSession: (params: { sessionId?: string; sessionKey?: string }) => boolean;
+  /** Host-native compaction for bypassed sessions; resolves undefined when unavailable. */
+  runtimeCompact?: () => Promise<CompactOpenVikingSessionResult | undefined>;
   diag: (stage: string, sessionId: string, data: Record<string, unknown>) => void;
 };
 
@@ -497,8 +499,8 @@ export async function assembleOpenVikingSession({
       const routingRef = sessionId ?? sessionKey ?? ovSessionId;
       const agentId = resolveAgentId(routingRef, sessionKey, ovSessionId);
       const actorPeerId = resolveOpenVikingActorPeerId({
-        peerRole: cfg.peer_role ?? "assistant",
-        personPeerId: sanitizeOpenVikingPeerId(sender.senderId),
+        peerRole: cfg.peer_role ?? "none",
+        senderPeerId: sanitizeOpenVikingPeerId(sender.senderId),
         assistantPeerId: agentId,
       });
       const queryConfig = await queryConfigStore?.getEffective({
@@ -910,9 +912,9 @@ export async function afterTurnOpenVikingSession({
           undefined,
           createdAt,
           resolveOpenVikingMessagePeerId({
-            peerRole: cfg.peer_role ?? "assistant",
+            peerRole: cfg.peer_role ?? "none",
             role: msg.role,
-            personPeerId: senderRoleId,
+            senderPeerId: senderRoleId,
             assistantPeerId: agentId,
           }),
         );
@@ -1014,6 +1016,7 @@ export async function compactOpenVikingSession({
   logger,
   resolveAgentId,
   isBypassedSession,
+  runtimeCompact,
   diag,
 }: CompactOpenVikingSessionParams): Promise<CompactOpenVikingSessionResult> {
   const ovSessionId = openClawSessionToOvStorageId(sessionId, sessionKey);
@@ -1027,6 +1030,18 @@ export async function compactOpenVikingSession({
   });
 
   if (isBypassedSession({ sessionId, sessionKey })) {
+    // Bypassed sessions store nothing in OV, but the host still needs a real
+    // compaction (preflight hard-fails on an unknown skip reason), so hand the
+    // request to OpenClaw's native compactor.
+    const delegated = await runtimeCompact?.();
+    if (delegated) {
+      diag("compact_result", ovSessionId, {
+        ok: delegated.ok,
+        compacted: delegated.compacted,
+        reason: delegated.reason ?? "session_bypassed_runtime_compaction",
+      });
+      return delegated;
+    }
     diag("compact_result", ovSessionId, {
       ok: true,
       compacted: false,

package/services/setup/setup-flow.ts

@@ -13,6 +13,8 @@ import {
 
 export type { SetupIO, SlotActivationResult };
 
+type SetupPeerRole = "none" | "assistant" | "sender" | "person";
+
 export type VersionCompatibility = "compatible" | "server_too_old" | "server_too_new" | "unknown";
 
 export type HealthResult = {
@@ -38,7 +40,7 @@ export type SetupResult = {
     mode: string;
     baseUrl: string;
     apiKey?: string;
-    peer_role?: "none" | "assistant" | "person";
+    peer_role?: SetupPeerRole;
     peer_prefix?: string;
     accountId?: string;
     userId?: string;
@@ -57,7 +59,7 @@ export type StatusResult = {
     mode: string;
     baseUrl: string;
     hasApiKey: boolean;
-    peer_role?: "none" | "assistant" | "person";
+    peer_role?: SetupPeerRole;
     peer_prefix?: string;
     hasAccountId: boolean;
     hasUserId: boolean;
@@ -71,7 +73,7 @@ export type SetupParams = {
   baseUrl: string;
   apiKey?: string;
   headers?: OpenVikingRequestHeaders;
-  peerRole?: "none" | "assistant" | "person";
+  peerRole?: SetupPeerRole;
   peerPrefix?: string;
   accountId?: string;
   userId?: string;
@@ -85,7 +87,7 @@ export type InteractiveRemoteConfigParams = {
   baseUrl: string;
   apiKey?: string;
   headers?: OpenVikingRequestHeaders;
-  peerRole?: "none" | "assistant" | "person";
+  peerRole?: SetupPeerRole;
   peerPrefix?: string;
   accountId?: string;
   userId?: string;
@@ -315,7 +317,7 @@ export function createOpenVikingSetupService({
           baseUrl,
           ...(apiKey ? { apiKey: maskKey(apiKey) } : {}),
           ...(headers ? { headers } : {}),
-          ...(existing.peer_role ? { peer_role: String(existing.peer_role) as "none" | "assistant" | "person" } : {}),
+          ...(existing.peer_role ? { peer_role: String(existing.peer_role) as SetupPeerRole } : {}),
           ...(existing.peer_prefix ? { peer_prefix: String(existing.peer_prefix) } : {}),
           ...(existing.accountId ? { accountId: String(existing.accountId) } : {}),
           ...(existing.userId ? { userId: String(existing.userId) } : {}),
@@ -346,7 +348,7 @@ export function createOpenVikingSetupService({
           mode: String(existing.mode ?? "remote"),
           baseUrl,
           hasApiKey: !!existing.apiKey,
-          ...(existing.peer_role ? { peer_role: String(existing.peer_role) as "none" | "assistant" | "person" } : {}),
+          ...(existing.peer_role ? { peer_role: String(existing.peer_role) as SetupPeerRole } : {}),
           ...(existing.peer_prefix ? { peer_prefix: String(existing.peer_prefix) } : {}),
           hasAccountId: !!existing.accountId,
           hasUserId: !!existing.userId,

package/skills/install-openviking-memory/SKILL.md

@@ -106,7 +106,7 @@ Send this message:
 > 我需要 3 条信息，不知道的可以问你的管理员：
 > 1. **OpenViking 服务地址** —— 例如 `https://ov.example.com` 或 `http://192.168.1.100:1933`，本机服务可以直接说"本机"
 > 2. **API Key** —— 用来鉴权；服务没开认证可以说"没有"
-> 3. **Agent 标识前缀**（可选） —— 用于区分多个 agent 的记忆命名空间，留空就用默认
+> 3. **记忆归属**（可选） —— 所有对话共用 user 记忆（默认），还是在 `peers/<assistant_id>` 或 `peers/<sender_id>` 下分开存放
 >
 > 先告诉我服务地址吧？
 
@@ -115,7 +115,7 @@ Send this message:
 > I need 3 things (ask your admin if unsure):
 > 1. **OpenViking server URL** — e.g. `https://ov.example.com` or `http://192.168.1.100:1933`. For a local server, just say "local".
 > 2. **API Key** — for auth. Say "none" if the server has no auth.
-> 3. **peer prefix** (optional) — used to namespace memories across agents. Leave blank for default.
+> 3. **Memory scope** (optional) — shared user memory (default), or peer memory under `peers/<assistant_id>` / `peers/<sender_id>`.
 >
 > What's the server URL?
 
@@ -141,15 +141,36 @@ Collect 3 values through natural conversation. Be flexible: if the user gives se
 - "no" / "none" / "没有" / "空" / empty → `API_KEY=""` (you will skip the flag later).
 - Otherwise store as-is.
 
-### 4c. `PEER_PREFIX` (OPTIONAL)
+### 4c. `PEER_ROLE` (OPTIONAL)
+
+> (CN) 记忆要存在哪一层？默认共享在 `viking://user/<user_id>/memories`（`none`）。也可以按 OpenClaw 助手存到 `.../peers/<assistant_id>/memories`（`assistant`），或按发送者存到 `.../peers/<sender_id>/memories`（`sender`）。
+> (EN) Where should memory live? The default is shared `viking://user/<user_id>/memories` (`none`). You can instead use `.../peers/<assistant_id>/memories` (`assistant`) or `.../peers/<sender_id>/memories` (`sender`).
+
+Default to `none`. **Never silently pick another value** — the three options mean different storage layouts and are awkward to change later:
+
+| Value | Concrete layout | Choose it when |
+|---|---|---|
+| `none` (default) | Shared memory under `viking://user/<user_id>/memories/...`; no concrete `peers/<peer_id>/memories` subtree is used. | General case. All conversations for this OpenViking user share user-level memory. |
+| `assistant` | Assistant-attributed peer memory under `viking://user/<user_id>/peers/<assistant_id>/memories/...`, keyed by the resolved OpenClaw agent id (fallback `main`; optional prefix supported). | **Human as OpenViking user**: one human uses multiple assistants and wants their peer memories separated. Example: Alice's `main` and `research` assistants use `.../peers/main/...` and `.../peers/research/...`. |
+| `sender` | Sender-attributed peer memory under `viking://user/<user_id>/peers/<sender_id>/memories/...`, keyed by the sender identity supplied by OpenClaw. | **Agent as OpenViking user**: one agent talks to multiple humans and wants their peer memories separated. Example: `support-agent` stores `customer-42` and `customer-99` under different peer subtrees. |
+
+`person` is a legacy alias for `sender`. Accept it from an existing config or explicit user input, but normalize/write new setup values as `sender`.
+
+OpenViking initializes the managed `peers/` container for every user. Do not tell the user that `none` removes that container: it only avoids a concrete peer memory subtree. With `assistant` or `sender`, actor-peer recall includes shared user memory plus the current peer memory; it hides other peer subtrees. Changing this setting does not move existing memories.
+
+- Empty / "default" / "默认" / "共用" → leave unset (plugin defaults to `none`).
+- Otherwise pass `--peer-role none|assistant|sender`. Treat explicit legacy `person` as `sender`. Any other value → ask again.
+
+### 4d. `PEER_PREFIX` (OPTIONAL, only when `PEER_ROLE=assistant`)
 
 > (CN) 想给这个 agent 一个记忆前缀吗？留空就用默认。只能用字母、数字、`_`、`-`。
 > (EN) Want to set an peer prefix? Leave blank for the default. Letters, digits, `_`, `-` only.
 
+- Only meaningful when `PEER_ROLE=assistant`; skip the question otherwise.
 - Empty / "default" / "默认" → leave unset (plugin defaults to `""`).
 - Otherwise validate against `/^[A-Za-z0-9_-]+$/`. If invalid, ask again.
 
-### 4d. (Conditional) Multi-Tenant Root-Key Fields
+### 4e. (Conditional) Multi-Tenant Root-Key Fields
 
 Only ask for these if STEP 7 detects a root key (`Root API key detected. Missing: --account-id, --user-id`). Don't ask up front.
 
@@ -259,14 +280,15 @@ Tell the user:
 Run the installer with `npx` (no global install needed):
 
 ```bash
-npx -y openclaw-openviking-setup-helper@latest --base-url BASE_URL [--api-key API_KEY] [--peer-prefix PEER_PREFIX] [--account-id ACCOUNT_ID] [--user-id USER_ID]
+npx -y openclaw-openviking-setup-helper@latest --base-url BASE_URL [--api-key API_KEY] [--peer-role PEER_ROLE] [--peer-prefix PEER_PREFIX] [--account-id ACCOUNT_ID] [--user-id USER_ID]
 ```
 
 Build the flag list according to what the user gave you:
 
 - Always pass `--base-url BASE_URL`.
 - Pass `--api-key API_KEY` only if `API_KEY` is non-empty.
-- Pass `--peer-prefix PEER_PREFIX` only if the user gave one.
+- Pass `--peer-role PEER_ROLE` only if the user chose `assistant` or `sender`; omit it for the `none` default. Normalize legacy `person` to `sender` first.
+- Pass `--peer-prefix PEER_PREFIX` only if the user gave one and `PEER_ROLE=assistant`.
 - `--account-id` / `--user-id` only if the root-key path requires them.
 
 `ov-install` will, in one shot:
@@ -287,14 +309,15 @@ If `ov-install` exits non-zero, capture the last 30 lines of its output, show th
 Run the setup wizard non-interactively. Build flags from collected values:
 
 ```bash
-openclaw openviking setup --base-url BASE_URL --json [--api-key API_KEY] [--peer-prefix PEER_PREFIX] [--account-id ACCOUNT_ID] [--user-id USER_ID] [--allow-offline] [--force-slot]
+openclaw openviking setup --base-url BASE_URL --json [--api-key API_KEY] [--peer-role PEER_ROLE] [--peer-prefix PEER_PREFIX] [--account-id ACCOUNT_ID] [--user-id USER_ID] [--allow-offline] [--force-slot]
 ```
 
 Rules:
 
 - `--base-url BASE_URL` is **required** under `--json`. Without it, the wizard prints `--json requires --base-url for non-interactive mode`.
 - `--api-key` only if `API_KEY` is non-empty.
-- `--peer-prefix` only if the user gave one. Use **`--peer-prefix`** for assistant peer prefixes; the old ID-style setup flag is no longer supported.
+- `--peer-role` only if the user chose `assistant` or `sender`; omit it for the `none` default. Normalize legacy `person` to `sender` first.
+- `--peer-prefix` only if the user gave one and `--peer-role assistant` is in play. Use **`--peer-prefix`** for assistant peer prefixes; the old ID-style setup flag is no longer supported.
 - `--account-id` / `--user-id` only after STEP 7 root-key detection (see below).
 - `--allow-offline` only if the user explicitly approved it in STEP 5.
 - `--force-slot` **never** in the first attempt. Add only after the user confirms (see slot_blocked handling below).
@@ -583,8 +606,8 @@ These are the keys under `plugins.entries.openviking.config` in `openclaw.json`.
 | `mode` | `"remote"` (forced by plugin) | Always remote in this skill. Don't set manually. |
 | `baseUrl` | `http://127.0.0.1:1933` | OpenViking server URL. |
 | `apiKey` | — | API key. Optional if server has no auth. |
-| `peer_role` | `assistant` | Peer identity mode: `none`, `assistant`, or `person`. Session messages use body `peer_id`; data-plane recall/search uses `X-OpenViking-Actor-Peer`. |
-| `peer_prefix` | `""` | Optional prefix for assistant `peer_id` / actor peer values when `peer_role=assistant`. Letters / digits / `_` / `-`. |
+| `peer_role` | `none` | Memory scope: `none` (shared `viking://user/<user_id>/memories`), `assistant` (`.../peers/<assistant_id>/memories`), or `sender` (`.../peers/<sender_id>/memories`). Legacy `person` is accepted as `sender`. Session messages use body `peer_id`; data-plane recall/search uses `X-OpenViking-Actor-Peer`. |
+| `peer_prefix` | `""` | Optional prefix for assistant `peer_id` / actor peer values. Only used when `peer_role=assistant`. Letters / digits / `_` / `-`. |
 | `accountId` | — | Required when `apiKey` is a root key. |
 | `userId` | — | Required when `apiKey` is a root key. |
 | `targetUri` | `viking://~/memories` | Default search scope URI. |

package/skills/openviking-context-database/SKILL.md

@@ -64,7 +64,7 @@ Core config lives under `plugins.entries.openviking.config`:
 |---|---:|---|
 | `baseUrl` | `http://127.0.0.1:1933` | OpenViking HTTP endpoint. Can also come from `OPENVIKING_BASE_URL` / `OPENVIKING_URL`. |
 | `apiKey` | empty | Optional API key. Can also come from `OPENVIKING_API_KEY`. |
-| `peer_role` | `assistant` | Peer identity mode: `none`, `assistant`, or `person`. Session messages use body `peer_id`; data-plane recall/search uses `X-OpenViking-Actor-Peer`. |
+| `peer_role` | `none` | Memory scope: `none` (shared `viking://user/<user_id>/memories`), `assistant` (assistant-attributed memory under `.../peers/<assistant_id>/memories`), or `sender` (sender-attributed memory under `.../peers/<sender_id>/memories`). Legacy `person` is accepted as `sender`. |
 | `peer_prefix` | empty | Optional prefix for assistant `peer_id` / actor peer values when `peer_role=assistant`. |
 | `accountId` / `userId` | empty | Advanced tenant identity headers for root-key or trusted deployments. |
 | `targetUri` | `viking://~/memories` | Default search scope for legacy targeted memory search. |
@@ -95,7 +95,7 @@ openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --json
 Useful variants:
 
 ```bash
-openclaw openviking setup --base-url <URL> --api-key <KEY> --peer-prefix openclaw-prod --json
+openclaw openviking setup --base-url <URL> --api-key <KEY> --peer-role assistant --peer-prefix openclaw-prod --json
 openclaw openviking setup --base-url <URL> --api-key <ROOT_KEY> --account-id <ACCOUNT_ID> --user-id <USER_ID> --json
 openclaw openviking setup --base-url <URL> --api-key <KEY> --recall-target-types resource --json
 openclaw openviking setup --base-url <URL> --api-key <KEY> --allow-offline --json