searching-context

OpenViking (OV) context searching

The ov search command performs context-aware retrieval across all memories and resources in OpenViking — combining semantic understanding with directory recursive retrieval to find the most relevant context for any query.

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