[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M75DM6MZ7RKJJA9WHYY5Q87F":3,"skill-same:01M75DM6MZ7RKJJA9WHYY5Q87F":62},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":41,"commitSha":42,"skillDirectory":43,"forksCount":44,"repositoryHtmlUrl":45,"repositoryHomepageUrl":6,"ownerHtmlUrl":46,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":47,"install":48,"resources":61},"01M75DM6MZ7RKJJA9WHYY5Q87F","install-openviking-memory",null,"Install and configure the OpenViking long-term memory plugin for OpenClaw via natural conversation. Once installed, the plugin automatically captures important facts from chats and recalls relevant context before each reply (auto-capture + auto-recall, cross-session). Covers prerequisites check, plugin install through OpenClaw's plugin manager first, with ov-install only as a backup path, wizard-based configuration, slot activation, gateway restart, verification, plus multi-tenant root-key support, multi-instance, and uninstall. Trigger when the user says any of: \"install OpenViking\", \"set up memory\", \"configure memory plugin\", \"add long-term memory\", \"connect to OpenViking server\", \"RAG\", \"semantic memory\", \"帮我装 OpenViking\", \"配置记忆插件\", \"安装记忆功能\", \"接入 OpenViking\", \"我有一台 OpenViking 服务器\". 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.","zhangmask\u002FC_AnimeCompanion","zhangmask","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F142085030?v=4","01M75DE4RMVR0PZNRT2CHBNB1K","Zeshan Zhang","01M75DE4SE8VQSYG2PMV66F3PE",2,"Apache-2.0","https:\u002F\u002Fgithub.com\u002Fzhangmask\u002FC_AnimeCompanion\u002Fblob\u002Fmain\u002Fothergithubdemo\u002FOpenViking-main\u002FOpenViking-main\u002Fexamples\u002Fopenclaw-plugin\u002Fskills\u002Finstall-openviking-memory\u002FSKILL.md",[],[],"2026-11-12 13:55:43",false,"---\nname: install-openviking-memory\ndescription: >\n  Install and configure the OpenViking long-term memory plugin for OpenClaw via natural conversation.\n  Once installed, the plugin automatically captures important facts from chats and recalls relevant\n  context before each reply (auto-capture + auto-recall, cross-session). Covers prerequisites check,\n  plugin install through OpenClaw's plugin manager first, with ov-install only as a backup path,\n  wizard-based configuration, slot activation,\n  gateway restart, verification, plus multi-tenant root-key support, multi-instance, and uninstall.\n  Trigger when the user says any of: \"install OpenViking\", \"set up memory\", \"configure memory plugin\",\n  \"add long-term memory\", \"connect to OpenViking server\", \"RAG\", \"semantic memory\",\n  \"帮我装 OpenViking\", \"配置记忆插件\", \"安装记忆功能\", \"接入 OpenViking\", \"我有一台 OpenViking 服务器\".\n  The user does NOT need to know any CLI commands — the agent runs everything and only asks for a few values.\n  This skill assumes the OpenViking server is already running. If the server is not ready, the skill\n  tells the user to contact their admin or set it up via the OpenViking docs — it does NOT install the server.\nversion: 2026.6.5\nmetadata:\n  openclaw:\n    requires:\n      bins:\n        - node\n        - openclaw\n  emoji: \"🦣\"\n  homepage: \"https:\u002F\u002Fgithub.com\u002Fvolcengine\u002FOpenViking\"\ntags:\n  - install\n  - setup\n  - memory\n  - openviking\n  - rag\n  - long-term-memory\n---\n\n# Install OpenViking Memory — Agent Installation & Reference Skill\n\nYou are about to help a user install and configure the OpenViking memory plugin for OpenClaw.\nThe user does NOT know how to use a terminal. You will collect a few values through natural conversation, then run **all** commands yourself using your shell tool.\n\n**Read this entire document before starting. Follow every step in order. Do NOT skip steps.**\n\nThis skill is split into two halves:\n\n- **Part 1 (STEP 0–10): Natural-language installation walkthrough.** Use this on first install or reconfigure.\n- **Part 2: Reference.** Tools, config schema, multi-tenant, multi-instance, daily ops, uninstall, error recovery. Read on demand.\n\n> **Server scope.** This skill **does not** install the OpenViking server itself. It assumes the server is already running locally on `127.0.0.1:1933` or on another machine. If the user has no server, see \"Server not ready\" handling in STEP 5.\n\n---\n\n# Part 1 — Natural-Language Installation Walkthrough\n\n## STEP 0: Detect Language\n\nIf the user's first message contains Chinese characters, respond in **Chinese** throughout.\nOtherwise respond in **English**.\nAll user-facing messages below have (CN)\u002F(EN) variants — use the matching one.\n\nDo NOT show this step to the user.\n\n---\n\n## STEP 1: Detect Operating System (silently)\n\nRun this command and remember the result. Do NOT show it to the user.\n\n```bash\nuname -s 2>\u002Fdev\u002Fnull || echo WINDOWS\n```\n\n- Output contains `Darwin` → `OS=mac`\n- Output contains `Linux` → `OS=linux`\n- Output is `WINDOWS` or the command fails → `OS=windows`\n\n---\n\n## STEP 2: Check Prerequisites (silently)\n\nRun silently:\n\n```bash\nnode -v\nopenclaw --version\n```\n\n**If `node` is missing:**\n\n> (CN) 你的系统没有安装 Node.js。OpenClaw 和 OpenViking 插件需要 Node.js >= 22。请先安装 Node.js，然后再回来找我。\n> (EN) Node.js is not installed. OpenClaw and the OpenViking plugin require Node.js >= 22. Please install Node.js first, then come back.\n\n**Stop. Do NOT continue.**\n\n**If `openclaw` is missing:**\n\n> (CN) 你的系统没有安装 OpenClaw。请先安装 OpenClaw（>= 2026.4.8），然后再回来找我。\n> (EN) OpenClaw is not installed. Please install OpenClaw (>= 2026.4.8) first, then come back.\n\n**Stop. Do NOT continue.**\n\nIf both exist, proceed to STEP 3 silently.\n\n---\n\n## STEP 3: Greet and Ask for 3 Values\n\nSend this message:\n\n> (CN) 好，我来帮你接入 OpenViking 长期记忆。装好之后，我会自动记住对话里的重要信息，下次聊也能回忆起来。\n>\n> 我需要 3 条信息，不知道的可以问你的管理员：\n> 1. **OpenViking 服务地址** —— 例如 `https:\u002F\u002Fov.example.com` 或 `http:\u002F\u002F192.168.1.100:1933`，本机服务可以直接说\"本机\"\n> 2. **API Key** —— 用来鉴权；服务没开认证可以说\"没有\"\n> 3. **Agent 标识前缀**（可选） —— 用于区分多个 agent 的记忆命名空间，留空就用默认\n>\n> 先告诉我服务地址吧？\n\n> (EN) I'll set up OpenViking long-term memory for you. Once configured, I'll automatically remember important info from our chats and recall it later.\n>\n> I need 3 things (ask your admin if unsure):\n> 1. **OpenViking server URL** — e.g. `https:\u002F\u002Fov.example.com` or `http:\u002F\u002F192.168.1.100:1933`. For a local server, just say \"local\".\n> 2. **API Key** — for auth. Say \"none\" if the server has no auth.\n> 3. **peer prefix** (optional) — used to namespace memories across agents. Leave blank for default.\n>\n> What's the server URL?\n\n---\n\n## STEP 4: Collect Values\n\nCollect 3 values through natural conversation. Be flexible: if the user gives several at once, parse them all. If they correct something, accept the new value.\n\n### 4a. `BASE_URL` (REQUIRED)\n\n- \"local\" \u002F \"本机\" \u002F \"localhost\" → use `http:\u002F\u002F127.0.0.1:1933`.\n- `ov.example.com` without protocol → prepend `https:\u002F\u002F`.\n- Strip trailing `\u002F`, `\u002Fhealth`, or `\u002Fapi`.\n- After normalization must start with `http:\u002F\u002F` or `https:\u002F\u002F`.\n- If the user says they don't know, ask them to check with the admin or look at how the server was started. **Do NOT make up a URL.**\n\n### 4b. `API_KEY` (OPTIONAL)\n\n> (CN) API Key 是什么？服务没开认证就直接说\"没有\"。\n> (EN) What's the API Key? Say \"none\" if the server has no auth.\n\n- \"no\" \u002F \"none\" \u002F \"没有\" \u002F \"空\" \u002F empty → `API_KEY=\"\"` (you will skip the flag later).\n- Otherwise store as-is.\n\n### 4c. `PEER_PREFIX` (OPTIONAL)\n\n> (CN) 想给这个 agent 一个记忆前缀吗？留空就用默认。只能用字母、数字、`_`、`-`。\n> (EN) Want to set an peer prefix? Leave blank for the default. Letters, digits, `_`, `-` only.\n\n- Empty \u002F \"default\" \u002F \"默认\" → leave unset (plugin defaults to `\"\"`).\n- Otherwise validate against `\u002F^[A-Za-z0-9_-]+$\u002F`. If invalid, ask again.\n\n### 4d. (Conditional) Multi-Tenant Root-Key Fields\n\nOnly ask for these if STEP 7 detects a root key (`Root API key detected. Missing: --account-id, --user-id`). Don't ask up front.\n\n- `ACCOUNT_ID`\n- `USER_ID`\n\nSee **Reference: Multi-Tenant** for what these mean.\n\n---\n\n## STEP 5: Pre-flight Connectivity Check (silently)\n\nTell the user briefly:\n\n> (CN) 我先测一下能不能连上服务……\n> (EN) Let me test the connection to your server...\n\nRun:\n\n**If OS=windows:**\n\n```powershell\ntry { (Invoke-WebRequest -Uri \"BASE_URL\u002Fhealth\" -TimeoutSec 10 -UseBasicParsing -ErrorAction Stop).StatusCode } catch { $_.Exception.Response.StatusCode.value__ }\n```\n\n**If OS=mac or OS=linux:**\n\n```bash\ncurl -sS -o \u002Fdev\u002Fnull -w \"%{http_code}\" --connect-timeout 10 \"BASE_URL\u002Fhealth\"\n```\n\nReplace `BASE_URL` with the actual value.\n\n| Status | Meaning | Action |\n|---|---|---|\n| `200` | Server reachable, no auth on `\u002Fhealth` | Proceed to STEP 6. |\n| `401` \u002F `403` | Server reachable but `\u002Fhealth` requires auth | Proceed to STEP 6 — the wizard's key probe will sort it out. |\n| `000` \u002F timeout \u002F connection refused | Server unreachable | **Server-not-ready handling** below. |\n| Anything else | Unexpected | Show status code to the user, go back to STEP 4a. |\n\n### Server-not-ready handling\n\nThis skill **does not install or operate the OpenViking server**. If the user's server is unreachable, present the situation honestly and offer two paths:\n\n> (CN) ❌ 我连不上 `BASE_URL`。可能是：\n> 1) 服务还没启动 —— 请联系你的 OpenViking 服务管理员把它起起来；如果是你自己负责，请参考 OpenViking 官方文档（`https:\u002F\u002Fgithub.com\u002Fvolcengine\u002FOpenViking`）的 server 启动指引。\n> 2) 地址不对 —— 你可以重新告诉我正确的地址。\n> 3) 网络不通（防火墙 \u002F VPN \u002F 内网）—— 你确认一下网络。\n>\n> 也可以选择\"先把配置写下来\"，等服务起来就自动生效，要这么办吗？\n\n> (EN) ❌ Cannot reach `BASE_URL`. Likely cause:\n> 1) **Server isn't running** — please ask your OpenViking admin to start it. If you own the server, follow the OpenViking official docs (`https:\u002F\u002Fgithub.com\u002Fvolcengine\u002FOpenViking`) to start it. **This skill does not install or run the server.**\n> 2) **Wrong URL** — give me the correct URL.\n> 3) **Network blocked** (firewall \u002F VPN \u002F private network) — please verify connectivity.\n>\n> Or I can save the config now (`--allow-offline`) so it will activate automatically once the server is up. Want me to do that?\n\nIf the user fixes the URL → back to STEP 4a.\nIf the user wants `--allow-offline` → remember `ALLOW_OFFLINE=true` and continue to STEP 6.\nIf the user gives up \u002F cannot fix → stop here. Do NOT continue with a broken state.\n\n---\n\n## STEP 6: Install the Plugin\n\nThe plugin can be installed two ways. **Always try Path A first.** Use Path B only as a backup when Path A fails because ClawHub is unavailable, rate-limited, or authentication blocks anonymous install. For version conflicts, dependency errors, or other non-registry failures, stop and show the user the error instead of switching paths silently.\n\n### Path A — Primary: `openclaw plugins install` (uses ClawHub)\n\nTell the user:\n\n> (CN) 现在开始装插件……\n> (EN) Installing the plugin now...\n\nRun:\n\n```bash\nopenclaw plugins install clawhub:@openviking\u002Fopenclaw-plugin\n```\n\nTrigger fallback to Path B only if the output contains any of these strings:\n\n- `429`\n- `rate limit` \u002F `rate-limited` \u002F `Too Many Requests`\n- `not logged in` \u002F `please log in` \u002F `please login` \u002F `unauthorized` \u002F `401` \u002F `403` together with `clawhub`\n- `ETIMEDOUT` \u002F `ECONNRESET` on a `clawhub`-related host\n- generic message indicating the registry refused an anonymous client\n\nBefore falling back, also try the explicit registry prefix once:\n\n```bash\nopenclaw plugins install clawhub:@openviking\u002Fopenclaw-plugin\n```\n\nIf the install **succeeds**, jump to STEP 7.\n\nIf both attempts fail with one of the fallback-eligible errors above, go to Path B. If the failure is a version conflict, missing dependency, package validation error, or another non-registry error, stop and show the last 30 lines to the user.\n\n### Path B — Backup: `ov-install` (bypasses ClawHub)\n\nTell the user:\n\n> (CN) ClawHub 现在好像被限流、不可用，或者当前账号不能安装。我改用备用路径，通过 npm 下载并部署插件包。\n> (EN) ClawHub looks rate-limited, unavailable, or blocked for this account. I'll use the backup path and install the plugin package from npm.\n\nRun the installer with `npx` (no global install needed):\n\n```bash\nnpx -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]\n```\n\nBuild the flag list according to what the user gave you:\n\n- Always pass `--base-url BASE_URL`.\n- Pass `--api-key API_KEY` only if `API_KEY` is non-empty.\n- Pass `--peer-prefix PEER_PREFIX` only if the user gave one.\n- `--account-id` \u002F `--user-id` only if the root-key path requires them.\n\n`ov-install` will, in one shot:\n1. Download the `@openviking\u002Fopenclaw-plugin` package from npm into a temporary staging dir.\n2. Copy the package into the OpenClaw `extensions\u002F` dir and install plugin dependencies.\n3. Register the plugin in `openclaw.json` (via `openclaw plugins enable` or direct write).\n4. Run `openclaw openviking setup --json --base-url … [--api-key …]` for the user.\n5. Return a non-zero exit if setup needs explicit `--allow-offline` or `--force-slot` consent.\n\nThis means **STEP 7 is effectively done by `ov-install`**. After `ov-install` exits 0, jump straight to **STEP 9** (gateway restart) and **STEP 10** (verify).\n\nIf `ov-install` exits non-zero, capture the last 30 lines of its output, show them to the user, and stop. Don't retry blindly.\n\n---\n\n## STEP 7: Configure (only on Path A — Path B did this for you)\n\nRun the setup wizard non-interactively. Build flags from collected values:\n\n```bash\nopenclaw 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]\n```\n\nRules:\n\n- `--base-url BASE_URL` is **required** under `--json`. Without it, the wizard prints `--json requires --base-url for non-interactive mode`.\n- `--api-key` only if `API_KEY` is non-empty.\n- `--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.\n- `--account-id` \u002F `--user-id` only after STEP 7 root-key detection (see below).\n- `--allow-offline` only if the user explicitly approved it in STEP 5.\n- `--force-slot` **never** in the first attempt. Add only after the user confirms (see slot_blocked handling below).\n\n### Parse the JSON output\n\nThe wizard prints a single JSON object:\n\n```json\n{\n  \"success\": true | false,\n  \"action\": \"configured\" | \"existing\" | \"error\" | \"slot_blocked\",\n  \"config\": { \"mode\": \"remote\", \"baseUrl\": \"...\", \"apiKey\": \"...\", \"peer_prefix\": \"...\", \"accountId\": \"...\", \"userId\": \"...\" },\n  \"health\": { \"ok\": true, \"version\": \"...\", \"compatibility\": \"compatible\" | \"server_too_old\" | \"server_too_new\" | \"unknown\" },\n  \"keyProbe\": { \"keyType\": \"user_key\" | \"root_key\" | \"no_key\" | \"unknown\", \"needsAccountId\": false, \"needsUserId\": false, \"detail\": \"...\" },\n  \"slot\": { \"activated\": true, \"replaced\": false, \"previousOwner\": \"openviking\" },\n  \"error\": \"...\"\n}\n```\n\n### Decision matrix\n\n| Condition | Action |\n|---|---|\n| `success: true` and `action: \"configured\"` or `\"existing\"` | Done. Proceed to STEP 9. |\n| `success: false` and `action: \"slot_blocked\"` | **Slot conflict — see below.** |\n| `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. |\n| `success: false` and `error` contains `\"Root API key detected\"` and `\"Missing: --account-id, --user-id\"` | **Root-key path — see below.** |\n| `success: false` and `error` contains `\"Invalid API key\"` \u002F `keyProbe.keyType: \"unknown\"` after auth failure detail | API key wrong. Back to STEP 4b. |\n| `success: false` and any other `action: \"error\"` | Show `error` to the user, stop. Do NOT pretend success. |\n\n### Slot conflict (`slot_blocked`)\n\nThe error text looks like:\n\n> `contextEngine slot is owned by \"\u003Cother-plugin>\". Config was saved but slot was NOT changed. Use --force-slot to replace.`\n\n**Do NOT silently use `--force-slot`.** Ask the user:\n\n> (CN) 你的 OpenClaw 当前 contextEngine 槽被 `\u003Cother-plugin>` 占着。如果用 OpenViking 替换它，`\u003Cother-plugin>` 就不再生效。要替换吗？\n> (EN) Your `contextEngine` slot is currently owned by `\u003Cother-plugin>`. Activating OpenViking will disable it. Replace?\n\nIf the user agrees, retry the same setup command with `--force-slot` appended. If they decline, tell them config has been saved but the slot is unchanged, and stop.\n\n### Root-key path\n\nThe error text looks like:\n\n> `Root API key detected. Missing: --account-id, --user-id. Provide both to enable multi-tenant scoping.`\n\nAsk the user:\n\n> (CN) 你给的是 root 级 API Key，需要再补两个值才能用：账户 ID（accountId）和用户 ID（userId）。这两个一般是 OpenViking 服务管理员配的，不知道就问他们。\n> (EN) Your API key is a root key, which needs two more values: `accountId` and `userId`. Both come from your OpenViking server admin — ask them if unsure.\n\nAfter collecting, retry the setup command with `--account-id` and `--user-id` appended.\n\n---\n\n## STEP 8: (Reserved — done inside STEP 7 or by `ov-install`)\n\nThe setup wizard already wrote `plugins.entries.openviking.config.*` and (if successful) set `plugins.slots.contextEngine = \"openviking\"`. There is no separate STEP 8 — go to STEP 9.\n\n---\n\n## STEP 9: Restart the Gateway\n\n```bash\nopenclaw gateway restart\n```\n\nIf it fails, try once more with:\n\n```bash\nopenclaw gateway --force\n```\n\nIf both fail:\n\n> (CN) Gateway 没能自动重启。请你手动跑一下 `openclaw gateway restart`。重启完告诉我，我来验证。\n> (EN) Gateway didn't restart cleanly. Please run `openclaw gateway restart` manually, then tell me when it's done so I can verify.\n\nWait ~3 seconds before STEP 10.\n\n---\n\n## STEP 10: Verify\n\n```bash\nopenclaw openviking status --json\n```\n\nExpected output:\n\n```json\n{\n  \"configured\": true,\n  \"slotActive\": true,\n  \"health\": { \"ok\": true },\n  \"config\": { \"baseUrl\": \"...\", \"peer_prefix\": \"...\" }\n}\n```\n\n### Decision\n\n- `configured: true` **and** `slotActive: true` **and** `health.ok: true` → **success.** Send the success message below.\n- `configured: true` but `slotActive: false` → if you previously skipped `--force-slot`, ask the user about replacing now and retry STEP 7 with `--force-slot`. Otherwise it's a gateway restart issue — back to STEP 9.\n- `configured: true` but `health.ok: false` → server became unreachable. Tell the user; the config will start working as soon as the server is back.\n- `configured: false` → setup didn't actually persist. Show full status JSON to the user and stop.\n\n### Success message\n\n> (CN) 🎉 全部搞定！OpenViking 长期记忆已经接好了。\n>\n> 工作方式：\n> - **每一轮**：你的对话会被自动追加到 OpenViking session 里；自动抽取依赖阈值 commit 或 `\u002Fcompact`\n> - **明确要记住时**：如果你说“记住\u002F保存\u002F存一下”某个长期事实，我会用 `memory_store` 立即提交到记忆管线\n> - **`\u002Fcompact` 时**：待提交的 session 消息会在 OpenViking 服务端被抽取成长期记忆\n> - **后续会话**：每次回复前我都会自动搜一下相关记忆并带进上下文\n>\n> 想验证一下吗？可以直接说“记住我的邮箱是 test@example.com”，让我通过 `memory_store` 立即提交；或者先聊几句包含可记忆事实的话，再调一下 `\u002Fcompact`。之后开新对话问“我的邮箱是？”，应该就能召回了。\n\n> (EN) 🎉 All set! OpenViking long-term memory is connected.\n>\n> How it works:\n> - **Every turn**: our messages are appended to an OpenViking session; automatic extraction depends on a threshold commit or `\u002Fcompact`\n> - **Explicit remember requests**: if you ask me to remember\u002Fsave\u002Fstore a long-term fact, I can use `memory_store` to commit it immediately\n> - **On `\u002Fcompact`**: pending session messages are extracted into long-term memories on the OpenViking server\n> - **Future sessions**: relevant memories are auto-retrieved and injected before my replies\n>\n> 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 `\u002Fcompact`. Then start a new chat and ask \"what's my email?\" — it should recall.\n\n---\n\n# Part 2 — Reference\n\n## How It Works\n\nThe context-engine pipeline has three distinct stages plus one explicit write path — keep them apart, especially when telling users when memories become searchable long-term memory on the OpenViking server:\n\n- **Archive \u002F capture (context-engine `afterTurn`)**: at the end of a user turn, the plugin appends user\u002Fassistant messages to the OpenViking session via `POST \u002Fapi\u002Fv1\u002Fsessions\u002F...\u002Fmessages`. 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:\u002F\u002Fuser\u002F...\u002Fmemories\u002F`.\n- **Memory extraction (threshold commit or `\u002Fcompact`)**: memory extraction runs after a session commit. The commit can be triggered asynchronously when `afterTurn` crosses `commitTokenThreshold`, synchronously when the user invokes OpenClaw's `\u002Fcompact` command, or explicitly by `memory_store`. The server-side extraction pipeline reads the archived session and writes new memories.\n  - `captureMode: \"semantic\"` (default): server extraction pipeline filters all qualifying text.\n  - `captureMode: \"keyword\"`: only text matching trigger words (e.g. \"remember\", \"preference\") is considered.\n- **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.\n\n**Practical implication for testing**: if you write down a short fact and immediately try to recall it without a threshold commit, `\u002Fcompact`, 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 `\u002Fcompact` or use `memory_store` for the fact being tested.\n\n### Explicit long-term memory writes\n\nAuto-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.\n\nUse `memory_store` as the integration-side reliable path for durable-memory intent:\n\n- It writes the supplied text into an OpenViking session and calls `commit(wait=true)`.\n- It complements auto-capture; it does not replace normal session capture.\n- If it commits but extracts 0 memories, the explicit path has done its job. Treat that as a server-side extraction\u002Fmodel\u002Fconfiguration issue and check OpenViking logs.\n\n## Available Tools\n\nThese are the plugin tools the agent can call once installed.\n\n### `memory_recall` — Search Memories\n\n| Parameter | Required | Description |\n|---|---|---|\n| `query` | Yes | Search query text |\n| `limit` | No | Maximum number of results (defaults to plugin config) |\n| `scoreThreshold` | No | Minimum relevance score 0–1 (defaults to plugin config) |\n| `targetUri` | No | Exact search scope URI. If provided, only that URI is searched. |\n| `resourceTypes` | No | Array of target types used when `targetUri` is omitted: `resource`, `user`, `agent`. Defaults to plugin `recallTargetTypes`. |\n\nExample: user asks \"What programming language did I say I like?\"\n\n### `memory_store` — Manual Store\n\n| Parameter | Required | Description |\n|---|---|---|\n| `text` | Yes | Information text to store |\n| `role` | No | Session role (default `user`) |\n| `sessionId` | No | Existing OpenViking session ID |\n\nUse this when the user explicitly asks to remember\u002Fsave\u002Fstore a long-term fact, preference, project, or decision.\n\nExample: user says \"Remember my email is xxx@example.com\".\n\n### `memory_forget` — Delete Memories\n\n| Parameter | Required | Description |\n|---|---|---|\n| `uri` | No | Exact memory URI (direct delete) |\n| `query` | No | Search query (find then delete) |\n| `targetUri` | No | Search scope URI |\n| `limit` | No | Search limit (default 5) |\n| `scoreThreshold` | No | Minimum relevance score |\n\nExample: user says \"Forget my phone number\".\n\n### `ov_archive_search` — Search Archived Original Messages\n\n| Parameter | Required | Description |\n|---|---|---|\n| `query` | Yes | A single keyword or short phrase. Prefer concrete names, dates, commands, paths, or distinctive nouns. |\n| `archiveId` | No | Optional archive ID such as `archive_002`. |\n\nUse when `[Session History Summary]` is too coarse. Try at least two keyword variants before concluding the detail is unavailable.\n\n### `ov_archive_expand` — Expand An Archive\n\n| Parameter | Required | Description |\n|---|---|---|\n| `archiveId` | Yes | Archive ID from `[Archive Index]`, e.g. `archive_002`. |\n\n### `add_resource` — Import Resource\n\nThe agent-visible `add_resource` tool is disabled by default (`enableAddResourceTool=false`). Use manual `\u002Fadd-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.\n\n| Parameter | Required | Description |\n|---|---|---|\n| `source` | Yes | Local path, OpenClaw media attachment path, directory path, public URL, or Git URL. |\n| `to` | No | Exact target URI under `viking:\u002F\u002Fresources`; mutually exclusive with `parent`. |\n| `parent` | No | Parent URI under `viking:\u002F\u002Fresources`; mutually exclusive with `to`. |\n| `reason` | No | Reason or note for import. |\n| `instruction` | No | Processing instruction for semantic extraction. |\n| `wait` | No | Wait for processing completion. |\n| `timeout` | No | Timeout in seconds when `wait=true`. |\n\n### `add_skill` — Import Agent Skill\n\n| Parameter | Required | Description |\n|---|---|---|\n| `source` | No | Local `SKILL.md` path or skill directory. Exactly one of `source` or `data` is required. |\n| `data` | No | Raw `SKILL.md` content or MCP tool dict. Exactly one of `source` or `data` is required. |\n| `wait` | No | Wait for processing completion. |\n| `timeout` | No | Timeout in seconds when `wait=true`. |\n\nAgent 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.\n\n### `ov_search` — Search Resources and Skills\n\n| Parameter | Required | Description |\n|---|---|---|\n| `query` | Yes | Search query. |\n| `uri` | No | Optional search URI. Defaults to resources plus agent skills. |\n| `limit` | No | Max results per search scope. Default: 10. |\n\nImportant: `ov_search` result URIs are OpenViking virtual URIs, not local file paths. If full content is needed, call `ov_read` with the exact `viking:\u002F\u002F...` URI returned by search or trace results; do not use filesystem read tools.\n\n### `ov_read` — Read OpenViking Content\n\n| Parameter | Required | Description |\n|---|---|---|\n| `uri` | Yes | Exact `viking:\u002F\u002F...` URI returned by `ov_search` or recall trace results. Local file paths and `openviking:\u002F\u002F...` display aliases are refused. |\n\n### `ov_recall_trace` — Query Recall Trace\n\n| Parameter | Required | Description |\n|---|---|---|\n| `turn` | No | `latest` or `all`; default `latest`. |\n| `traceId` | No | Exact trace ID. |\n| `sessionId` \u002F `sessionKey` \u002F `ovSessionId` | No | Session filters. |\n| `source` | No | `auto_recall`, `memory_recall`, `ov_search`, or `ov_archive_search`. |\n| `resourceTypes` | No | Target type filters: `resource`, `user`, `agent`. |\n| `since` \u002F `until` | No | Unix timestamp bounds in milliseconds. |\n| `includeContent` | No | Read selected\u002Fdisplayed URI content previews on demand. |\n| `limit` | No | Maximum traces to return. Default: 20. |\n\nRequires `traceRecall=true`; persisted lookup also requires `traceRecallPersist=true`.\n\n### Externalized Tool Result Tools\n\nUse these when a preview contains a `viking:\u002F\u002Fsession\u002F\u003Csession_id>\u002Ftool-results\u002F\u003Ctool_result_id>` ref.\n\n| Tool | Parameters |\n|---|---|\n| `openviking_tool_result_list` | `tool_name?`, `limit?` (default 50) |\n| `openviking_tool_result_search` | `tool_output_ref`, `query`, `limit?` (default 20), `context_chars?` (default 300) |\n| `openviking_tool_result_read` | `tool_output_ref`, `offset?` (default 0), `limit?` (default 20000) |\n\n## Configuration Schema\n\nThese are the keys under `plugins.entries.openviking.config` in `openclaw.json`. The setup wizard \u002F `ov-install` sets the first few; the rest are tunables.\n\n| Field | Default | Description |\n|---|---|---|\n| `mode` | `\"remote\"` (forced by plugin) | Always remote in this skill. Don't set manually. |\n| `baseUrl` | `http:\u002F\u002F127.0.0.1:1933` | OpenViking server URL. |\n| `apiKey` | — | API key. Optional if server has no auth. |\n| `peer_role` | `assistant` | Peer identity mode: `none`, `assistant`, or `person`. Session messages use body `peer_id`; data-plane recall\u002Fsearch uses `X-OpenViking-Actor-Peer`. |\n| `peer_prefix` | `\"\"` | Optional prefix for assistant `peer_id` \u002F actor peer values when `peer_role=assistant`. Letters \u002F digits \u002F `_` \u002F `-`. |\n| `accountId` | — | Required when `apiKey` is a root key. |\n| `userId` | — | Required when `apiKey` is a root key. |\n| `targetUri` | `viking:\u002F\u002Fuser\u002Fmemories` | Default search scope URI. |\n| `timeoutMs` | (plugin default) | HTTP timeout for OpenViking calls. |\n| `autoCapture` | `true` | Auto-append turn messages to the OpenViking session at `afterTurn`; extraction runs only after a threshold commit, `\u002Fcompact`, or explicit `memory_store`. |\n| `captureMode` | `\"semantic\"` | Filter mode used by the server-side extraction pipeline: `semantic` or `keyword`. |\n| `captureMaxLength` | `24000` | Max text length per archived turn. |\n| `autoRecall` | `true` | Auto-recall and inject memories before reply. |\n| `recallTargetTypes` | `user,agent` | Default target types when `targetUri` is omitted. Allowed: `resource`, `user`, `agent`. |\n| `recallResources` | `false` | Compatibility shortcut that appends `resource` to default recall targets when `recallTargetTypes` is unset. |\n| `recallLimit` | `6` | Max memories injected per recall. |\n| `recallScoreThreshold` | `0.15` | Min relevance score to inject. |\n| `recallMaxInjectedChars` | `4000` | Hard cap on injected character count. Complete memories that do not fit are skipped, not truncated. |\n| `recallPreferAbstract` | (plugin default) | Prefer abstract memories over raw. |\n| `recallTokenBudget` | deprecated | Compatibility alias for `recallMaxInjectedChars`. |\n| `commitTokenThresholdRatio` | `0.5` | Async-commit threshold as a fraction (0-1) of the model context window (e.g. 0.5 = 50%); `0` commits every turn. |\n| `commitKeepRecentCount` | `10` | Recent messages kept live after afterTurn commit. Compact always uses `0`. |\n| `bypassSessionPatterns` | — | Glob patterns for sessions skipped by capture. |\n| `ingestReplyAssist` | (plugin default) | Reply-assist ingestion toggle. |\n| `emitStandardDiagnostics` | `false` | Emit structured `openviking: diag {...}` lines. |\n| `logFindRequests` | `false` | Log routing for find\u002Fsession writes. Also enabled by `OPENVIKING_LOG_ROUTING=1` or `OPENVIKING_DEBUG=1`. |\n| `traceRecall` | `false` | Record recall traces in memory. |\n| `traceRecallPersist` | `false` | Persist recall traces to JSONL files. |\n| `traceRecallDir` | `~\u002F.openclaw\u002Fopenviking\u002Frecall-traces` | Recall trace directory. |\n\nTo change a value:\n\n```bash\nopenclaw config set plugins.entries.openviking.config.\u003Cfield> \u003Cvalue>\nopenclaw gateway restart\n```\n\n## Multi-Tenant (Root API Keys)\n\nSome OpenViking deployments use a single **root** API key shared across tenants. In that case the plugin needs both `accountId` and `userId` so it can scope memories correctly. The setup wizard detects this automatically and returns:\n\n```\nRoot API key detected. Missing: --account-id, --user-id\n```\n\nWhen you see this:\n\n1. Ask the user for both values (they come from the OpenViking admin).\n2. Retry STEP 7 with both flags:\n\n```bash\nopenclaw openviking setup --base-url BASE_URL --api-key API_KEY --account-id ACCOUNT_ID --user-id USER_ID --json\n```\n\nA **user key** (issued per tenant) does not need these flags.\n\n## Multi-Instance (`--workdir` \u002F `OPENCLAW_STATE_DIR`)\n\nIf the user runs multiple OpenClaw instances (e.g. testing several agents in parallel), each has its own state dir.\n\nTo target a non-default instance:\n\n```bash\nnpx -y openclaw-openviking-setup-helper@latest --workdir ~\u002F.openclaw-second --base-url ... --api-key ...\n```\n\n`ov-install` writes a helper env file when the state dir is non-default:\n\n- Unix: `~\u002F.openclaw\u002Fopenviking.env` containing `export OPENCLAW_STATE_DIR='...'`\n- Windows: `~\u002F.openclaw\u002Fopenviking.env.bat` and `.ps1` setting the same variable\n\nSource it before running `openclaw` commands so they hit the correct state:\n\n**Unix:**\n```bash\nsource ~\u002F.openclaw\u002Fopenviking.env\nopenclaw status\n```\n\n**Windows (PowerShell):**\n```powershell\n. \"$HOME\u002F.openclaw\u002Fopenviking.env.ps1\"\nopenclaw status\n```\n\nOr pass `--workdir` directly to each `openclaw` invocation (note: not all `openclaw` subcommands honor `--workdir` consistently — when in doubt, prefer the env var).\n\n## Daily Operations\n\n```bash\n# Start or restart OpenClaw gateway after config changes\nopenclaw gateway restart\n\n# Check overall status\nopenclaw status\nopenclaw openviking status --json\n\n# Read current OpenViking slot\nopenclaw config get plugins.slots.contextEngine\n\n# Disable OpenViking memory (keep config, deactivate slot)\nopenclaw config set plugins.slots.contextEngine legacy\nopenclaw gateway restart\n\n# Re-enable\nopenclaw config set plugins.slots.contextEngine openviking\nopenclaw gateway restart\n```\n\n## Uninstall\n\n### Preferred: via OpenClaw plugin manager\n\n```bash\nopenclaw plugins uninstall openviking\nopenclaw config set plugins.slots.contextEngine legacy\nopenclaw gateway restart\n```\n\n### If installed through backup `ov-install`\n\n```bash\nnpx -y openclaw-openviking-setup-helper@latest --uninstall\n```\n\nThis will:\n\n1. Stop the OpenClaw gateway.\n2. Back up `openclaw.json`.\n3. Remove all OpenViking plugin config from `openclaw.json` (`plugins.entries.openviking`, `plugins.allow`, `plugins.installs.openviking`, `plugins.slots.contextEngine`).\n4. Move the plugin directory to `disabled-extensions\u002F` as backup.\n5. Remove the helper env files (`openviking.env`, `.bat`, `.ps1`).\n\nAdd `--base-url dummy` for fully non-interactive mode (skips the confirmation prompt).\n\n### Manual\n\n```bash\nopenclaw gateway stop\nopenclaw config set plugins.slots.contextEngine legacy\n# Then edit ~\u002F.openclaw\u002Fopenclaw.json and remove openviking from\n#   plugins.entries\n#   plugins.allow\n#   plugins.installs\nopenclaw gateway restart\n```\n\n## Error Recovery Reference\n\nMatch against actual stderr \u002F JSON `error` strings.\n\n| Symptom (exact string) | Likely cause | Fix |\n|---|---|---|\n| `command not found: openclaw` | OpenClaw not installed | Stop. Ask user to install OpenClaw >= 2026.4.8. |\n| `command not found: node` \u002F `'node' is not recognized` | Node missing | Stop. Ask user to install Node.js >= 22. |\n| `429` \u002F `rate limit` \u002F `Too Many Requests` from `plugins install` | ClawHub throttle | Switch to backup Path B (`ov-install`). |\n| `not logged in` \u002F `please log in` from `plugins install` | Anonymous user hit limit | Switch to backup Path B (`ov-install`). |\n| `ECONNREFUSED` \u002F `connection refused` on `BASE_URL\u002Fhealth` | Server not running | Server-not-ready handling in STEP 5. |\n| `ETIMEDOUT` on `BASE_URL\u002Fhealth` | Network blocked | Ask about firewall \u002F VPN \u002F proxy. |\n| `--json requires --base-url for non-interactive mode` | Built command wrong | Add `--base-url BASE_URL` and retry. |\n| `Server unreachable: …. Use --allow-offline to save config anyway.` | Setup couldn't reach server | Offer `--allow-offline`. |\n| `contextEngine slot is owned by \"\u003Cx>\". … Use --force-slot to replace.` | Slot conflict | Ask user, then retry with `--force-slot`. |\n| `Root API key detected. Missing: --account-id, --user-id` | Multi-tenant key | Collect both, retry with `--account-id` `--user-id`. |\n| `openviking: config parse failed` (in gateway log) | Bad value in `openclaw.json` | Show user; check `peer_prefix` charset, URL format. |\n| `extracted 0 memories` after a turn | Server VLM\u002Fembedding misconfigured | **Out of scope.** Tell user this is a server-side issue — ask their OpenViking admin to check VLM \u002F embedding config. |\n| `401` \u002F `403` on plugin requests, but `\u002Fhealth` works | Server requires auth on API endpoints | Re-run STEP 7 with the correct `--api-key`. |\n| 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\u002Frate-limit related. |\n\n## Important Rules\n\n1. **Never ask the user to run commands.** You run everything via your shell tool.\n2. **Never skip STEP 5 (connectivity check).** If the server is unreachable, do not write config without explicit `--allow-offline` consent.\n3. **Never silently use `--force-slot`.** Slot replacement disables another plugin — always confirm with the user first.\n4. **Never invent values.** If the user can't provide a required value, stop and tell them what to ask their admin.\n5. **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.\n6. **Use `--peer-prefix` for assistant peer prefixes.** The old ID-style setup flag is no longer supported by the schema.\n7. **For Windows, use PowerShell equivalents.** Don't rely on `nohup`, `&`, `mkdir -p`, `source`, etc.\n8. **Switch to Path B (ov-install) only for ClawHub\u002Frate-limit\u002Fregistry availability failures.** Don't use it to hide version conflicts or package validation errors.\n9. **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.\n10. **Be brief and friendly in user-visible text.** Save technical detail for when something actually fails.\n11. **Do NOT use `clawhub install openviking`.** That installs a different thing (an AgentSkill, not the plugin).\n","# Install OpenViking Memory — Agent Installation & Reference Skill\n\nYou are about to help a user install and configure the OpenViking memory plugin for OpenClaw.\nThe user does NOT know how to use a terminal. You will collect a few values through natural conversation, then run **all** commands yourself using your shell tool.\n\n**Read this entire document before starting. Follow every step in order. Do NOT skip steps.**\n\nThis skill is split into two halves:\n\n- **Part 1 (STEP 0–10): Natural-language installation walkthrough.** Use this on first install or reconfigure.\n- **Part 2: Reference.** Tools, config schema, multi-tenant, multi-instance, daily ops, uninstall, error recovery. Read on demand.\n\n> **Server scope.** This skill **does not** install the OpenViking server itself. It assumes the server is already running locally on `127.0.0.1:1933` or on another machine. If the user has no server, see \"Server not ready\" handling in STEP 5.\n\n---\n\n# Part 1 — Natural-Language Installation Walkthrough\n\n## STEP 0: Detect Language\n\nIf the user's first message contains Chinese characters, respond in **Chinese** throughout.\nOtherwise respond in **English**.\nAll user-facing messages below have (CN)\u002F(EN) variants — use the matching one.\n\nDo NOT show this step to the user.\n\n---\n\n## STEP 1: Detect Operating System (silently)\n\nRun this command and remember the result. Do NOT show it to the user.\n\n```bash\nuname -s 2>\u002Fdev\u002Fnull || echo WINDOWS\n```\n\n- Output contains `Darwin` → `OS=mac`\n- Output contains `Linux` → `OS=linux`\n- Output is `WINDOWS` or the command fails → `OS=windows`\n\n---\n\n## STEP 2: Check Prerequisites (silently)\n\nRun silently:\n\n```bash\nnode -v\nopenclaw --version\n```\n\n**If `node` is missing:**\n\n> (CN) 你的系统没有安装 Node.js。OpenClaw 和 OpenViking 插件需要 Node.js >= 22。请先安装 Node.js，然后再回来找我。\n> (EN) Node.js is not installed. OpenClaw and the OpenViking plugin require Node.js >= 22. Please install Node.js first, then come back.\n\n**Stop. Do NOT continue.**\n\n**If `openclaw` is missing:**\n\n> (CN) 你的系统没有安装 OpenClaw。请先安装 OpenClaw（>= 2026.4.8），然后再回来找我。\n> (EN) OpenClaw is not installed. Please install OpenClaw (>= 2026.4.8) first, then come back.\n\n**Stop. Do NOT continue.**\n\nIf both exist, proceed to STEP 3 silently.\n\n---\n\n## STEP 3: Greet and Ask for 3 Values\n\nSend this message:\n\n> (CN) 好，我来帮你接入 OpenViking 长期记忆。装好之后，我会自动记住对话里的重要信息，下次聊也能回忆起来。\n>\n> 我需要 3 条信息，不知道的可以问你的管理员：\n> 1. **OpenViking 服务地址** —— 例如 `https:\u002F\u002Fov.example.com` 或 `http:\u002F\u002F192.168.1.100:1933`，本机服务可以直接说\"本机\"\n> 2. **API Key** —— 用来鉴权；服务没开认证可以说\"没有\"\n> 3. **Agent 标识前缀**（可选） —— 用于区分多个 agent 的记忆命名空间，留空就用默认\n>\n> 先告诉我服务地址吧？\n\n> (EN) I'll set up OpenViking long-term memory for you. Once configured, I'll automatically remember important info from our chats and recall it later.\n>\n> I need 3 things (ask your admin if unsure):\n> 1. **OpenViking server URL** — e.g. `https:\u002F\u002Fov.example.com` or `http:\u002F\u002F192.168.1.100:1933`. For a local server, just say \"local\".\n> 2. **API Key** — for auth. Say \"none\" if the server has no auth.\n> 3. **peer prefix** (optional) — used to namespace memories across agents. Leave blank for default.\n>\n> What's the server URL?\n\n---\n\n## STEP 4: Collect Values\n\nCollect 3 values through natural conversation. Be flexible: if the user gives several at once, parse them all. If they correct something, accept the new value.\n\n### 4a. `BASE_URL` (REQUIRED)\n\n- \"local\" \u002F \"本机\" \u002F \"localhost\" → use `http:\u002F\u002F127.0.0.1:1933`.\n- `ov.example.com` without protocol → prepend `https:\u002F\u002F`.\n- Strip trailing `\u002F`, `\u002Fhealth`, or `\u002Fapi`.\n- After normalization must start with `http:\u002F\u002F` or `https:\u002F\u002F`.\n- If the user says they don't know, ask them to check with the admin or look at how the server was started. **Do NOT make up a URL.**\n\n### 4b. `API_KEY` (OPTIONAL)\n\n> (CN) API Key 是什么？服务没开认证就直接说\"没有\"。\n> (EN) What's the API Key? Say \"none\" if the server has no auth.\n\n- \"no\" \u002F \"none\" \u002F \"没有\" \u002F \"空\" \u002F empty → `API_KEY=\"\"` (you will skip the flag later).\n- Otherwise store as-is.\n\n### 4c. `PEER_PREFIX` (OPTIONAL)\n\n> (CN) 想给这个 agent 一个记忆前缀吗？留空就用默认。只能用字母、数字、`_`、`-`。\n> (EN) Want to set an peer prefix? Leave blank for the default. Letters, digits, `_`, `-` only.\n\n- Empty \u002F \"default\" \u002F \"默认\" → leave unset (plugin defaults to `\"\"`).\n- Otherwise validate against `\u002F^[A-Za-z0-9_-]+$\u002F`. If invalid, ask again.\n\n### 4d. (Conditional) Multi-Tenant Root-Key Fields\n\nOnly ask for these if STEP 7 detects a root key (`Root API key detected. Missing: --account-id, --user-id`). Don't ask up front.\n\n- `ACCOUNT_ID`\n- `USER_ID`\n\nSee **Reference: Multi-Tenant** for what these mean.\n\n---\n\n## STEP 5: Pre-flight Connectivity Check (silently)\n\nTell the user briefly:\n\n> (CN) 我先测一下能不能连上服务……\n> (EN) Let me test the connection to your server...\n\nRun:\n\n**If OS=windows:**\n\n```powershell\ntry { (Invoke-WebRequest -Uri \"BASE_URL\u002Fhealth\" -TimeoutSec 10 -UseBasicParsing -ErrorAction Stop).StatusCode } catch { $_.Exception.Response.StatusCode.value__ }\n```\n\n**If OS=mac or OS=linux:**\n\n```bash\ncurl -sS -o \u002Fdev\u002Fnull -w \"%{http_code}\" --connect-timeout 10 \"BASE_URL\u002Fhealth\"\n```\n\nReplace `BASE_URL` with the actual value.\n\n| Status | Meaning | Action |\n|---|---|---|\n| `200` | Server reachable, no auth on `\u002Fhealth` | Proceed to STEP 6. |\n| `401` \u002F `403` | Server reachable but `\u002Fhealth` requires auth | Proceed to STEP 6 — the wizard's key probe will sort it out. |\n| `000` \u002F timeout \u002F connection refused | Server unreachable | **Server-not-ready handling** below. |\n| Anything else | Unexpected | Show status code to the user, go back to STEP 4a. |\n\n### Server-not-ready handling\n\nThis skill **does not install or operate the OpenViking server**. If the user's server is unreachable, present the situation honestly and offer two paths:\n\n> (CN) ❌ 我连不上 `BASE_URL`。可能是：\n> 1) 服务还没启动 —— 请联系你的 OpenViking 服务管理员把它起起来；如果是你自己负责，请参考 OpenViking 官方文档（`https:\u002F\u002Fgithub.com\u002Fvolcengine\u002FOpenViking`）的 server 启动指引。\n> 2) 地址不对 —— 你可以重新告诉我正确的地址。\n> 3) 网络不通（防火墙 \u002F VPN \u002F 内网）—— 你确认一下网络。\n>\n> 也可以选择\"先把配置写下来\"，等服务起来就自动生效，要这么办吗？\n\n> (EN) ❌ Cannot reach `BASE_URL`. Likely cause:\n> 1) **Server isn't running** — please ask your OpenViking admin to start it. If you own the server, follow the OpenViking official docs (`https:\u002F\u002Fgithub.com\u002Fvolcengine\u002FOpenViking`) to start it. **This skill does not install or run the server.**\n> 2) **Wrong URL** — give me the correct URL.\n> 3) **Network blocked** (firewall \u002F VPN \u002F private network) — please verify connectivity.\n>\n> Or I can save the config now (`--allow-offline`) so it will activate automatically once the server is up. Want me to do that?\n\nIf the user fixes the URL → back to STEP 4a.\nIf the user wants `--allow-offline` → remember `ALLOW_OFFLINE=true` and continue to STEP 6.\nIf the user gives up \u002F cannot fix → stop here. Do NOT continue with a broken state.\n\n---\n\n## STEP 6: Install the Plugin\n\nThe plugin can be installed two ways. **Always try Path A first.** Use Path B only as a backup when Path A fails because ClawHub is unavailable, rate-limited, or authentication blocks anonymous install. For version conflicts, dependency errors, or other non-registry failures, stop and show the user the error instead of switching paths silently.\n\n### Path A — Primary: `openclaw plugins install` (uses ClawHub)\n\nTell the user:\n\n> (CN) 现在开始装插件……\n> (EN) Installing the plugin now...\n\nRun:\n\n```bash\nopenclaw plugins install clawhub:@openviking\u002Fopenclaw-plugin\n```\n\nTrigger fallback to Path B only if the output contains any of these strings:\n\n- `429`\n- `rate limit` \u002F `rate-limited` \u002F `Too Many Requests`\n- `not logged in` \u002F `please log in` \u002F `please login` \u002F `unauthorized` \u002F `401` \u002F `403` together with `clawhub`\n- `ETIMEDOUT` \u002F `ECONNRESET` on a `clawhub`-related host\n- generic message indicating the registry refused an anonymous client\n\nBefore falling back, also try the explicit registry prefix once:\n\n```bash\nopenclaw plugins install clawhub:@openviking\u002Fopenclaw-plugin\n```\n\nIf the install **succeeds**, jump to STEP 7.\n\nIf both attempts fail with one of the fallback-eligible errors above, go to Path B. If the failure is a version conflict, missing dependency, package validation error, or another non-registry error, stop and show the last 30 lines to the user.\n\n### Path B — Backup: `ov-install` (bypasses ClawHub)\n\nTell the user:\n\n> (CN) ClawHub 现在好像被限流、不可用，或者当前账号不能安装。我改用备用路径，通过 npm 下载并部署插件包。\n> (EN) ClawHub looks rate-limited, unavailable, or blocked for this account. I'll use the backup path and install the plugin package from npm.\n\nRun the installer with `npx` (no global install needed):\n\n```bash\nnpx -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]\n```\n\nBuild the flag list according to what the user gave you:\n\n- Always pass `--base-url BASE_URL`.\n- Pass `--api-key API_KEY` only if `API_KEY` is non-empty.\n- Pass `--peer-prefix PEER_PREFIX` only if the user gave one.\n- `--account-id` \u002F `--user-id` only if the root-key path requires them.\n\n`ov-install` will, in one shot:\n1. Download the `@openviking\u002Fopenclaw-plugin` package from npm into a temporary staging dir.\n2. Copy the package into the OpenClaw `extensions\u002F` dir and install plugin dependencies.\n3. Register the plugin in `openclaw.json` (via `openclaw plugins enable` or direct write).\n4. Run `openclaw openviking setup --json --base-url … [--api-key …]` for the user.\n5. Return a non-zero exit if setup needs explicit `--allow-offline` or `--force-slot` consent.\n\nThis means **STEP 7 is effectively done by `ov-install`**. After `ov-install` exits 0, jump straight to **STEP 9** (gateway restart) and **STEP 10** (verify).\n\nIf `ov-install` exits non-zero, capture the last 30 lines of its output, show them to the user, and stop. Don't retry blindly.\n\n---\n\n## STEP 7: Configure (only on Path A — Path B did this for you)\n\nRun the setup wizard non-interactively. Build flags from collected values:\n\n```bash\nopenclaw 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]\n```\n\nRules:\n\n- `--base-url BASE_URL` is **required** under `--json`. Without it, the wizard prints `--json requires --base-url for non-interactive mode`.\n- `--api-key` only if `API_KEY` is non-empty.\n- `--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.\n- `--account-id` \u002F `--user-id` only after STEP 7 root-key detection (see below).\n- `--allow-offline` only if the user explicitly approved it in STEP 5.\n- `--force-slot` **never** in the first attempt. Add only after the user confirms (see slot_blocked handling below).\n\n### Parse the JSON output\n\nThe wizard prints a single JSON object:\n\n```json\n{\n  \"success\": true | false,\n  \"action\": \"configured\" | \"existing\" | \"error\" | \"slot_blocked\",\n  \"config\": { \"mode\": \"remote\", \"baseUrl\": \"...\", \"apiKey\": \"...\", \"peer_prefix\": \"...\", \"accountId\": \"...\", \"userId\": \"...\" },\n  \"health\": { \"ok\": true, \"version\": \"...\", \"compatibility\": \"compatible\" | \"server_too_old\" | \"server_too_new\" | \"unknown\" },\n  \"keyProbe\": { \"keyType\": \"user_key\" | \"root_key\" | \"no_key\" | \"unknown\", \"needsAccountId\": false, \"needsUserId\": false, \"detail\": \"...\" },\n  \"slot\": { \"activated\": true, \"replaced\": false, \"previousOwner\": \"openviking\" },\n  \"error\": \"...\"\n}\n```\n\n### Decision matrix\n\n| Condition | Action |\n|---|---|\n| `success: true` and `action: \"configured\"` or `\"existing\"` | Done. Proceed to STEP 9. |\n| `success: false` and `action: \"slot_blocked\"` | **Slot conflict — see below.** |\n| `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. |\n| `success: false` and `error` contains `\"Root API key detected\"` and `\"Missing: --account-id, --user-id\"` | **Root-key path — see below.** |\n| `success: false` and `error` contains `\"Invalid API key\"` \u002F `keyProbe.keyType: \"unknown\"` after auth failure detail | API key wrong. Back to STEP 4b. |\n| `success: false` and any other `action: \"error\"` | Show `error` to the user, stop. Do NOT pretend success. |\n\n### Slot conflict (`slot_blocked`)\n\nThe error text looks like:\n\n> `contextEngine slot is owned by \"\u003Cother-plugin>\". Config was saved but slot was NOT changed. Use --force-slot to replace.`\n\n**Do NOT silently use `--force-slot`.** Ask the user:\n\n> (CN) 你的 OpenClaw 当前 contextEngine 槽被 `\u003Cother-plugin>` 占着。如果用 OpenViking 替换它，`\u003Cother-plugin>` 就不再生效。要替换吗？\n> (EN) Your `contextEngine` slot is currently owned by `\u003Cother-plugin>`. Activating OpenViking will disable it. Replace?\n\nIf the user agrees, retry the same setup command with `--force-slot` appended. If they decline, tell them config has been saved but the slot is unchanged, and stop.\n\n### Root-key path\n\nThe error text looks like:\n\n> `Root API key detected. Missing: --account-id, --user-id. Provide both to enable multi-tenant scoping.`\n\nAsk the user:\n\n> (CN) 你给的是 root 级 API Key，需要再补两个值才能用：账户 ID（accountId）和用户 ID（userId）。这两个一般是 OpenViking 服务管理员配的，不知道就问他们。\n> (EN) Your API key is a root key, which needs two more values: `accountId` and `userId`. Both come from your OpenViking server admin — ask them if unsure.\n\nAfter collecting, retry the setup command with `--account-id` and `--user-id` appended.\n\n---\n\n## STEP 8: (Reserved — done inside STEP 7 or by `ov-install`)\n\nThe setup wizard already wrote `plugins.entries.openviking.config.*` and (if successful) set `plugins.slots.contextEngine = \"openviking\"`. There is no separate STEP 8 — go to STEP 9.\n\n---\n\n## STEP 9: Restart the Gateway\n\n```bash\nopenclaw gateway restart\n```\n\nIf it fails, try once more with:\n\n```bash\nopenclaw gateway --force\n```\n\nIf both fail:\n\n> (CN) Gateway 没能自动重启。请你手动跑一下 `openclaw gateway restart`。重启完告诉我，我来验证。\n> (EN) Gateway didn't restart cleanly. Please run `openclaw gateway restart` manually, then tell me when it's done so I can verify.\n\nWait ~3 seconds before STEP 10.\n\n---\n\n## STEP 10: Verify\n\n```bash\nopenclaw openviking status --json\n```\n\nExpected output:\n\n```json\n{\n  \"configured\": true,\n  \"slotActive\": true,\n  \"health\": { \"ok\": true },\n  \"config\": { \"baseUrl\": \"...\", \"peer_prefix\": \"...\" }\n}\n```\n\n### Decision\n\n- `configured: true` **and** `slotActive: true` **and** `health.ok: true` → **success.** Send the success message below.\n- `configured: true` but `slotActive: false` → if you previously skipped `--force-slot`, ask the user about replacing now and retry STEP 7 with `--force-slot`. Otherwise it's a gateway restart issue — back to STEP 9.\n- `configured: true` but `health.ok: false` → server became unreachable. Tell the user; the config will start working as soon as the server is back.\n- `configured: false` → setup didn't actually persist. Show full status JSON to the user and stop.\n\n### Success message\n\n> (CN) 🎉 全部搞定！OpenViking 长期记忆已经接好了。\n>\n> 工作方式：\n> - **每一轮**：你的对话会被自动追加到 OpenViking session 里；自动抽取依赖阈值 commit 或 `\u002Fcompact`\n> - **明确要记住时**：如果你说“记住\u002F保存\u002F存一下”某个长期事实，我会用 `memory_store` 立即提交到记忆管线\n> - **`\u002Fcompact` 时**：待提交的 session 消息会在 OpenViking 服务端被抽取成长期记忆\n> - **后续会话**：每次回复前我都会自动搜一下相关记忆并带进上下文\n>\n> 想验证一下吗？可以直接说“记住我的邮箱是 test@example.com”，让我通过 `memory_store` 立即提交；或者先聊几句包含可记忆事实的话，再调一下 `\u002Fcompact`。之后开新对话问“我的邮箱是？”，应该就能召回了。\n\n> (EN) 🎉 All set! OpenViking long-term memory is connected.\n>\n> How it works:\n> - **Every turn**: our messages are appended to an OpenViking session; automatic extraction depends on a threshold commit or `\u002Fcompact`\n> - **Explicit remember requests**: if you ask me to remember\u002Fsave\u002Fstore a long-term fact, I can use `memory_store` to commit it immediately\n> - **On `\u002Fcompact`**: pending session messages are extracted into long-term memories on the OpenViking server\n> - **Future sessions**: relevant memories are auto-retrieved and injected before my replies\n>\n> 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 `\u002Fcompact`. Then start a new chat and ask \"what's my email?\" — it should recall.\n\n---\n\n# Part 2 — Reference\n\n## How It Works\n\nThe context-engine pipeline has three distinct stages plus one explicit write path — keep them apart, especially when telling users when memories become searchable long-term memory on the OpenViking server:\n\n- **Archive \u002F capture (context-engine `afterTurn`)**: at the end of a user turn, the plugin appends user\u002Fassistant messages to the OpenViking session via `POST \u002Fapi\u002Fv1\u002Fsessions\u002F...\u002Fmessages`. 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:\u002F\u002Fuser\u002F...\u002Fmemories\u002F`.\n- **Memory extraction (threshold commit or `\u002Fcompact`)**: memory extraction runs after a session commit. The commit can be triggered asynchronously when `afterTurn` crosses `commitTokenThreshold`, synchronously when the user invokes OpenClaw's `\u002Fcompact` command, or explicitly by `memory_store`. The server-side extraction pipeline reads the archived session and writes new memories.\n  - `captureMode: \"semantic\"` (default): server extraction pipeline filters all qualifying text.\n  - `captureMode: \"keyword\"`: only text matching trigger words (e.g. \"remember\", \"preference\") is considered.\n- **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.\n\n**Practical implication for testing**: if you write down a short fact and immediately try to recall it without a threshold commit, `\u002Fcompact`, 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 `\u002Fcompact` or use `memory_store` for the fact being tested.\n\n### Explicit long-term memory writes\n\nAuto-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.\n\nUse `memory_store` as the integration-side reliable path for durable-memory intent:\n\n- It writes the supplied text into an OpenViking session and calls `commit(wait=true)`.\n- It complements auto-capture; it does not replace normal session capture.\n- If it commits but extracts 0 memories, the explicit path has done its job. Treat that as a server-side extraction\u002Fmodel\u002Fconfiguration issue and check OpenViking logs.\n\n## Available Tools\n\nThese are the plugin tools the agent can call once installed.\n\n### `memory_recall` — Search Memories\n\n| Parameter | Required | Description |\n|---|---|---|\n| `query` | Yes | Search query text |\n| `limit` | No | Maximum number of results (defaults to plugin config) |\n| `scoreThreshold` | No | Minimum relevance score 0–1 (defaults to plugin config) |\n| `targetUri` | No | Exact search scope URI. If provided, only that URI is searched. |\n| `resourceTypes` | No | Array of target types used when `targetUri` is omitted: `resource`, `user`, `agent`. Defaults to plugin `recallTargetTypes`. |\n\nExample: user asks \"What programming language did I say I like?\"\n\n### `memory_store` — Manual Store\n\n| Parameter | Required | Description |\n|---|---|---|\n| `text` | Yes | Information text to store |\n| `role` | No | Session role (default `user`) |\n| `sessionId` | No | Existing OpenViking session ID |\n\nUse this when the user explicitly asks to remember\u002Fsave\u002Fstore a long-term fact, preference, project, or decision.\n\nExample: user says \"Remember my email is xxx@example.com\".\n\n### `memory_forget` — Delete Memories\n\n| Parameter | Required | Description |\n|---|---|---|\n| `uri` | No | Exact memory URI (direct delete) |\n| `query` | No | Search query (find then delete) |\n| `targetUri` | No | Search scope URI |\n| `limit` | No | Search limit (default 5) |\n| `scoreThreshold` | No | Minimum relevance score |\n\nExample: user says \"Forget my phone number\".\n\n### `ov_archive_search` — Search Archived Original Messages\n\n| Parameter | Required | Description |\n|---|---|---|\n| `query` | Yes | A single keyword or short phrase. Prefer concrete names, dates, commands, paths, or distinctive nouns. |\n| `archiveId` | No | Optional archive ID such as `archive_002`. |\n\nUse when `[Session History Summary]` is too coarse. Try at least two keyword variants before concluding the detail is unavailable.\n\n### `ov_archive_expand` — Expand An Archive\n\n| Parameter | Required | Description |\n|---|---|---|\n| `archiveId` | Yes | Archive ID from `[Archive Index]`, e.g. `archive_002`. |\n\n### `add_resource` — Import Resource\n\nThe agent-visible `add_resource` tool is disabled by default (`enableAddResourceTool=false`). Use manual `\u002Fadd-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.\n\n| Parameter | Required | Description |\n|---|---|---|\n| `source` | Yes | Local path, OpenClaw media attachment path, directory path, public URL, or Git URL. |\n| `to` | No | Exact target URI under `viking:\u002F\u002Fresources`; mutually exclusive with `parent`. |\n| `parent` | No | Parent URI under `viking:\u002F\u002Fresources`; mutually exclusive with `to`. |\n| `reason` | No | Reason or note for import. |\n| `instruction` | No | Processing instruction for semantic extraction. |\n| `wait` | No | Wait for processing completion. |\n| `timeout` | No | Timeout in seconds when `wait=true`. |\n\n### `add_skill` — Import Agent Skill\n\n| Parameter | Required | Description |\n|---|---|---|\n| `source` | No | Local `SKILL.md` path or skill directory. Exactly one of `source` or `data` is required. |\n| `data` | No | Raw `SKILL.md` content or MCP tool dict. Exactly one of `source` or `data` is required. |\n| `wait` | No | Wait for processing completion. |\n| `timeout` | No | Timeout in seconds when `wait=true`. |\n\nAgent 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.\n\n### `ov_search` — Search Resources and Skills\n\n| Parameter | Required | Description |\n|---|---|---|\n| `query` | Yes | Search query. |\n| `uri` | No | Optional search URI. Defaults to resources plus agent skills. |\n| `limit` | No | Max results per search scope. Default: 10. |\n\nImportant: `ov_search` result URIs are OpenViking virtual URIs, not local file paths. If full content is needed, call `ov_read` with the exact `viking:\u002F\u002F...` URI returned by search or trace results; do not use filesystem read tools.\n\n### `ov_read` — Read OpenViking Content\n\n| Parameter | Required | Description |\n|---|---|---|\n| `uri` | Yes | Exact `viking:\u002F\u002F...` URI returned by `ov_search` or recall trace results. Local file paths and `openviking:\u002F\u002F...` display aliases are refused. |\n\n### `ov_recall_trace` — Query Recall Trace\n\n| Parameter | Required | Description |\n|---|---|---|\n| `turn` | No | `latest` or `all`; default `latest`. |\n| `traceId` | No | Exact trace ID. |\n| `sessionId` \u002F `sessionKey` \u002F `ovSessionId` | No | Session filters. |\n| `source` | No | `auto_recall`, `memory_recall`, `ov_search`, or `ov_archive_search`. |\n| `resourceTypes` | No | Target type filters: `resource`, `user`, `agent`. |\n| `since` \u002F `until` | No | Unix timestamp bounds in milliseconds. |\n| `includeContent` | No | Read selected\u002Fdisplayed URI content previews on demand. |\n| `limit` | No | Maximum traces to return. Default: 20. |\n\nRequires `traceRecall=true`; persisted lookup also requires `traceRecallPersist=true`.\n\n### Externalized Tool Result Tools\n\nUse these when a preview contains a `viking:\u002F\u002Fsession\u002F\u003Csession_id>\u002Ftool-results\u002F\u003Ctool_result_id>` ref.\n\n| Tool | Parameters |\n|---|---|\n| `openviking_tool_result_list` | `tool_name?`, `limit?` (default 50) |\n| `openviking_tool_result_search` | `tool_output_ref`, `query`, `limit?` (default 20), `context_chars?` (default 300) |\n| `openviking_tool_result_read` | `tool_output_ref`, `offset?` (default 0), `limit?` (default 20000) |\n\n## Configuration Schema\n\nThese are the keys under `plugins.entries.openviking.config` in `openclaw.json`. The setup wizard \u002F `ov-install` sets the first few; the rest are tunables.\n\n| Field | Default | Description |\n|---|---|---|\n| `mode` | `\"remote\"` (forced by plugin) | Always remote in this skill. Don't set manually. |\n| `baseUrl` | `http:\u002F\u002F127.0.0.1:1933` | OpenViking server URL. |\n| `apiKey` | — | API key. Optional if server has no auth. |\n| `peer_role` | `assistant` | Peer identity mode: `none`, `assistant`, or `person`. Session messages use body `peer_id`; data-plane recall\u002Fsearch uses `X-OpenViking-Actor-Peer`. |\n| `peer_prefix` | `\"\"` | Optional prefix for assistant `peer_id` \u002F actor peer values when `peer_role=assistant`. Letters \u002F digits \u002F `_` \u002F `-`. |\n| `accountId` | — | Required when `apiKey` is a root key. |\n| `userId` | — | Required when `apiKey` is a root key. |\n| `targetUri` | `viking:\u002F\u002Fuser\u002Fmemories` | Default search scope URI. |\n| `timeoutMs` | (plugin default) | HTTP timeout for OpenViking calls. |\n| `autoCapture` | `true` | Auto-append turn messages to the OpenViking session at `afterTurn`; extraction runs only after a threshold commit, `\u002Fcompact`, or explicit `memory_store`. |\n| `captureMode` | `\"semantic\"` | Filter mode used by the server-side extraction pipeline: `semantic` or `keyword`. |\n| `captureMaxLength` | `24000` | Max text length per archived turn. |\n| `autoRecall` | `true` | Auto-recall and inject memories before reply. |\n| `recallTargetTypes` | `user,agent` | Default target types when `targetUri` is omitted. Allowed: `resource`, `user`, `agent`. |\n| `recallResources` | `false` | Compatibility shortcut that appends `resource` to default recall targets when `recallTargetTypes` is unset. |\n| `recallLimit` | `6` | Max memories injected per recall. |\n| `recallScoreThreshold` | `0.15` | Min relevance score to inject. |\n| `recallMaxInjectedChars` | `4000` | Hard cap on injected character count. Complete memories that do not fit are skipped, not truncated. |\n| `recallPreferAbstract` | (plugin default) | Prefer abstract memories over raw. |\n| `recallTokenBudget` | deprecated | Compatibility alias for `recallMaxInjectedChars`. |\n| `commitTokenThresholdRatio` | `0.5` | Async-commit threshold as a fraction (0-1) of the model context window (e.g. 0.5 = 50%); `0` commits every turn. |\n| `commitKeepRecentCount` | `10` | Recent messages kept live after afterTurn commit. Compact always uses `0`. |\n| `bypassSessionPatterns` | — | Glob patterns for sessions skipped by capture. |\n| `ingestReplyAssist` | (plugin default) | Reply-assist ingestion toggle. |\n| `emitStandardDiagnostics` | `false` | Emit structured `openviking: diag {...}` lines. |\n| `logFindRequests` | `false` | Log routing for find\u002Fsession writes. Also enabled by `OPENVIKING_LOG_ROUTING=1` or `OPENVIKING_DEBUG=1`. |\n| `traceRecall` | `false` | Record recall traces in memory. |\n| `traceRecallPersist` | `false` | Persist recall traces to JSONL files. |\n| `traceRecallDir` | `~\u002F.openclaw\u002Fopenviking\u002Frecall-traces` | Recall trace directory. |\n\nTo change a value:\n\n```bash\nopenclaw config set plugins.entries.openviking.config.\u003Cfield> \u003Cvalue>\nopenclaw gateway restart\n```\n\n## Multi-Tenant (Root API Keys)\n\nSome OpenViking deployments use a single **root** API key shared across tenants. In that case the plugin needs both `accountId` and `userId` so it can scope memories correctly. The setup wizard detects this automatically and returns:\n\n```\nRoot API key detected. Missing: --account-id, --user-id\n```\n\nWhen you see this:\n\n1. Ask the user for both values (they come from the OpenViking admin).\n2. Retry STEP 7 with both flags:\n\n```bash\nopenclaw openviking setup --base-url BASE_URL --api-key API_KEY --account-id ACCOUNT_ID --user-id USER_ID --json\n```\n\nA **user key** (issued per tenant) does not need these flags.\n\n## Multi-Instance (`--workdir` \u002F `OPENCLAW_STATE_DIR`)\n\nIf the user runs multiple OpenClaw instances (e.g. testing several agents in parallel), each has its own state dir.\n\nTo target a non-default instance:\n\n```bash\nnpx -y openclaw-openviking-setup-helper@latest --workdir ~\u002F.openclaw-second --base-url ... --api-key ...\n```\n\n`ov-install` writes a helper env file when the state dir is non-default:\n\n- Unix: `~\u002F.openclaw\u002Fopenviking.env` containing `export OPENCLAW_STATE_DIR='...'`\n- Windows: `~\u002F.openclaw\u002Fopenviking.env.bat` and `.ps1` setting the same variable\n\nSource it before running `openclaw` commands so they hit the correct state:\n\n**Unix:**\n```bash\nsource ~\u002F.openclaw\u002Fopenviking.env\nopenclaw status\n```\n\n**Windows (PowerShell):**\n```powershell\n. \"$HOME\u002F.openclaw\u002Fopenviking.env.ps1\"\nopenclaw status\n```\n\nOr pass `--workdir` directly to each `openclaw` invocation (note: not all `openclaw` subcommands honor `--workdir` consistently — when in doubt, prefer the env var).\n\n## Daily Operations\n\n```bash\n# Start or restart OpenClaw gateway after config changes\nopenclaw gateway restart\n\n# Check overall status\nopenclaw status\nopenclaw openviking status --json\n\n# Read current OpenViking slot\nopenclaw config get plugins.slots.contextEngine\n\n# Disable OpenViking memory (keep config, deactivate slot)\nopenclaw config set plugins.slots.contextEngine legacy\nopenclaw gateway restart\n\n# Re-enable\nopenclaw config set plugins.slots.contextEngine openviking\nopenclaw gateway restart\n```\n\n## Uninstall\n\n### Preferred: via OpenClaw plugin manager\n\n```bash\nopenclaw plugins uninstall openviking\nopenclaw config set plugins.slots.contextEngine legacy\nopenclaw gateway restart\n```\n\n### If installed through backup `ov-install`\n\n```bash\nnpx -y openclaw-openviking-setup-helper@latest --uninstall\n```\n\nThis will:\n\n1. Stop the OpenClaw gateway.\n2. Back up `openclaw.json`.\n3. Remove all OpenViking plugin config from `openclaw.json` (`plugins.entries.openviking`, `plugins.allow`, `plugins.installs.openviking`, `plugins.slots.contextEngine`).\n4. Move the plugin directory to `disabled-extensions\u002F` as backup.\n5. Remove the helper env files (`openviking.env`, `.bat`, `.ps1`).\n\nAdd `--base-url dummy` for fully non-interactive mode (skips the confirmation prompt).\n\n### Manual\n\n```bash\nopenclaw gateway stop\nopenclaw config set plugins.slots.contextEngine legacy\n# Then edit ~\u002F.openclaw\u002Fopenclaw.json and remove openviking from\n#   plugins.entries\n#   plugins.allow\n#   plugins.installs\nopenclaw gateway restart\n```\n\n## Error Recovery Reference\n\nMatch against actual stderr \u002F JSON `error` strings.\n\n| Symptom (exact string) | Likely cause | Fix |\n|---|---|---|\n| `command not found: openclaw` | OpenClaw not installed | Stop. Ask user to install OpenClaw >= 2026.4.8. |\n| `command not found: node` \u002F `'node' is not recognized` | Node missing | Stop. Ask user to install Node.js >= 22. |\n| `429` \u002F `rate limit` \u002F `Too Many Requests` from `plugins install` | ClawHub throttle | Switch to backup Path B (`ov-install`). |\n| `not logged in` \u002F `please log in` from `plugins install` | Anonymous user hit limit | Switch to backup Path B (`ov-install`). |\n| `ECONNREFUSED` \u002F `connection refused` on `BASE_URL\u002Fhealth` | Server not running | Server-not-ready handling in STEP 5. |\n| `ETIMEDOUT` on `BASE_URL\u002Fhealth` | Network blocked | Ask about firewall \u002F VPN \u002F proxy. |\n| `--json requires --base-url for non-interactive mode` | Built command wrong | Add `--base-url BASE_URL` and retry. |\n| `Server unreachable: …. Use --allow-offline to save config anyway.` | Setup couldn't reach server | Offer `--allow-offline`. |\n| `contextEngine slot is owned by \"\u003Cx>\". … Use --force-slot to replace.` | Slot conflict | Ask user, then retry with `--force-slot`. |\n| `Root API key detected. Missing: --account-id, --user-id` | Multi-tenant key | Collect both, retry with `--account-id` `--user-id`. |\n| `openviking: config parse failed` (in gateway log) | Bad value in `openclaw.json` | Show user; check `peer_prefix` charset, URL format. |\n| `extracted 0 memories` after a turn | Server VLM\u002Fembedding misconfigured | **Out of scope.** Tell user this is a server-side issue — ask their OpenViking admin to check VLM \u002F embedding config. |\n| `401` \u002F `403` on plugin requests, but `\u002Fhealth` works | Server requires auth on API endpoints | Re-run STEP 7 with the correct `--api-key`. |\n| 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\u002Frate-limit related. |\n\n## Important Rules\n\n1. **Never ask the user to run commands.** You run everything via your shell tool.\n2. **Never skip STEP 5 (connectivity check).** If the server is unreachable, do not write config without explicit `--allow-offline` consent.\n3. **Never silently use `--force-slot`.** Slot replacement disables another plugin — always confirm with the user first.\n4. **Never invent values.** If the user can't provide a required value, stop and tell them what to ask their admin.\n5. **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.\n6. **Use `--peer-prefix` for assistant peer prefixes.** The old ID-style setup flag is no longer supported by the schema.\n7. **For Windows, use PowerShell equivalents.** Don't rely on `nohup`, `&`, `mkdir -p`, `source`, etc.\n8. **Switch to Path B (ov-install) only for ClawHub\u002Frate-limit\u002Fregistry availability failures.** Don't use it to hide version conflicts or package validation errors.\n9. **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.\n10. **Be brief and friendly in user-visible text.** Save technical detail for when something actually fails.\n11. **Do NOT use `clawhub install openviking`.** That installs a different thing (an AgentSkill, not the plugin).\n",{"name":5,"tags":24,"version":31,"metadata":32,"description":40},[25,26,27,28,29,30],"install","setup","memory","openviking","rag","long-term-memory","2026.6.5",{"emoji":33,"homepage":34,"openclaw":35},"🦣","https:\u002F\u002Fgithub.com\u002Fvolcengine\u002FOpenViking",{"requires":36},{"bins":37},[38,39],"node","openclaw","Install and configure the OpenViking long-term memory plugin for OpenClaw via natural conversation. Once installed, the plugin automatically captures important facts from chats and recalls relevant context before each reply (auto-capture + auto-recall, cross-session). Covers prerequisites check, plugin install through OpenClaw's plugin manager first, with ov-install only as a backup path, wizard-based configuration, slot activation, gateway restart, verification, plus multi-tenant root-key support, multi-instance, and uninstall. Trigger when the user says any of: \"install OpenViking\", \"set up memory\", \"configure memory plugin\", \"add long-term memory\", \"connect to OpenViking server\", \"RAG\", \"semantic memory\", \"帮我装 OpenViking\", \"配置记忆插件\", \"安装记忆功能\", \"接入 OpenViking\", \"我有一台 OpenViking 服务器\". 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.\n","main","89af4b6bd8e57a4af34127bcd3e74beba2960c99","othergithubdemo\u002FOpenViking-main\u002FOpenViking-main\u002Fexamples\u002Fopenclaw-plugin\u002Fskills\u002Finstall-openviking-memory",0,"https:\u002F\u002Fgithub.com\u002Fzhangmask\u002FC_AnimeCompanion","https:\u002F\u002Fgithub.com\u002Fzhangmask","2026-08-12 23:25:19",{"source":8,"skillName":5,"commands":49,"prompt":59,"zipAvailable":60},[50,53,56],{"tool":51,"command":52},"npx","npx skills add zhangmask\u002FC_AnimeCompanion --skill install-openviking-memory",{"tool":54,"command":55},"bunx","bunx skills add zhangmask\u002FC_AnimeCompanion --skill install-openviking-memory",{"tool":57,"command":58},"pnpm","pnpm dlx skills add zhangmask\u002FC_AnimeCompanion --skill install-openviking-memory","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fzhangmask\u002FC_AnimeCompanion\u002Fblob\u002Fmain\u002Fothergithubdemo\u002FOpenViking-main\u002FOpenViking-main\u002Fexamples\u002Fopenclaw-plugin\u002Fskills\u002Finstall-openviking-memory\u002FSKILL.md",true,[],[63,71,79,87,95,103],{"skillNo":64,"name":65,"nameZh":6,"description":66,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":67,"sourceHtmlUrl":68,"categories":69,"keywords":70,"publishedAt":19},"01M75DWFRG97DMF5XB527G18KQ","mem0","Mem0 Platform SDK for adding persistent memory to AI applications. TRIGGER when: user mentions \"mem0\", \"MemoryClient\", \"memory layer\", \"remember user preferences\", \"persistent context\", \"personalization\", or needs to add long-term memory to chatbots, agents, or AI apps. Covers Python SDK (mem0ai), TypeScript SDK (mem0ai), and framework integrations (LangChain, CrewAI, OpenAI Agents SDK, Pipecat, LlamaIndex, AutoGen, LangGraph). Also covers the open-source self-hosted Memory class. This is the DEFAULT mem0 skill for ambiguous queries. DO NOT TRIGGER when: user asks about CLI commands, terminal usage, or shell scripts (use mem0-cli), or Vercel AI SDK \u002F @mem0\u002Fvercel-ai-provider \u002F createMem0 (use mem0-vercel-ai-sdk).","https:\u002F\u002Fgithub.com\u002Fzhangmask\u002FC_AnimeCompanion\u002Fblob\u002Fmain\u002Fothergithubdemo\u002Fmem0-main\u002Fmem0-main\u002Fskills\u002Fmem0\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fzhangmask\u002FC_AnimeCompanion\u002Fblob\u002Fmain\u002Fothergithubdemo\u002Fmem0-main\u002Fmem0-main\u002Fskills\u002Fmem0\u002FSKILL.md",[],[],{"skillNo":72,"name":73,"nameZh":6,"description":74,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":75,"sourceHtmlUrl":76,"categories":77,"keywords":78,"publishedAt":19},"01M75DWA6DYJVW82BRA7PGWAWP","mem0-vercel-ai-sdk","Mem0 provider for Vercel AI SDK (@mem0\u002Fvercel-ai-provider). TRIGGER when: user mentions \"vercel ai sdk\", \"@mem0\u002Fvercel-ai-provider\", \"createMem0\", \"retrieveMemories\", \"addMemories\", \"getMemories\", \"searchMemories\", \"mem0 vercel\", \"AI SDK provider\", \"AI SDK memory\", or is using generateText\u002FstreamText with mem0. Also triggers for Next.js apps needing memory-augmented AI. DO NOT TRIGGER when: user asks about direct Python\u002FTS SDK calls without Vercel (use mem0 skill), or CLI terminal commands (use mem0-cli skill).","https:\u002F\u002Fgithub.com\u002Fzhangmask\u002FC_AnimeCompanion\u002Fblob\u002Fmain\u002Fothergithubdemo\u002Fmem0-main\u002Fmem0-main\u002Fskills\u002Fmem0-vercel-ai-sdk\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fzhangmask\u002FC_AnimeCompanion\u002Fblob\u002Fmain\u002Fothergithubdemo\u002Fmem0-main\u002Fmem0-main\u002Fskills\u002Fmem0-vercel-ai-sdk\u002FSKILL.md",[],[],{"skillNo":80,"name":81,"nameZh":6,"description":82,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":83,"sourceHtmlUrl":84,"categories":85,"keywords":86,"publishedAt":19},"01M75DW1BKX9416VYXSV0MWWKK","mem0-test-integration","Verify a Mem0 integration produced by \u002Fmem0-integrate. Runs in the same workspace on the same branch (loose coupling) — installs dependencies, runs the repo's native test suite, then exercises a real end-to-end smoke flow against the user's API key. Produces a scorecard. TRIGGER when: user has just run \u002Fmem0-integrate and says \"verify\", \"test the integration\", \"run \u002Fmem0-test-integration\", or when a .mem0-integration\u002F directory exists and tests have not been run yet on the current branch. DO NOT TRIGGER when: the user wants to run general project tests (defer to the repo's native test command), or when no prior \u002Fmem0-integrate run exists in the current branch (ask them to run \u002Fmem0-integrate first). This skill ONLY catches compile and runtime bugs by design. Logical integration errors — wrong data stored, wrong time retrieved, wrong user scoping — are on the human reviewer.","https:\u002F\u002Fgithub.com\u002Fzhangmask\u002FC_AnimeCompanion\u002Fblob\u002Fmain\u002Fothergithubdemo\u002Fmem0-main\u002Fmem0-main\u002Fskills\u002Fmem0-test-integration\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fzhangmask\u002FC_AnimeCompanion\u002Fblob\u002Fmain\u002Fothergithubdemo\u002Fmem0-main\u002Fmem0-main\u002Fskills\u002Fmem0-test-integration\u002FSKILL.md",[],[],{"skillNo":88,"name":89,"nameZh":6,"description":90,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":91,"sourceHtmlUrl":92,"categories":93,"keywords":94,"publishedAt":19},"01M75DVRVCQK3DNHFASD8SD2A2","mem0-oss-to-platform","Plan and then execute a migration of a project from the mem0 open-source \u002F self-hosted SDK (the local `Memory` class) to the mem0 Platform \u002F hosted \u002F managed SDK (the `MemoryClient` class). Use this whenever a developer wants to move, switch, or migrate their mem0 usage off OSS\u002Fself-hosted to the hosted API — e.g. \"migrate my mem0 setup to the platform\", \"switch from self-hosted mem0 to MemoryClient\", \"use my mem0 API key instead of a local Qdrant\", \"move mem0 to the cloud\u002Fhosted\u002Fmanaged service\", or \"replace my local mem0 vector store + embedder config with the platform\". Applies to Python (`from mem0 import Memory` → `from mem0 import MemoryClient`) and TypeScript\u002FJavaScript (`import { Memory } from \"mem0ai\u002Foss\"` → `import MemoryClient from \"mem0ai\"`). Trigger even when the user doesn't say the word \"migrate\" but clearly wants their existing mem0 integration to run against the hosted platform. It first produces a reviewable migration plan, then executes it after the developer approves. Strictly scoped to the mem0 integration — it does not refactor, restructure, or \"improve\" any unrelated code.","https:\u002F\u002Fgithub.com\u002Fzhangmask\u002FC_AnimeCompanion\u002Fblob\u002Fmain\u002Fothergithubdemo\u002Fmem0-main\u002Fmem0-main\u002Fskills\u002Fmem0-oss-to-platform\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fzhangmask\u002FC_AnimeCompanion\u002Fblob\u002Fmain\u002Fothergithubdemo\u002Fmem0-main\u002Fmem0-main\u002Fskills\u002Fmem0-oss-to-platform\u002FSKILL.md",[],[],{"skillNo":96,"name":97,"nameZh":6,"description":98,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":99,"sourceHtmlUrl":100,"categories":101,"keywords":102,"publishedAt":19},"01M75DVH4QN1KKJ6JWFH0ZEP4K","mem0-integrate","Integrate Mem0 into an existing repository using a goal-driven, TDD pipeline. Detects the repo's language automatically and asks the user to pick between Mem0 Platform (managed) and Mem0 Open Source (self-hosted). Writes failing tests before any implementation. Produces a local feature branch plus `.mem0-integration\u002F` artifacts consumed by the paired verification skill. TRIGGER when: user says \"integrate mem0\", \"add mem0 to this repo\", \"wire mem0 into \u003Crepo>\", or asks how to add memory to an existing project. DO NOT TRIGGER when: the user wants general SDK usage (use skill:mem0), CLI usage (use skill:mem0-cli), or Vercel AI SDK (use skill:mem0-vercel-ai-sdk). After success, invoke skill:mem0-test-integration to verify in the same workspace (loose coupling).","https:\u002F\u002Fgithub.com\u002Fzhangmask\u002FC_AnimeCompanion\u002Fblob\u002Fmain\u002Fothergithubdemo\u002Fmem0-main\u002Fmem0-main\u002Fskills\u002Fmem0-integrate\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fzhangmask\u002FC_AnimeCompanion\u002Fblob\u002Fmain\u002Fothergithubdemo\u002Fmem0-main\u002Fmem0-main\u002Fskills\u002Fmem0-integrate\u002FSKILL.md",[],[],{"skillNo":104,"name":105,"nameZh":6,"description":106,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":107,"sourceHtmlUrl":108,"categories":109,"keywords":110,"publishedAt":19},"01M75DV93TE88NQW790RDN7WRY","mem0-cli","Mem0 CLI -- the command-line interface for mem0 memory operations. TRIGGER when: user mentions \"mem0 cli\", \"mem0 command line\", \"@mem0\u002Fcli\", \"mem0-cli\", \"pip install mem0-cli\", \"npm install -g @mem0\u002Fcli\", or is running mem0 commands in a terminal\u002Fshell (mem0 add, mem0 search, mem0 list, mem0 get, mem0 init, mem0 config, mem0 import). Also triggers when query includes CLI flags like --user-id, --output, --json, --agent, or describes bash\u002Fzsh\u002Fterminal\u002Fshell usage. DO NOT TRIGGER when: user asks about programmatic SDK integration in Python\u002FTS code (use mem0 skill), or Vercel AI SDK provider (use mem0-vercel-ai-sdk skill).","https:\u002F\u002Fgithub.com\u002Fzhangmask\u002FC_AnimeCompanion\u002Fblob\u002Fmain\u002Fothergithubdemo\u002Fmem0-main\u002Fmem0-main\u002Fskills\u002Fmem0-cli\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fzhangmask\u002FC_AnimeCompanion\u002Fblob\u002Fmain\u002Fothergithubdemo\u002Fmem0-main\u002Fmem0-main\u002Fskills\u002Fmem0-cli\u002FSKILL.md",[],[]]