find()

Fast semantic search without session context for quick lookups

Overview

The find() method performs fast semantic search using vector similarity. It’s optimized for simple queries where you don’t need session context or intent analysis.

Key Differences from search():

• No Intent Analysis: Direct vector similarity search
• No Session Context: Stateless, doesn’t use conversation history
• Faster: Lower latency due to simpler pipeline
• Simple Queries: Best for straightforward lookup tasks

Basic Usage

Python SDK

from openviking import OpenViking

client = OpenViking()

# Simple semantic search
results = client.find("how to authenticate users")

for ctx in results.resources:
    print(f"URI: {ctx.uri}")
    print(f"Score: {ctx.score:.3f}")
    print(f"Type: {ctx.context_type}")
    print(f"Abstract: {ctx.abstract[:100]}...")
    print("---")

Parameters

query · string · required

Search query string. Use natural language or specific keywords.

target_uri · string · default: ""

Limit search to specific Viking URI prefix. Examples:

• viking://resources/ - Search only resources
• viking://user/memories/ - Search user memories
• viking://skills/ - Search available skills
• viking://resources/my-project/ - Search specific project

limit · integer · default: "10"

Maximum number of results to return.

score_threshold · float · default: "None"

Minimum relevance score (0-1). Filters out low-quality matches.

filter · Dict[str, Any] · default: "None"

Additional metadata filters for constraining results.

Response Structure

Returns a FindResult object:

memories · List[MatchedContext]

Matched memory contexts.

resources · List[MatchedContext]

Matched resource contexts.

skills · List[MatchedContext]

Matched skill contexts.

total · integer

Total number of matches.

MatchedContext Structure

uri · string

Viking URI of the matched context. May include level suffix:

• .abstract.md - L0 directory abstract
• .overview.md - L1 directory overview
• No suffix - L2 file content

context_type · ContextType

Type: memory, resource, or skill.

level · integer

Context layer:

• 0: L0 (abstract)
• 1: L1 (overview)
• 2: L2 (content)

abstract · string

L0 abstract - concise summary.

score · float

Relevance score (0-1). Combines semantic similarity with hotness.

category · string

Context category or classification.

relations · List[RelatedContext]

Related contexts with URIs and abstracts.

Examples

Basic Search

from openviking import OpenViking

client = OpenViking()

# Find authentication documentation
results = client.find("authentication")

for ctx in results.resources:
    print(f"{ctx.uri} - {ctx.score:.3f}")

Search with Target URI

# Search only in resources
results = client.find(
    "authentication",
    target_uri="viking://resources/"
)

# Search only in user memories
results = client.find(
    "preferences",
    target_uri="viking://user/memories/"
)

# Search only in skills
results = client.find(
    "web search",
    target_uri="viking://skills/"
)

# Search in specific project
results = client.find(
    "API endpoints",
    target_uri="viking://resources/my-project/"
)

Search with Score Threshold

# Only return high-confidence matches
results = client.find(
    "OAuth 2.0 implementation",
    score_threshold=0.7,
    limit=5
)

print(f"Found {results.total} high-quality matches")
for ctx in results.resources:
    print(f"  {ctx.uri} (score: {ctx.score:.3f})")

Progressive Content Loading

results = client.find("authentication")

for ctx in results.resources:
    # Start with L0 (abstract) - already in ctx.abstract
    print(f"Abstract: {ctx.abstract}")
    
    if ctx.level == 0:  # Directory
        # Get L1 (overview)
        overview = client.overview(ctx.uri.rstrip('.abstract.md') + '/')
        print(f"Overview: {overview[:500]}...")
    elif ctx.level == 2:  # File
        # Load L2 (full content)
        content = client.read(ctx.uri)
        print(f"Content: {content[:500]}...")

HTTP API Example

curl -X POST http://localhost:1933/api/v1/search/find \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "query": "OAuth authentication",
    "target_uri": "viking://resources/",
    "limit": 5,
    "score_threshold": 0.6
  }'

Response:

{
  "status": "ok",
  "result": {
    "memories": [],
    "resources": [
      {
        "uri": "viking://resources/docs/auth/.abstract.md",
        "context_type": "resource",
        "level": 0,
        "abstract": "Authentication guide covering OAuth 2.0, JWT tokens, and session management.",
        "score": 0.92,
        "category": "documentation",
        "relations": [
          {
            "uri": "viking://resources/examples/oauth/",
            "abstract": "OAuth 2.0 implementation examples"
          }
        ]
      },
      {
        "uri": "viking://resources/docs/auth/oauth.md",
        "context_type": "resource",
        "level": 2,
        "abstract": "Detailed OAuth 2.0 authorization code flow implementation guide.",
        "score": 0.88,
        "category": "documentation",
        "relations": []
      }
    ],
    "skills": [],
    "total": 2
  },
  "time": 0.08
}

Retrieval Strategy

Hierarchical Directory-Recursive Search

OpenViking uses a unique hierarchical retrieval strategy:

1. Global Starting Points

   • Performs global vector search to identify relevant directories
   • Uses context_type to determine root namespaces (resources, memories, skills)
   • Merges global results with explicit target_uri directories

2. Recursive Directory Exploration

   • Starts from identified directories
   • Searches children at each level using vector similarity
   • Propagates scores from parent to child (weighted by SCORE_PROPAGATION_ALPHA = 0.5)
   • Recurses into directories (L0/L1), treats files (L2) as terminal

3. Score Calculation

   final_score = (1 - alpha) * semantic_score + alpha * hotness_score
   
   where:
   - semantic_score: Vector similarity (with parent propagation)
   - hotness_score: Based on active_count + recency (updated_at)
   - alpha = 0.2 (HOTNESS_ALPHA)
   

4. Convergence

   • Tracks top-k results across rounds
   • Stops when top-k stabilizes for 3 consecutive rounds
   • Deduplicates by URI (keeps highest score)

Vector Search Types

• Dense Vectors: Semantic embeddings for meaning-based search
• Sparse Vectors: Keyword-based sparse embeddings (if available)
• Hybrid: Combines dense + sparse for best results

Context Layers

Results can come from any layer:

• L0 (Abstract): Directory summaries - quick overviews
• L1 (Overview): Directory content summaries
• L2 (Content): Full file content - detailed information

When to Use find() vs search()

Scenario	Best Method
Quick lookup	find()
No conversation context	find()
Need speed	find()
Conversational search	search()
Multi-turn dialogue	search()
Complex intent	search()

Working with Results

Iterating Over All Results

results = client.find("authentication")

# FindResult is iterable
for ctx in results:
    print(f"{ctx.context_type}: {ctx.uri}")

# Or iterate by type
for ctx in results.resources:
    print(f"Resource: {ctx.uri}")
for ctx in results.memories:
    print(f"Memory: {ctx.uri}")

Accessing Related Contexts

results = client.find("OAuth implementation")

for ctx in results.resources:
    print(f"Found: {ctx.uri}")
    
    # Check related contexts
    if ctx.relations:
        print("  Related:")
        for rel in ctx.relations:
            print(f"    - {rel.uri}")
            print(f"      {rel.abstract[:80]}...")

Understanding Scores

results = client.find("authentication", score_threshold=0.5)

# Scores combine semantic similarity + hotness
for ctx in results.resources:
    print(f"URI: {ctx.uri}")
    print(f"Score: {ctx.score:.3f}")
    print(f"Level: L{ctx.level}")
    
    if ctx.score > 0.9:
        print("  -> Highly relevant")
    elif ctx.score > 0.7:
        print("  -> Good match")
    else:
        print("  -> Moderate match")

Best Practices

1. Use Specific Queries: More specific queries yield better results

   # Good - specific
   results = client.find("OAuth 2.0 authorization code flow implementation")
   
   # Less effective - too broad
   results = client.find("auth")
   

2. Scope Your Search: Use target_uri to search in relevant namespaces

   results = client.find(
       "error handling",
       target_uri="viking://resources/backend/"
   )
   

3. Filter by Score: Set thresholds to get quality matches

   results = client.find(
       "API design patterns",
       score_threshold=0.6
   )
   

4. Progressive Loading: Start with abstracts, load more as needed

   results = client.find("authentication")
   
   # Examine abstracts first
   for ctx in results.resources[:3]:
       print(ctx.abstract)
       
   # Load full content only if needed
   if results.resources:
       best_match = results.resources[0]
       if best_match.level == 2:  # It's a file
           full_content = client.read(best_match.uri)
   

5. Leverage Relations: Follow related contexts for comprehensive information

   results = client.find("OAuth setup")
   
   for ctx in results.resources:
       # Check related resources
       for rel in ctx.relations:
           related_content = client.abstract(rel.uri)
           print(f"Related: {related_content}")
   

Performance

• Latency: ~50-100ms for typical queries
• Scalability: Handles millions of contexts efficiently
• Caching: Embeddings are cached for repeated queries
• Convergence: Usually converges in 2-3 directory levels

Related Methods

• search() - Context-aware search with session support
• abstract() - Read L0 abstracts
• overview() - Read L1 overviews
• read() - Read L2 full content