Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

5.9 KB
Raw Blame

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. Context mode (search(mode="context")) recalls through find(), so it uses vector scores unless the server enables retrieval.apply_rerank_to_context; it then reranks its merged candidates once per request, against the original query and its session expansions, before quotas and the token budget apply.

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. A request score_threshold filters any score; without one, rerank.threshold filters only model rerank scores; vector scores (reranking disabled or failed) only need to exceed 0.
  • 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