@openviking/openclaw-plugin 2026.6.2 → 2026.6.17-dev.2

package/INSTALL-AGENT.md

@@ -99,7 +99,7 @@ openclaw openviking setup \
 Custom agent routing prefix (optional; only when the user explicitly requests a prefix):
 
 ```bash
-openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --agent-prefix <PREFIX> --json
+openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --peer-prefix <PREFIX> --json
 ```
 
 Slot replacement retry, only after user approval:
@@ -139,7 +139,7 @@ Also inspect:
 | `health.version` | Records server version |
 | `health.compatibility` | Determines whether to warn |
 | `config.hasApiKey` | Confirms whether an API key was saved |
-| `config.agent_prefix` | Confirms configured agent prefix when present |
+| `config.peer_prefix` | Confirms configured peer prefix when present |
 
 ## Environment Detection
 
@@ -267,7 +267,7 @@ Core fields:
 | `mode` | Legacy compatibility field. Expected value: `remote`. |
 | `baseUrl` | OpenViking HTTP endpoint |
 | `apiKey` | OpenViking API key |
-| `agent_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_prefix` | Optional; prefix for OpenClaw agent IDs when set. 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 +329,7 @@ Existing config fields are preserved during migration. The new plugin reads old
 
 - `baseUrl`
 - `apiKey`
-- `agent_prefix`: optional; interactive setup accepts only letters, digits, `_`, and `-`
+- `peer_prefix`: optional; interactive setup accepts only letters, digits, `_`, and `-`
 
 ## Backup Path: ov-install
 

package/INSTALL-ZH.md

@@ -46,6 +46,62 @@ node -v
 openclaw --version
 ```
 
+## 火山 OpenViking Service 一键接入
+
+如果你使用的是火山控制台创建的 OpenViking Service 库，不需要启动本地 `openviking-server`。从控制台复制 OpenViking Service 的 server url、API Key，并按需配置 peer 标识：
+
+```bash
+OPENVIKING_BASE_URL="https://api.vikingdb.cn-beijing.volces.com/openviking" \
+OPENVIKING_API_KEY="<your-openviking-service-api-key>" \
+bash scripts/install.sh --json
+```
+
+这条命令会完成：
+
+- 默认从 TOS `latest` 安装 OpenViking 插件。
+- 写入 `$OPENCLAW_STATE_DIR/openviking.env`，默认是 `~/.openclaw/openviking.env`，权限为 `0600`。
+- 调用 `openclaw openviking setup --base-url ... --api-key ...` 写入插件配置。
+- 重启 `openclaw gateway`。
+- 执行 `openclaw openviking status --json` 和 `openclaw config get plugins.slots.contextEngine` 验证。
+
+如果需要把 OpenClaw assistant 说话人写成独立 `peer_id`，并让数据面 recall/search 使用对应 actor peer 视图，可以额外传：
+
+```bash
+OPENVIKING_BASE_URL="https://api.vikingdb.cn-beijing.volces.com/openviking" \
+OPENVIKING_API_KEY="<your-openviking-service-api-key>" \
+OPENVIKING_PEER_ROLE="assistant" \
+OPENVIKING_PEER_PREFIX="openclaw-prod" \
+bash scripts/install.sh --json
+```
+
+如果使用 root key 或可信服务身份，补充租户信息：
+
+```bash
+OPENVIKING_BASE_URL="https://api.vikingdb.cn-beijing.volces.com/openviking" \
+OPENVIKING_API_KEY="<root-key>" \
+OPENVIKING_ACCOUNT_ID="<account-id>" \
+OPENVIKING_USER_ID="<user-id>" \
+bash scripts/install.sh --json
+```
+
+离线下载包安装：
+
+```bash
+sh build.sh
+OPENVIKING_BASE_URL="https://api.vikingdb.cn-beijing.volces.com/openviking" \
+OPENVIKING_API_KEY="<your-openviking-service-api-key>" \
+OPENVIKING_PEER_ROLE="assistant" \
+OPENVIKING_PEER_PREFIX="openclaw-prod" \
+bash output/install.sh --source tarball --tarball output/openviking.tgz --json
+```
+
+接入后，在火山 OpenViking Service 控制台检查：
+
+- 发送一轮 OpenClaw 对话后，`Session` 下出现原始会话。
+- 触发 `/compact` 或等待 commit 后，`User/memories` 出现长期记忆。
+- 如果配置了 `peer_role=assistant`，数据面 recall/search 会携带对应 `X-OpenViking-Actor-Peer`，session message 仍用 body `peer_id` 做消息归因。
+- 通过手动 `/add-resource` 导入文档、URL 或目录后，`Resources` 下出现对应知识，并可做目录递归检索。Agent 可见的 `add_resource` 工具默认禁用，只有显式设置 `enableAddResourceTool=true` 后才暴露。
+
 ## 启动 OpenViking Server
 
 如果 OpenViking 和 OpenClaw 在同一台机器上，最短流程是：
@@ -141,10 +197,10 @@ openclaw openviking setup \
 openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --force-slot --json
 ```
 
-如需自定义 agent 路由前缀（可选；多数用户留空即可）：
+如需给默认 assistant peer 路由增加前缀，可以额外传：
 
 ```bash
-openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --agent-prefix <PREFIX> --json
+openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --peer-role assistant --peer-prefix <PREFIX> --json
 ```
 
 ### 3. 重启 OpenClaw Gateway
@@ -205,7 +261,8 @@ plugins.entries.openviking.config
 | `mode` | `remote` | 兼容旧配置的字段。当前只支持 remote。 |
 | `baseUrl` | `http://127.0.0.1:1933` | OpenViking HTTP 地址 |
 | `apiKey` | 空 | OpenViking API key |
-| `agent_prefix` | 空 | OpenClaw agent ID 的可选前缀；若没有 agent ID，插件使用 `main`。交互式配置只接受字母、数字、`_` 和 `-`。 |
+| `peer_role` | `assistant` | Peer 身份模式：`none`、`assistant` 或 `person`。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 时需要 |
 
@@ -229,14 +286,16 @@ openclaw config get plugins.entries.openviking.config
 | --- | --- | --- |
 | `baseUrl` | `http://127.0.0.1:1933` | 远端 OpenViking 服务地址 |
 | `apiKey` | 空 | 远端 OpenViking API Key；服务端未开启认证时可不填 |
-| `agent_prefix` | 空 | OpenClaw agent ID 的可选前缀；如果拿不到 agent ID，插件使用 `main`。交互式配置只接受字母、数字、`_` 和 `-` |
+| `peer_role` | `assistant` | Peer 身份模式：`none`、`assistant` 或 `person`；session message 使用 body `peer_id`，数据面 recall/search 使用 `X-OpenViking-Actor-Peer` |
+| `peer_prefix` | 空 | `peer_role=assistant` 时 assistant `peer_id` / actor peer 值的可选前缀 |
 
 常见设置：
 
 ```bash
 openclaw config set plugins.entries.openviking.config.baseUrl http://your-server:1933
 openclaw config set plugins.entries.openviking.config.apiKey your-api-key
-openclaw config set plugins.entries.openviking.config.agent_prefix your-prefix
+openclaw config set plugins.entries.openviking.config.peer_role assistant
+openclaw config set plugins.entries.openviking.config.peer_prefix your-prefix
 ```
 
 ## 升级
@@ -289,7 +348,8 @@ ov-install
 | `--current-version` | 查看 helper 记录的当前版本 |
 | `--base-url URL` | OpenViking 服务器地址（启用非交互模式） |
 | `--api-key KEY` | OpenViking API key |
-| `--agent-prefix PREFIX` | Agent 路由前缀 |
+| `--peer-role ROLE` | Peer role：`none`、`assistant` 或 `person` |
+| `--peer-prefix PREFIX` | assistant `peer_id` / actor peer 值的前缀 |
 | `--update` | 更新 helper 管理的安装 |
 
 面向用户的安装，请先使用 `openclaw plugins install clawhub:@openviking/openclaw-plugin`。只有作为备用路径时才选择 `ov-install`。
@@ -315,7 +375,7 @@ openclaw gateway restart
 openclaw openviking status --json
 ```
 
-已有的配置字段（`baseUrl`、`apiKey`、`agentId` 等）会保留。新版本在运行时兼容读取旧字段名，无需手动修改配置。
+已有的配置字段（`baseUrl`、`apiKey`、`peer_role`、`peer_prefix` 等）会保留。
 
 ### 旧插件 ID（memory-openviking，版本 < 0.3.x）
 
@@ -342,4 +402,4 @@ openclaw openviking status --json
 bash examples/openclaw-plugin/upgrade_scripts/cleanup-memory-openviking.sh
 ```
 
-另见：[INSTALL.md](./INSTALL.md) 和 [INSTALL-AGENT.md](./INSTALL-AGENT.md)。
+另见：[INSTALL.md](./INSTALL.md)、[INSTALL-AGENT.md](./INSTALL-AGENT.md) 和 [docs/openviking-tos-install-guide.md](./docs/openviking-tos-install-guide.md)。

package/INSTALL.md

@@ -141,10 +141,10 @@ 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 need a custom agent routing prefix (optional; most users leave this empty):
+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:
 
 ```bash
-openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --agent-prefix <PREFIX> --json
+openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --peer-role assistant --peer-prefix <PREFIX> --json
 ```
 
 ### 3. Restart OpenClaw Gateway
@@ -205,7 +205,8 @@ 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 |
-| `agent_prefix` | empty | Optional prefix for OpenClaw agent IDs. If no agent ID is available, the plugin uses `main`. Interactive setup accepts only letters, digits, `_`, and `-`. |
+| `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` | 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 |
 
@@ -271,7 +272,8 @@ 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 |
-| `--agent-prefix PREFIX` | Agent routing prefix |
+| `--peer-role ROLE` | Peer role: `none`, `assistant`, or `person` |
+| `--peer-prefix PREFIX` | Prefix for assistant `peer_id` / actor peer values |
 | `--update` | Update an existing helper-managed install |
 
 For user-facing installs, use `openclaw plugins install clawhub:@openviking/openclaw-plugin` first. Choose `ov-install` only as the backup path.
@@ -297,7 +299,7 @@ openclaw gateway restart
 openclaw openviking status --json
 ```
 
-Your existing config fields (`baseUrl`, `apiKey`, `agentId`, etc.) are preserved. The new plugin version reads old field names at runtime — no manual config edits needed.
+Your existing config fields such as `baseUrl`, `apiKey`, `peer_role`, and `peer_prefix` are preserved.
 
 The plugin configuration lives under `plugins.entries.openviking.config`.
 
@@ -315,14 +317,16 @@ 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 |
-| `agent_prefix` | empty | Optional prefix for OpenClaw agent IDs. If no agent ID is available, the plugin uses `main`. Interactive setup accepts only letters, digits, `_`, and `-` |
+| `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_prefix` | empty | Optional prefix for assistant `peer_id` / actor peer values when `peer_role=assistant` |
 
 Common settings:
 
 ```bash
 openclaw config set plugins.entries.openviking.config.baseUrl http://your-server:1933
 openclaw config set plugins.entries.openviking.config.apiKey your-api-key
-openclaw config set plugins.entries.openviking.config.agent_prefix your-prefix
+openclaw config set plugins.entries.openviking.config.peer_role assistant
+openclaw config set plugins.entries.openviking.config.peer_prefix your-prefix
 ```
 
 ## Start
@@ -359,4 +363,4 @@ Or use the cleanup script:
 bash examples/openclaw-plugin/upgrade_scripts/cleanup-memory-openviking.sh
 ```
 
-See also: [INSTALL-ZH.md](./INSTALL-ZH.md) and [INSTALL-AGENT.md](./INSTALL-AGENT.md).
+See also: [INSTALL-ZH.md](./INSTALL-ZH.md), [INSTALL-AGENT.md](./INSTALL-AGENT.md), and [docs/openviking-tos-install-guide.md](./docs/openviking-tos-install-guide.md).

package/README.md

@@ -39,20 +39,26 @@ Once installed, the plugin provides these agent tools:
 | `memory_forget` | Delete memories by URI or query |
 | `ov_archive_search` | Search across archives by keyword |
 | `ov_archive_expand` | Expand an archive back to raw messages |
-| `add_resource` | Import documents, URLs, or Git repos |
-| `add_skill` | Import agent skills |
+| `ov_recall_trace` | Inspect why recall/search returned or injected specific results |
+| `add_resource` | Import documents, URLs, or Git repos when explicitly enabled |
+| `add_skill` | Import OpenViking skills |
 | `ov_search` | Search imported resources and skills |
+| `ov_read` | Read the full original content of one exact OpenViking URI |
+| `ov_multi_read` | Read the full original content of multiple OpenViking URIs |
+| `ov_list` | List OpenViking directories after search to inspect sibling chunks and overview files |
 | `openviking_tool_result_read` | Restore the full original content of an externalized tool result |
 | `openviking_tool_result_search` | Search inside an externalized tool result by keyword |
 | `openviking_tool_result_list` | List externalized tool results in the current session |
 
+`add_resource` is hidden from agents by default (`enableAddResourceTool=false`), while manual `/add-resource` remains available. Configure `recallTargetTypes` to choose default recall targets (`user`, `agent`, `resource`); legacy `recallResources=true` appends `resource` only when `recallTargetTypes` is unset.
+
 ## Data Flow & Privacy
 
 - **What is sent**: User/assistant message text from each turn (after stripping injected memory blocks and metadata noise).
 - **Where it goes**: Your configured OpenViking server (`baseUrl`). The plugin only sends data to that server; downstream model/provider data handling (embedding, VLM) depends on the server's configuration.
-- **Storage**: All data lives on your OpenViking server under `viking://user/*`, `viking://agent/*`, and `viking://session/*`.
-- **API Key**: Sent as `X-OpenViking-Key` header over your configured connection. Never logged or forwarded.
-- **Multi-tenant isolation**: Supports `accountId`, `userId`, and `agent_prefix` for per-tenant scoping.
+- **Storage**: All data lives on your OpenViking server under `viking://user/*` (including `viking://user/sessions/*`) and `viking://resources/*`.
+- **API Key**: Sent as `X-API-Key` header over your configured connection. Never logged or forwarded.
+- **Multi-tenant isolation**: Supports `accountId` and `userId`. Optional `peer_role` / `peer_prefix` controls whether OpenClaw speakers are written as OpenViking `peer_id`.
 
 ## Verify
 
@@ -68,6 +74,11 @@ openclaw config get plugins.slots.contextEngine  # should output: openviking
 | [INSTALL.md](./INSTALL.md) | Full install, upgrade, and uninstall guide |
 | [INSTALL-ZH.md](./INSTALL-ZH.md) | Chinese install guide |
 | [INSTALL-AGENT.md](./INSTALL-AGENT.md) | Agent-oriented operator guide |
+| [docs/openviking-tos-install-guide.md](./docs/openviking-tos-install-guide.md) | TOS release bundle publishing and installer guide |
+| [docs/openviking-openclaw-plugin-guide.md](./docs/openviking-openclaw-plugin-guide.md) | Comprehensive Chinese guide for usage, configuration, debugging, testing, build, release, deployment, and rollback |
+| [docs/openviking-websocket-rpc-api.md](./docs/openviking-websocket-rpc-api.md) | Gateway WebSocket RPC usage for OpenViking tools |
+| [docs/openviking-runtime-query-config.md](./docs/openviking-runtime-query-config.md) | Runtime query config scopes, fields, and commands |
+| [docs/openviking-install-package-contract.md](./docs/openviking-install-package-contract.md) | Package and install contract verification notes |
 
 > **Plugin vs Skill**: This page is for `@openviking/openclaw-plugin` (the context-engine plugin). Do **not** use `clawhub install openviking` — that installs a different AgentSkill.
 
@@ -99,53 +110,45 @@ The diagram above reflects the current implementation boundary:
 
 - OpenClaw remains the primary runtime on the left. The plugin does not take over agent execution.
 - The middle layer combines hooks, the context engine, tools, and runtime management in one plugin registration.
-- All HTTP traffic goes through `OpenVikingClient`, which centralizes `X-OpenViking-*` headers and routing logs.
-- The OpenViking service owns sessions, memories, archives, and Phase 2 extraction, with storage under `viking://user/*`, `viking://agent/*`, and `viking://session/*`.
+- All HTTP traffic goes through `OpenVikingClient`, which centralizes tenant headers and routing logs.
+- The OpenViking service owns sessions, memories, archives, and Phase 2 extraction, with storage under `viking://user/*` (including `viking://user/sessions/*`) and `viking://resources/*`.
 
 That split lets OpenClaw stay focused on reasoning and orchestration while OpenViking becomes the source of truth for long-lived context.
 
 ## Identity and Routing
 
-The plugin does not send one fixed agent ID to OpenViking. It tries to keep OpenClaw session identity and OpenViking routing aligned.
+The plugin keeps OpenClaw session identity in session and peer metadata. It does not send an OpenViking agent identity or create an agent namespace.
 
 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
-- resolve `X-OpenViking-Agent` per session, not per process
-- when `plugins.entries.openviking.config.agent_prefix` is non-empty, prefix the session agent as `<agent_prefix>_<sessionAgent>`
-- when OpenClaw does not provide a session agent, use its default agent `main`
-- send `X-OpenViking-Agent` on OpenViking requests, including startup health checks
+- `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`
+- 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 the plugin is built to support multi-agent and multi-session OpenClaw usage without mixing memories across sessions.
+This matters because OpenViking tenant identity is account/user-scoped, while OpenClaw agent identity is runtime metadata.
 
 The recommended remote-mode configuration only needs:
 
 - `baseUrl`
 - `apiKey`
-- `agent_prefix`
+- optionally `peer_role`
+- optionally `peer_prefix` when `peer_role=assistant`
 
 In this setup:
 
 - `apiKey` should usually be a user key
+- new installs default to `peer_role=assistant`
 - `accountId` / `userId` are advanced options only when the deployment needs explicit identity headers, such as root-key or trusted-server flows
-- `isolateUserScopeByAgent` / `isolateAgentScopeByUser` must match the server-side account namespace policy when using the PR #1356 canonical namespace model
-- `agentScopeMode` is a deprecated compatibility alias for older hash-based routing and should only be used against older servers
-
-### Canonical namespace policy
-
-For OpenViking servers that include PR #1356, the plugin no longer treats agent or user scope as a locally computed hash. Instead it expands shorthand aliases into canonical URIs using the configured namespace policy:
 
-- `viking://user/memories`
-  - `viking://user/<user_id>/memories` when `isolateUserScopeByAgent=false`
-  - `viking://user/<user_id>/agent/<agent_id>/memories` when `isolateUserScopeByAgent=true`
-- `viking://agent/memories`
-  - `viking://agent/<agent_id>/memories` when `isolateAgentScopeByUser=false`
-  - `viking://agent/<agent_id>/user/<user_id>/memories` when `isolateAgentScopeByUser=true`
+### User namespace
 
-The plugin cannot auto-discover this policy today because `/api/v1/system/status` does not expose it. Configure the two booleans explicitly so they stay aligned with the server-side account policy.
+The plugin writes and searches user-scoped memory through `viking://user/...`; OpenViking resolves that alias from the request tenant and actor-peer context. Deprecated agent URI paths are not used by the plugin.
 
 ## assemble Recall Flow
 
@@ -161,9 +164,9 @@ During recall, the plugin:
 1. Extracts query text from the latest user message.
 2. Resolves the agent routing for the current `sessionId/sessionKey`.
 3. Runs a quick availability precheck so model requests do not stall when OpenViking is unavailable.
-4. Queries both `viking://user/memories` and `viking://agent/memories` in parallel.
+4. Queries the configured `recallTargetTypes` (`user,agent` by default; optionally `resource`; use `ov_archive_search` and `ov_archive_expand` for session history).
 5. Deduplicates, threshold-filters, reranks, and trims the results under a token budget.
-6. Prepends the selected memories as a `<relevant-memories>` block to the current user message; it does not append a standalone synthetic user message.
+6. Prepends the selected memories as a `## Long-term Memories` section inside `<openviking-context>` to the current user message; it does not append a standalone synthetic user message.
 
 The reranking logic is not pure vector-score sorting. The current implementation also considers:
 
@@ -198,7 +201,7 @@ That means OpenClaw sees "compressed history summary + archive index + active me
 - it slices only the newly added messages
 - it keeps only `user` / `assistant` capture text
 - it preserves `toolCall` / `toolResult` content in the serialized turn text
-- it strips injected `<relevant-memories>` blocks and metadata noise before capture
+- it strips injected `<openviking-context>` blocks, historical `<relevant-memories>` blocks, and metadata noise before capture
 - it appends the sanitized turn text into the OpenViking session
 
 After that, the plugin checks `pending_tokens`. Once the session crosses `commitTokenThreshold`, it triggers `commit(wait=false)`:
@@ -232,15 +235,19 @@ So `afterTurn()` is closer to "incremental append plus threshold-triggered async
 
 ## Tools and Expandability
 
-Beyond automatic behavior, the plugin exposes seven tools directly:
+Beyond automatic behavior, the plugin exposes these tools directly:
 
 - `memory_recall`: explicit long-term memory search
 - `memory_store`: write explicit long-term facts into an OpenViking session and trigger commit
 - `memory_forget`: delete by URI, or search first and remove a single strong match
 - `ov_archive_expand`: expand a concrete archive back into raw messages
-- `add_resource`: import a document, directory, URL, or Git repository as an OpenViking resource
-- `add_skill`: import or register an OpenViking agent skill
+- `ov_recall_trace`: inspect recent recall/search trace records when `traceRecall` is enabled
+- `add_resource`: import a document, directory, URL, or Git repository as an OpenViking resource when explicitly enabled
+- `add_skill`: import or register an OpenViking skill
 - `ov_search`: search OpenViking resources and skills, especially after importing them
+- `ov_read`: read one exact `viking://` URI returned by `ov_search` or `ov_list`
+- `ov_multi_read`: read multiple exact `viking://` URIs, useful for an overview plus sibling chunks
+- `ov_list`: list a hit's parent directory after `ov_search` to recover sibling chunks, `.overview.md`, and related split-document context
 
 They serve different roles:
 
@@ -251,6 +258,9 @@ They serve different roles:
 - `add_resource` lets the agent save explicit document or repository import requests without asking the user to remember slash commands
 - `add_skill` imports skills into OpenViking, while `add_resource` imports resources
 - `ov_search` closes the loop after import by letting the user or agent confirm and consume resources and skills
+- `ov_read` turns a ranked hit into original evidence before answering precise documentation, codebase, configuration, or procedural questions
+- `ov_multi_read` reads overview and sibling chunks together when a split document needs more context than a single hit
+- `ov_list` complements `ov_search` when a ranked hit is only one chunk of a larger procedure or document
 
 `ov_archive_expand` is especially important because `assemble()` normally returns archive summaries and indexes, not the full raw transcript.
 
@@ -259,7 +269,7 @@ They serve different roles:
 Resource and skill imports are intentionally separate because they land in different OpenViking namespaces and use different server APIs:
 
 - resources go through `/api/v1/resources` and land under `viking://resources/...`
-- skills go through `/api/v1/skills` and land under `viking://agent/skills/...`
+- skills go through `/api/v1/skills` and land under `viking://user/skills/...`
 
 The plugin also registers explicit slash commands for manual imports:
 
@@ -267,7 +277,7 @@ The plugin also registers explicit slash commands for manual imports:
 /add-resource ./README.md --to viking://resources/openviking-readme --wait
 /add-skill ./skills/install-openviking-memory --wait
 /ov-search "OpenViking install" --uri viking://resources/openviking-readme
-/ov-search "memory install skill" --uri viking://agent/skills
+/ov-search "memory install skill" --uri viking://user/skills
 ```
 
 Resource import supports remote URLs, Git URLs, local files, local directories, and uploaded zip files. OpenViking's built-in parsers cover common documents and media such as Markdown, text, PDF, HTML, Word, PowerPoint, Excel, EPUB, images, audio, and video. Directory imports also accept common code, documentation, and config file extensions such as `.py`, `.js`, `.ts`, `.go`, `.rs`, `.java`, `.cpp`, `.json`, `.yaml`, `.toml`, `.csv`, `.rst`, `.proto`, `.tf`, and `.vue`.

package/adapters/http-transport.ts

@@ -0,0 +1,3 @@
+export type HttpTransport = (url: string, init: RequestInit) => Promise<Response>;
+
+export const defaultHttpTransport: HttpTransport = (url, init) => fetch(url, init);

package/adapters/resource-packager.ts

@@ -0,0 +1,141 @@
+import { randomUUID } from "node:crypto";
+import { once } from "node:events";
+import { createWriteStream } from "node:fs";
+import { mkdtemp, readdir, readFile, rm, stat } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { basename, dirname, join, relative } from "node:path";
+
+import { Zip, ZipDeflate } from "fflate";
+
+const REMOTE_RESOURCE_PREFIXES = ["http://", "https://", "git@", "ssh://", "git://"];
+
+export type PackagedResourceSource =
+  | { kind: "remote"; path: string }
+  | { kind: "upload"; uploadPath: string; sourceName?: string; cleanupPath?: string };
+
+export type ResourcePackager = {
+  prepareResourceSource(pathOrUrl: string): Promise<PackagedResourceSource>;
+  prepareLocalUploadSource(path: string): Promise<PackagedResourceSource>;
+  createTempUploadBody(uploadPath: string): Promise<BodyInit>;
+  cleanup(source?: PackagedResourceSource): Promise<void>;
+};
+
+function toBlobPart(value: Buffer): ArrayBuffer {
+  return value.buffer.slice(value.byteOffset, value.byteOffset + value.byteLength) as ArrayBuffer;
+}
+
+export function isRemoteResourceSource(source: string): boolean {
+  return REMOTE_RESOURCE_PREFIXES.some((prefix) => source.startsWith(prefix));
+}
+
+export async function cleanupUploadTempPath(path?: string): Promise<void> {
+  if (!path) {
+    return;
+  }
+  await rm(path, { force: true }).catch(() => undefined);
+  await rm(dirname(path), { recursive: true, force: true }).catch(() => undefined);
+}
+
+export async function zipDirectoryForUpload(dirPath: string): Promise<string> {
+  const rootStats = await stat(dirPath);
+  if (!rootStats.isDirectory()) {
+    throw new Error(`Not a directory: ${dirPath}`);
+  }
+
+  const zipDir = await mkdtemp(join(tmpdir(), "openviking-openclaw-upload-"));
+  const zipPath = join(zipDir, `${basename(dirPath).replace(/[^a-zA-Z0-9._-]/g, "_")}-${randomUUID()}.zip`);
+  const output = createWriteStream(zipPath);
+  const outputClosed = once(output, "close");
+  const outputErrored = once(output, "error").then(([err]) => Promise.reject(err));
+  const zip = new Zip((err, chunk, final) => {
+    if (err) {
+      output.destroy(err);
+      return;
+    }
+    if (chunk?.length) {
+      output.write(Buffer.from(chunk));
+    }
+    if (final) {
+      output.end();
+    }
+  });
+
+  const walk = async (currentDir: string) => {
+    const entries = await readdir(currentDir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = join(currentDir, entry.name);
+      if (entry.isDirectory()) {
+        await walk(fullPath);
+        continue;
+      }
+      if (!entry.isFile()) {
+        continue;
+      }
+      const relPath = relative(dirPath, fullPath).split("\\").join("/");
+      if (!relPath || relPath.startsWith("../") || relPath.includes("/../")) {
+        throw new Error(`Unsafe relative path while zipping: ${relPath}`);
+      }
+      const file = new ZipDeflate(relPath);
+      zip.add(file);
+      file.push(new Uint8Array(await readFile(fullPath)), true);
+    }
+  };
+  try {
+    await walk(dirPath);
+    zip.end();
+    await Promise.race([outputClosed, outputErrored]);
+  } catch (err) {
+    zip.terminate();
+    output.destroy(err as Error);
+    await cleanupUploadTempPath(zipPath);
+    throw err;
+  }
+  return zipPath;
+}
+
+async function prepareLocalUploadSource(path: string, includeSourceName = false): Promise<PackagedResourceSource> {
+  const localStats = await stat(path);
+  if (localStats.isDirectory()) {
+    const uploadPath = await zipDirectoryForUpload(path);
+    return {
+      kind: "upload",
+      uploadPath,
+      cleanupPath: uploadPath,
+      ...(includeSourceName ? { sourceName: basename(path) } : {}),
+    };
+  }
+  if (!localStats.isFile()) {
+    throw new Error(`Path is not a file or directory: ${path}`);
+  }
+  return { kind: "upload", uploadPath: path };
+}
+
+export const defaultResourcePackager: ResourcePackager = {
+  async prepareResourceSource(pathOrUrl: string): Promise<PackagedResourceSource> {
+    if (isRemoteResourceSource(pathOrUrl)) {
+      return { kind: "remote", path: pathOrUrl };
+    }
+    return prepareLocalUploadSource(pathOrUrl, true);
+  },
+
+  async prepareLocalUploadSource(path: string): Promise<PackagedResourceSource> {
+    return prepareLocalUploadSource(path, false);
+  },
+
+  async createTempUploadBody(uploadPath: string): Promise<BodyInit> {
+    const fileBytes = await readFile(uploadPath);
+    const form = new FormData();
+    form.append(
+      "file",
+      new Blob([toBlobPart(fileBytes)], { type: "application/octet-stream" }),
+      basename(uploadPath),
+    );
+    return form;
+  },
+
+  async cleanup(source?: PackagedResourceSource): Promise<void> {
+    if (source?.kind === "upload") {
+      await cleanupUploadTempPath(source.cleanupPath);
+    }
+  },
+};