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.
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.
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 (). Do not use during search, retrieval, URI reading, or search-result optimization. Use and in those flows.
enableAddResourceTool=false
add_resource
ov_search
ov_read
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.
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:
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.
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>.
