Table of Content

When to Use
Search Modes
- Context-Aware Search (ov search)
- Content Pattern Search (ov grep)
- File Glob Search (ov glob)
Search Options
- Result Control
- Scope Control
- Session-Aware Search
Output
Other Utilities
- List Contents (ov ls)
- Tree View (ov tree)
- Read File Content (ov read)
Agent Best Practices
- Choosing Search Methods
- Query Formulation
- Combining with Other Commands
Prerequisite

When to Use

Finding specific information within imported resources or saved memories
Retrieving context about topics, APIs, or patterns previously added
Searching across project documentation, code, and learnings
When an agent needs to reference previously stored knowledge

note: cli command can be outdated, when sees error, use --help to get latest usage

Search Modes

Context-Aware Search (`ov search`)

Primary search method with session context awareness:

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

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

# Limit results and set threshold
ov search "error handling" --limit 5 --threshold 0.7

Content Pattern Search (`ov grep`)

Literal pattern matching:

# Search for exact text pattern
ov grep "viking://resources" "TODO:"

# Case-insensitive search
ov grep "viking://resources" "API_KEY" --ignore-case

File Glob Search (`ov glob`)

File path pattern matching:

# Find all markdown files
ov glob "**/*.md"

# Find Python files in specific directory
ov glob --uri="viking://user/" "**/*.md"

Search Options

Result Control

# Limit number of results
ov search "authentication" --limit 5

# Set minimum relevance threshold (0.0-1.0)
ov search "deployment" --threshold 0.8

# Combine limit and threshold
ov search "monitoring" --limit 10 --threshold 0.7

Scope Control

# Search specific directory
ov search "API design" --uri "viking://resources/xxx"

# Search within memories
ov search "user habits" --uri "viking://user/memories"

Session-Aware Search

# Search with session context (uses conversation history for better retrieval)
ov search "previous decision" --session-id "session-abc123"

Output

Returns a ranked list of matching resources with relevance scores:

URI: viking://resources/docs/api.md
Score: 0.8523
Abstract: API endpoints for user authentication...

URI: viking://user/memories/preferences
Score: 0.7891
Abstract: User prefers dark mode and compact layout...

Other Utilities

List Contents (`ov ls`)

Browse directory structure:

# List root directory
ov ls

# List specific directory
ov ls viking://resources/my-project

# Simple path output (for scripts)
ov ls viking://resources --simple

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

# Show hidden files
ov ls viking://resources --all

# Control output limits
ov ls viking://resources --node-limit 50 --abs-limit 128

Tree View (`ov tree`)

Visualize directory hierarchy:

# Show tree structure
ov tree viking://resources

# Control depth and limits
ov tree viking://resources --node-limit 100 --abs-limit 128

# Show all files including hidden
ov tree viking://resources --all

Read File Content (`ov read`)

Retrieve full content (L2 layer):

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

# Read abstract (L0 - quick summary)
ov abstract viking://resources/docs/api.md

# Read overview (L1 - key points)
ov overview viking://resources/docs/api.md

Agent Best Practices

Choosing Search Methods

ov search — Default choice. Context-aware, combines semantic + directory recursive retrieval
ov grep — Exact text pattern matching (like grep command)
ov glob — File path pattern matching (like shell glob)

Query Formulation

Write specific, contextual queries:

# Too vague
ov search "API"

# Better
ov search "REST API authentication with JWT tokens"

# Even better with scope
ov search "JWT token refresh flow" --uri "viking://resources/backend"

Combining with Other Commands

Use search results to guide further actions:

ov ls viking://resources/

# Search for relevant files
ov search "authentication" --uri "viking://resources/xxx"

# Then read specific content
ov read viking://resources/backend/auth.md

# Or get overview for context
ov overview viking://resources/backend

Prerequisites

CLI configured: ~/.openviking/ovcli.conf
Resources or memories previously added to OpenViking

searching-context

OpenViking (OV) context searching