@openviking/openclaw-plugin 2026.5.8

package/INSTALL.md

@@ -0,0 +1,362 @@
+# Install OpenViking for OpenClaw
+
+OpenViking provides long-term memory, knowledge base search, semantic retrieval, and RAG-style context for OpenClaw through the `@openviking/openclaw-plugin` plugin.
+
+This guide describes the current plugin install flow. It is written for both people and automation agents.
+
+## Do Not Install The Skill By Mistake
+
+`@openviking/openclaw-plugin` is an OpenClaw plugin.
+
+Do not use this command for plugin installation:
+
+```bash
+clawhub install openviking
+```
+
+That command installs an AgentSkill named `openviking`, not the OpenClaw plugin.
+
+Use this plugin command instead:
+
+```bash
+openclaw plugins install @openviking/openclaw-plugin
+```
+
+## Requirements
+
+| Component | Required |
+| --- | --- |
+| Node.js | >= 22 |
+| OpenClaw | >= 2026.4.8 |
+
+The plugin connects to an existing OpenViking server. It does not start the OpenViking server for you. Start OpenViking first, keep it running, then point the plugin `baseUrl` at that HTTP service. The default local URL is `http://127.0.0.1:1933`.
+
+OpenClaw plugin package boundaries:
+
+- `2026.4.8` is the minimum supported OpenClaw version for the current plugin.
+- `2026.5.3` starts validating package installs so TypeScript plugin entries need compiled JavaScript output.
+- `2026.5.4` and later stop falling back to `.ts` source for installed/global plugin runtime loading when compiled JavaScript is missing.
+- The recommended `openclaw plugins install @openviking/openclaw-plugin` path installs a published package that already includes `dist/*.js`.
+- `ov-install` is the backup/source install path. Use it when ClawHub or the OpenClaw plugin manager path is unavailable/rate-limited, or when explicitly testing a source ref. For OpenClaw `>= 2026.5.3`, it builds the plugin during installation.
+
+Quick check:
+
+```bash
+node -v
+openclaw --version
+```
+
+## Start OpenViking Server
+
+For a local OpenViking server on the same machine as OpenClaw:
+
+```bash
+pip install openviking --upgrade --force-reinstall
+openviking-server init
+openviking-server doctor
+openviking-server
+```
+
+`openviking-server init` writes the server configuration, `openviking-server doctor` validates local model/provider auth, and `openviking-server` starts the HTTP API. Keep this process running while OpenClaw uses the plugin.
+
+To run the server in the background:
+
+```bash
+mkdir -p ~/.openviking/data/log
+nohup openviking-server > ~/.openviking/data/log/openviking.log 2>&1 &
+```
+
+If OpenViking runs on another machine, start it on a reachable host/port, for example:
+
+```bash
+openviking-server --host 0.0.0.0 --port 1933
+```
+
+Then configure the OpenClaw plugin `baseUrl` to that address, such as `http://your-server:1933`.
+
+Verify the server before installing or restarting the plugin:
+
+```bash
+curl http://127.0.0.1:1933/health
+```
+
+## Recommended Install Path
+
+Use this path for normal users, production installs, and agent-assisted installs.
+
+### 1. Install The Plugin
+
+```bash
+openclaw plugins install @openviking/openclaw-plugin
+```
+
+If your OpenClaw installation requires an explicit registry prefix, use:
+
+```bash
+openclaw plugins install clawhub:@openviking/openclaw-plugin
+```
+
+### 2. Configure The Plugin
+
+For interactive human setup:
+
+```bash
+openclaw openviking setup
+```
+
+For non-interactive agent setup:
+
+```bash
+openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --json
+```
+
+Example:
+
+```bash
+openclaw openviking setup --base-url http://127.0.0.1:1933 --api-key sk-xxx --json
+```
+
+The setup command writes `plugins.entries.openviking.config` and activates `plugins.slots.contextEngine=openviking`.
+
+If the OpenViking server is temporarily unreachable but you still want to save the config:
+
+```bash
+openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --allow-offline --json
+```
+
+If your API key is a root key, setup may require tenant context:
+
+```bash
+openclaw openviking setup \
+  --base-url <OPENVIKING_URL> \
+  --api-key <ROOT_API_KEY> \
+  --account-id <ACCOUNT_ID> \
+  --user-id <USER_ID> \
+  --json
+```
+
+If another context engine already owns the slot, setup will not replace it by default. To intentionally replace the current owner:
+
+```bash
+openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --force-slot --json
+```
+
+If you need a custom agent routing prefix (optional; most users leave this empty):
+
+```bash
+openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --agent-prefix <PREFIX> --json
+```
+
+### 3. Restart OpenClaw Gateway
+
+```bash
+openclaw gateway restart
+```
+
+If your OpenClaw version uses a different restart command, use the equivalent gateway restart for your environment.
+
+### 4. Verify
+
+```bash
+openclaw openviking status --json
+```
+
+Expected result:
+
+| JSON field | Expected value |
+| --- | --- |
+| `configured` | `true` |
+| `slotActive` | `true` |
+| `health.ok` | `true` when the server is reachable |
+
+You can also inspect the raw OpenClaw config:
+
+```bash
+openclaw config get plugins.entries.openviking.config
+openclaw config get plugins.slots.contextEngine
+```
+
+`plugins.slots.contextEngine` should be `openviking`.
+
+## Agent Result Handling
+
+Automation should prefer `--json` and branch on these fields:
+
+| Result | Meaning | Recommended action |
+| --- | --- | --- |
+| `success: true` | Config saved and setup completed | Restart gateway, then run status |
+| `success: false`, `action: "slot_blocked"` | Config may be saved, but another plugin owns `contextEngine` | Ask before rerunning with `--force-slot` |
+| `success: false`, `action: "error"` | Validation failed | Show `error`; do not claim install succeeded |
+| `health.ok: false` | Server unreachable | Check URL/server, or rerun with `--allow-offline` only if the user accepts |
+| `keyProbe.keyType: "root_key"` | Root key needs tenant context | Rerun with `--account-id` and `--user-id` |
+
+## Configuration Reference
+
+The plugin config lives at:
+
+```text
+plugins.entries.openviking.config
+```
+
+Core fields:
+
+| Field | Default | Description |
+| --- | --- | --- |
+| `mode` | `remote` | Legacy compatibility field. Only remote mode is supported. |
+| `baseUrl` | `http://127.0.0.1:1933` | OpenViking HTTP endpoint |
+| `apiKey` | empty | OpenViking API key |
+| `agent_prefix` | empty | Optional prefix for OpenClaw agent IDs. If no agent ID is available, the plugin uses `main`. Interactive setup accepts only letters, digits, `_`, and `-`. |
+| `accountId` | empty | Required when using a root API key |
+| `userId` | empty | Required when using a root API key |
+
+Use setup for normal changes when possible:
+
+```bash
+openclaw openviking setup --reconfigure
+```
+
+Manual config inspection:
+
+```bash
+openclaw config get plugins.entries.openviking.config
+```
+
+## Upgrade
+
+```bash
+openclaw plugins update openviking
+openclaw gateway restart
+openclaw openviking status --json
+```
+
+Confirm that `configured` and `slotActive` are both `true`.
+
+## Uninstall
+
+```bash
+openclaw plugins uninstall openviking
+openclaw config set plugins.slots.contextEngine legacy
+openclaw gateway restart
+```
+
+Current OpenClaw native uninstall does not always reset `plugins.slots.contextEngine`. The explicit `config set` step avoids leaving the slot pointed at an uninstalled plugin.
+
+## Optional Pipeline Health Check
+
+After status passes, you can run the bundled end-to-end health check from a repository checkout:
+
+```bash
+python examples/openclaw-plugin/health_check_tools/ov-healthcheck.py
+```
+
+This checks the Gateway to OpenViking path by injecting a real conversation and verifying capture, commit, archive, and memory extraction. See [health_check_tools/HEALTHCHECK.md](./health_check_tools/HEALTHCHECK.md).
+
+## Backup Path: ov-install
+
+`ov-install` is the backup path, not the primary install path. Use it when `openclaw plugins install @openviking/openclaw-plugin` cannot reach ClawHub, is rate-limited, or when you explicitly need to install/test plugin files from a Git branch or source ref.
+
+Try the OpenClaw plugin manager first. If that path is unavailable, run:
+
+```bash
+npm install -g openclaw-openviking-setup-helper
+ov-install
+```
+
+Useful backup/source flags:
+
+| Flag | Meaning |
+| --- | --- |
+| `--workdir PATH` | Target OpenClaw state directory |
+| `--version REF` | Git ref, tag, branch, or release version to install |
+| `--current-version` | Print the version tracked by the helper |
+| `--base-url URL` | OpenViking server URL (enables non-interactive mode) |
+| `--api-key KEY` | OpenViking API key |
+| `--agent-prefix PREFIX` | Agent routing prefix |
+| `--update` | Update an existing helper-managed install |
+
+For user-facing installs, use `openclaw plugins install @openviking/openclaw-plugin` first. Choose `ov-install` only as the backup path.
+
+## Migrate From ov-install To openclaw plugin install
+
+If you previously installed OpenViking with `ov-install`, follow these steps before switching to the recommended `openclaw plugins install` path.
+
+### Same Plugin ID (openviking, version >= 0.3.x)
+
+The ov-install context-engine deployment writes files to `~/.openclaw/extensions/openviking/`. After installing via npm, OpenClaw may still load from the old directory. Clean it up:
+
+```bash
+# Remove ov-install deployed files
+rm -rf ~/.openclaw/extensions/openviking/
+
+# Install via the OpenClaw plugin manager
+openclaw plugins install @openviking/openclaw-plugin
+
+# Reconfigure (your existing config in openclaw.json is preserved)
+openclaw openviking setup --reconfigure
+openclaw gateway restart
+openclaw openviking status --json
+```
+
+Your existing config fields (`baseUrl`, `apiKey`, `agentId`, etc.) are preserved. The new plugin version reads old field names at runtime — no manual config edits needed.
+
+The plugin configuration lives under `plugins.entries.openviking.config`.
+
+Get the current full plugin configuration:
+
+```bash
+openclaw config get plugins.entries.openviking.config
+```
+
+### Configuration Parameters
+
+The plugin connects to an existing remote OpenViking server.
+
+| Parameter | Default | Meaning |
+| --- | --- | --- |
+| `baseUrl` | `http://127.0.0.1:1933` | Remote OpenViking HTTP endpoint |
+| `apiKey` | empty | Optional OpenViking API key |
+| `agent_prefix` | empty | Optional prefix for OpenClaw agent IDs. If no agent ID is available, the plugin uses `main`. Interactive setup accepts only letters, digits, `_`, and `-` |
+
+Common settings:
+
+```bash
+openclaw config set plugins.entries.openviking.config.baseUrl http://your-server:1933
+openclaw config set plugins.entries.openviking.config.apiKey your-api-key
+openclaw config set plugins.entries.openviking.config.agent_prefix your-prefix
+```
+
+## Start
+
+After installation (if you skipped reconfigure above):
+
+```bash
+openclaw gateway restart
+openclaw openviking status --json
+```
+
+### Old Plugin ID (memory-openviking, version < 0.3.x)
+
+The old memory plugin used a different plugin ID and slot:
+
+```bash
+# Uninstall old plugin
+openclaw plugins uninstall memory-openviking 2>/dev/null || true
+
+# Clean up old slot and files
+openclaw config set plugins.slots.memory none
+rm -rf ~/.openclaw/extensions/memory-openviking/
+
+# Install new plugin
+openclaw plugins install @openviking/openclaw-plugin
+openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --json
+openclaw gateway restart
+openclaw openviking status --json
+```
+
+Or use the cleanup script:
+
+```bash
+bash examples/openclaw-plugin/upgrade_scripts/cleanup-memory-openviking.sh
+```
+
+See also: [INSTALL-ZH.md](./INSTALL-ZH.md) and [INSTALL-AGENT.md](./INSTALL-AGENT.md).

package/README.md

@@ -0,0 +1,315 @@
+# @openviking/openclaw-plugin — OpenViking OpenClaw Plugin
+
+OpenClaw context-engine plugin for OpenViking remote memory, context database, RAG and semantic retrieval.
+
+## Important: Plugin vs Skill
+
+This page is for the **OpenClaw plugin package**:
+
+```
+@openviking/openclaw-plugin
+```
+
+**Do NOT** install the plugin with `clawhub install openviking` — that installs the `openviking` AgentSkill (under `skills/openviking`), which is a different thing.
+
+For **agent-assisted plugin setup**, ask the agent to follow [INSTALL-AGENT.md](./INSTALL-AGENT.md). The primary install path is still `openclaw plugins install @openviking/openclaw-plugin`.
+
+## Install (Natural Language)
+
+Ask your agent:
+
+> Install the OpenClaw plugin @openviking/openclaw-plugin for OpenViking remote memory. My server is at `http://my-server:1933` and my API key is `sk-xxx`.
+
+Or in Chinese:
+
+> 帮我安装 OpenViking 远程记忆插件 @openviking/openclaw-plugin。我的服务器地址是 `http://my-server:1933`，API key 是 `sk-xxx`。
+
+The agent will automatically run install → setup → restart → verify. No manual steps needed.
+
+## Install (Command Line)
+
+```bash
+openclaw plugins install @openviking/openclaw-plugin
+openclaw openviking setup --base-url http://my-server:1933 --api-key sk-xxx --json
+openclaw gateway restart
+openclaw openviking status --json
+```
+
+The `setup` command automatically activates the context-engine slot and validates the server connection.
+
+## Search Keywords
+
+@openviking/openclaw-plugin, openclaw openviking plugin, openviking remote memory plugin, OpenViking Context Database plugin, install-openviking-memory.
+
+## Documentation
+
+- Install and upgrade: [INSTALL.md](./INSTALL.md)
+- Chinese design and install guide: [INSTALL-ZH.md](./INSTALL-ZH.md)
+- Agent-oriented operator guide: [INSTALL-AGENT.md](./INSTALL-AGENT.md)
+
+---
+
+## Technical Overview
+
+Use [OpenViking](https://github.com/volcengine/OpenViking) as the long-term memory backend for [OpenClaw](https://github.com/openclaw/openclaw). In OpenClaw, this plugin is registered as the `openviking` context engine.
+
+The remainder of this document is an implementation-focused design note for integrators and engineers.
+
+## Design Positioning
+
+- OpenClaw still owns the agent runtime, prompt orchestration, and tool execution.
+- OpenViking owns long-term memory retrieval, session archiving, archive summaries, and memory extraction.
+- `examples/openclaw-plugin` is not a narrow "memory lookup" plugin. It is an integration layer that spans the OpenClaw lifecycle.
+
+In the current implementation, the plugin plays four roles at once:
+
+- `context-engine`: implements `assemble`, `afterTurn`, and `compact`
+- hook layer: handles `session_start`, `session_end`, and `before_reset`
+- tool provider: registers memory/archive tools plus OpenViking resource and skill import tools
+- runtime manager: connects to and monitors a remote OpenViking service
+
+## Overall Architecture
+
+![Overall OpenClaw and OpenViking plugin architecture](./images/openclaw-plugin-engine-overview.png)
+
+The diagram above reflects the current implementation boundary:
+
+- OpenClaw remains the primary runtime on the left. The plugin does not take over agent execution.
+- The middle layer combines hooks, the context engine, tools, and runtime management in one plugin registration.
+- All HTTP traffic goes through `OpenVikingClient`, which centralizes `X-OpenViking-*` headers and routing logs.
+- The OpenViking service owns sessions, memories, archives, and Phase 2 extraction, with storage under `viking://user/*`, `viking://agent/*`, and `viking://session/*`.
+
+That split lets OpenClaw stay focused on reasoning and orchestration while OpenViking becomes the source of truth for long-lived context.
+
+## Identity and Routing
+
+The plugin does not send one fixed agent ID to OpenViking. It tries to keep OpenClaw session identity and OpenViking routing aligned.
+
+The main rules are:
+
+- reuse `sessionId` directly when it is already a UUID
+- prefer `sessionKey` when deriving a stable `ovSessionId`
+- normalize unsafe path characters, or fall back to a stable SHA-256 when needed
+- resolve `X-OpenViking-Agent` per session, not per process
+- when `plugins.entries.openviking.config.agent_prefix` is non-empty, prefix the session agent as `<agent_prefix>_<sessionAgent>`
+- when OpenClaw does not provide a session agent, use its default agent `main`
+- send `X-OpenViking-Agent` on OpenViking requests, including startup health checks
+- only add `X-OpenViking-Account` / `X-OpenViking-User` when `accountId` / `userId` are explicitly configured
+
+This matters because the plugin is built to support multi-agent and multi-session OpenClaw usage without mixing memories across sessions.
+
+The recommended remote-mode configuration only needs:
+
+- `baseUrl`
+- `apiKey`
+- `agent_prefix`
+
+In this setup:
+
+- `apiKey` should usually be a user key
+- `accountId` / `userId` are advanced options only when the deployment needs explicit identity headers, such as root-key or trusted-server flows
+- `isolateUserScopeByAgent` / `isolateAgentScopeByUser` must match the server-side account namespace policy when using the PR #1356 canonical namespace model
+- `agentScopeMode` is a deprecated compatibility alias for older hash-based routing and should only be used against older servers
+
+### Canonical namespace policy
+
+For OpenViking servers that include PR #1356, the plugin no longer treats agent or user scope as a locally computed hash. Instead it expands shorthand aliases into canonical URIs using the configured namespace policy:
+
+- `viking://user/memories`
+  - `viking://user/<user_id>/memories` when `isolateUserScopeByAgent=false`
+  - `viking://user/<user_id>/agent/<agent_id>/memories` when `isolateUserScopeByAgent=true`
+- `viking://agent/memories`
+  - `viking://agent/<agent_id>/memories` when `isolateAgentScopeByUser=false`
+  - `viking://agent/<agent_id>/user/<user_id>/memories` when `isolateAgentScopeByUser=true`
+
+The plugin cannot auto-discover this policy today because `/api/v1/system/status` does not expose it. Configure the two booleans explicitly so they stay aligned with the server-side account policy.
+
+## assemble Recall Flow
+
+![Automatic recall flow before prompt build](./images/openclaw-plugin-recall-flow.png)
+
+Auto-recall now runs through `assemble()`. OpenClaw calls the same context engine method in two shapes, and the plugin assigns different responsibilities to each shape:
+
+1. Preflight assemble: params include `prompt`; `messages` is still old history. The plugin reads archive/session context back from OpenViking and rebuilds history.
+2. transformContext assemble: params do not include `prompt`; the latest `messages` entry is already the current user turn. The plugin only runs long-term recall and prepends the memory block to that user message content.
+
+During recall, the plugin:
+
+1. Extracts query text from the latest user message.
+2. Resolves the agent routing for the current `sessionId/sessionKey`.
+3. Runs a quick availability precheck so model requests do not stall when OpenViking is unavailable.
+4. Queries both `viking://user/memories` and `viking://agent/memories` in parallel.
+5. Deduplicates, threshold-filters, reranks, and trims the results under a token budget.
+6. Prepends the selected memories as a `<relevant-memories>` block to the current user message; it does not append a standalone synthetic user message.
+
+The reranking logic is not pure vector-score sorting. The current implementation also considers:
+
+- whether a result is a leaf memory with `level == 2`
+- whether it looks like a preference memory
+- whether it looks like an event memory
+- lexical overlap with the current query
+
+## Session Lifecycle
+
+![Session lifecycle and compaction boundary](./images/openclaw-plugin-session-lifecycle.png)
+
+Session handling is the main axis of this design. In the current implementation it covers history assembly, incremental append, asynchronous commit, and blocking compaction readback.
+
+### What `assemble()` does
+
+During preflight, `assemble()` is not just replaying old chat history. It reads session context back from OpenViking under a token budget, then rebuilds OpenClaw-facing messages:
+
+- `latest_archive_overview` becomes `[Session History Summary]`
+- `pre_archive_abstracts` becomes `[Archive Index]`
+- active session messages stay in message-block form
+- assistant tool parts become `toolCall` (input compatible: `toolUse`/`input` is normalized to `toolCall`/`arguments`)
+- tool output becomes separate `toolResult`
+- the final message list goes through a tool-use/result pairing repair pass
+
+That means OpenClaw sees "compressed history summary + archive index + active messages", not an ever-growing raw transcript.
+
+### What `afterTurn()` does
+
+`afterTurn()` has a narrower job: append only the new turn into the OpenViking session.
+
+- it slices only the newly added messages
+- it keeps only `user` / `assistant` capture text
+- it preserves `toolCall` / `toolResult` content in the serialized turn text
+- it strips injected `<relevant-memories>` blocks and metadata noise before capture
+- it appends the sanitized turn text into the OpenViking session
+
+After that, the plugin checks `pending_tokens`. Once the session crosses `commitTokenThreshold`, it triggers `commit(wait=false)`:
+
+- archive generation and Phase 2 memory extraction continue asynchronously on the server
+- the current turn is not blocked waiting for extraction
+- if `logFindRequests` is enabled, the logs include the task id and follow-up extraction detail
+
+### What `compact()` does
+
+`compact()` is the stricter synchronous boundary:
+
+- it calls `commit(wait=true)` and blocks for completion
+- when an archive exists, it re-reads `latest_archive_overview`
+- it returns updated token estimates, the latest archive id, and summary content
+- if the summary is too coarse, the model can call `ov_archive_expand` to reopen a specific archive
+
+So `afterTurn()` is closer to "incremental append plus threshold-triggered async commit", while `compact()` is the explicit "wait for archive and compaction to finish" boundary.
+
+## Tools and Expandability
+
+Beyond automatic behavior, the plugin exposes six tools directly:
+
+- `memory_recall`: explicit long-term memory search
+- `memory_store`: write text into an OpenViking session and trigger commit
+- `memory_forget`: delete by URI, or search first and remove a single strong match
+- `ov_archive_expand`: expand a concrete archive back into raw messages
+- `ov_import`: import a resource or skill; defaults to resource and uses `kind: "skill"` for skills
+- `memory_search`: search OpenViking resources and skills, especially after importing them
+
+They serve different roles:
+
+- automatic recall covers the default case where the model does not know what to search yet
+- `memory_recall` gives the model an explicit follow-up search path
+- `memory_store` is for immediately persisting clearly important information
+- `ov_archive_expand` is the "go back to archive detail" escape hatch when summaries are not enough
+- `ov_import` lets the agent complete explicit import requests without asking the user to remember slash commands
+- `memory_search` closes the loop after import by letting the user or agent confirm and consume resources and skills
+
+`ov_archive_expand` is especially important because `assemble()` normally returns archive summaries and indexes, not the full raw transcript.
+
+### Resource and Skill Import
+
+Resource and skill imports are intentionally separate because they land in different OpenViking namespaces and use different server APIs:
+
+- resources go through `/api/v1/resources` and land under `viking://resources/...`
+- skills go through `/api/v1/skills` and land under `viking://agent/skills/...`
+
+The plugin also registers explicit slash commands for manual imports:
+
+```text
+/ov-import ./README.md --to viking://resources/openviking-readme --wait
+/ov-import ./skills/install-openviking-memory --kind skill --wait
+/memory-search "OpenViking install" --uri viking://resources/openviking-readme
+/memory-search "memory install skill" --uri viking://agent/skills
+```
+
+Resource import supports remote URLs, Git URLs, local files, local directories, and uploaded zip files. OpenViking's built-in parsers cover common documents and media such as Markdown, text, PDF, HTML, Word, PowerPoint, Excel, EPUB, images, audio, and video. Directory imports also accept common code, documentation, and config file extensions such as `.py`, `.js`, `.ts`, `.go`, `.rs`, `.java`, `.cpp`, `.json`, `.yaml`, `.toml`, `.csv`, `.rst`, `.proto`, `.tf`, and `.vue`.
+
+For HTTP safety, the plugin never sends a direct local filesystem path to the OpenViking server. Local files and directories are first uploaded through `/api/v1/resources/temp_upload`; directories are zipped locally with a pure JavaScript zip implementation before upload.
+
+## Runtime Mode
+
+![Runtime modes and routing behavior](./images/openclaw-plugin-runtime-routing.png)
+
+The plugin operates exclusively in remote mode as a pure HTTP client:
+
+- `baseUrl` and optional `apiKey` come from plugin config
+- no local subprocess is started or managed
+- session context, memory search/read, commit, and archive expansion behavior stays the same
+
+The OpenViking service must be deployed and running independently before the plugin can connect to it.
+
+## Relationship to the Older Design Draft
+
+The repo also contains a more future-looking design draft at `docs/design/openclaw-context-engine-refactor.md`. It is important not to conflate the two:
+
+- this README describes current implemented behavior
+- the older draft discusses a stronger future move into context-engine-owned lifecycle control
+- in the current version, the main automatic recall path lives in `assemble()`: preflight rebuilds history, transformContext injects long-term memories
+- in the current version, `afterTurn()` already appends to the OpenViking session, but commit remains threshold-triggered and asynchronous on that path
+- in the current version, `compact()` already uses `commit(wait=true)`, but it is still focused on synchronous commit plus readback rather than owning every orchestration concern
+
+That distinction matters, otherwise the future design draft is easy to misread as already shipped behavior.
+
+## Operator and Debugging Surfaces
+
+If you need to debug this plugin, start with these entry points.
+
+### Inspect the current setup
+
+```bash
+openclaw openviking status --json
+openclaw plugins list
+openclaw config get plugins.entries.openviking.config
+openclaw config get plugins.slots.contextEngine
+```
+
+### Watch logs
+
+OpenClaw plugin logs:
+
+```bash
+openclaw logs --follow
+```
+
+OpenViking service logs:
+
+```bash
+cat ~/.openviking/data/log/openviking.log
+```
+
+### Web Console
+
+```bash
+python -m openviking.console.bootstrap --host 0.0.0.0 --port 8020 --openviking-url http://127.0.0.1:1933
+```
+
+### `ov tui`
+
+```bash
+ov tui
+```
+
+### Common things to check
+
+| Symptom | More likely cause | First check |
+| --- | --- | --- |
+| `plugins.slots.contextEngine` is not `openviking` | The plugin slot was never set, or another plugin replaced it | `openclaw config get plugins.slots.contextEngine` |
+| Cannot connect to OpenViking service | `baseUrl` is wrong or the service is down | Check `baseUrl` in config and test connectivity manually |
+| recall behaves inconsistently across sessions | Routing identity is not what you expected | Enable `logFindRequests`, then inspect `openclaw logs --follow` |
+| long chats stop extracting memory | `pending_tokens` never crosses the threshold, or Phase 2 fails server-side | Check plugin config and `~/.openviking/data/log/openviking.log` |
+| summaries are too coarse for detailed questions | You need archive-level detail, not just summary | Use an ID from `[Archive Index]` with `ov_archive_expand` |
+
+---
+
+For installation, upgrade, and uninstall operations, use [INSTALL.md](./INSTALL.md).