Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
fix(openclaw): stop offering the legacy person peer role at install time (#5355)
Zayn Jarvis9ecb2863a7df
diff --git a/docs/en/agent-integrations/03-openclaw.md b/docs/en/agent-integrations/03-openclaw.mdindex fb8fc046e..af0045016 100644--- a/docs/en/agent-integrations/03-openclaw.md+++ b/docs/en/agent-integrations/03-openclaw.md@@ -53,7 +53,7 @@ Key parameters:| `--plugin-version=VER` | Plugin version: npm version, dist-tag, or Git ref || `--base-url URL` | OpenViking server URL || `--api-key KEY` | OpenViking API key |-| `--peer-role ROLE` | Memory scope: `none`, `assistant`, or `sender` (`person` is a legacy alias) |+| `--peer-role ROLE` | Memory scope: `none`, `assistant`, or `sender` || `--uninstall` | Uninstall the plugin |Full parameter list in the [install guide](https://github.com/volcengine/OpenViking/blob/main/examples/openclaw-plugin/INSTALL.md).@@ -80,7 +80,7 @@ openclaw openviking setup --base-url http://your-server:1933 --api-key sk-xxx --openclaw openviking setup --base-url http://your-server:1933 --api-key sk-xxx --peer-role sender --json```-New configuration should use `sender`; existing `peer_role=person` configurations remain compatible and are treated as `sender`. OpenViking initializes the managed `peers/` container for every user, so `none` 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.+Setup and the installer accept only `sender`; existing `peer_role=person` configurations remain compatible and are treated as `sender`. OpenViking initializes the managed `peers/` container for every user, so `none` 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.## How assemble builds contextdiff --git a/docs/images/agents/en/openclaw.md b/docs/images/agents/en/openclaw.mdindex f90c900d5..b8f027191 100644--- a/docs/images/agents/en/openclaw.md+++ b/docs/images/agents/en/openclaw.md@@ -12,7 +12,7 @@openclaw openviking setup --base-url https://api.vikingdb.cn-beijing.volces.com/openviking --api-key <$OPENVIKING_API_KEY>```-3. Configure `peer_role`: `peer_role` identifies the type of conversation participant. It is not a permission role. `assistant` represents agents, tools, or models; `person` represents human participants. After the setup above, `peer_role` defaults to `none`. To change `peer_role`, run:+3. Configure `peer_role`: `peer_role` identifies the type of conversation participant. It is not a permission role. `assistant` represents agents, tools, or models; `sender` represents human participants. After the setup above, `peer_role` defaults to `none`. To change `peer_role`, run:```bashopenclaw openviking setup --reconfigurediff --git a/docs/images/agents/zh/openclaw.md b/docs/images/agents/zh/openclaw.mdindex 12c894100..904075ba8 100644--- a/docs/images/agents/zh/openclaw.md+++ b/docs/images/agents/zh/openclaw.md@@ -12,7 +12,7 @@openclaw openviking setup --base-url https://api.vikingdb.cn-beijing.volces.com/openviking --api-key <$OPENVIKING_API_KEY>```-3. 配置 `peer_role`:`peer_role` 用于标识对话参与者的类型,并非权限角色。其中,`assistant` 表示不同的 Agent、工具或模型,`person` 表示不同的人类参与者。完成上述配置后,`peer_role` 默认为 `none`。如需调整 `peer_role`,可执行以下命令:+3. 配置 `peer_role`:`peer_role` 用于标识对话参与者的类型,并非权限角色。其中,`assistant` 表示不同的 Agent、工具或模型,`sender` 表示不同的人类参与者。完成上述配置后,`peer_role` 默认为 `none`。如需调整 `peer_role`,可执行以下命令:```bashopenclaw openviking setup --reconfigurediff --git a/docs/zh/agent-integrations/03-openclaw.md b/docs/zh/agent-integrations/03-openclaw.mdindex 2ea59ed90..a79e30370 100644--- a/docs/zh/agent-integrations/03-openclaw.md+++ b/docs/zh/agent-integrations/03-openclaw.md@@ -53,7 +53,7 @@ ov-install --base-url http://your-server:1933| `--plugin-version=VER` | 插件版本:npm 版本、dist-tag 或 Git ref || `--base-url URL` | OpenViking 服务地址 || `--api-key KEY` | OpenViking API Key |-| `--peer-role ROLE` | 记忆归属:`none`、`assistant` 或 `sender`(`person` 是旧别名) |+| `--peer-role ROLE` | 记忆归属:`none`、`assistant` 或 `sender` || `--uninstall` | 卸载插件 |完整参数列表见 [安装指南](https://github.com/volcengine/OpenViking/blob/main/examples/openclaw-plugin/INSTALL.md)。@@ -80,7 +80,7 @@ openclaw openviking setup --base-url http://your-server:1933 --api-key sk-xxx --openclaw openviking setup --base-url http://your-server:1933 --api-key sk-xxx --peer-role sender --json```-新配置请使用 `sender`;已有的 `peer_role=person` 配置仍兼容,并按 `sender` 处理。OpenViking 会为每个用户初始化受管的 `peers/` 容器,因此 `none` 的含义是不使用具体的 `peers/<peer_id>/memories` 子树。Actor-peer 召回同时包含用户共享记忆和当前 peer 记忆;切换 scope 不会搬迁已有记忆。+安装和 setup 只接受 `sender`;已有的 `peer_role=person` 配置仍兼容,并按 `sender` 处理。OpenViking 会为每个用户初始化受管的 `peers/` 容器,因此 `none` 的含义是不使用具体的 `peers/<peer_id>/memories` 子树。Actor-peer 召回同时包含用户共享记忆和当前 peer 记忆;切换 scope 不会搬迁已有记忆。## assemble 如何组装上下文diff --git a/examples/openclaw-plugin/INSTALL-AGENT.md b/examples/openclaw-plugin/INSTALL-AGENT.mdindex 527078fd3..85b92cb8d 100644--- a/examples/openclaw-plugin/INSTALL-AGENT.md+++ b/examples/openclaw-plugin/INSTALL-AGENT.md@@ -42,7 +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. |+| Memory scope | Optional; default `none` | Ask whether memory is shared, separated by assistant, or separated by sender. Use `sender`. || 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` |@@ -82,7 +82,7 @@ Choose memory scope before building that command:| `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.+Setup rejects `person`; always pass `sender`. An existing config that still says `person` keeps working as `sender`. 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:diff --git a/examples/openclaw-plugin/INSTALL-ZH.md b/examples/openclaw-plugin/INSTALL-ZH.mdindex 995d179cb..cc81b575f 100644--- a/examples/openclaw-plugin/INSTALL-ZH.md+++ b/examples/openclaw-plugin/INSTALL-ZH.md@@ -205,7 +205,7 @@ openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --forc| `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`。+安装和 setup 只接受 `sender`;已有配置里的 `person` 仍按 `sender` 生效。例如,让每个助手使用独立的 peer 记忆,并可选给 assistant id 加前缀:@@ -405,7 +405,7 @@ ov-install| `--current-version` | 查看 helper 记录的当前版本 || `--base-url URL` | OpenViking 服务器地址(启用非交互模式) || `--api-key KEY` | OpenViking API key |-| `--peer-role ROLE` | 记忆归属:`none`、`assistant` 或 `sender`;旧值 `person` 作为 `sender` 的别名兼容 |+| `--peer-role ROLE` | 记忆归属:`none`、`assistant` 或 `sender` || `--peer-prefix PREFIX` | assistant `peer_id` / actor peer 值的前缀 || `--update` | 更新 helper 管理的安装 |diff --git a/examples/openclaw-plugin/INSTALL.md b/examples/openclaw-plugin/INSTALL.mdindex ac8893f6a..6007d3713 100644--- a/examples/openclaw-plugin/INSTALL.md+++ b/examples/openclaw-plugin/INSTALL.md@@ -149,7 +149,7 @@ Choose `--peer-role` from what the OpenViking user represents:| `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`.+Setup and the installer accept only `sender`. An existing config that still says `person` keeps working as `sender`.For example, give each assistant its own peer memory and optionally namespace the assistant id:@@ -329,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` | Memory scope: `none`, `assistant`, or `sender`; legacy `person` is accepted as `sender` |+| `--peer-role ROLE` | Memory scope: `none`, `assistant`, or `sender` || `--peer-prefix PREFIX` | Prefix for assistant `peer_id` / actor peer values || `--update` | Update an existing helper-managed install |diff --git a/examples/openclaw-plugin/commands/setup.ts b/examples/openclaw-plugin/commands/setup.tsindex b732c5dde..2ce101f4b 100644--- a/examples/openclaw-plugin/commands/setup.ts+++ b/examples/openclaw-plugin/commands/setup.ts@@ -136,6 +136,12 @@ function normalizePeerRole(value: unknown): PeerRole | undefined {return undefined;}+// `person` survives only in existing configs; setup input must say `sender`.+function normalizePeerRoleInput(value: unknown): PeerRole | undefined {+ if (typeof value === "string" && value.trim().toLowerCase() === "person") return undefined;+ return normalizePeerRole(value);+}+function resolveExistingPeerRole(existing: Record<string, unknown> | null | undefined): PeerRole {const explicit = normalizePeerRole(existing?.peer_role);if (explicit) return explicit;@@ -151,9 +157,9 @@ function resolveExistingPeerPrefix(existing: Record<string, unknown> | null | unfunction resolveSetupPeerRole(value: unknown): PeerRole {if (value === undefined) return DEFAULT_SETUP_PEER_ROLE;- const role = normalizePeerRole(value);+ const role = normalizePeerRoleInput(value);if (role) return role;- throw new Error('peer_role must be "none", "assistant", or "sender" (legacy alias: "person")');+ throw new Error('peer_role must be "none", "assistant", or "sender" ("person" was renamed to "sender")');}function normalizeSetupRecallTargetTypes(value: unknown): RecallTargetType[] | undefined {@@ -217,10 +223,10 @@ async function askPeerRole(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).",+ "sender: viking://user/<user_id>/peers/<sender_id>/memories.","记忆归属 —— 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)。",+ "sender:viking://user/<user_id>/peers/<sender_id>/memories。",)}`,);while (true) {@@ -228,13 +234,13 @@ async function askPeerRole(tr(zh, "Memory scope (none/assistant/sender)", "记忆归属(none/assistant/sender)"),defaultValue,);- const role = normalizePeerRole(value);+ const role = normalizePeerRoleInput(value);if (role) return role;console.log(` ✗ ${tr(zh,- 'Memory scope must be "none", "assistant", or "sender" (legacy "person" is also accepted).',- '记忆归属必须是 "none"、"assistant" 或 "sender"(也兼容旧值 "person")。',+ 'Memory scope must be "none", "assistant", or "sender" ("person" was renamed to "sender").',+ '记忆归属必须是 "none"、"assistant" 或 "sender"("person" 已更名为 "sender")。',)}`,);}@@ -496,7 +502,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>", "Memory scope: none (shared), assistant (per assistant), or sender (per sender); person is a legacy alias")+ .option("--peer-role <role>", "Memory scope: none (shared), assistant (per assistant), or sender (per sender)").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)")diff --git a/examples/openclaw-plugin/setup-helper/install.js b/examples/openclaw-plugin/setup-helper/install.jsindex cca2c42c0..938a0770b 100755--- a/examples/openclaw-plugin/setup-helper/install.js+++ b/examples/openclaw-plugin/setup-helper/install.js@@ -290,16 +290,16 @@ for (let i = 0; i < argv.length; i++) {if (arg === "--peer-role") {const val = argv[i + 1]?.trim();if (!val) { console.error("--peer-role requires a value"); process.exit(1); }- const role = normalizePeerRole(val);- if (!role) { console.error('--peer-role must be "none", "assistant", or "sender" (legacy alias: "person")'); process.exit(1); }+ const role = normalizePeerRoleInput(val);+ if (!role) { console.error('--peer-role must be "none", "assistant", or "sender" ("person" was renamed to "sender")'); process.exit(1); }remotePeerRole = role;peerRoleExplicit = true;i += 1;continue;}if (arg.startsWith("--peer-role=")) {- const role = normalizePeerRole(arg.slice("--peer-role=".length));- if (!role) { console.error('--peer-role must be "none", "assistant", or "sender" (legacy alias: "person")'); process.exit(1); }+ const role = normalizePeerRoleInput(arg.slice("--peer-role=".length));+ if (!role) { console.error('--peer-role must be "none", "assistant", or "sender" ("person" was renamed to "sender")'); process.exit(1); }remotePeerRole = role;peerRoleExplicit = true;continue;@@ -343,6 +343,10 @@ for (let i = 0; i < argv.length; i++) {}}+if (remotePeerRole === "person") {+ console.error('OPENVIKING_PEER_ROLE must be "none", "assistant", or "sender" ("person" was renamed to "sender")');+ process.exit(1);+}remotePeerRole = normalizePeerRole(remotePeerRole) || "none";if (!isValidPeerPrefixInput(remotePeerPrefix)) {console.error("--peer-prefix may only contain letters, digits, underscores, and hyphens");@@ -373,7 +377,7 @@ function printHelp() {console.log(" --uninstall, --remove Uninstall OpenViking plugin from OpenClaw (backup config, remove plugin entries)");console.log(" --base-url=URL OpenViking server URL (default: $OPENVIKING_BASE_URL or http://127.0.0.1:1933)");console.log(" --api-key=KEY OpenViking API key (default: $OPENVIKING_API_KEY)");- console.log(" --peer-role=ROLE Memory scope: none (shared), assistant (per assistant), sender (per sender); person is a legacy alias (default: $OPENVIKING_PEER_ROLE or none)");+ console.log(" --peer-role=ROLE Memory scope: none (shared), assistant (per assistant), sender (per sender) (default: $OPENVIKING_PEER_ROLE or none)");console.log(" --peer-prefix=PREFIX Prefix for assistant peer_id values (default: $OPENVIKING_PEER_PREFIX)");console.log(" --account-id=ID Account ID for root API key (default: $OPENVIKING_ACCOUNT_ID)");console.log(" --user-id=ID User ID for root API key (default: $OPENVIKING_USER_ID)");@@ -525,6 +529,12 @@ function normalizePeerRole(value) {return role === "none" || role === "assistant" || role === "sender" ? role : null;}+// `person` survives only in existing configs; installer input must say `sender`.+function normalizePeerRoleInput(value) {+ const role = String(value || "").trim().toLowerCase();+ return role === "person" ? null : normalizePeerRole(role);+}+function parseJsonObjectFromOutput(output) {const text = String(output || "").trim();if (!text) return null;@@ -550,21 +560,21 @@ async function questionPeerRole(defaultValue = "none") {info(tr("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).",+ + "sender: viking://user/<user_id>/peers/<sender_id>/memories.","记忆归属 —— 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)。",+ + "sender:viking://user/<user_id>/peers/<sender_id>/memories。",));while (true) {const answer = await question(tr("Memory scope (none/assistant/sender)", "记忆归属(none/assistant/sender)"),defaultValue,);- const role = normalizePeerRole(answer);+ const role = normalizePeerRoleInput(answer);if (role) return role;warn(tr(- 'Memory scope must be "none", "assistant", or "sender" (legacy "person" is also accepted).',- '记忆归属必须是 "none"、"assistant" 或 "sender"(也兼容旧值 "person")。',+ 'Memory scope must be "none", "assistant", or "sender" ("person" was renamed to "sender").',+ '记忆归属必须是 "none"、"assistant" 或 "sender"("person" 已更名为 "sender")。',));}}diff --git a/examples/openclaw-plugin/tests/ut/package-install-contract.test.ts b/examples/openclaw-plugin/tests/ut/package-install-contract.test.tsindex abfad0c60..6d373d0bd 100644--- a/examples/openclaw-plugin/tests/ut/package-install-contract.test.ts+++ b/examples/openclaw-plugin/tests/ut/package-install-contract.test.ts@@ -148,6 +148,7 @@ describe("OpenClaw plugin package and install contract", () => {expect(installHelper).toContain("OPENVIKING_PEER_ROLE");expect(installHelper).toContain("OPENVIKING_PEER_PREFIX");expect(installHelper).toContain('if (role === "person") return "sender"');+ expect(installHelper).toContain('return role === "person" ? null : normalizePeerRole(role);');expect(installHelper).not.toContain("OPENVIKING_AGENT_PREFIX");});});diff --git a/examples/openclaw-plugin/tests/ut/setup-command.test.ts b/examples/openclaw-plugin/tests/ut/setup-command.test.tsindex 02dd80a08..85f9df426 100644--- a/examples/openclaw-plugin/tests/ut/setup-command.test.ts+++ b/examples/openclaw-plugin/tests/ut/setup-command.test.ts@@ -35,10 +35,11 @@ describe("openviking setup agent prefix validation", () => {},);- it("uses sender as the canonical setup value and accepts legacy person input", () => {+ it("reads legacy person from existing config but rejects it as setup input", () => {expect(setupCommandTest.normalizePeerRole("sender")).toBe("sender");expect(setupCommandTest.normalizePeerRole("person")).toBe("sender");- expect(setupCommandTest.resolveSetupPeerRole("person")).toBe("sender");+ expect(setupCommandTest.resolveSetupPeerRole("sender")).toBe("sender");+ expect(() => setupCommandTest.resolveSetupPeerRole("person")).toThrow('"person" was renamed to "sender"');});it("interactive reconfiguration preserves the selected retention policy", async () => {