OpenViking: When Memory, Resources, and Skills Share One Context Tree

Put one concrete task on the desk. You ask a coding agent to fix duplicate charges in an expense system. During its first investigation it reads the billing repository, a payment API guide, and three test logs, then narrows the problem to an idempotency key. You also say, explicitly, “do not mock the database here.” Two days later you open a new session and say only: “continue that expense bug—first check whether tenant configuration caused it.”

Four kinds of context must arrive together. The repository and documentation are resources. The point reached in the previous investigation is session history. “Do not mock the database” is long-term memory. Checking tenant configuration may require a reusable skill or workflow. A conventional stack gives each a separate home: files enter a knowledge base, preferences enter a memory store, skills stay in a local directory, and the agent runtime owns sessions. Each part can work. The hard part is making the next answer decide where to look, how deeply to read, and what actually belongs in the prompt.

OpenViking's core answer is not “replace the vector database with a better one.” It first gives context a shared address, hierarchy, and lifecycle. Search returns candidates. The content store remains the evidence. An integration chooses when to retrieve, when to read L2, and how to assemble the model view. Once that boundary is clear, L0/L1/L2, find/search, and session commit stop looking like a pile of new nouns. They become one continuous context supply chain.

1. It Does Not Add a Memory Box; It Redraws the Context Address Book

1.1 Why three kinds of material belong in one tree

Return to the expense bug. billing/retry.py does not become user memory merely because the agent read it once. “Do not mock the database” should not be mixed into public project documentation. A reliable tenant-check procedure is closer to a reusable skill. OpenViking preserves those differences while giving them a shared addressing convention: the URI first says who owns the context and what kind it is; each kind then keeps its own lifecycle.

viking://
├── resources/                       # public or account-scoped resources
├── user/{user_id}/
│   ├── memories/                    # persistent knowledge learned from interactions
│   ├── resources/                   # private user resources
│   ├── skills/                      # private user skills
│   └── sessions/{session_id}/       # live messages and history archives
└── agent/
    └── skills/                      # account-shared skills

The first benefit is ownership. Shared payment documentation can live under viking://resources/. A user's project constraint can live under viking://user/{user_id}/memories/. A team-wide checking procedure can live under viking://agent/skills/. Retrieval returns more than similar prose: it can retain URI, context type, level, and scope. The official context-types documentation draws the same line between user-added resources, persistent knowledge learned from interaction, and executable skills.

1.2 “Filesystem” describes the interaction model, not “a database made of local files”

OpenViking often calls itself a context filesystem. The easiest mistake is to read that as “everything is directly stored in folders on one disk.” In practice, viking:// is a URI abstraction offering operations that feel like ls, read, mv, abstract, overview, and find. Beneath it, content storage and index storage remain separate. “Filesystem” gives the system addresses, hierarchy, and familiar operations. It does not imply a trivial deployment or a local-only backend.

2. How a Repository Grows into a Context Tree: Source First, Semantics Later

Now import the billing repository. A dangerous design would summarize while ingesting and treat the summary as the only record: if the model call fails, the resource is half-present; if the summary distorts a fact, there is no independent evidence left. OpenViking's ingestion path parses source material, builds final URIs, and commits content before the semantic queue completes L0/L1 and vector indexing. The ordering matters more than the class names: recoverable source becomes fact before model-generated representations arrive.

2.1 The five source steps explain more than a one-line add API

The docstring of ResourceProcessor.process_resource() lists parse, URI metadata, source commit, vector index, and summarization. The implementation first lets a media processor write content into a temporary area. TreeBuilder.finalize_from_temp() then derives the final URI and temp_uri metadata; only afterward does ResourceProcessor call VikingFS.persist_temp_tree() to copy the temporary tree into its formal location. The parser understands shape, TreeBuilder chooses addresses, and VikingFS persists content. None asks an LLM to invent a repository tree from prose.

# Only the source call-chain skeleton
parse_result = await media_processor.process(source=path, ...)
context_tree = await tree_builder.finalize_from_temp(
    temp_dir_path=parse_result.temp_dir_path,
    scope=scope,
    to_uri=to,
)
root_uri = context_tree.root.uri
temp_uri = context_tree.root.temp_uri
await viking_fs.persist_temp_tree(temp_uri, root_uri, ...)
# After source commit, the semantic queue adds L0/L1 and the index.

The semantic processor's responsibility is equally explicit: generate .abstract.md and .overview.md bottom-up, then vectorize those representations. Child summaries exist before a parent writes its overview. The repository therefore becomes a navigable hierarchy, not a bag of unrelated chunks.

3. L0, L1, and L2 Are Reading Depths, Not Short-, Medium-, and Long-Term Memory

Once the repository is in the tree, the agent should not swallow the entire billing directory to answer “where is tenant configuration read?” OpenViking gives one node three representations. L0 is a short abstract for deciding whether a path is promising. L1 is a structured overview for understanding what a branch contains and where to descend. L2 is the original file or complete content. They answer “how deeply should I read?”, not “how long should I remember?”

viking://resources/billing/
├── .abstract.md       # L0: what this is, roughly one hundred tokens
├── .overview.md       # L1: what this branch contains and how to navigate it
├── .relations.json    # related URIs
├── tenant-config.md   # L2: complete document
└── retry.py           # L2: original code

The official context-layer documentation assigns L0 to vector search and quick filtering, L1 to reranking and navigation, and L2 to on-demand complete content. That explains why a retrieval result carrying abstract and level is useful: a caller can choose a path before paying the token cost of source content.

3.1 The content tree proves; the vector index guides

Another mistake follows quickly: if the vector database carries abstracts, has it become the source of truth? OpenViking's storage documentation draws the opposite boundary. RAGFS stores L0/L1/L2 content and relations; the vector database stores URIs, vectors, and metadata to locate candidates. Moving, deleting, or renaming requires coordinated maintenance, but “what did the source actually say?” is still answered from the content layer.

4. find Skips Session Planning; search May Plan First—Then Both Use the Same Retriever

“Continue that expense bug” contains none of the full phrases “billing,” “idempotency key,” or “tenant configuration.” If an application already knows what it wants, find sends the raw query straight to the retriever. If it passes the current session to search, the system can first use an archive overview, recent messages, and the current query to split the vague request into typed, prioritized queries. After planning, both APIs call HierarchicalRetriever.retrieve(). Their boundary is whether session-aware query planning happens first, not “vectors for one API, trees for the other.”

4.1 Intent analysis is a constrained query plan, not unlimited understanding

VikingFS.search() reads the latest archive overview and current messages. When intent is enabled and context exists, it creates IntentAnalyzer(max_recent_messages=5). The analyzer passes the compression summary, five recent messages, current query, and optional target abstract to a query planner, producing several TypedQuery objects. Without session context—or with intent disabled—it falls back to the raw query. “Understand the task” therefore has a specific gate; it is not an unconditional extra LLM call.

# One vague request might become three constrained queries
TypedQuery("billing duplicate charge idempotency", context_type=RESOURCE, priority=1)
TypedQuery("do not mock database", context_type=MEMORY, priority=2)
TypedQuery("inspect tenant configuration", context_type=SKILL, priority=2)

That output is illustrative, not a promised fixed plan. The actual contract in IntentAnalyzer gives each query a context_type, intent, and priority. A planner response that cannot be parsed is surfaced as an error rather than quietly treated as success.

4.2 Thinking mode is more than “search several times”

Hierarchical retrieval works because directories have L0/L1 too. Quick mode searches vectors in the target scope and ranks them directly. Thinking mode first searches L0/L1 globally, places promising directories in a priority queue, and searches only their children. The recursive loop tracks visited URIs, propagates scores, optionally reranks, and descends only through non-L2 nodes. L2 files are terminal evidence, not directories to expand.

The result is a MatchedContext carrying candidate information such as URI, level, abstract, and score, grouped into memory/resource/skill buckets. Product copy can easily compress that into “relevant context enters the model automatically.” The source boundary is stricter: find/search locates; read/overview loads; an application or plugin decides what this turn exposes to the model. An MCP endpoint alone does nothing if the agent never calls it and no hook performs automatic recall.

5. How a Session Becomes Memory: Hand Off Evidence First, Distill It Later

Suppose the agent stops halfway through the fix. A naive commit synchronously asks a model for a summary and then clears old messages. A timeout, restart, or interrupted write can lose both source messages and summary. OpenViking's current source splits session commit in two. Phase 1 reloads authoritative messages under a path lock, plans retention, writes the raw archive, enqueues durable work, and publishes a ready marker. Phase 2 lets a queue consumer generate the archive summary and any policy-allowed memories.

5.1 Phase 1 establishes an unambiguous handoff point

Session.commit_async() reloads messages.jsonl and metadata under a path lock because another worker's Session object may be stale. It then plans archive and retained tail by message count or turn/token budget. It writes Phase 1 intent, persists archived messages to history/archive_NNN/messages.jsonl, enqueues the SESSION_COMMIT job, registers a task, rewrites the live root, and finally publishes phase1.status=ready.

{
  "status": "accepted",
  "task_id": "...",
  "archive_uri": "viking://user/.../sessions/.../history/archive_003",
  "archived": true
}

This response means “background work has been durably handed off,” not “long-term memory already exists.” A caller that needs the new memory immediately must still track task state. But a process restart after acceptance can recover from the raw archive, queued message, and ready marker.

5.2 Policy chooses what Phase 2 extracts; .done is always written last

The queue consumer eventually calls resume_queued_commit(). It first checks .done, .failed.json, and Phase 1 readiness, then reads the raw archive. Phase 2 also waits for the preceding archive to finish, preserving memory order across concurrent commits.

Archive summary, long-term memory, and execution memory are not all forced on for every session. The source first checks memory policy, agent-evolution settings, and allowed types, then concurrently runs only work whose gates pass. Successful long-term changes may be recorded in memory_diff.json. After relations and active counts are updated, .done is written last. Progress markers keep recovery from blindly replaying memory steps that already succeeded.

6. The Database Has Context—Who Puts It into This Answer?

OpenViking can now store, locate, read, and archive, yet the expense agent may still know none of it. Database capability and runtime timing are different responsibilities. MCP can expose find, search, recall, and remember for an agent to invoke deliberately. Hooks or a plugin can run fixed actions at session start, before user prompts, after turns, and before compaction. Both paths eventually meet an application's model-view assembler.

The official Codex integration guide gives one concrete lifecycle: SessionStart loads profile and indexes; UserPromptSubmit recalls related memories; Stop appends new conversation; PreCompact completes and commits the transcript. It also records a failure boundary: SIGTERM, Ctrl+C, and /exit do not fire hooks, so orphan sessions are recovered on a later startup. Those details matter more than “automatic memory,” because they reveal when capture can be missed and how recovery happens.

7. It Belongs in the Agent Memory Series, Filling the Gap Between a Memory Layer and a Platform

OpenViking does not need a separate series. It still answers the Agent Memory questions: who owns history, who distills durable knowledge, who retrieves, and who assembles model view. But it moves the series one layer outward. It manages not only memory records extracted from conversation, but also repositories, documentation, session archives, and skills under a shared address and reading protocol. Its natural position is after TencentDB Agent Memory and before Cognee / Supermemory.

7.1 It is not a complete agent framework either

OpenViking has MCP, plugins, and integrations such as VikingBot, but the core repository's stable responsibility remains the context service: ingest material, organize URIs, generate layered representations, retrieve candidates, persist sessions, and distill policy-controlled memory. OpenViking itself calls models for summaries, query planning, and memory extraction. Task planning, user-facing answer generation, code execution, approval, and action orchestration still belong to an upper runtime. “Context substrate” fits the source boundary better than “another all-purpose agent.”

8. When It Is Worth Using: First Ask Whether You Need a Context Supply Chain

OpenViking gathers many hard problems into one system and therefore thickens the operating surface: a Python service, Rust RAGFS, vector database, asynchronous QueueFS, embedding/VLM, and optional reranker and query planner may all enter a deployment. Semantic summaries, intent queries, and memory extraction also introduce model error; one of the current snapshot's latest fixes reduces unsupported entity hallucination in summaries. The main repository is AGPL-3.0 as well, so production evaluation must cover operations, quality, and licensing together.

In one sentence: OpenViking does not merely help an agent remember more; it turns scattered context into a tree with addresses, reading depths, and recovery points. The expense agent's gain is not magical recollection of an idempotency key. It is the ability to explain which session archive supplied the clue, which resource branch contained tenant configuration, and why “do not mock the database” entered this model view as a user constraint. Once that evidence chain is visible, memory is no longer a mysterious similarity box.

References

• volcengine/OpenViking
• OpenViking source snapshot: cfd74413
• Architecture
• Context types
• L0 / L1 / L2 context layers
• Storage architecture
• Retrieval
• Session management
• Codex memory plugin lifecycle
• ResourceProcessor.process_resource()
• SemanticProcessor bottom-up contract
• VikingFS.find() and search()
• HierarchicalRetriever quick/thinking split
• Recursive child search
• Session.commit_async() Phase 1
• Restart-safe Phase 2