Skip to content
Skills Library
AI & agents · Tool integration

openviking-context-database

/openviking-context-database

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.

Repository
OpenViking ↗
Licence
AGPL-3.0
Last repository change
26.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
1
Deprecation

No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.

Licence

AGPL-3.0, copyleft: przeróbki udostępniane innym muszą mieć tę samą licencję.

What it does and when to use it

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.

Original author 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.

How it works

  1. Scope and Safety Rules
  2. Current Architecture
  3. Configuration Quick Reference
  4. Tool Selection Guide
  5. Tool Interface Reference
  6. Slash Commands
  7. Troubleshooting
  8. Reference Docs in This Repo
Original SKILL.md headings · 263 lines, 2,157 words
SKILL.md preview
---
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` | `none` | Memory scope: `none` (shared `viking://user/<user_id>/memories`), `assistant` (assistant-attributed memory under `.../peers/<assistant_id>/memories`), or `sender` (sender-attributed memory under `.../peers/<sender_id>/memories`). Legacy `person` is accepted as `sender`. |
| `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://~/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-role assistant --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. |

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://~/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. |

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
/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.

Versions

The database has no other skills named openviking-context-database.

Database snapshot: 13.11.2026 · package version dcb36b0631dd (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 95install-openviking-memory
    Install and configure the OpenViking long-term memory plugin for OpenClaw via natural conversation. Once installed, the plugin automatically captures facts from chats and recalls relevant context before each reply (auto-capture + auto-recall, cross-session). Covers…
  • 100openviking
    OpenViking is an open-source context database for AI agents: one virtual file system under viking:// that holds an agent's knowledge, memories and skills, with generated summaries and semantic search. Use when the user wants persistent agent memory across sessions, wants to…
  • 100novel-openviking
    翰林院 OpenViking 记忆增强 — 将小说写作 pipeline 的设定、摘要、伏笔接入 OpenViking 语义记忆。若你从属于翰林院,当你看到这个skill时,务必加载这个skill。
  • 100openviking-memory
    Recall and persist long-term memory through the OpenViking MCP tools. Use at the start of any substantive task (coding, configuration, debugging, multi-step or tool-based work) to retrieve relevant prior knowledge with find/search/read, and during or after work to persist…
  • 100huawei-cloud-openviking-agent-integration
    Integrate and unbind OpenViking long-term memory with coding agents. Supports 8 agents (CodeArts CLI, OpenCode, OpenClaw, Hermes, WorkSwarm, KimiCode, DeepSeek Harness, Prime Agent) via their native mechanism — MCP, HTTP memory provider, TypeScript extension hooks, or…
  • 90mem9
    Persistent cloud memory for OpenClaw agents. Use when users say: - "install mem9" - "setup memory" - "add memory plugin" - "openclaw memory" - "mem9 onboarding" - "memory not working" - "import memories" - "upload sessions

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.