@openviking/openclaw-plugin 2026.9.2 → 2026.9.4-1

package/INSTALL-AGENT.md

@@ -42,6 +42,7 @@ Before setup, determine:
 | --- | --- | --- |
 | OpenViking base URL | Yes | Ask user or read `OPENVIKING_BASE_URL` |
 | API key | Usually | Ask user or read `OPENVIKING_API_KEY` |
+| Memory scope | Optional; default `none` | Ask whether memory is shared, separated by assistant, or separated by sender. Use `sender`; accept legacy `person` as an alias. |
 | Account ID | Only for root API keys | Ask user if setup reports root-key tenant context is needed |
 | User ID | Only for root API keys | Ask user if setup reports root-key tenant context is needed |
 | Slot replacement approval | Only if another context engine owns the slot | Ask user before using `--force-slot` |
@@ -73,6 +74,23 @@ Run setup with `--json` whenever possible:
 openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --json
 ```
 
+Choose memory scope before building that command:
+
+| Value | Concrete layout | Use when |
+| --- | --- | --- |
+| `none` (default; omit the flag) | Shared `viking://user/<user_id>/memories/...`; no concrete peer memory subtree | General case |
+| `assistant` | Assistant-attributed peer memory under `.../peers/<assistant_id>/memories/...` | A human is the OpenViking user and uses multiple OpenClaw assistants |
+| `sender` | Sender-attributed peer memory under `.../peers/<sender_id>/memories/...` | An agent is the OpenViking user and receives messages from multiple humans |
+
+`person` is a legacy alias for `sender`. Accept it from existing config or user input, but write `sender` in new setup commands. OpenViking initializes the managed `peers/` container for every user; `none` only means that no concrete `peers/<peer_id>/memories` subtree is used. Actor-peer recall includes shared user memory plus the current peer memory, and changing the scope does not move existing memories.
+
+Examples:
+
+```bash
+openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --peer-role assistant --json
+openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --peer-role sender --json
+```
+
 Branch on the result:
 
 | JSON result | Meaning | Agent action |
@@ -96,10 +114,10 @@ openclaw openviking setup \
   --json
 ```
 
-Custom agent routing prefix (optional; only when the user explicitly requests a prefix):
+Custom assistant routing prefix (optional; only with `peer_role=assistant` and when the user explicitly requests a prefix):
 
 ```bash
-openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --peer-prefix <PREFIX> --json
+openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --peer-role assistant --peer-prefix <PREFIX> --json
 ```
 
 Slot replacement retry, only after user approval:
@@ -139,6 +157,7 @@ Also inspect:
 | `health.version` | Records server version |
 | `health.compatibility` | Determines whether to warn |
 | `config.hasApiKey` | Confirms whether an API key was saved |
+| `config.peer_role` | Confirms `none`, `assistant`, or canonical `sender` scope |
 | `config.peer_prefix` | Confirms configured peer prefix when present |
 
 ## Environment Detection
@@ -267,7 +286,8 @@ Core fields:
 | `mode` | Legacy compatibility field. Expected value: `remote`. |
 | `baseUrl` | OpenViking HTTP endpoint |
 | `apiKey` | OpenViking API key |
-| `peer_prefix` | Optional; prefix for OpenClaw agent IDs when set. Interactive setup accepts only letters, digits, `_`, and `-`. If unset, the plugin follows session agent IDs. |
+| `peer_role` | `none` (shared user memory), `assistant` (`peers/<assistant_id>`), or `sender` (`peers/<sender_id>`). Legacy `person` is accepted as `sender`. |
+| `peer_prefix` | Optional only with `peer_role=assistant`; prefix for OpenClaw agent IDs. Interactive setup accepts only letters, digits, `_`, and `-`. If unset, the plugin follows session agent IDs. |
 | `accountId` | Required for root API keys |
 | `userId` | Required for root API keys |
 
@@ -329,7 +349,8 @@ Existing config fields are preserved during migration. The new plugin reads old
 
 - `baseUrl`
 - `apiKey`
-- `peer_prefix`: optional; interactive setup accepts only letters, digits, `_`, and `-`
+- `peer_role`: optional; `none`, `assistant`, or `sender`; legacy `person` is accepted as `sender`
+- `peer_prefix`: optional only with `peer_role=assistant`; interactive setup accepts only letters, digits, `_`, and `-`
 
 ## Backup Path: ov-install
 

package/INSTALL-ZH.md

@@ -197,12 +197,30 @@ openclaw openviking setup \
 openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --force-slot --json
 ```
 
-如需给默认 assistant peer 路由增加前缀，可以额外传：
+根据 OpenViking user 代表谁来选择 `--peer-role`：
+
+| 值 | 存储示例 | 适用场景 |
+| --- | --- | --- |
+| `none`（默认） | `viking://user/alice/memories/...` | 该 OpenViking 用户下的所有对话共享 user-level 记忆，不使用具体 peer 的记忆子树。 |
+| `assistant` | `viking://user/alice/peers/main/memories/...` | OpenViking user 代表人，并希望把 assistant 归因的 peer 记忆按不同 OpenClaw 助手分开。 |
+| `sender` | `viking://user/support-agent/peers/customer-42/memories/...` | OpenViking user 代表 agent，并希望把 sender 归因的 peer 记忆按不同发送者分开。 |
+
+`person` 仍作为 `sender` 的旧配置别名被兼容；新配置请使用 `sender`。
+
+例如，让每个助手使用独立的 peer 记忆，并可选给 assistant id 加前缀：
 
 ```bash
 openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --peer-role assistant --peer-prefix <PREFIX> --json
 ```
 
+如果 OpenViking user 是 agent，按给它发消息的 sender 分开 peer 记忆：
+
+```bash
+openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --peer-role sender --json
+```
+
+OpenViking 会为每个用户初始化受管的 `peers/` 容器。`none` 表示插件不创建、也不路由到具体的 `peers/<peer_id>/memories` 子树。Actor-peer 召回同时包含用户共享记忆和当前 peer 记忆；切换配置不会搬迁已有记忆。
+
 #### 无法执行 CLI 时直接配置文件
 
 如果容器内无法执行 `openclaw` CLI，可以把以下字段合并到 OpenClaw 实际读取的配置文件。设置了 `OPENCLAW_CONFIG_PATH` 时使用该路径；否则通常是 `$OPENCLAW_STATE_DIR/openclaw.json`（默认 `~/.openclaw/openclaw.json`）。
@@ -300,7 +318,7 @@ plugins.entries.openviking.config
 | `mode` | `remote` | 兼容旧配置的字段。当前只支持 remote。 |
 | `baseUrl` | `http://127.0.0.1:1933` | OpenViking HTTP 地址 |
 | `apiKey` | 空 | OpenViking API key |
-| `peer_role` | `assistant` | Peer 身份模式：`none`、`assistant` 或 `person`。Session message 使用 body `peer_id`；数据面 recall/search 使用 `X-OpenViking-Actor-Peer`。 |
+| `peer_role` | `none` | 记忆归属：`none`（共享 `viking://user/<user_id>/memories`）、`assistant`（`.../peers/<assistant_id>/memories`）或 `sender`（`.../peers/<sender_id>/memories`）。旧值 `person` 作为 `sender` 的别名兼容。Session message 使用 body `peer_id`；数据面 recall/search 使用 `X-OpenViking-Actor-Peer`。 |
 | `peer_prefix` | 空 | `peer_role=assistant` 时 assistant `peer_id` / actor peer 值的可选前缀。 |
 | `accountId` | 空 | 使用 root API key 时需要 |
 | `userId` | 空 | 使用 root API key 时需要 |
@@ -325,7 +343,7 @@ openclaw config get plugins.entries.openviking.config
 | --- | --- | --- |
 | `baseUrl` | `http://127.0.0.1:1933` | 远端 OpenViking 服务地址 |
 | `apiKey` | 空 | 远端 OpenViking API Key；服务端未开启认证时可不填 |
-| `peer_role` | `assistant` | Peer 身份模式：`none`、`assistant` 或 `person`；session message 使用 body `peer_id`，数据面 recall/search 使用 `X-OpenViking-Actor-Peer` |
+| `peer_role` | `none` | 记忆归属：`none`、`assistant` 或 `sender`；旧值 `person` 作为 `sender` 的别名兼容。Session message 使用 body `peer_id`，数据面 recall/search 使用 `X-OpenViking-Actor-Peer` |
 | `peer_prefix` | 空 | `peer_role=assistant` 时 assistant `peer_id` / actor peer 值的可选前缀 |
 
 常见设置：
@@ -387,7 +405,7 @@ ov-install
 | `--current-version` | 查看 helper 记录的当前版本 |
 | `--base-url URL` | OpenViking 服务器地址（启用非交互模式） |
 | `--api-key KEY` | OpenViking API key |
-| `--peer-role ROLE` | Peer role：`none`、`assistant` 或 `person` |
+| `--peer-role ROLE` | 记忆归属：`none`、`assistant` 或 `sender`；旧值 `person` 作为 `sender` 的别名兼容 |
 | `--peer-prefix PREFIX` | assistant `peer_id` / actor peer 值的前缀 |
 | `--update` | 更新 helper 管理的安装 |
 

package/INSTALL.md

@@ -141,12 +141,30 @@ If another context engine already owns the slot, setup will not replace it by de
 openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --force-slot --json
 ```
 
-If you want assistant messages to carry a prefixed `peer_id` and data-plane recall/search requests to use the matching actor peer view, pass a prefix explicitly:
+Choose `--peer-role` from what the OpenViking user represents:
+
+| Value | Storage example | Use when |
+| --- | --- | --- |
+| `none` (default) | `viking://user/alice/memories/...` | All conversations for this OpenViking user share user-level memory. No peer-specific memory subtree is used. |
+| `assistant` | `viking://user/alice/peers/main/memories/...` | The OpenViking user is a human and assistant-attributed peer memory should be separated by OpenClaw assistant. |
+| `sender` | `viking://user/support-agent/peers/customer-42/memories/...` | The OpenViking user is an agent and sender-attributed peer memory should be separated by human sender. |
+
+`person` is still accepted as a legacy alias for `sender`. New configuration should use `sender`.
+
+For example, give each assistant its own peer memory and optionally namespace the assistant id:
 
 ```bash
 openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --peer-role assistant --peer-prefix <PREFIX> --json
 ```
 
+Or scope peer memory by the sender talking to an agent:
+
+```bash
+openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --peer-role sender --json
+```
+
+OpenViking initializes the managed `peers/` container for every user. `none` means the plugin does not create or route into a concrete `peers/<peer_id>/memories` subtree. Actor-peer recall includes shared user memory plus the current peer memory, and changing the setting does not move existing memories.
+
 #### Configure The File Directly When The CLI Is Unavailable
 
 If the `openclaw` CLI cannot run inside the container, merge the following fields into the config file that OpenClaw actually reads. Use `OPENCLAW_CONFIG_PATH` when it is set; otherwise the file is usually `$OPENCLAW_STATE_DIR/openclaw.json` (default: `~/.openclaw/openclaw.json`).
@@ -244,7 +262,7 @@ Core fields:
 | `mode` | `remote` | Legacy compatibility field. Only remote mode is supported. |
 | `baseUrl` | `http://127.0.0.1:1933` | OpenViking HTTP endpoint |
 | `apiKey` | empty | 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` (`.../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` | empty | Optional prefix for assistant `peer_id` / actor peer values when `peer_role=assistant`. |
 | `accountId` | empty | Required when using a root API key |
 | `userId` | empty | Required when using a root API key |
@@ -311,7 +329,7 @@ Useful backup/source flags:
 | `--current-version` | Print the version tracked by the helper |
 | `--base-url URL` | OpenViking server URL (enables non-interactive mode) |
 | `--api-key KEY` | OpenViking API key |
-| `--peer-role ROLE` | Peer role: `none`, `assistant`, or `person` |
+| `--peer-role ROLE` | Memory scope: `none`, `assistant`, or `sender`; legacy `person` is accepted as `sender` |
 | `--peer-prefix PREFIX` | Prefix for assistant `peer_id` / actor peer values |
 | `--update` | Update an existing helper-managed install |
 
@@ -356,7 +374,7 @@ The plugin connects to an existing remote OpenViking server.
 | --- | --- | --- |
 | `baseUrl` | `http://127.0.0.1:1933` | Remote OpenViking HTTP endpoint |
 | `apiKey` | empty | Optional OpenViking API key |
-| `peer_role` | `assistant` | Peer identity mode: `none`, `assistant`, or `person`; session messages use body `peer_id`, while data-plane recall/search uses `X-OpenViking-Actor-Peer` |
+| `peer_role` | `none` | Memory scope: `none`, `assistant`, or `sender`; legacy `person` is accepted as `sender`. Session messages use body `peer_id`, while data-plane recall/search uses `X-OpenViking-Actor-Peer` |
 | `peer_prefix` | empty | Optional prefix for assistant `peer_id` / actor peer values when `peer_role=assistant` |
 
 Common settings:

package/README.md

@@ -124,15 +124,26 @@ The main rules are:
 - reuse `sessionId` directly when it is already a UUID
 - prefer `sessionKey` when deriving a stable `ovSessionId`
 - normalize unsafe path characters, or fall back to a stable SHA-256 when needed
-- `peer_role=assistant` is the default and writes assistant messages with `peer_id=<sessionAgent>`; if `peer_prefix` is set, the value becomes `<peer_prefix>_<sessionAgent>`
-- `peer_role=none` disables peer message attribution and actor-peer routing
-- `peer_role=person` writes user messages with `peer_id` derived from OpenClaw sender identity; assistant messages do not get `peer_id`
-- data-plane recall/search/read/import/delete sends the same resolved peer identity as `X-OpenViking-Actor-Peer` when `peer_role` is `assistant` or `person`
+- `peer_role=none` is the default: messages have no peer attribution and memory stays in the shared user scope, for example `viking://user/alice/memories/...`; no peer-specific memory subtree is used
+- `peer_role=assistant` writes assistant messages with `peer_id=<sessionAgent>` and uses peer-scoped memory such as `viking://user/alice/peers/main/memories/...`; if `peer_prefix` is set, the peer id becomes `<peer_prefix>_<sessionAgent>`
+- `peer_role=sender` writes user messages with the OpenClaw sender identity as `peer_id` and uses peer-scoped memory such as `viking://user/support-agent/peers/customer-42/memories/...`; assistant messages do not get `peer_id`
+- `person` remains accepted as a legacy config alias for `sender`, but new configuration and documentation use `sender`
+- data-plane recall/search/read/import/delete sends the same resolved peer identity as `X-OpenViking-Actor-Peer` when `peer_role` is `assistant` or `sender`
 - when OpenClaw does not provide a session agent, use its default agent `main` for local session and assistant peer metadata
 - only add `X-OpenViking-Account` / `X-OpenViking-User` when `accountId` / `userId` are explicitly configured
 
 This matters because OpenViking tenant identity is account/user-scoped, while OpenClaw agent identity is runtime metadata.
 
+Choose the scope from what `viking://user/<user_id>` represents:
+
+| Model | Example | Result |
+| --- | --- | --- |
+| General/shared (`none`) | `user_id=alice` uses any OpenClaw assistant | Shared user memory under `viking://user/alice/memories/...` |
+| Human is the OpenViking user (`assistant`) | Alice uses OpenClaw assistants `main` and `research` | Assistant-scoped memories are separated under `.../peers/main/memories/...` and `.../peers/research/memories/...` |
+| Agent is the OpenViking user (`sender`) | `user_id=support-agent` receives messages from `customer-42` and `customer-99` | Sender-scoped memories are separated under `.../peers/customer-42/memories/...` and `.../peers/customer-99/memories/...` |
+
+OpenViking creates the managed `peers/` container as part of the user namespace. `none` means that the plugin does not create or route into a specific `peers/<peer_id>/memories` subtree. With `assistant` or `sender`, actor-peer recall includes the shared user memory plus the current peer's memory; changing the setting does not move existing memories.
+
 The recommended remote-mode configuration only needs:
 
 - `baseUrl`
@@ -143,7 +154,7 @@ The recommended remote-mode configuration only needs:
 In this setup:
 
 - `apiKey` should usually be a user key
-- new installs default to `peer_role=assistant`
+- new installs default to `peer_role=none`
 - `accountId` / `userId` are advanced options only when the deployment needs explicit identity headers, such as root-key or trusted-server flows
 
 ### User namespace

package/commands/setup.ts

@@ -84,8 +84,8 @@ const CONFIG_KEYS_TO_PRESERVE = [
   "logFindRequests",
 ] as const;
 
-type PeerRole = "none" | "assistant" | "person";
-const DEFAULT_SETUP_PEER_ROLE: PeerRole = "assistant";
+type PeerRole = "none" | "assistant" | "sender";
+const DEFAULT_SETUP_PEER_ROLE: PeerRole = "none";
 type RecallTargetType = "resource" | "user" | "agent";
 const ALLOWED_RECALL_TARGET_TYPES = ["resource", "user", "agent"] as const;
 
@@ -126,7 +126,8 @@ function isValidPeerPrefixInput(value: string): boolean {
 function normalizePeerRole(value: unknown): PeerRole | undefined {
   if (typeof value !== "string") return undefined;
   const role = value.trim().toLowerCase();
-  if (role === "none" || role === "assistant" || role === "person") return role;
+  if (role === "person") return "sender";
+  if (role === "none" || role === "assistant" || role === "sender") return role;
   return undefined;
 }
 
@@ -147,7 +148,7 @@ function resolveSetupPeerRole(value: unknown): PeerRole {
   if (value === undefined) return DEFAULT_SETUP_PEER_ROLE;
   const role = normalizePeerRole(value);
   if (role) return role;
-  throw new Error('peer_role must be "none", "assistant", or "person"');
+  throw new Error('peer_role must be "none", "assistant", or "sender" (legacy alias: "person")');
 }
 
 function normalizeSetupRecallTargetTypes(value: unknown): RecallTargetType[] | undefined {
@@ -206,9 +207,20 @@ async function askPeerRole(
   q: (prompt: string, def?: string) => Promise<string>,
   defaultValue: PeerRole,
 ): Promise<PeerRole> {
+  console.log(
+    `  ${tr(
+      zh,
+      "Memory scope — none (default): viking://user/<user_id>/memories, shared across all conversations; " +
+        "assistant: viking://user/<user_id>/peers/<assistant_id>/memories; " +
+        "sender: viking://user/<user_id>/peers/<sender_id>/memories (legacy alias: person).",
+      "记忆归属 —— none（默认）：viking://user/<user_id>/memories，所有对话共享；" +
+        "assistant：viking://user/<user_id>/peers/<assistant_id>/memories；" +
+        "sender：viking://user/<user_id>/peers/<sender_id>/memories（兼容旧值 person）。",
+    )}`,
+  );
   while (true) {
     const value = await q(
-      tr(zh, "Peer Role (none/assistant/person)", "Peer Role（none/assistant/person）"),
+      tr(zh, "Memory scope (none/assistant/sender)", "记忆归属（none/assistant/sender）"),
       defaultValue,
     );
     const role = normalizePeerRole(value);
@@ -216,8 +228,8 @@ async function askPeerRole(
     console.log(
       `  ✗ ${tr(
         zh,
-        'Peer Role must be "none", "assistant", or "person".',
-        'Peer Role 必须是 "none"、"assistant" 或 "person"。',
+        'Memory scope must be "none", "assistant", or "sender" (legacy "person" is also accepted).',
+        '记忆归属必须是 "none"、"assistant" 或 "sender"（也兼容旧值 "person"）。',
       )}`,
     );
   }
@@ -605,7 +617,7 @@ export function registerSetupCli(api: any): void {
         .option("--zh", "Chinese prompts")
         .option("--base-url <url>", "OpenViking server URL (enables non-interactive mode)")
         .option("--api-key <key>", "API key for authentication")
-        .option("--peer-role <role>", "Peer ID role: none, assistant, or person")
+        .option("--peer-role <role>", "Memory scope: none (shared), assistant (per assistant), or sender (per sender); person is a legacy alias")
         .option("--peer-prefix <prefix>", "Prefix for assistant peer_id values")
         .option("--account-id <id>", "Account ID (required for root API keys)")
         .option("--user-id <id>", "User ID (required for root API keys)")
@@ -1182,6 +1194,8 @@ async function setupRemote(
 export const __test__ = {
   isLegacyLocalMode,
   isValidPeerPrefixInput,
+  normalizePeerRole,
+  resolveSetupPeerRole,
   normalizeSetupRecallTargetTypes,
   activateContextEngineSlot,
   isContextEngineSlotActive,

package/config.ts

@@ -30,7 +30,8 @@ export type OpenVikingSecretRef =
 export type MemoryOpenVikingConfig = {
   mode?: "remote";
   baseUrl?: string;
-  peer_role?: "none" | "assistant" | "person";
+  /** `person` is a legacy alias for `sender`. */
+  peer_role?: "none" | "assistant" | "sender" | "person";
   peer_prefix?: string;
   apiKey?: string | OpenVikingSecretRef;
   /** Optional HTTP headers merged into every OpenViking request. */
@@ -127,10 +128,12 @@ export type MemoryOpenVikingConfig = {
 
 /** Runtime config after memoryOpenVikingConfigSchema.parse() has applied defaults. */
 export type ParsedMemoryOpenVikingConfig = Required<
-  Omit<MemoryOpenVikingConfig, "agentExperience" | "recallTargetTypes" | "apiKey">
+  Omit<MemoryOpenVikingConfig, "agentExperience" | "recallTargetTypes" | "apiKey" | "peer_role">
 > & {
   /** parse() resolves SecretRef values, so the runtime shape is always a plain string. */
   apiKey: string;
+  /** Runtime uses the canonical name; legacy `person` input normalizes to `sender`. */
+  peer_role: "none" | "assistant" | "sender";
   agentExperience: Required<NonNullable<MemoryOpenVikingConfig["agentExperience"]>>;
   recallTargetTypes: Array<"resource" | "user" | "agent">;
 };
@@ -152,7 +155,7 @@ const DEFAULT_COMMIT_TOKEN_THRESHOLD_RATIO = 0.5;
 const DEFAULT_COMMIT_KEEP_RECENT_COUNT = 10;
 const DEFAULT_BYPASS_SESSION_PATTERNS: string[] = [];
 const DEFAULT_EMIT_STANDARD_DIAGNOSTICS = false;
-const DEFAULT_PEER_ROLE = "assistant" as const;
+const DEFAULT_PEER_ROLE = "none" as const;
 const DEFAULT_PEER_PREFIX = "";
 const DEFAULT_TRACE_RECALL_DIR = "~/.openclaw/openviking/recall-traces";
 const DEFAULT_TRACE_RECALL_RETENTION_DAYS = 14;
@@ -292,16 +295,23 @@ function resolveSecret(
   }
 }
 
-function resolvePeerRole(configured: unknown) {
+function resolvePeerRole(configured: unknown): "none" | "assistant" | "sender" {
   if (typeof configured === "string") {
     const role = configured.trim().toLowerCase();
-    if (role === "none" || role === "assistant" || role === "person") {
+    if (role === "none" || role === "assistant" || role === "sender") {
       return role;
     }
-    throw new Error(`openviking peer_role must be "none", "assistant", or "person"`);
+    if (role === "person") {
+      return "sender";
+    }
+    throw new Error(
+      `openviking peer_role must be "none", "assistant", or "sender" (legacy alias: "person")`,
+    );
   }
   if (configured !== undefined) {
-    throw new Error(`openviking peer_role must be "none", "assistant", or "person"`);
+    throw new Error(
+      `openviking peer_role must be "none", "assistant", or "sender" (legacy alias: "person")`,
+    );
   }
   return DEFAULT_PEER_ROLE;
 }
@@ -776,14 +786,17 @@ export const memoryOpenVikingConfigSchema = {
       help: "HTTP URL when mode is remote (or use ${OPENVIKING_BASE_URL})",
     },
     peer_role: {
-      label: "Peer Role",
+      label: "Memory Scope (peer_role)",
       placeholder: DEFAULT_PEER_ROLE,
-      help: 'Controls which session messages get peer_id: "none", "assistant", or "person".',
+      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 applied to 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",

package/context-engine.ts

@@ -1,5 +1,5 @@
 import type { OpenVikingClient } from "./client.js";
-import type { MemoryOpenVikingConfig } from "./config.js";
+import type { ParsedMemoryOpenVikingConfig } from "./config.js";
 import type { RuntimeQueryConfigStore } from "./query-config.js";
 import {
   AUTO_RECALL_SOURCE_MARKER,
@@ -248,7 +248,7 @@ export function createMemoryOpenVikingContextEngine(params: {
   id: string;
   name: string;
   version?: string;
-  cfg: Required<MemoryOpenVikingConfig>;
+  cfg: ParsedMemoryOpenVikingConfig;
   logger: Logger;
   getClient: () => Promise<OpenVikingClient>;
   /** Extra args help match hook-populated routing when OpenClaw provides sessionKey / OV session id. */

package/dist/commands/setup.js

@@ -76,7 +76,7 @@ const CONFIG_KEYS_TO_PRESERVE = [
     "emitStandardDiagnostics",
     "logFindRequests",
 ];
-const DEFAULT_SETUP_PEER_ROLE = "assistant";
+const DEFAULT_SETUP_PEER_ROLE = "none";
 const ALLOWED_RECALL_TARGET_TYPES = ["resource", "user", "agent"];
 function tr(langZh, en, zh) {
     return langZh ? zh : en;
@@ -98,7 +98,9 @@ function normalizePeerRole(value) {
     if (typeof value !== "string")
         return undefined;
     const role = value.trim().toLowerCase();
-    if (role === "none" || role === "assistant" || role === "person")
+    if (role === "person")
+        return "sender";
+    if (role === "none" || role === "assistant" || role === "sender")
         return role;
     return undefined;
 }
@@ -121,7 +123,7 @@ function resolveSetupPeerRole(value) {
     const role = normalizePeerRole(value);
     if (role)
         return role;
-    throw new Error('peer_role must be "none", "assistant", or "person"');
+    throw new Error('peer_role must be "none", "assistant", or "sender" (legacy alias: "person")');
 }
 function normalizeSetupRecallTargetTypes(value) {
     if (value === undefined || value === null || value === "") {
@@ -172,12 +174,17 @@ function preserveCurrentConfig(existing) {
     return config;
 }
 async function askPeerRole(zh, q, defaultValue) {
+    console.log(`  ${tr(zh, "Memory scope — none (default): viking://user/<user_id>/memories, shared across all conversations; " +
+        "assistant: viking://user/<user_id>/peers/<assistant_id>/memories; " +
+        "sender: viking://user/<user_id>/peers/<sender_id>/memories (legacy alias: person).", "记忆归属 —— none（默认）：viking://user/<user_id>/memories，所有对话共享；" +
+        "assistant：viking://user/<user_id>/peers/<assistant_id>/memories；" +
+        "sender：viking://user/<user_id>/peers/<sender_id>/memories（兼容旧值 person）。")}`);
     while (true) {
-        const value = await q(tr(zh, "Peer Role (none/assistant/person)", "Peer Role（none/assistant/person）"), defaultValue);
+        const value = await q(tr(zh, "Memory scope (none/assistant/sender)", "记忆归属（none/assistant/sender）"), defaultValue);
         const role = normalizePeerRole(value);
         if (role)
             return role;
-        console.log(`  ✗ ${tr(zh, 'Peer Role must be "none", "assistant", or "person".', 'Peer Role 必须是 "none"、"assistant" 或 "person"。')}`);
+        console.log(`  ✗ ${tr(zh, 'Memory scope must be "none", "assistant", or "sender" (legacy "person" is also accepted).', '记忆归属必须是 "none"、"assistant" 或 "sender"（也兼容旧值 "person"）。')}`);
     }
 }
 async function askPeerPrefix(zh, q, defaultValue) {
@@ -473,7 +480,7 @@ export function registerSetupCli(api) {
             .option("--zh", "Chinese prompts")
             .option("--base-url <url>", "OpenViking server URL (enables non-interactive mode)")
             .option("--api-key <key>", "API key for authentication")
-            .option("--peer-role <role>", "Peer ID role: none, assistant, or person")
+            .option("--peer-role <role>", "Memory scope: none (shared), assistant (per assistant), or sender (per sender); person is a legacy alias")
             .option("--peer-prefix <prefix>", "Prefix for assistant peer_id values")
             .option("--account-id <id>", "Account ID (required for root API keys)")
             .option("--user-id <id>", "User ID (required for root API keys)")
@@ -952,6 +959,8 @@ async function setupRemote(zh, configPath, existing, q) {
 export const __test__ = {
     isLegacyLocalMode,
     isValidPeerPrefixInput,
+    normalizePeerRole,
+    resolveSetupPeerRole,
     normalizeSetupRecallTargetTypes,
     activateContextEngineSlot,
     isContextEngineSlotActive,

package/dist/config.js

@@ -18,7 +18,7 @@ const DEFAULT_COMMIT_TOKEN_THRESHOLD_RATIO = 0.5;
 const DEFAULT_COMMIT_KEEP_RECENT_COUNT = 10;
 const DEFAULT_BYPASS_SESSION_PATTERNS = [];
 const DEFAULT_EMIT_STANDARD_DIAGNOSTICS = false;
-const DEFAULT_PEER_ROLE = "assistant";
+const DEFAULT_PEER_ROLE = "none";
 const DEFAULT_PEER_PREFIX = "";
 const DEFAULT_TRACE_RECALL_DIR = "~/.openclaw/openviking/recall-traces";
 const DEFAULT_TRACE_RECALL_RETENTION_DAYS = 14;
@@ -144,13 +144,16 @@ function resolveSecret(value, label) {
 function resolvePeerRole(configured) {
     if (typeof configured === "string") {
         const role = configured.trim().toLowerCase();
-        if (role === "none" || role === "assistant" || role === "person") {
+        if (role === "none" || role === "assistant" || role === "sender") {
             return role;
         }
-        throw new Error(`openviking peer_role must be "none", "assistant", or "person"`);
+        if (role === "person") {
+            return "sender";
+        }
+        throw new Error(`openviking peer_role must be "none", "assistant", or "sender" (legacy alias: "person")`);
     }
     if (configured !== undefined) {
-        throw new Error(`openviking peer_role must be "none", "assistant", or "person"`);
+        throw new Error(`openviking peer_role must be "none", "assistant", or "sender" (legacy alias: "person")`);
     }
     return DEFAULT_PEER_ROLE;
 }
@@ -481,14 +484,16 @@ export const memoryOpenVikingConfigSchema = {
             help: "HTTP URL when mode is remote (or use ${OPENVIKING_BASE_URL})",
         },
         peer_role: {
-            label: "Peer Role",
+            label: "Memory Scope (peer_role)",
             placeholder: DEFAULT_PEER_ROLE,
-            help: 'Controls which session messages get peer_id: "none", "assistant", or "person".',
+            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 applied to 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",

package/dist/plugin/openviking-memory-tools.js

@@ -45,7 +45,7 @@ export function registerOpenVikingMemoryTools(deps) {
                 const peerId = resolveOpenVikingMessagePeerId({
                     peerRole: deps.peerRole,
                     role,
-                    personPeerId: session.actorPeerId,
+                    senderPeerId: session.actorPeerId,
                     assistantPeerId: session.actorPeerId,
                 });
                 await client.addSessionMessage(sessionId, role, [{ type: "text", text }], undefined, undefined, peerId);

package/dist/plugin/openviking-session-routing-runtime.js

@@ -1,6 +1,6 @@
 import { createSessionAgentResolver, openClawSessionToOvStorageId, resolveOpenVikingActorPeerId, sanitizeOpenVikingPeerId, } from "../routing/identity-routing.js";
 export function createOpenVikingSessionRoutingRuntime(options) {
-    const peerRole = options.peerRole ?? "assistant";
+    const peerRole = options.peerRole ?? "none";
     const sessionAgentResolver = createSessionAgentResolver(options.peerPrefix);
     const rememberSessionAgentId = (ctx) => {
         sessionAgentResolver.remember(ctx);
@@ -48,7 +48,7 @@ export function createOpenVikingSessionRoutingRuntime(options) {
             agentId,
             actorPeerId: resolveOpenVikingActorPeerId({
                 peerRole,
-                personPeerId: sanitizeOpenVikingPeerId(ctx?.requesterSenderId ?? ctx?.senderId),
+                senderPeerId: sanitizeOpenVikingPeerId(ctx?.requesterSenderId ?? ctx?.senderId),
                 assistantPeerId: agentId,
             }),
         };

package/dist/routing/identity-routing.js

@@ -12,8 +12,8 @@ export function sanitizeOpenVikingPeerId(raw) {
     return normalized || undefined;
 }
 export function resolveOpenVikingMessagePeerId(params) {
-    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;
@@ -23,10 +23,10 @@ export function resolveOpenVikingMessagePeerId(params) {
 export function resolveOpenVikingActorPeerId(params) {
     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/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,
                 }));
             }

package/dist/shared/recall-core.mjs

@@ -397,6 +397,29 @@ export async function isContextFaceLegacy(path = stateFile("context-face.json"),
 export async function markContextFaceLegacy(path = stateFile("context-face.json"), now = Date.now()) {
     await writeJsonFile(path, { legacyUntil: now + LEGACY_CACHE_TTL_MS });
 }
+/**
+ * A `peer_scope` the server rejects is remembered the same way, but unlike the
+ * context face this one is not a silent capability probe: dropping the field
+ * widens recall from the caller's own peer to the whole user root, so doctor
+ * reads this file back and warns.
+ */
+export function peerScopeMemoPath() {
+    return stateFile("peer-scope.json");
+}
+export async function readPeerScopeDowngrade(path = peerScopeMemoPath(), now = Date.now()) {
+    const cached = await readJsonFile(path);
+    if (!cached?.legacyUntil || Number(cached.legacyUntil) <= now)
+        return null;
+    return cached;
+}
+export async function markPeerScopeDowngrade(scope, status, path = peerScopeMemoPath(), now = Date.now()) {
+    await writeJsonFile(path, {
+        legacyUntil: now + LEGACY_CACHE_TTL_MS,
+        scope: String(scope || ""),
+        status: Number(status) || 0,
+        at: now,
+    });
+}
 function looksLikeUnknownField(res) {
     const text = JSON.stringify(res?.error ?? res?.result ?? res?.detail ?? "").toLowerCase();
     return text.includes("extra") || text.includes("mode") || text.includes("unexpected");
@@ -532,7 +555,13 @@ async function recallViaEndpoint(fetchJSON, cfg, query, actorPeerId = "", log =
 export async function postRecall(fetchJSON, body, opts = {}) {
     const actorPeerId = opts.actorPeerId || "";
     const log = opts.log || (() => { });
+    const memoPath = opts.peerScopeMemoPath;
     const request = { ...body };
+    // A remembered downgrade is still a downgrade: recall runs wider than the
+    // caller asked for, so the memo doubles as the doctor's evidence.
+    if (request.peer_scope && await readPeerScopeDowngrade(memoPath)) {
+        delete request.peer_scope;
+    }
     const res = await fetchJSON("/api/v1/search/recall", {
         method: "POST",
         body: JSON.stringify(request),
@@ -540,15 +569,46 @@ export async function postRecall(fetchJSON, body, opts = {}) {
     if (!request.peer_scope || (res.status !== 400 && res.status !== 422)) {
         return res;
     }
+    // Only an unknown-field rejection means "this server predates peer_scope".
+    // Retrying every other 400/422 without it silently widens the search from
+    // the caller's own peer to the whole user root.
+    if (!looksLikeUnknownField(res)) {
+        log("recall_peer_scope_error", { status: res.status || 0 });
+        return res;
+    }
     const downgraded = { ...request };
     delete downgraded.peer_scope;
+    await markPeerScopeDowngrade(String(request.peer_scope), res.status || 0, memoPath);
     log("recall_peer_scope_downgrade", { status: res.status || 0 });
     return fetchJSON("/api/v1/search/recall", {
         method: "POST",
         body: JSON.stringify(downgraded),
     }, { actorPeerId });
 }
+/**
+ * Recall, plus whatever is still filed under the peer this workspace used
+ * before the identity rule changed.
+ *
+ * Under the default `peer_scope: "all"` this costs nothing: the server's own
+ * sweep of `{user_root}/peers` already reaches the old peer's memories. Under
+ * `"actor"` that sweep is off by definition, so the old peer is asked for
+ * separately — as itself, which is both cheaper and wider than a bare
+ * cross-peer read (that would need the user id, and reaches memories only).
+ */
 export async function buildRecallBlock(fetchJSON, cfg, query, options = {}) {
+    const primary = await recallForPeer(fetchJSON, cfg, query, options);
+    const legacyPeerId = String(options.legacyPeerId || "").trim();
+    const actorPeerId = options.actorPeerId ?? cfg.peerId ?? "";
+    if (cfg.recallPeerScope !== "actor" || !legacyPeerId || legacyPeerId === actorPeerId)
+        return primary;
+    const log = options.log || (() => { });
+    const legacy = await recallForPeer(fetchJSON, cfg, query, { ...options, actorPeerId: legacyPeerId });
+    if (!legacy)
+        return primary;
+    log("recall_legacy_peer_hit", { legacyPeerId });
+    return primary ? `${primary}\n${legacy}` : legacy;
+}
+async function recallForPeer(fetchJSON, cfg, query, options = {}) {
     const actorPeerId = options.actorPeerId ?? cfg.peerId ?? "";
     const log = options.log || (() => { });
     const trimmed = String(query || "").trim();

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",
@@ -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.2",
+  "version": "2026.9.4-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/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

@@ -497,8 +497,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 +910,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,
           }),
         );

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/shared/recall-core.mjs

@@ -417,6 +417,31 @@ export async function markContextFaceLegacy(path = stateFile("context-face.json"
   await writeJsonFile(path, { legacyUntil: now + LEGACY_CACHE_TTL_MS });
 }
 
+/**
+ * A `peer_scope` the server rejects is remembered the same way, but unlike the
+ * context face this one is not a silent capability probe: dropping the field
+ * widens recall from the caller's own peer to the whole user root, so doctor
+ * reads this file back and warns.
+ */
+export function peerScopeMemoPath() {
+  return stateFile("peer-scope.json");
+}
+
+export async function readPeerScopeDowngrade(path = peerScopeMemoPath(), now = Date.now()) {
+  const cached = await readJsonFile(path);
+  if (!cached?.legacyUntil || Number(cached.legacyUntil) <= now) return null;
+  return cached;
+}
+
+export async function markPeerScopeDowngrade(scope, status, path = peerScopeMemoPath(), now = Date.now()) {
+  await writeJsonFile(path, {
+    legacyUntil: now + LEGACY_CACHE_TTL_MS,
+    scope: String(scope || ""),
+    status: Number(status) || 0,
+    at: now,
+  });
+}
+
 function looksLikeUnknownField(res) {
   const text = JSON.stringify(res?.error ?? res?.result ?? res?.detail ?? "").toLowerCase();
   return text.includes("extra") || text.includes("mode") || text.includes("unexpected");
@@ -558,7 +583,15 @@ async function recallViaEndpoint(fetchJSON, cfg, query, actorPeerId = "", log =
 export async function postRecall(fetchJSON, body, opts = {}) {
   const actorPeerId = opts.actorPeerId || "";
   const log = opts.log || (() => {});
+  const memoPath = opts.peerScopeMemoPath;
   const request = { ...body };
+
+  // A remembered downgrade is still a downgrade: recall runs wider than the
+  // caller asked for, so the memo doubles as the doctor's evidence.
+  if (request.peer_scope && await readPeerScopeDowngrade(memoPath)) {
+    delete request.peer_scope;
+  }
+
   const res = await fetchJSON("/api/v1/search/recall", {
     method: "POST",
     body: JSON.stringify(request),
@@ -566,9 +599,17 @@ export async function postRecall(fetchJSON, body, opts = {}) {
   if (!request.peer_scope || (res.status !== 400 && res.status !== 422)) {
     return res;
   }
+  // Only an unknown-field rejection means "this server predates peer_scope".
+  // Retrying every other 400/422 without it silently widens the search from
+  // the caller's own peer to the whole user root.
+  if (!looksLikeUnknownField(res)) {
+    log("recall_peer_scope_error", { status: res.status || 0 });
+    return res;
+  }
 
   const downgraded = { ...request };
   delete downgraded.peer_scope;
+  await markPeerScopeDowngrade(String(request.peer_scope), res.status || 0, memoPath);
   log("recall_peer_scope_downgrade", { status: res.status || 0 });
   return fetchJSON("/api/v1/search/recall", {
     method: "POST",
@@ -576,7 +617,31 @@ export async function postRecall(fetchJSON, body, opts = {}) {
   }, { actorPeerId });
 }
 
+/**
+ * Recall, plus whatever is still filed under the peer this workspace used
+ * before the identity rule changed.
+ *
+ * Under the default `peer_scope: "all"` this costs nothing: the server's own
+ * sweep of `{user_root}/peers` already reaches the old peer's memories. Under
+ * `"actor"` that sweep is off by definition, so the old peer is asked for
+ * separately — as itself, which is both cheaper and wider than a bare
+ * cross-peer read (that would need the user id, and reaches memories only).
+ */
 export async function buildRecallBlock(fetchJSON, cfg, query, options = {}) {
+  const primary = await recallForPeer(fetchJSON, cfg, query, options);
+
+  const legacyPeerId = String(options.legacyPeerId || "").trim();
+  const actorPeerId = options.actorPeerId ?? cfg.peerId ?? "";
+  if (cfg.recallPeerScope !== "actor" || !legacyPeerId || legacyPeerId === actorPeerId) return primary;
+
+  const log = options.log || (() => {});
+  const legacy = await recallForPeer(fetchJSON, cfg, query, { ...options, actorPeerId: legacyPeerId });
+  if (!legacy) return primary;
+  log("recall_legacy_peer_hit", { legacyPeerId });
+  return primary ? `${primary}\n${legacy}` : legacy;
+}
+
+async function recallForPeer(fetchJSON, cfg, query, options = {}) {
   const actorPeerId = options.actorPeerId ?? cfg.peerId ?? "";
   const log = options.log || (() => {});
   const trimmed = String(query || "").trim();

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