find()

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

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.

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:

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

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)

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}")

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

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")

Scope Your Search: Use target_uri to search in relevant namespaces

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

Filter by Score: Set thresholds to get quality matches

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

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)

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

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

Overview

Resources

Filesystem

Search & Retrieval

Sessions

Skills

System

Admin

Overview

Basic Usage

Parameters

Response Structure

MatchedContext Structure

Examples

Basic Search

Search with Target URI

Search with Score Threshold

Progressive Content Loading

HTTP API Example

Retrieval Strategy

Hierarchical Directory-Recursive Search

Vector Search Types

Context Layers

When to Use find() vs search()

Working with Results

Iterating Over All Results

Understanding Scores

Best Practices

Performance

Overview

Resources

Filesystem

Search & Retrieval

Sessions

Skills

System

Admin

​Overview

​Basic Usage

​Parameters

​Response Structure

​MatchedContext Structure

​Examples

​Basic Search

​Search with Target URI

​Search with Score Threshold

​Progressive Content Loading

​HTTP API Example

​Retrieval Strategy

​Hierarchical Directory-Recursive Search

​Vector Search Types

​Context Layers

​When to Use find() vs search()

​Working with Results

​Iterating Over All Results

​Accessing Related Contexts

​Understanding Scores

​Best Practices

​Performance

​Related Methods

Overview

Basic Usage

Parameters

Response Structure

MatchedContext Structure

Examples

Basic Search

Search with Target URI

Search with Score Threshold

Progressive Content Loading

HTTP API Example

Retrieval Strategy

Hierarchical Directory-Recursive Search

Vector Search Types

Context Layers

When to Use find() vs search()

Working with Results

Iterating Over All Results

Accessing Related Contexts

Understanding Scores

Best Practices

Performance

Related Methods