ContextQMD
Back to Openviking

Semantic Search (`ov find` / `ov search`)

examples/skills/ov-resources/docs/search.md

0.4.13.4 KB
Original Source

Semantic Search (ov find / ov search)

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

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

bash
# 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.

bash
# 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
Aspectfindsearch
Intent AnalysisNoYes
Session ContextNoYes
Query ExpansionNoYes
Default Limit1010
Use CaseSimple queriesConversational search

Common Parameters

ParameterDescription
--uriLimit search to specific URI prefix
--node-limit / --limitMaximum number of results
--threshold / --score-thresholdMinimum relevance score (0-1)
--afterLower time bound (2h, 7d, ISO 8601)
--beforeUpper time bound (30m, ISO 8601)
--time-fieldupdated_at (default) or created_at
--level / -LLimit to levels: 0, 1, 2, 0,1,2
--peer-idStable interaction peer ID
--session-idSession ID for context-aware search (search only)

Search Result Structure

Results are grouped by context_type:

json
{
  "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

bash
# 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

bash
# 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