---
name: openviking-context-database
description: >
  Use OpenViking from OpenClaw through @openviking/openclaw-plugin: long-term memory,
  session archives, resource and Agent Skill import, semantic recall, recall trace debugging,
  and externalized tool-result recovery. Prefer this skill when the user wants to use, query,
  debug, or operate OpenViking context from an OpenClaw agent. For first-time plugin installation,
  use the install-openviking-memory skill instead.
version: 2026.6.5
metadata:
  openclaw:
    requires:
      plugin: "@openviking/openclaw-plugin"
  emoji: "🦣"
tags:
  - openviking
  - context-engine
  - memory
  - resources
  - skills
  - recall-trace
---

# OpenViking Context Database — OpenClaw Plugin Operator Skill

Use this skill after `@openviking/openclaw-plugin` is installed and configured. It describes the current OpenClaw plugin implementation, not the standalone OpenViking Python SDK.

## Scope and Safety Rules

- The plugin is **remote-only**. It talks to an existing OpenViking server through HTTP and does not start or manage `openviking-server`.
- Do not invent OpenViking REST endpoints. Use the registered OpenClaw tools and commands described below.
- The agent-visible `add_resource` tool is disabled by default (`enableAddResourceTool=false`). Do not use `add_resource` during search, retrieval, URI reading, or search-result optimization. Use `ov_search` and `ov_read` in those flows.
- Use manual `/add-resource`, or `add_resource` only when it is explicitly enabled and the user explicitly asks to import, add, upload, save, or index a resource.
- Use `add_skill` only when the user explicitly asks to import, add, install, or register an Agent Skill into OpenViking.
- For local files and directories, pass the local path to the plugin tool. The plugin uploads them through `/api/v1/resources/temp_upload`; do not send raw local filesystem paths to a remote server yourself.
- Never log or echo API keys. The plugin sends API keys as `X-API-Key` / setup probe headers and masks them in setup output.

## Current Architecture

OpenClaw owns agent execution, prompts, and tool invocation. OpenViking owns long-lived context:

| Layer | Current behavior |
|---|---|
| `assemble` | Rebuilds compressed session history from OpenViking and injects relevant recall into the latest user message. |
| `afterTurn` | Appends only the new turn to the OpenViking session; may trigger async commit when `pending_tokens >= tokenBudget * commitTokenThresholdRatio`. |
| `compact` | Runs `commit(wait=true)`, waits for archive/extraction completion, and reads back latest archive overview. |
| Tools | Memory recall/store/forget, archive search/expand, resource/skill import/search, recall trace query, tool-result list/search/read. |

Long-term memories are usually extracted on `/compact` or on threshold-triggered commit. A fact mentioned in a fresh conversation may still be present as recent session context before it becomes a long-term memory.

## Configuration Quick Reference

Read status first:

```bash
openclaw openviking status --json
openclaw config get plugins.entries.openviking.config
openclaw config get plugins.slots.contextEngine
```

Core config lives under `plugins.entries.openviking.config`:

| Field | Default | Purpose |
|---|---:|---|
| `baseUrl` | `http://127.0.0.1:1933` | OpenViking HTTP endpoint. Can also come from `OPENVIKING_BASE_URL` / `OPENVIKING_URL`. |
| `apiKey` | empty | Optional API key. Can also come from `OPENVIKING_API_KEY`. |
| `peer_role` | `assistant` | Peer identity mode: `none`, `assistant`, or `person`. Session messages use body `peer_id`; data-plane recall/search uses `X-OpenViking-Actor-Peer`. |
| `peer_prefix` | empty | Optional prefix for assistant `peer_id` / actor peer values when `peer_role=assistant`. |
| `accountId` / `userId` | empty | Advanced tenant identity headers for root-key or trusted deployments. |
| `targetUri` | `viking://user/memories` | Default search scope for legacy targeted memory search. |
| `autoCapture` | `true` | Append sanitized turn text to OpenViking sessions. |
| `captureMode` | `semantic` | `semantic` or `keyword`; affects server-side extraction filtering. |
| `captureMaxLength` | `24000` | Max sanitized text length per captured turn. |
| `autoRecall` | `true` | Run recall before replies and inject relevant context. |
| `recallTargetTypes` | `user,agent` | Default target types when `targetUri` is omitted. Allowed: `resource`, `user`, `agent`. |
| `recallResources` | `false` | Compatibility shortcut that appends `resource` to default recall targets when `recallTargetTypes` is unset. |
| `recallLimit` | `6` | Max selected recall items. |
| `recallScoreThreshold` | `0.15` | Min score after post-processing. |
| `recallMaxInjectedChars` | `4000` | Total injected character cap; complete memories that do not fit are skipped. |
| `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. |
| `commitKeepRecentCount` | `10` | Recent messages kept live after afterTurn commit. Compact always uses `0`. |
| `bypassSessionPatterns` | empty | Glob-like session keys that completely bypass OpenViking (`*` segment, `**` multi-segment). |
| `emitStandardDiagnostics` | `false` | Emit structured `openviking: diag {...}` lines. |
| `logFindRequests` | `false` | Log routing for find/session writes. Also enabled by `OPENVIKING_LOG_ROUTING=1` or `OPENVIKING_DEBUG=1`. |
| `traceRecall` | `false` | Record recall traces in memory. |
| `traceRecallPersist` | `false` | Persist recall traces as local JSONL files. |
| `traceRecallDir` | `~/.openclaw/openviking/recall-traces` | Recall trace directory when persistence is enabled. |

Normal setup command:

```bash
openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --json
```

Useful variants:

```bash
openclaw openviking setup --base-url <URL> --api-key <KEY> --peer-prefix openclaw-prod --json
openclaw openviking setup --base-url <URL> --api-key <ROOT_KEY> --account-id <ACCOUNT_ID> --user-id <USER_ID> --json
openclaw openviking setup --base-url <URL> --api-key <KEY> --recall-target-types resource --json
openclaw openviking setup --base-url <URL> --api-key <KEY> --allow-offline --json
openclaw openviking setup --base-url <URL> --api-key <KEY> --force-slot --json
```

## Tool Selection Guide

| User intent | Use |
|---|---|
| “What did I say before?”, preferences, decisions, known facts | `memory_recall` |
| “Remember this now” | `memory_store` |
| “Forget X” | `memory_forget` |
| Summary lacks an exact command/path/snippet from old chat | `ov_archive_search`, then `ov_archive_expand` if needed |
| Import docs, PDFs, local dirs, URLs, Git repos, media attachments | manual `/add-resource`; `add_resource` only if `enableAddResourceTool=true` |
| Import/register an Agent Skill | `add_skill` |
| Search imported resources or skills | `ov_search` |
| Read an exact `viking://...` hit from `ov_search` or recall trace | `ov_read` |
| Explain why recall/search returned something | `ov_recall_trace` |
| A previous tool result shows only a preview/ref | `openviking_tool_result_list`, `openviking_tool_result_search`, `openviking_tool_result_read` |

## Tool Interface Reference

### `memory_recall`

Semantic search over memories/resources. Use archive tools for session history.

| Parameter | Required | Description |
|---|---|---|
| `query` | Yes | Search query. |
| `limit` | No | Max selected results. Defaults to `recallLimit`. |
| `scoreThreshold` | No | Score threshold `0..1`. Defaults to `recallScoreThreshold`. |
| `targetUri` | No | Exact search URI. If set, only this URI is searched. |
| `resourceTypes` | No | Array of `resource`, `user`, `agent`; used only when `targetUri` is omitted. |

Notes: when `targetUri` is omitted, the plugin resolves a search plan from `resourceTypes` or configured `recallTargetTypes`, fetches more candidates than requested, deduplicates, filters leaf memories, reranks, and respects `recallMaxInjectedChars`.

### `memory_store`

Persist text immediately by writing a session and committing with `wait=true`.

| Parameter | Required | Description |
|---|---|---|
| `text` | Yes | Information source text. |
| `role` | No | Session role, default `user`. |
| `sessionId` | No | Existing OpenViking/OpenClaw session reference. If omitted, a temporary `memory-store-*` session is created. |

### `memory_forget`

Delete a memory.

| Parameter | Required | Description |
|---|---|---|
| `uri` | No | Exact `viking://user/.../memories/...` memory URI. Non-memory URIs are refused. |
| `query` | No | Search query when `uri` is unknown. |
| `targetUri` | No | Search scope URI, default `targetUri`. |
| `limit` | No | Search limit, default `5`. |
| `scoreThreshold` | No | Search threshold, default `recallScoreThreshold`. |

If query mode finds multiple candidates, report candidates and ask the user to choose the exact URI; do not delete ambiguous memories.

### `ov_archive_search`

Keyword grep across archived original conversation messages of the current session.

| Parameter | Required | Description |
|---|---|---|
| `query` | Yes | Single keyword or short phrase; prefer names, dates, file paths, commands, or distinctive nouns. |
| `archiveId` | No | Restrict to one archive, e.g. `archive_002`. |

Try at least two concrete keyword variants before concluding archived detail is unavailable.

### `ov_archive_expand`

| Parameter | Required | Description |
|---|---|---|
| `archiveId` | Yes | Archive ID from `[Archive Index]`, e.g. `archive_002`. |

Use after an archive search or when the `[Archive Index]` already identifies the archive likely to contain exact detail.

### `add_resource`

Import resources into `viking://resources/...`.

This agent tool is disabled by default. Prefer manual `/add-resource` for resource ingestion. If `enableAddResourceTool=true` exposes the tool, use it only for explicit import/index requests and never as part of search/retrieval optimization.

| Parameter | Required | Description |
|---|---|---|
| `source` | Yes | Local path, OpenClaw media attachment path, directory path, public URL, or Git URL. |
| `to` | No | Exact target URI, e.g. `viking://resources/project-docs`. Mutually exclusive with `parent`. |
| `parent` | No | Parent URI under `viking://resources`. Mutually exclusive with `to`. |
| `reason` | No | Reason/note for import. |
| `instruction` | No | Processing instruction for semantic extraction. |
| `wait` | No | Wait for processing completion. |
| `timeout` | No | Timeout in seconds when `wait=true`. |

The current OpenClaw tool exposes the parameters above. The underlying client also supports server-facing resource options such as `strict`, `ignore_dirs`, `include`, `exclude`, and `preserve_structure` for command/internal paths; do not pass them to the tool unless the registered schema exposes them.

### `add_skill`

Import Agent Skills into `viking://user/skills/...`.

| Parameter | Required | Description |
|---|---|---|
| `source` | No | Local `SKILL.md` path or skill directory. Exactly one of `source` or `data` is required. |
| `data` | No | Raw `SKILL.md` content or an MCP tool dict. Exactly one of `source` or `data` is required. |
| `wait` | No | Wait for processing completion. |
| `timeout` | No | Timeout in seconds when `wait=true`. |

Agent Skill best practice: a skill should have precise frontmatter (`name`, trigger-oriented `description`, useful `tags`), clear scope boundaries, explicit “when not to use” guidance if needed, and executable steps with concrete parameters. Keep secrets out of skill content.

### `ov_search`

| Parameter | Required | Description |
|---|---|---|
| `query` | Yes | Search query. |
| `uri` | No | Search URI. Defaults to resources plus agent skills. |
| `limit` | No | Max results per scope, default `10`. |

Use after importing resources/skills, or when the user asks to search OpenViking-managed knowledge.

Important: `ov_search` returns OpenViking virtual URIs such as `viking://resources/project-docs/api.md#chunk-3`. These are not local file paths. Do not use filesystem read tools for them; call `ov_read` with the exact URI when full content is needed.

### `ov_read`

Read full content for one exact OpenViking virtual URI through `/api/v1/content/read`.

| Parameter | Required | Description |
|---|---|---|
| `uri` | Yes | Exact `viking://...` URI returned by `ov_search` or recall trace results. `openviking://...` aliases and local file paths are refused. |

### `ov_recall_trace`

| Parameter | Required | Description |
|---|---|---|
| `turn` | No | `latest` or `all`, default `latest`. |
| `traceId` | No | Exact trace ID. |
| `sessionId` / `sessionKey` / `ovSessionId` | No | Filter by OpenClaw/OpenViking session. |
| `source` | No | `auto_recall`, `memory_recall`, `ov_search`, or `ov_archive_search`. |
| `resourceTypes` | No | Array/string containing `resource`, `user`, `agent`. |
| `since` / `until` | No | Unix timestamp bounds in milliseconds. |
| `includeContent` | No | Read selected/displayed URI content previews on demand. |
| `limit` | No | Maximum traces to return, default `20`. |

Trace records exist only when `traceRecall=true`; persisted lookup requires `traceRecallPersist=true` and accessible trace files.

### Externalized tool-result tools

Use when a preview contains `viking://session/<session_id>/tool-results/<tool_result_id>`.

| Tool | Parameters |
|---|---|
| `openviking_tool_result_list` | `tool_name?`, `limit?` (default `50`) |
| `openviking_tool_result_search` | `tool_output_ref`, `query`, `limit?` (default `20`), `context_chars?` (default `300`) |
| `openviking_tool_result_read` | `tool_output_ref`, `offset?` (default `0`), `limit?` (default `20000`, `-1` accepted by server path for all remaining content) |

The plugin refuses to read/search a tool-result ref from another session.

## Slash Commands

```text
/add-resource ./README.md --to viking://resources/openviking-readme --wait
/add-skill ./skills/install-openviking-memory --wait --timeout=30
/ov-search "OpenViking install" --uri viking://resources/openviking-readme --limit=5
/ov-recall-trace --turn latest --source auto_recall --include-content
```

Command parsers support quoted args and flags. Resource-only flags are rejected for skill imports.

## Troubleshooting

| Symptom | Likely cause | First action |
|---|---|---|
| `configured=false` | Setup did not persist config | Re-run `openclaw openviking setup ... --json`; branch on JSON `error`. |
| `slotActive=false` | Another context engine owns the slot or gateway has stale state | Inspect `plugins.slots.contextEngine`; use `--force-slot` only after user confirms. |
| `health.ok=false` | Server unreachable or wrong `baseUrl` / key | Check `baseUrl`, network, `/health`, and auth. |
| No long-term memory after a fresh fact | `/compact` or commit/extraction has not run, or server extraction failed | Use `memory_store` for explicit remember/save/store intents; otherwise run `/compact` or wait for threshold commit, then check OpenViking server logs. |
| Recall misses shared documents | `resource` target is not enabled | Use `memory_recall` with `resourceTypes:["resource"]` or configure `recallTargetTypes: ["resource"]`. |
| Summary lacks exact detail | Archive summary is too coarse | Use `ov_archive_search` with concrete keywords, then `ov_archive_expand`. |
| Large tool output preview is insufficient | Tool result was externalized | Use `openviking_tool_result_search/read` with the ref. |
| Need to explain recall behavior | Trace disabled or no trace for that turn | Enable `traceRecall`; optionally `traceRecallPersist`; query `ov_recall_trace`. |

## Reference Docs in This Repo

- `README.md` / `README_CN.md`: feature overview and quick start.
- `INSTALL.md` / `INSTALL-ZH.md`: install, upgrade, uninstall, and JSON setup handling.
- `INSTALL-AGENT.md`: agent-oriented installation workflow.
- `docs/openviking-openclaw-plugin-guide.md`: comprehensive Chinese operator/developer guide.