Retrieval Mechanism

OpenViking uses global vector retrieval with optional reranking after recall. Session intent analysis is a separate preceding stage.

Overview

Query → Intent Analysis (optional) → Global Vector Search → Rerank (optional) → Results

find() vs search()

Feature	find()	search()
Session context	Not used	Optional; used when session_id is supplied
Intent analysis	Not used	Uses an LLM when session content exists and intent analysis is enabled
Query count	Single query	zero or more TypedQueries
Latency	Usually lower	Depends on intent analysis, query count, and reranking
Use case	Simple queries	Complex tasks

For search, limit applies to each planned query. Merged results may exceed it, and the current implementation does not guarantee deduplication across queries.

Usage Examples

These examples use a configured synchronous Python SDK client named client.

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

# search(): Complex task (needs session context)
session_info = client.create_session()
client.add_message(
    session_id=session_info["session_id"], role="user",
    content="We are designing the OAuth login flow for this project.",
)
results = client.search(
    query="Help me create an RFC document",
    session_id=session_info["session_id"],
)

Intent Analysis

When retrieval.enable_intent=true and the session contains a summary or messages, IntentAnalyzer uses an LLM to analyze query intent and generate zero or more TypedQueries. The model used for this stage is separately configurable via the query_planner config, falling back to vlm when unset.

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

Type	Style	Example
skill	Verb-first	"Create RFC document", "Extract PDF tables"
resource	Noun phrase	"RFC document template", "API usage guide"
memory	"User's XX"	"User's code style preferences"

Special Cases

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

Global Retrieval

HierarchicalRetriever runs one global vector search per query. Target directories, context type, permissions, metadata filters, and level constrain the search scope. Without an explicit level, text queries can directly match L0/L1/L2 records; retrieval does not navigate directories recursively.

Retrieval Modes

Mode	Vector candidates	Rerank
QUICK	limit	Disabled
THINKING with a usable rerank configuration	2 × limit	One pass over the recalled candidates, returning at most limit results
THINKING without a usable rerank configuration	limit	Disabled

find() uses QUICK. search() automatically selects THINKING when a reranker is configured, otherwise QUICK. This internal retrieval mode is separate from LLM reasoning parameters and session intent analysis. Queries generated by intent analysis continue to be retrieved and ranked separately, then aggregated as before.

Image queries skip text reranking and recall limit candidates. They default to L2 unless level is specified.

Rerank Strategy

Rerank processes only the candidates from the completed global search; it never starts another search. For example, with limit=10, reranking recalls the top 20 vector hits and returns at most 10 results after reranking. Without reranking, recall is limited to 10 hits.

• Candidate index records supply the abstract text for reranking.
• Scores and ranking use rerank scores when available, otherwise vector scores; access frequency, update time, and parent-directory scores do not affect them.
• Score thresholds apply after reranking, or to vector scores when reranking is disabled.
• Failed requests or invalid rerank results retain the existing fallback to vector scores.
• Directory priority queues, parent-to-child score propagation, and convergence rounds are removed.

See rerank configuration for supported providers and settings.

Retrieval Results

The following excerpts show server-internal types. For HTTP/SDK response fields, see the Retrieval API.

MatchedContext

@dataclass
class MatchedContext:
    uri: str                # Resource URI
    context_type: ContextType
    level: int              # 0=abstract, 1=overview, 2=detail
    abstract: str           # L0 abstract
    score: float            # Final score

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