The First Mental Model: What OpenViking Actually Controls

The OpenViking model becomes useful when its types, addresses, layers, and ingestion stages are treated as one chain rather than as separate features. This synthesis follows a single resource from its arrival in the system to the moment an agent can inspect its detail, so the reader can distinguish authoritative content from derived context and judge what “ready” means before relying on retrieval or memory.

A resource is a chain, not a single object

Take a repository that a team wants an agent to use when answering questions about a payment service. In OpenViking, the repository is not simply “uploaded into a vector database.” It enters as a Resource, receives a Viking URI, and becomes a structured tree whose source files can be read directly. That initial identity matters: it tells the system that the material is externally supplied project knowledge, gives it a scope in which it can be shared or restricted, and provides a stable address for later operations.

The first transition is structural. A parser converts the repository or document into a tree in temporary space. It can split a long document by headings, preserve useful file boundaries, and recognize different formats. This stage establishes what the material contains as files and directories; it does not yet claim to understand the subject. TreeBuilder then moves the source tree into content storage under its target scope and submits semantic work.

The second transition is semantic. OpenViking processes the tree from the leaves upward. File summaries and child-directory abstracts become inputs to an overview for the containing directory. The system derives a short abstract from the overview, writes the directory sidecars, and creates vector records for semantic discovery. The project’s hierarchy is therefore not an afterthought added to search results. It is part of the route by which meaning is assembled.

The third transition is agent-facing. A query need not expose the entire repository to the model. An abstract can establish that the project contains authentication material. An overview can show which directory or file is likely to matter. The agent can then read the source file whose exact content supports the answer. A Resource has become usable context not because its vector exists in isolation, but because its URI, structure, derived views, and original detail cooperate.

flowchart LR A["Resource type and Viking URI"] --> B["Parse and store source tree"] B --> C["Bottom-up directory summaries"] C --> D["Vector indexing"] D --> E["Agent sees abstract or overview"] E --> F["Read original detail when needed"] C --> G["Parent refresh pending after child change"] G --> C

This chain also explains why the same repository can support different tasks without becoming a different object each time. A question about a public API may use the directory overview to locate documentation. A question about implementation may use a code skeleton to find a function or class. An incident investigation may combine the repository with a runbook and a previous Memory. The source identity remains stable while the agent’s route through it changes.