Ov Resources

OpenViking (OV) Resource Management

The ov command group for resources covers adding external knowledge, filesystem operations, scheduled refresh (watch tasks), and ovpack import/export/backup/restore.

Goal

Guide an agent to correctly invoke resource and filesystem commands without guessing flags, URI semantics, or processing behavior.

Load When

• User explicitly requests resource operations: ov add-resource, ov task watch, ov export, ov import, ov backup, ov restore.
• User asks to browse, read, write, create, move, or delete files under viking://resources/.
• User asks to search for context: ov find, ov search, ov grep, ov glob.
• User asks to create or manage relations between resources (ov link, ov relations, ov unlink).
• Agent needs to list, inspect, or search the resource tree to find context.

Inputs

Workflow

1. Identify the user's intent and map to the correct ov <subcommand>. 2. Resolve the target (local path, URL, or Viking URI). 3. Construct the command with appropriate flags. 4. Execute and report results.

Permissions

• ov add-resource from external URLs may download untrusted content; verify the source when the user provides an untrusted URL.
• ov rm --recursive is destructive; confirm with the user before executing on large directories.
• ov export, ov import, ov backup, ov restore require ROOT or ADMIN permissions.
• ov write replaces file content in-place; the old version is not retained.

Output

• CLI output returned directly to the user.
• Errors surfaced with suggested fixes and relevant flag guidance.

Verification

• After add-resource, ov ls or ov tree should show the new resource under the expected URI.
• After rm, ov ls should no longer list the removed path.
• After write, ov read should reflect the new content.
• After ov import or ov restore, ov tree should show the imported structure.

Boundaries

• Do not invent paths or URLs. Use what the user provides.
• Do not execute ov rm --recursive on broad paths like viking://resources/ without explicit user confirmation.
• Do not treat ov add-skill or ov skills as equivalent to resource commands; skill management is handled by ov-skills.
• Do not treat ov add-memory as a resource command; memory management is out of scope for this skill.

Runtime Resources

• docs/add-resource.md — detailed resource ingestion docs, source types, and async processing.
• docs/filesystem.md — filesystem operations reference (ls, tree, read, write, mkdir, rm, mv, grep, glob, link, relations, unlink).
• docs/search.md — semantic search (ov find, ov search) and search combination strategies.
• docs/watch-management.md — watch task lifecycle (create, pause, resume, trigger, update, remove).
• docs/ovpack.md — ovpack export/import/backup/restore reference.
• examples/commands.md — common command patterns by scenario.

Resource Ingestion (ov add-resource)

The ov add-resource command imports external resources into OpenViking's context database. By default it writes shared account resources under viking://resources/, and it can also target current-user or peer-scoped resource roots.

Supported Sources

Basic Usage

# From URL
ov add-resource https://github.com/volcengine/OpenViking
ov add-resource https://arxiv.org/pdf/2602.09540

# From local file
ov add-resource ./docs/api-spec.md
ov add-resource ./team_building.jpg
ov add-resource /User/volcengine/Documents/project.docx

# From local directory
ov add-resource /User/volcengine/Photo/Travels/2026/ --include "*.jpg,*.jpeg,*.png"

# From ZIP
ov add-resource ./docs-of-project.zip

Target Location

By default resources go under shared viking://resources/. Use --to or --parent to override:

# Exact target (must not exist)
ov add-resource ./docs --to "viking://resources/2026/2026-01-01/"

# Place under existing parent directory
ov add-resource ./docs --parent "viking://resources/docs/"

# Place under the current user's private resource root
ov add-resource ./docs --parent "viking://user/resources/docs/"

# Place under a specific peer's private resource root
ov add-resource ./docs --parent "viking://user/alice/peers/web-visitor-alice/resources/docs/"

# Auto-create parent if missing
ov add-resource ./docs --parent-auto-create "viking://resources/docs/2026/05/07"
ov add-resource ./docs -p "viking://resources/docs/{calendar:today}"

viking://user/resources/... is current-user shorthand and resolves to viking://user/{user_id}/resources/.... peer_id path segments must be safe single-segment identifiers such as web-visitor-alice; values with :, +, ., .., or path separators are rejected.

Async Processing Control

Semantic processing runs asynchronously. Use --wait to block until complete:

# Wait for completion
ov add-resource ./docs --wait

# Wait with timeout
ov add-resource ./docs --wait --timeout 60

# Fire and forget (default)
ov add-resource ./docs

When wait=false, the CLI returns after upload/parse/finalize (non-Git sources) or after preflight (Git sources). Use the returned task_id with GET /api/v1/tasks/{task_id} or ov observer queue to track progress.

Scheduled Refresh (--watch-interval)

Create a watch task to re-import periodically:

# Refresh every 60 minutes, bound to a fixed URI
ov add-resource https://github.com/volcengine/OpenViking \
  --to "viking://resources/repos/OpenViking" \
  --watch-interval 60

# Refresh every 30 minutes, bound to imported root_uri
ov add-resource https://example.com/spec.md --watch-interval 30

# Cancel watch for the same target
ov add-resource https://github.com/volcengine/OpenViking \
  --to "viking://resources/repos/OpenViking" \
  --watch-interval 0

--watch-interval is in minutes. > 0 creates/updates; <= 0 cancels. Prefer --to for stable long-term watches.

Filtering Options

# Include only matching files
ov add-resource ./project --include "*.py,*.md"

# Exclude patterns
ov add-resource ./project --exclude "*.tmp,*.log"

# Ignore specific directory names
ov add-resource ./project --ignore-dirs "node_modules,target,.git"

# Preserve directory structure
ov add-resource ./project --preserve-structure

For local directories, scanning respects .gitignore with standard Git semantics; ignore_dirs, include, and exclude further refine ingestion.

CLI Output

Default table format:

Note: Resource is being processed in the background.
Use 'ov wait' to wait for completion, or 'ov observer queue' to check status.
status       success
root_uri     viking://resources/01-overview
task_id      uuid-xxx

JSON format (-o json):

{
  "status": "success",
  "root_uri": "viking://resources/01-overview",
  "task_id": "uuid-xxx"
}

With --wait, the response includes queue_status with pending, processing, completed counts.

Key Parameters

Important Notes

• path and temp_file_id are mutually exclusive.
• to and parent are mutually exclusive.
• When to points to an existing resource, the call triggers an incremental update.
• For Git repos with wait=false, OpenViking validates the repo, resolves the target URI, reserves root_uri, and returns immediately; clone/parse/finalize continues in background.
• To create or update plain text directly, use ov write instead of add_resource.

Filesystem Operations

OpenViking provides Unix-like filesystem operations for the viking://resources/ namespace.

Read Operations

ov read — Read L2 full content

ov read viking://resources/docs/api.md

Accepts file URIs only. Passing a directory returns INVALID_ARGUMENT (400) with structured details.expected="file", details.actual="directory" so clients can fall back to ov ls.

Parameters: uri (required), offset (line number, 0-indexed), limit (lines, -1 for all).

ov abstract — Read L0 abstract (~100 tokens)

ov abstract viking://resources/docs/

Directories only.

ov overview — Read L1 overview

ov overview viking://resources/docs/

Directories only.

ov ls — List directory contents

# Basic listing
ov ls viking://resources/

# Simple paths only
ov ls viking://resources/ --simple

# Recursive
ov ls viking://resources/ --recursive

Parameters: uri (required), --simple, --recursive, --show-all-hidden, --node-limit.

Entry fields: name, size, mode, modTime, isDir, uri, meta.

ov tree — Directory tree structure

ov tree viking://resources/my-project/

Parameters: uri (required), --show-all-hidden, --node-limit, --level-limit.

ov stat — File/directory status

ov stat viking://resources/docs/api.md
ov stat viking://resources/docs

For directories, returns count (estimated item count). isLocked reports whether a path lock or ancestor TreeLock is held.

Write Operations

ov write — Update or create a file

ov write viking://resources/docs/api.md \
  --content "# Updated API\n\nFresh content." \
  --wait

Modes:

• replace (default): overwrite existing file
• append: append to existing file
• create: create new file (fails if exists, accepts .md, .txt, .json, .yaml, .yml, .toml, .py, .js, .ts)

--wait blocks until semantic/vector refresh completes. Parent directories are auto-created for create.

Derived semantic files cannot be written directly: .abstract.md, .overview.md, .relations.json.

ov mkdir — Create a directory

ov mkdir viking://resources/new-project/
ov mkdir viking://resources/new-project/ --description "API docs directory"

--description writes to .abstract.md and queues for L0 vectorization.

Modify Operations

ov rm — Remove file or directory

# Remove single file
ov rm viking://resources/docs/old.md

# Remove directory recursively
ov rm viking://resources/old-project/ --recursive

rm is idempotent: removing a non-existent valid URI succeeds. Invalid URI formats return INVALID_URI. Recursive delete returns estimated_deleted_count.

ov mv — Move file or directory

ov mv viking://resources/old-name/ viking://resources/new-name/

Search Operations

ov grep — Search by regex pattern

ov grep viking://resources/ "authentication" --ignore-case

Parameters: uri, pattern (required), --ignore-case, --exclude-uri, --node-limit, --level-limit.

Response: matches with uri, line, content.

ov glob — Match files by glob pattern

ov glob "**/*.md" --uri viking://resources/
ov glob "**/*.py" --uri viking://resources/

Parameters: pattern (required), --uri, --node-limit.

Relation Operations

ov link — Create relations

# Single link
ov link viking://resources/docs/auth/ viking://resources/docs/security/ \
  --reason "Security best practices"

# Multiple links (via API/SDK)

ov relations — List relations

ov relations viking://resources/docs/auth/

ov unlink — Remove a relation

ov unlink viking://resources/docs/auth/ viking://resources/docs/security/

WebDAV

OpenViking exposes a minimal WebDAV adapter at /webdav/resources:

• Resources only (memories, skills, sessions not exposed)
• PUT accepts UTF-8 text only
• Supported methods: OPTIONS, PROPFIND, GET, HEAD, PUT, DELETE, MKCOL, MOVE
• Semantic sidecars and internal files are hidden
• PUT does not auto-create parent collections; use MKCOL first
• Creating or replacing a file triggers semantic generation

OVPack Import/Export/Backup/Restore

OVPack is a .ovpack archive format for backing up and migrating OpenViking resource trees. Requires ROOT or ADMIN permissions.

Export (ov export)

Packages resources under a URI into a .ovpack file.

# Export a resource tree
ov export viking://resources/my-project/ ./exports/my-project.ovpack

# Include dense vector snapshot
ov export viking://resources/my-project/ ./exports/my-project.ovpack --include-vectors

The ZIP stores user content under <root>/files/ and metadata under <root>/_ovpack/:

• manifest.json — entry list with path, size, sha256, content_sha256
• index_records.jsonl — portable index scalar fields
• dense.f32 — pure-dense float32 vector snapshot (when --include-vectors)

Hybrid index types reject vector snapshot export.

Import (ov import)

Restores a .ovpack file to a target location.

# Basic import
ov import ./exports/my-project.ovpack viking://resources/imported/

# Explicit conflict policy
ov import ./exports/my-project.ovpack viking://resources/imported/ --on-conflict overwrite

# Require compatible dense vector snapshot
ov import ./exports/my-project.ovpack viking://resources/imported/ --vector-mode require

Conflict policies: fail (default), overwrite, skip. Vector modes: auto (default), recompute, require.

Backup (ov backup)

Backs up all public scope roots (resources, user, agent, session) as a restore-only .ovpack.

ov backup ./backups/openviking.ovpack
ov backup ./backups/openviking.ovpack --include-vectors

Restore (ov restore)

Restores a backup package created by ov backup to the original public scope roots.

ov restore ./backups/openviking.ovpack --on-conflict overwrite
ov restore ./backups/openviking.ovpack --on-conflict overwrite --vector-mode require

Regular import rejects backup packages. Session files are restored without vectorization.

Important Notes

• Packages without a manifest are rejected.
• Content integrity is validated (file sizes, sha256, content_sha256).
• Runtime fields (id, uri, account_id, created_at, updated_at) are regenerated on import.
• Top-level scope packages (e.g. viking://resources/) must be imported to viking://.

Semantic Search (ov find / ov search)

OpenViking provides two semantic search commands for retrieving context from resources, memories, and skills.

ov find — Pure Vector Similarity Search

Performs hierarchical vector similarity search without session context. Best for simple, direct queries.

# Basic search across all context
ov find "how to handle API rate limits"

# Search within specific URI scope
ov find "authentication flow" --uri "viking://resources/my-project"

# Limit results and set relevance threshold
ov find "error handling" --node-limit 5 --threshold 0.3

# Time-filtered search
ov find "invoice" --after 7d --time-field created_at

# Level-filtered search (L0 only)
ov find "overview" --level 0

# Multiple levels
ov find "details" -L 1,2

ov search — Context-Aware Search with Intent Analysis

Adds session context understanding and intent analysis on top of find(). Better for conversational queries.

# Search with session context
ov search "best practices" --session-id abc123

# Search with time filter
ov search "watch vs scheduled" --after 2026-03-15 --before 2026-03-20

# Search without session (still performs intent analysis)
ov search "how to implement OAuth 2.0 authorization code flow"

# Level-filtered
ov search "best practices" --level 0
ov search "how to implement OAuth" -L 1,2

Find vs Search

Common Parameters

Search Result Structure

Results are grouped by context_type:

{
  "memories": [],
  "resources": [
    {
      "uri": "viking://resources/docs/auth.md",
      "context_type": "resource",
      "level": 2,
      "score": 0.95,
      "abstract": "OAuth 2.0 best practices...",
      "overview": "This guide covers...",
      "match_reason": "Context-aware match: OAuth login best practices",
      "relations": []
    }
  ],
  "skills": [],
  "total": 1,
  "query_plan": {
    "reasoning": "User is asking about OAuth implementation...",
    "queries": [...]
  }
}

query_plan is only present in search results.

URI Scope Targets

# Search only resources
ov find "authentication" --uri "viking://resources"

# Search only memories
ov find "preferences" --uri "viking://user/memories"

# Search only skills
ov find "web search" --uri "viking://user/skills"

# Search specific project
ov find "API endpoints" --uri "viking://resources/my-project"

Combining Search with Browse

# Step 1: Semantic search to find relevant directories
ov find "authentication" --uri "viking://resources/project-A"

# Step 2: Get overview for context
ov overview viking://resources/project-A/backend

# Step 3: Read specific content
ov read viking://resources/project-A/backend/auth.md

Watch Task Management (ov task watch)

Watch tasks enable scheduled refresh of resources imported via ov add-resource --watch-interval. The control plane is available via ov task watch CLI subcommands.

Core Concepts

• Creation: Set watch_interval > 0 on ov add-resource to create or update a watch task.
• Binding: Tasks bind to --to if provided; otherwise to the imported root_uri.
• Scheduling: WatchScheduler checks expired tasks every 60 seconds.
• Pause/Resume: is_active is orthogonal to watch_interval; pause without losing cadence.

Subcommands

ov task watch ls — List watch tasks

# List active watches only
ov task watch ls --active-only

# List all (including paused)
ov task watch ls

ov task watch show — Inspect a single watch

ov task watch show viking://resources/guide.md
ov task watch show <task_id>

The key argument is auto-classified: viking:// URIs route by URI, anything else is treated as a task ID.

ov task watch pause — Pause without losing cadence

ov task watch pause viking://resources/guide.md

Sets is_active=false. The watch_interval is preserved.

ov task watch resume — Resume a paused watch

ov task watch resume viking://resources/guide.md

Sets is_active=true.

ov task watch update — Update watch parameters

# Update interval
ov task watch update viking://resources/guide.md --interval 30

# Update reason and instruction
ov task watch update viking://resources/guide.md \
  --reason "Updated docs" \
  --instruction "Focus on API changes"

Supported update fields: --interval, --active / --no-active, --reason, --instruction.

ov task watch trigger — Immediate refresh

ov task watch trigger viking://resources/guide.md

Fire-and-forget; returns immediately while re-ingest runs in background.

ov task watch rm — Remove a watch task

ov task watch rm viking://resources/guide.md

Lifecycle Summary

key can be either a viking:// URI or a task ID.

Common Resource Management Command Patterns

Adding Resources

# Local file
ov add-resource ./docs/api.md

# Local directory with filters
ov add-resource ./project --include "*.py,*.md" --ignore-dirs "node_modules"

# URL
ov add-resource https://example.com/guide.md

# Git repository with watch
ov add-resource https://github.com/volcengine/OpenViking \
  --to "viking://resources/repos/OpenViking" \
  --watch-interval 60

# To specific location with wait
ov add-resource ./docs --to "viking://resources/docs/" --wait

# Auto-create parent path
ov add-resource ./guide.md -p "viking://resources/docs/{calendar:today}"

Browsing Resources

# List top-level resources
ov ls viking://resources/

# Recursive listing
ov ls viking://resources/my-project/ --recursive

# Tree view (limited depth)
ov tree viking://resources/my-project/ --level-limit 3

# Simple path list
ov ls viking://resources/ --simple

# File stats
ov stat viking://resources/docs/api.md

Reading Content

# Full content
ov read viking://resources/docs/api.md

# With line range
ov read viking://resources/docs/api.md --offset 10 --limit 20

# Abstract (directory)
ov abstract viking://resources/docs/

# Overview (directory)
ov overview viking://resources/docs/

Writing Content

# Replace existing file
ov write viking://resources/docs/api.md \
  --content "# Updated\n\nNew content." \
  --wait

# Create new file
ov write viking://resources/docs/new.md \
  --content "# New doc" \
  --mode create

# Append to existing
ov write viking://resources/docs/notes.md \
  --content "\nNew line." \
  --mode append

Directory Management

# Create directory
ov mkdir viking://resources/new-project/

# Create with description
ov mkdir viking://resources/new-project/ --description "Project docs"

# Move
ov mv viking://resources/old-name/ viking://resources/new-name/

# Remove file
ov rm viking://resources/docs/old.md

# Remove directory recursively
ov rm viking://resources/old-project/ --recursive

Searching Resources

# Grep content
ov grep viking://resources/ "TODO" --ignore-case

# Glob files
ov glob "**/*.md" --uri viking://resources/
ov glob "**/*.py" --uri viking://resources/

Watch Task Management

# List active watches
ov task watch ls --active-only

# Inspect a watch
ov task watch show viking://resources/guide.md

# Pause / resume
ov task watch pause viking://resources/guide.md
ov task watch resume viking://resources/guide.md

# Update interval
ov task watch update viking://resources/guide.md --interval 30

# Trigger immediate refresh
ov task watch trigger viking://resources/guide.md

# Remove watch
ov task watch rm viking://resources/guide.md

# Cancel via add-resource
ov add-resource https://example.com/guide.md \
  --to "viking://resources/guide.md" \
  --watch-interval 0

OVPack Operations

# Export
ov export viking://resources/my-project/ ./backups/my-project.ovpack

# Import
ov import ./backups/my-project.ovpack viking://resources/imported/

# Backup all public scopes
ov backup ./backups/openviking.ovpack

# Restore from backup
ov restore ./backups/openviking.ovpack --on-conflict overwrite

Searching Resources

# Semantic find across all context
ov find "how to handle API rate limits"

# Find within specific scope
ov find "authentication flow" --uri "viking://resources/my-project"

# Find with time filter
ov find "invoice" --after 7d --time-field created_at

# Find L0 abstracts only
ov find "overview" --level 0

# Context-aware search
ov search "best practices" --session-id abc123

# Search with intent analysis
ov search "how to implement OAuth 2.0"

# Combined: search then read
ov find "authentication" --uri "viking://resources/project-A"
ov overview viking://resources/project-A/backend
ov read viking://resources/project-A/backend/auth.md

Relations

# Link resources
ov link viking://resources/docs/auth/ viking://resources/docs/security/ \
  --reason "Security best practices"

# List relations
ov relations viking://resources/docs/auth/

# Unlink
ov unlink viking://resources/docs/auth/ viking://resources/docs/security/