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:

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:

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

Useful variants:

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

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