Retrieval Is Exploration, Not a Vector Lookup

OpenViking’s retrieval system is designed to answer a practical question: once context has been organized into a layered URI tree, how should an agent find the right branch and load only the evidence it can use? The distinction between direct find, context-aware search, hierarchical exploration, and budgeted assembly lets a reader choose a retrieval path instead of treating every query as an identical nearest-vector operation.

Two retrieval questions, not one

There are two different situations behind the word “search.” In the first, the user has a reasonably clear question and the system needs to locate relevant context with as little extra reasoning as possible. In the second, the user’s request depends on a conversation, implicit goals, or more than one kind of context. The system first needs to interpret what the user is trying to do and then decide which searches to run.

OpenViking expresses the distinction through find() and search().

find() is the direct path. It accepts a query, optionally limits the target to a URI or context type, and performs semantic retrieval without relying on session context or an LLM intent-planning step. It is a natural choice for a question such as “Where is the OAuth authentication guide?” or for an application that already knows how it wants to scope a request. Its advantage is a shorter path and a more predictable cost.

search() adds interpretation. It can use a session and recent conversational context to analyze the request and produce typed queries aimed at Resources, Memories, or Skills. A request such as “Use the approach we discussed yesterday and prepare the release note” may require project documentation, a remembered decision, and a document-generation skill. Rather than forcing the caller to split that request into three searches, the query-planning stage can represent those needs separately. It can produce up to five typed queries, each with a rewritten query, an intent, a context type, and a priority.

That extra reasoning is useful when the query is underspecified or crosses context types. It is not free, and it is not automatically better for every request. Intent analysis adds model latency and another possible failure point. A simple lookup can be slower if it is sent through a planning path that contributes no useful expansion. The right comparison is therefore not “smart search versus dumb search.” It is direct retrieval versus retrieval that spends additional computation to infer the user’s information needs.

Vector recall chooses a starting point; the tree supplies the route

After a query has been turned into an embedding, OpenViking does not have to treat the top results as the final answer. Its hierarchical retriever uses global vector search to locate promising starting directories, evaluates those candidates, and recursively explores their children. A priority queue keeps the most promising directories in play, so the system can descend where the relevance signal justifies further inspection.

Consider a repository organized into documentation, source code, and operations. A question about authentication might initially match the repository root or a documentation directory. The retriever can then evaluate the children under that directory and discover a specific guide or implementation area. The path gives the result a relationship to its siblings and parent; the vector score gives the system a reason to continue down one branch rather than another.

This is the important difference between a vector hit and structured retrieval.