Retrieval Mechanism

Retrieval Mechanism

OpenViking uses two-stage retrieval: intent analysis + hierarchical retrieval + rerank.

Overview

Query → Intent Analysis → Hierarchical Retrieval → Rerank → Results
              ↓                    ↓                  ↓
         TypedQuery          Directory Recursion   Refined Scoring

find() vs search()

Usage Examples

# find(): Simple query
results = await client.find(
    "OAuth authentication",
    target_uri="viking://resources/"
)

# search(): Complex task (needs session context)
results = await client.search(
    "Help me create an RFC document",
    session_info=session
)

Intent Analysis

IntentAnalyzer uses LLM to analyze query intent and generate 0-5 TypedQueries.

Input

• Session compression summary
• Last 5 messages
• Current query

Output

@dataclass
class TypedQuery:
    query: str              # Rewritten query
    context_type: ContextType  # MEMORY/RESOURCE/SKILL
    intent: str             # Query purpose
    priority: int           # 1-5 priority

Query Styles

Special Cases

• 0 queries: Chitchat, greetings that don't need retrieval
• Multiple queries: Complex tasks may need skill + resource + memory

Hierarchical Retrieval

HierarchicalRetriever uses priority queue to recursively search directory structure.

Flow

Step 1: Determine root directories by context_type
        ↓
Step 2: Global vector search to locate starting directories
        ↓
Step 3: Merge starting points + Rerank scoring
        ↓
Step 4: Recursive search (priority queue)
        ↓
Step 5: Convert to MatchedContext

Root Directory Mapping

Recursive Search Algorithm

while dir_queue:
    current_uri, parent_score = heapq.heappop(dir_queue)

    # Search children
    results = await search(parent_uri=current_uri)

    for r in results:
        # Score propagation
        final_score = 0.5 * embedding_score + 0.5 * parent_score

        if final_score > threshold:
            collected.append(r)

            if not r.is_leaf:  # Directory continues recursion
                heapq.heappush(dir_queue, (r.uri, final_score))

    # Convergence detection
    if topk_unchanged_for_3_rounds:
        break

Key Parameters

Rerank Strategy

Rerank refines candidate results in THINKING mode.

Trigger Conditions

• Rerank AK/SK configured
• Using THINKING mode (default for search())

Scoring Method

if rerank_client and mode == THINKING:
    scores = rerank_client.rerank_batch(query, documents)
else:
    scores = [r["_score"] for r in results]  # Vector scores

Usage Points

1. Starting point evaluation: Evaluate global search candidate directories
2. Recursive search: Evaluate children at each level

Backend Support

Retrieval Results

MatchedContext

@dataclass
class MatchedContext:
    uri: str                # Resource URI
    context_type: ContextType
    is_leaf: bool           # Whether file
    abstract: str           # L0 abstract
    score: float            # Final score
    relations: List[RelatedContext]  # Related contexts

FindResult

@dataclass
class FindResult:
    memories: List[MatchedContext]
    resources: List[MatchedContext]
    skills: List[MatchedContext]
    query_plan: Optional[QueryPlan]      # Present for search()
    query_results: Optional[List[QueryResult]]
    total: int

Related Documents

• Architecture Overview - System architecture
• Storage Architecture - Vector index
• Context Layers - L0/L1/L2 model
• Context Types - Three context types