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

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

@@ -13,7 +13,7 @@ description: >
   The user does NOT need to know any CLI commands — the agent runs everything and only asks for a few values.
   This skill assumes the OpenViking server is already running. If the server is not ready, the skill
   tells the user to contact their admin or set it up via the OpenViking docs — it does NOT install the server.
-version: 2.0.1
+version: 2026.6.5
 metadata:
   openclaw:
     requires:
@@ -118,7 +118,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. **Agent prefix** (optional) — used to namespace memories across agents. Leave blank for default.
+> 3. **peer prefix** (optional) — used to namespace memories across agents. Leave blank for default.
 >
 > What's the server URL?
 
@@ -144,10 +144,10 @@ 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. `AGENT_PREFIX` (OPTIONAL)
+### 4c. `PEER_PREFIX` (OPTIONAL)
 
 > (CN) 想给这个 agent 一个记忆前缀吗？留空就用默认。只能用字母、数字、`_`、`-`。
-> (EN) Want to set an agent prefix? Leave blank for the default. Letters, digits, `_`, `-` only.
+> (EN) Want to set an peer prefix? Leave blank for the default. Letters, digits, `_`, `-` only.
 
 - Empty / "default" / "默认" → leave unset (plugin defaults to `""`).
 - Otherwise validate against `/^[A-Za-z0-9_-]+$/`. If invalid, ask again.
@@ -262,14 +262,14 @@ 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] [--agent-prefix AGENT_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-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 `--agent-prefix AGENT_PREFIX` only if the user gave one.
+- Pass `--peer-prefix PEER_PREFIX` only if the user gave one.
 - `--account-id` / `--user-id` only if the root-key path requires them.
 
 `ov-install` will, in one shot:
@@ -290,14 +290,14 @@ 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] [--agent-prefix AGENT_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-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.
-- `--agent-prefix` only if the user gave one. Use **`--agent-prefix`**, not `--agent-id` (deprecated and removed).
+- `--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.
 - `--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).
@@ -310,10 +310,10 @@ The wizard prints a single JSON object:
 {
   "success": true | false,
   "action": "configured" | "existing" | "error" | "slot_blocked",
-  "config": { "mode": "remote", "baseUrl": "...", "apiKey": "...", "agent_prefix": "...", "accountId": "...", "userId": "..." },
-  "health": { "ok": true, "status": 200 },
-  "keyProbe": { "keyType": "user_key" | "root_key" | "none", "ok": true },
-  "slot": { "ok": true, "owner": "openviking" },
+  "config": { "mode": "remote", "baseUrl": "...", "apiKey": "...", "peer_prefix": "...", "accountId": "...", "userId": "..." },
+  "health": { "ok": true, "version": "...", "compatibility": "compatible" | "server_too_old" | "server_too_new" | "unknown" },
+  "keyProbe": { "keyType": "user_key" | "root_key" | "no_key" | "unknown", "needsAccountId": false, "needsUserId": false, "detail": "..." },
+  "slot": { "activated": true, "replaced": false, "previousOwner": "openviking" },
   "error": "..."
 }
 ```
@@ -326,7 +326,7 @@ The wizard prints a single JSON object:
 | `success: false` and `action: "slot_blocked"` | **Slot conflict — see below.** |
 | `success: false` and `error` contains `"Server unreachable"` | Connectivity broke between STEP 5 and STEP 7. Offer `--allow-offline`; if accepted, retry. Otherwise back to STEP 4a. |
 | `success: false` and `error` contains `"Root API key detected"` and `"Missing: --account-id, --user-id"` | **Root-key path — see below.** |
-| `success: false` and `error` contains `"Invalid API key"` / `keyProbe.keyType: "none"` with `ok: false` | API key wrong. Back to STEP 4b. |
+| `success: false` and `error` contains `"Invalid API key"` / `keyProbe.keyType: "unknown"` after auth failure detail | API key wrong. Back to STEP 4b. |
 | `success: false` and any other `action: "error"` | Show `error` to the user, stop. Do NOT pretend success. |
 
 ### Slot conflict (`slot_blocked`)
@@ -397,7 +397,7 @@ Expected output:
   "configured": true,
   "slotActive": true,
   "health": { "ok": true },
-  "config": { "baseUrl": "...", "agent_prefix": "..." }
+  "config": { "baseUrl": "...", "peer_prefix": "..." }
 }
 ```
 
@@ -413,22 +413,20 @@ Expected output:
 > (CN) 🎉 全部搞定！OpenViking 长期记忆已经接好了。
 >
 > 工作方式：
-> - **每一轮**：你的对话会被自动追加到 OpenViking session 里；自动抽取依赖阈值 commit 或 `/compact`
-> - **明确要记住时**：如果你说“记住/保存/存一下”某个长期事实，我会用 `memory_store` 立即提交到记忆管线
-> - **`/compact` 时**：待提交的 session 消息会被抽取成长期记忆，写到 `~/.openviking/data/` 下
+> - **每一轮**：你的对话会被自动归档到 OpenViking session 里
+> - **`/compact` 时**：归档消息会在 OpenViking 服务端被抽取成长期记忆
 > - **后续会话**：每次回复前我都会自动搜一下相关记忆并带进上下文
 >
-> 想验证一下吗？可以直接说“记住我的邮箱是 test@example.com”，让我通过 `memory_store` 立即提交；或者先聊几句包含可记忆事实的话，再调一下 `/compact`。之后开新对话问“我的邮箱是？”，应该就能召回了。
+> 想验证一下吗？跟我聊几句包含可记忆事实的话（例如"我的邮箱是 test@example.com"），然后调一下 `/compact`，再开新对话问"我的邮箱是？"，应该就能召回了。
 
 > (EN) 🎉 All set! OpenViking long-term memory is connected.
 >
 > How it works:
-> - **Every turn**: our messages are appended to an OpenViking session; automatic extraction depends on a threshold commit or `/compact`
-> - **Explicit remember requests**: if you ask me to remember/save/store a long-term fact, I can use `memory_store` to commit it immediately
-> - **On `/compact`**: pending session messages are extracted into long-term memories under `~/.openviking/data/`
+> - **Every turn**: our messages are auto-archived into an OpenViking session
+> - **On `/compact`**: archived messages are extracted into long-term memories on the OpenViking server
 > - **Future sessions**: relevant memories are auto-retrieved and injected before my replies
 >
-> Want to verify? Say "remember my email is test@example.com" so I can commit it via `memory_store`, or tell me a few memory-worthy facts and run `/compact`. Then start a new chat and ask "what's my email?" — it should recall.
+> Want to verify? Tell me a few facts (e.g. "my email is test@example.com"), run `/compact`, then start a new chat and ask "what's my email?" — it should recall.
 
 ---
 
@@ -436,25 +434,15 @@ Expected output:
 
 ## How It Works
 
-The context-engine pipeline has three distinct stages plus one explicit write path — keep them apart, especially when telling users when memories actually appear in `~/.openviking/data/`:
+The context-engine pipeline has three distinct stages — keep them apart, especially when telling users when memories become searchable long-term memory on the OpenViking server:
 
-- **Archive / capture (context-engine `afterTurn`)**: at the end of a user turn, the plugin appends user/assistant messages to the OpenViking session via `POST /api/v1/sessions/.../messages`. This is **session capture only** unless `pending_tokens` crosses `commitTokenThreshold`; below the threshold, no memory extraction runs yet. You'll see session message counts grow on the server, but no new files under `viking://user/.../memories/`.
-- **Memory extraction (threshold commit or `/compact`)**: memory extraction runs after a session commit. The commit can be triggered asynchronously when `afterTurn` crosses `commitTokenThreshold`, synchronously when the user invokes OpenClaw's `/compact` command, or explicitly by `memory_store`. The server-side extraction pipeline reads the archived session and writes new memories.
+- **Archive / capture (context-engine `afterTurn`)**: at the end of a user turn, the plugin commits user/assistant messages to the OpenViking session via `POST /api/v1/sessions/.../messages`. This is **archive only** — no memory extraction yet. You'll see session message counts grow on the server, but no new files under `viking://user/.../memories/`.
+- **Memory extraction (on `/compact`)**: memory extraction runs when the user invokes OpenClaw's `/compact` command. The server-side extraction pipeline reads the archived session and writes new memories. The plugin's `after_compaction` hook is currently reserved; the extraction itself is driven by the server. **No `/compact`, no new memory files.**
   - `captureMode: "semantic"` (default): server extraction pipeline filters all qualifying text.
   - `captureMode: "keyword"`: only text matching trigger words (e.g. "remember", "preference") is considered.
 - **Auto-Recall (context-engine `assemble()`)**: before prompt context is assembled, the plugin queries OpenViking for relevant memories and injects them into context. Recall works even when there are no extracted memories yet — you just won't see anything come back.
 
-**Practical implication for testing**: if you write down a short fact and immediately try to recall it without a threshold commit, `/compact`, or `memory_store`, the plugin may only retrieve it as recent session context, not as a long-term memory. To verify long-term memory cross-session deterministically, run `/compact` or use `memory_store` for the fact being tested.
-
-### Explicit long-term memory writes
-
-Auto-capture is best-effort and commit-dependent. When the user explicitly says to remember, save, or store an important long-term fact, preference, project, or decision, the agent should call `memory_store` instead of waiting for ordinary auto-capture.
-
-Use `memory_store` as the integration-side reliable path for durable-memory intent:
-
-- It writes the supplied text into an OpenViking session and calls `commit(wait=true)`.
-- It complements auto-capture; it does not replace normal session capture.
-- If it commits but extracts 0 memories, the explicit path has done its job. Treat that as a server-side extraction/model/configuration issue and check OpenViking logs.
+**Practical implication for testing**: if you write down a fact and immediately try to recall it without `/compact`, the plugin will only retrieve it as recent session context (archived messages), not as a long-term memory. To verify long-term memory cross-session, you must run `/compact` first.
 
 ## Available Tools
 
@@ -467,7 +455,8 @@ These are the plugin tools the agent can call once installed.
 | `query` | Yes | Search query text |
 | `limit` | No | Maximum number of results (defaults to plugin config) |
 | `scoreThreshold` | No | Minimum relevance score 0–1 (defaults to plugin config) |
-| `targetUri` | No | Search scope URI (defaults to plugin config) |
+| `targetUri` | No | Exact search scope URI. If provided, only that URI is searched. |
+| `resourceTypes` | No | Array of target types used when `targetUri` is omitted: `resource`, `user`, `agent`. Defaults to plugin `recallTargetTypes`. |
 
 Example: user asks "What programming language did I say I like?"
 
@@ -479,8 +468,6 @@ Example: user asks "What programming language did I say I like?"
 | `role` | No | Session role (default `user`) |
 | `sessionId` | No | Existing OpenViking session ID |
 
-Use this when the user explicitly asks to remember/save/store a long-term fact, preference, project, or decision.
-
 Example: user says "Remember my email is xxx@example.com".
 
 ### `memory_forget` — Delete Memories
@@ -495,6 +482,87 @@ Example: user says "Remember my email is xxx@example.com".
 
 Example: user says "Forget my phone number".
 
+### `ov_archive_search` — Search Archived Original Messages
+
+| Parameter | Required | Description |
+|---|---|---|
+| `query` | Yes | A single keyword or short phrase. Prefer concrete names, dates, commands, paths, or distinctive nouns. |
+| `archiveId` | No | Optional archive ID such as `archive_002`. |
+
+Use when `[Session History Summary]` is too coarse. Try at least two keyword variants before concluding the detail is unavailable.
+
+### `ov_archive_expand` — Expand An Archive
+
+| Parameter | Required | Description |
+|---|---|---|
+| `archiveId` | Yes | Archive ID from `[Archive Index]`, e.g. `archive_002`. |
+
+### `add_resource` — Import Resource
+
+The agent-visible `add_resource` tool is disabled by default (`enableAddResourceTool=false`). Use manual `/add-resource` for resource ingestion unless you explicitly opt in. Even when enabled, never use `add_resource` during search, retrieval, URI reading, or search-result optimization; use `ov_search` and `ov_read` for those flows.
+
+| Parameter | Required | Description |
+|---|---|---|
+| `source` | Yes | Local path, OpenClaw media attachment path, directory path, public URL, or Git URL. |
+| `to` | No | Exact target URI under `viking://resources`; mutually exclusive with `parent`. |
+| `parent` | No | Parent URI under `viking://resources`; mutually exclusive with `to`. |
+| `reason` | No | Reason or note for import. |
+| `instruction` | No | Processing instruction for semantic extraction. |
+| `wait` | No | Wait for processing completion. |
+| `timeout` | No | Timeout in seconds when `wait=true`. |
+
+### `add_skill` — Import Agent Skill
+
+| Parameter | Required | Description |
+|---|---|---|
+| `source` | No | Local `SKILL.md` path or skill directory. Exactly one of `source` or `data` is required. |
+| `data` | No | Raw `SKILL.md` content or MCP tool dict. Exactly one of `source` or `data` is required. |
+| `wait` | No | Wait for processing completion. |
+| `timeout` | No | Timeout in seconds when `wait=true`. |
+
+Agent Skill best practice: verify frontmatter has a precise `name`, a trigger-oriented `description`, useful `tags`, explicit scope boundaries, and concrete execution steps. Do not include secrets in skill content.
+
+### `ov_search` — Search Resources and Skills
+
+| Parameter | Required | Description |
+|---|---|---|
+| `query` | Yes | Search query. |
+| `uri` | No | Optional search URI. Defaults to resources plus agent skills. |
+| `limit` | No | Max results per search scope. Default: 10. |
+
+Important: `ov_search` result URIs are OpenViking virtual URIs, not local file paths. If full content is needed, call `ov_read` with the exact `viking://...` URI returned by search or trace results; do not use filesystem read tools.
+
+### `ov_read` — Read OpenViking Content
+
+| Parameter | Required | Description |
+|---|---|---|
+| `uri` | Yes | Exact `viking://...` URI returned by `ov_search` or recall trace results. Local file paths and `openviking://...` display aliases are refused. |
+
+### `ov_recall_trace` — Query Recall Trace
+
+| Parameter | Required | Description |
+|---|---|---|
+| `turn` | No | `latest` or `all`; default `latest`. |
+| `traceId` | No | Exact trace ID. |
+| `sessionId` / `sessionKey` / `ovSessionId` | No | Session filters. |
+| `source` | No | `auto_recall`, `memory_recall`, `ov_search`, or `ov_archive_search`. |
+| `resourceTypes` | No | Target type filters: `resource`, `user`, `agent`. |
+| `since` / `until` | No | Unix timestamp bounds in milliseconds. |
+| `includeContent` | No | Read selected/displayed URI content previews on demand. |
+| `limit` | No | Maximum traces to return. Default: 20. |
+
+Requires `traceRecall=true`; persisted lookup also requires `traceRecallPersist=true`.
+
+### Externalized Tool Result Tools
+
+Use these when a preview contains a `viking://session/<session_id>/tool-results/<tool_result_id>` ref.
+
+| Tool | Parameters |
+|---|---|
+| `openviking_tool_result_list` | `tool_name?`, `limit?` (default 50) |
+| `openviking_tool_result_search` | `tool_output_ref`, `query`, `limit?` (default 20), `context_chars?` (default 300) |
+| `openviking_tool_result_read` | `tool_output_ref`, `offset?` (default 0), `limit?` (default 20000) |
+
 ## Configuration Schema
 
 These are the keys under `plugins.entries.openviking.config` in `openclaw.json`. The setup wizard / `ov-install` sets the first few; the rest are tunables.
@@ -504,27 +572,32 @@ 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. |
-| `agent_prefix` | `""` | Prefix for routing memories per agent. Letters / digits / `_` / `-`. |
+| `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 / `_` / `-`. |
 | `accountId` | — | Required when `apiKey` is a root key. |
 | `userId` | — | Required when `apiKey` is a root key. |
 | `targetUri` | `viking://user/memories` | Default search scope URI. |
 | `timeoutMs` | (plugin default) | HTTP timeout for OpenViking calls. |
-| `autoCapture` | `true` | Auto-append turn messages to the OpenViking session at `afterTurn`; extraction runs only after a threshold commit, `/compact`, or explicit `memory_store`. |
+| `autoCapture` | `true` | Auto-archive turn messages to OpenViking session at `afterTurn` (extraction itself runs on `/compact`, not here). |
 | `captureMode` | `"semantic"` | Filter mode used by the server-side extraction pipeline: `semantic` or `keyword`. |
 | `captureMaxLength` | `24000` | Max text length per archived turn. |
 | `autoRecall` | `true` | Auto-recall and inject memories before reply. |
+| `recallTargetTypes` | `user,agent` | Default target types when `targetUri` is omitted. Allowed: `resource`, `user`, `agent`. |
+| `recallResources` | `false` | Compatibility shortcut that appends `resource` to default recall targets when `recallTargetTypes` is unset. |
 | `recallLimit` | `6` | Max memories injected per recall. |
 | `recallScoreThreshold` | `0.15` | Min relevance score to inject. |
-| `recallMaxInjectedChars` | (plugin default) | Hard cap on injected character count. |
+| `recallMaxInjectedChars` | `4000` | Hard cap on injected character count. Complete memories that do not fit are skipped, not truncated. |
 | `recallPreferAbstract` | (plugin default) | Prefer abstract memories over raw. |
-| `recallTokenBudget` | (plugin default) | Token budget for injected memories. |
-| `isolateUserScopeByAgent` | (plugin default) | Multi-tenant scoping toggle. |
-| `isolateAgentScopeByUser` | (plugin default) | Multi-tenant scoping toggle. |
-| `agentScopeMode` | (plugin default) | Agent scope strategy. |
+| `recallTokenBudget` | deprecated | Compatibility alias for `recallMaxInjectedChars`. |
+| `commitTokenThreshold` | `20000` | Pending-token threshold for async commit after turns; `0` commits every turn. |
+| `commitKeepRecentCount` | `10` | Recent messages kept live after afterTurn commit. Compact always uses `0`. |
 | `bypassSessionPatterns` | — | Glob patterns for sessions skipped by capture. |
 | `ingestReplyAssist` | (plugin default) | Reply-assist ingestion toggle. |
-| `emitStandardDiagnostics` | (plugin default) | Verbose diagnostic logs. |
-| `logFindRequests` | (plugin default) | Log retrieval requests. |
+| `emitStandardDiagnostics` | `false` | Emit structured `openviking: diag {...}` lines. |
+| `logFindRequests` | `false` | Log routing for find/session writes. Also enabled by `OPENVIKING_LOG_ROUTING=1` or `OPENVIKING_DEBUG=1`. |
+| `traceRecall` | `false` | Record recall traces in memory. |
+| `traceRecallPersist` | `false` | Persist recall traces to JSONL files. |
+| `traceRecallDir` | `~/.openclaw/openviking/recall-traces` | Recall trace directory. |
 
 To change a value:
 
@@ -659,7 +732,7 @@ Match against actual stderr / JSON `error` strings.
 | `Server unreachable: …. Use --allow-offline to save config anyway.` | Setup couldn't reach server | Offer `--allow-offline`. |
 | `contextEngine slot is owned by "<x>". … Use --force-slot to replace.` | Slot conflict | Ask user, then retry with `--force-slot`. |
 | `Root API key detected. Missing: --account-id, --user-id` | Multi-tenant key | Collect both, retry with `--account-id` `--user-id`. |
-| `openviking: config parse failed` (in gateway log) | Bad value in `openclaw.json` | Show user; check `agent_prefix` charset, URL format. |
+| `openviking: config parse failed` (in gateway log) | Bad value in `openclaw.json` | Show user; check `peer_prefix` charset, URL format. |
 | `extracted 0 memories` after a turn | Server VLM/embedding misconfigured | **Out of scope.** Tell user this is a server-side issue — ask their OpenViking admin to check VLM / embedding config. |
 | `401` / `403` on plugin requests, but `/health` works | Server requires auth on API endpoints | Re-run STEP 7 with the correct `--api-key`. |
 | Plugin doesn't appear in `openclaw plugins list` after Path A | Install didn't actually finish | Re-run Path A; use Path B only if the failure is registry/rate-limit related. |
@@ -671,7 +744,7 @@ Match against actual stderr / JSON `error` strings.
 3. **Never silently use `--force-slot`.** Slot replacement disables another plugin — always confirm with the user first.
 4. **Never invent values.** If the user can't provide a required value, stop and tell them what to ask their admin.
 5. **Never claim success without STEP 10.** Only after `openclaw openviking status --json` shows `configured: true && slotActive: true && health.ok: true` may you tell the user it's done.
-6. **Use `--agent-prefix`, not `--agent-id`.** The latter is deprecated and removed from the schema.
+6. **Use `--peer-prefix` for assistant peer prefixes.** The old ID-style setup flag is no longer supported by the schema.
 7. **For Windows, use PowerShell equivalents.** Don't rely on `nohup`, `&`, `mkdir -p`, `source`, etc.
 8. **Switch to Path B (ov-install) only for ClawHub/rate-limit/registry availability failures.** Don't use it to hide version conflicts or package validation errors.
 9. **Do NOT install or operate the OpenViking server.** This skill assumes the server is already running. If it isn't, tell the user to contact their admin or follow the OpenViking docs.

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

@@ -0,0 +1,286 @@
+---
+name: openviking-context-database
+description: >
+  Use OpenViking from OpenClaw through @openviking/openclaw-plugin: long-term memory,
+  session archives, resource and Agent Skill import, semantic recall, recall trace debugging,
+  and externalized tool-result recovery. Prefer this skill when the user wants to use, query,
+  debug, or operate OpenViking context from an OpenClaw agent. For first-time plugin installation,
+  use the install-openviking-memory skill instead.
+version: 2026.6.5
+metadata:
+  openclaw:
+    requires:
+      plugin: "@openviking/openclaw-plugin"
+  emoji: "🦣"
+tags:
+  - openviking
+  - context-engine
+  - memory
+  - resources
+  - skills
+  - recall-trace
+---
+
+# OpenViking Context Database — OpenClaw Plugin Operator Skill
+
+Use this skill after `@openviking/openclaw-plugin` is installed and configured. It describes the current OpenClaw plugin implementation, not the standalone OpenViking Python SDK.
+
+## Scope and Safety Rules
+
+- The plugin is **remote-only**. It talks to an existing OpenViking server through HTTP and does not start or manage `openviking-server`.
+- Do not invent OpenViking REST endpoints. Use the registered OpenClaw tools and commands described below.
+- The agent-visible `add_resource` tool is disabled by default (`enableAddResourceTool=false`). Do not use `add_resource` during search, retrieval, URI reading, or search-result optimization. Use `ov_search` and `ov_read` in those flows.
+- Use manual `/add-resource`, or `add_resource` only when it is explicitly enabled and the user explicitly asks to import, add, upload, save, or index a resource.
+- Use `add_skill` only when the user explicitly asks to import, add, install, or register an Agent Skill into OpenViking.
+- For local files and directories, pass the local path to the plugin tool. The plugin uploads them through `/api/v1/resources/temp_upload`; do not send raw local filesystem paths to a remote server yourself.
+- Never log or echo API keys. The plugin sends API keys as `X-API-Key` / setup probe headers and masks them in setup output.
+
+## Current Architecture
+
+OpenClaw owns agent execution, prompts, and tool invocation. OpenViking owns long-lived context:
+
+| Layer | Current behavior |
+|---|---|
+| `assemble` | Rebuilds compressed session history from OpenViking and injects relevant recall into the latest user message. |
+| `afterTurn` | Appends only the new turn to the OpenViking session; may trigger async commit when `pending_tokens >= commitTokenThreshold`. |
+| `compact` | Runs `commit(wait=true)`, waits for archive/extraction completion, and reads back latest archive overview. |
+| Tools | Memory recall/store/forget, archive search/expand, resource/skill import/search, recall trace query, tool-result list/search/read. |
+
+Long-term memories are usually extracted on `/compact` or on threshold-triggered commit. A fact mentioned in a fresh conversation may still be present as recent session context before it becomes a long-term memory.
+
+## Configuration Quick Reference
+
+Read status first:
+
+```bash
+openclaw openviking status --json
+openclaw config get plugins.entries.openviking.config
+openclaw config get plugins.slots.contextEngine
+```
+
+Core config lives under `plugins.entries.openviking.config`:
+
+| Field | Default | Purpose |
+|---|---:|---|
+| `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_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://user/memories` | Default search scope for legacy targeted memory search. |
+| `autoCapture` | `true` | Append sanitized turn text to OpenViking sessions. |
+| `captureMode` | `semantic` | `semantic` or `keyword`; affects server-side extraction filtering. |
+| `captureMaxLength` | `24000` | Max sanitized text length per captured turn. |
+| `autoRecall` | `true` | Run recall before replies and inject relevant context. |
+| `recallTargetTypes` | `user,agent` | Default target types when `targetUri` is omitted. Allowed: `resource`, `user`, `agent`. |
+| `recallResources` | `false` | Compatibility shortcut that appends `resource` to default recall targets when `recallTargetTypes` is unset. |
+| `recallLimit` | `6` | Max selected recall items. |
+| `recallScoreThreshold` | `0.15` | Min score after post-processing. |
+| `recallMaxInjectedChars` | `4000` | Total injected character cap; complete memories that do not fit are skipped. |
+| `commitTokenThreshold` | `20000` | Pending-token threshold for async commit after turns; `0` commits every turn. |
+| `commitKeepRecentCount` | `10` | Recent messages kept live after afterTurn commit. Compact always uses `0`. |
+| `bypassSessionPatterns` | empty | Glob-like session keys that completely bypass OpenViking (`*` segment, `**` multi-segment). |
+| `emitStandardDiagnostics` | `false` | Emit structured `openviking: diag {...}` lines. |
+| `logFindRequests` | `false` | Log routing for find/session writes. Also enabled by `OPENVIKING_LOG_ROUTING=1` or `OPENVIKING_DEBUG=1`. |
+| `traceRecall` | `false` | Record recall traces in memory. |
+| `traceRecallPersist` | `false` | Persist recall traces as local JSONL files. |
+| `traceRecallDir` | `~/.openclaw/openviking/recall-traces` | Recall trace directory when persistence is enabled. |
+
+Normal setup command:
+
+```bash
+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 <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
+openclaw openviking setup --base-url <URL> --api-key <KEY> --force-slot --json
+```
+
+## Tool Selection Guide
+
+| User intent | Use |
+|---|---|
+| “What did I say before?”, preferences, decisions, known facts | `memory_recall` |
+| “Remember this now” | `memory_store` |
+| “Forget X” | `memory_forget` |
+| Summary lacks an exact command/path/snippet from old chat | `ov_archive_search`, then `ov_archive_expand` if needed |
+| Import docs, PDFs, local dirs, URLs, Git repos, media attachments | manual `/add-resource`; `add_resource` only if `enableAddResourceTool=true` |
+| Import/register an Agent Skill | `add_skill` |
+| Search imported resources or skills | `ov_search` |
+| Read an exact `viking://...` hit from `ov_search` or recall trace | `ov_read` |
+| Explain why recall/search returned something | `ov_recall_trace` |
+| A previous tool result shows only a preview/ref | `openviking_tool_result_list`, `openviking_tool_result_search`, `openviking_tool_result_read` |
+
+## Tool Interface Reference
+
+### `memory_recall`
+
+Semantic search over memories/resources. Use archive tools for session history.
+
+| Parameter | Required | Description |
+|---|---|---|
+| `query` | Yes | Search query. |
+| `limit` | No | Max selected results. Defaults to `recallLimit`. |
+| `scoreThreshold` | No | Score threshold `0..1`. Defaults to `recallScoreThreshold`. |
+| `targetUri` | No | Exact search URI. If set, only this URI is searched. |
+| `resourceTypes` | No | Array of `resource`, `user`, `agent`; used only when `targetUri` is omitted. |
+
+Notes: when `targetUri` is omitted, the plugin resolves a search plan from `resourceTypes` or configured `recallTargetTypes`, fetches more candidates than requested, deduplicates, filters leaf memories, reranks, and respects `recallMaxInjectedChars`.
+
+### `memory_store`
+
+Persist text immediately by writing a session and committing with `wait=true`.
+
+| Parameter | Required | Description |
+|---|---|---|
+| `text` | Yes | Information source text. |
+| `role` | No | Session role, default `user`. |
+| `sessionId` | No | Existing OpenViking/OpenClaw session reference. If omitted, a temporary `memory-store-*` session is created. |
+
+### `memory_forget`
+
+Delete a memory.
+
+| Parameter | Required | Description |
+|---|---|---|
+| `uri` | No | Exact `viking://user/.../memories/...` memory URI. Non-memory URIs are refused. |
+| `query` | No | Search query when `uri` is unknown. |
+| `targetUri` | No | Search scope URI, default `targetUri`. |
+| `limit` | No | Search limit, default `5`. |
+| `scoreThreshold` | No | Search threshold, default `recallScoreThreshold`. |
+
+If query mode finds multiple candidates, report candidates and ask the user to choose the exact URI; do not delete ambiguous memories.
+
+### `ov_archive_search`
+
+Keyword grep across archived original conversation messages of the current session.
+
+| Parameter | Required | Description |
+|---|---|---|
+| `query` | Yes | Single keyword or short phrase; prefer names, dates, file paths, commands, or distinctive nouns. |
+| `archiveId` | No | Restrict to one archive, e.g. `archive_002`. |
+
+Try at least two concrete keyword variants before concluding archived detail is unavailable.
+
+### `ov_archive_expand`
+
+| Parameter | Required | Description |
+|---|---|---|
+| `archiveId` | Yes | Archive ID from `[Archive Index]`, e.g. `archive_002`. |
+
+Use after an archive search or when the `[Archive Index]` already identifies the archive likely to contain exact detail.
+
+### `add_resource`
+
+Import resources into `viking://resources/...`.
+
+This agent tool is disabled by default. Prefer manual `/add-resource` for resource ingestion. If `enableAddResourceTool=true` exposes the tool, use it only for explicit import/index requests and never as part of search/retrieval optimization.
+
+| Parameter | Required | Description |
+|---|---|---|
+| `source` | Yes | Local path, OpenClaw media attachment path, directory path, public URL, or Git URL. |
+| `to` | No | Exact target URI, e.g. `viking://resources/project-docs`. Mutually exclusive with `parent`. |
+| `parent` | No | Parent URI under `viking://resources`. Mutually exclusive with `to`. |
+| `reason` | No | Reason/note for import. |
+| `instruction` | No | Processing instruction for semantic extraction. |
+| `wait` | No | Wait for processing completion. |
+| `timeout` | No | Timeout in seconds when `wait=true`. |
+
+The current OpenClaw tool exposes the parameters above. The underlying client also supports server-facing resource options such as `strict`, `ignore_dirs`, `include`, `exclude`, and `preserve_structure` for command/internal paths; do not pass them to the tool unless the registered schema exposes them.
+
+### `add_skill`
+
+Import Agent Skills into `viking://user/skills/...`.
+
+| Parameter | Required | Description |
+|---|---|---|
+| `source` | No | Local `SKILL.md` path or skill directory. Exactly one of `source` or `data` is required. |
+| `data` | No | Raw `SKILL.md` content or an MCP tool dict. Exactly one of `source` or `data` is required. |
+| `wait` | No | Wait for processing completion. |
+| `timeout` | No | Timeout in seconds when `wait=true`. |
+
+Agent Skill best practice: a skill should have precise frontmatter (`name`, trigger-oriented `description`, useful `tags`), clear scope boundaries, explicit “when not to use” guidance if needed, and executable steps with concrete parameters. Keep secrets out of skill content.
+
+### `ov_search`
+
+| Parameter | Required | Description |
+|---|---|---|
+| `query` | Yes | Search query. |
+| `uri` | No | Search URI. Defaults to resources plus agent skills. |
+| `limit` | No | Max results per scope, default `10`. |
+
+Use after importing resources/skills, or when the user asks to search OpenViking-managed knowledge.
+
+Important: `ov_search` returns OpenViking virtual URIs such as `viking://resources/project-docs/api.md#chunk-3`. These are not local file paths. Do not use filesystem read tools for them; call `ov_read` with the exact URI when full content is needed.
+
+### `ov_read`
+
+Read full content for one exact OpenViking virtual URI through `/api/v1/content/read`.
+
+| Parameter | Required | Description |
+|---|---|---|
+| `uri` | Yes | Exact `viking://...` URI returned by `ov_search` or recall trace results. `openviking://...` aliases and local file paths are refused. |
+
+### `ov_recall_trace`
+
+| Parameter | Required | Description |
+|---|---|---|
+| `turn` | No | `latest` or `all`, default `latest`. |
+| `traceId` | No | Exact trace ID. |
+| `sessionId` / `sessionKey` / `ovSessionId` | No | Filter by OpenClaw/OpenViking session. |
+| `source` | No | `auto_recall`, `memory_recall`, `ov_search`, or `ov_archive_search`. |
+| `resourceTypes` | No | Array/string containing `resource`, `user`, `agent`. |
+| `since` / `until` | No | Unix timestamp bounds in milliseconds. |
+| `includeContent` | No | Read selected/displayed URI content previews on demand. |
+| `limit` | No | Maximum traces to return, default `20`. |
+
+Trace records exist only when `traceRecall=true`; persisted lookup requires `traceRecallPersist=true` and accessible trace files.
+
+### Externalized tool-result tools
+
+Use when a preview contains `viking://session/<session_id>/tool-results/<tool_result_id>`.
+
+| Tool | Parameters |
+|---|---|
+| `openviking_tool_result_list` | `tool_name?`, `limit?` (default `50`) |
+| `openviking_tool_result_search` | `tool_output_ref`, `query`, `limit?` (default `20`), `context_chars?` (default `300`) |
+| `openviking_tool_result_read` | `tool_output_ref`, `offset?` (default `0`), `limit?` (default `20000`, `-1` accepted by server path for all remaining content) |
+
+The plugin refuses to read/search a tool-result ref from another session.
+
+## Slash Commands
+
+```text
+/add-resource ./README.md --to viking://resources/openviking-readme --wait
+/add-skill ./skills/install-openviking-memory --wait --timeout=30
+/ov-search "OpenViking install" --uri viking://resources/openviking-readme --limit=5
+/ov-recall-trace --turn latest --source auto_recall --include-content
+```
+
+Command parsers support quoted args and flags. Resource-only flags are rejected for skill imports.
+
+## Troubleshooting
+
+| Symptom | Likely cause | First action |
+|---|---|---|
+| `configured=false` | Setup did not persist config | Re-run `openclaw openviking setup ... --json`; branch on JSON `error`. |
+| `slotActive=false` | Another context engine owns the slot or gateway has stale state | Inspect `plugins.slots.contextEngine`; use `--force-slot` only after user confirms. |
+| `health.ok=false` | Server unreachable or wrong `baseUrl` / key | Check `baseUrl`, network, `/health`, and auth. |
+| No long-term memory after a fresh fact | `/compact` or commit/extraction has not run, or server extraction failed | Run `/compact`; check OpenViking server logs. |
+| Recall misses shared documents | `resource` target is not enabled | Use `memory_recall` with `resourceTypes:["resource"]` or configure `recallTargetTypes: ["resource"]`. |
+| Summary lacks exact detail | Archive summary is too coarse | Use `ov_archive_search` with concrete keywords, then `ov_archive_expand`. |
+| Large tool output preview is insufficient | Tool result was externalized | Use `openviking_tool_result_search/read` with the ref. |
+| Need to explain recall behavior | Trace disabled or no trace for that turn | Enable `traceRecall`; optionally `traceRecallPersist`; query `ov_recall_trace`. |
+
+## Reference Docs in This Repo
+
+- `README.md` / `README_CN.md`: feature overview and quick start.
+- `INSTALL.md` / `INSTALL-ZH.md`: install, upgrade, uninstall, and JSON setup handling.
+- `INSTALL-AGENT.md`: agent-oriented installation workflow.
+- `docs/openviking-openclaw-plugin-guide.md`: comprehensive Chinese operator/developer guide.