• Fragmented context -- memory, docs, and skills scattered across separate systems (vector DBs, file stores, prompt templates)
• Surging context demand -- agents consume more tokens as tasks grow complex, but context windows are finite
• Poor retrieval -- flat vector search (RAG) lacks structural awareness; returns fragments without hierarchy

• Unobservable retrieval -- no visibility into why certain context was selected or missed
• No memory iteration -- agents cannot learn across sessions; each run starts cold

viking://
  |-- resources/      # project docs, repos, web
  |   |-- github.com/
  |   |   |-- volcengine/OpenViking/
  |   |       |-- README.md
  |   |       |-- docs/
  |   |       |-- examples/
  |   |-- uploads/
  |-- user/           # preferences, habits
  |-- agent/          # skills, instructions
      |-- skills/
      |-- memories/

Why a filesystem?

• Agents already understand ls, find, tree, glob -- zero new abstractions
• Hierarchical structure enables directory-level retrieval, not just flat vector search
• Every context item gets a unique URI, enabling precise references
• Natural mapping: repos become directories, docs become files, sections become sub-files

# Get each tier programmatically
l0 = client.abstract(uri)  # L0
l1 = client.overview(uri)  # L1
l2 = client.read(uri)      # L2

Naive RAG Approach

Load all 50 docs into context. Expensive, slow, often exceeds context window.

OpenViking Tiered

25,000 tokens total -- 95% reduction

Traditional RAG

• Chunk documents into fixed-size pieces
• Embed all chunks into a flat vector space
• Query returns top-K most similar chunks
• No structural awareness -- related chunks may not be returned together
• Chunk boundaries often split meaningful context

OpenViking Retrieval

• Preserves document hierarchy as directories
• Searches at directory level first, then drills down
• Returns coherent context units (whole files/sections)
• L0/L1 tiers act as natural "summaries" for matching
• Recursive search ensures related content stays grouped

When the agent retrieves context, OpenViking records the full trajectory:

# Retrieval trajectory for:
# "How to configure K8s deployment"

Query decomposition:
  cond_1: kubernetes deployment config
  cond_2: helm chart setup

Directory scan:
  viking://resources/ -> score: 0.82
    docs/deployment/ -> score: 0.94
      k8s-guide.md -> score: 0.97
    examples/k8s-helm/ -> score: 0.91

Selected: 2 resources, 4200 tokens

Why This Matters

• Debugging -- see exactly why the agent got wrong context
• Optimization -- identify poorly-scored directories, improve L0/L1 summaries
• Trust -- verify the agent is using the right sources before acting
• Auditing -- trace every decision back to its information source

At the end of each session, OpenViking's memory extraction mechanism processes the conversation to extract:

• Tool call patterns -- which tools worked, with what parameters
• Operational tips -- "this API needs retry logic with backoff"
• User preferences -- communication style, output format preferences
• Task strategies -- successful approaches for recurring task types

Extracted knowledge is stored under viking://user/ and viking://agent/ and surfaced in future sessions via L0/L1 retrieval.

Two Modes

Components

• openviking-server -- Python server (REST API)
• ov CLI -- Rust-based CLI client
• openviking Python SDK -- programmatic access
• AGFS -- Go-based filesystem layer

K8s / Helm Deployment

# Production deployment
helm install openviking \
  ./deploy/helm/openviking \
  --set vlm.provider=openai \
  --set vlm.model=gpt-4o \
  --set embedding.provider=openai

# ov.conf -- LiteLLM with Claude
{
  "vlm": {
    "provider": "litellm",
    "model": "claude-3-5-sonnet",
    "api_key": "sk-..."
  },
  "embedding": {
    "dense": {
      "provider": "openai",
      "model": "text-embedding-3-large",
      "dimension": 3072
    }
  }
}

Available Integrations

VikingBot Quick Start

# Install with bot support
pip install "openviking[bot]"

# Start server with built-in bot
openviking-server --with-bot

# Chat with your context
ov chat

Task Completion Rate

Input Token Consumption

volcengine/OpenViking
|-- openviking/        # Python core package
|-- openviking_cli/    # Python CLI wrapper
|-- crates/ov_cli/     # Rust CLI (fast)
|-- src/               # Core implementation
|-- deploy/helm/       # K8s Helm charts
|-- examples/          # Integration demos
|   |-- claude-memory-plugin/
|   |-- mcp-query/
|   |-- openclaw-plugin/
|   |-- multi_tenant/
|   |-- server_client/
|   |-- skills/
|-- tests/             # Test suite

Language Mix

Why Not Just RAG?

• RAG treats all documents as flat bags of chunks -- no hierarchy
• Chunk boundaries are arbitrary, splitting semantic units
• Top-K retrieval returns isolated fragments, not coherent context
• No built-in memory evolution -- every session starts cold

Why Not Just Long Context?

• 128K-1M token windows are still finite
• Cost scales linearly with context size
• Retrieval accuracy degrades in the "lost in the middle" zone
• No persistence between sessions

OpenViking's Position

• Hierarchical -- filesystem structure preserves document relationships
• Progressive -- L0/L1/L2 tiers load only what is needed
• Persistent -- memory survives across sessions
• Observable -- every retrieval path is traceable
• Evolving -- knowledge base grows with usage

// ~/.openviking/ov.conf
{
  "storage": {
    "workspace": "/data/openviking"
  },
  "log": {
    "level": "INFO",
    "output": "stdout"
  },
  "embedding": {
    "dense": {
      "api_base": "https://api.openai.com/v1",
      "api_key": "sk-...",
      "provider": "openai",
      "dimension": 3072,
      "model": "text-embedding-3-large"
    },
    "max_concurrent": 10
  },
  "vlm": {
    "api_base": "https://api.openai.com/v1",
    "api_key": "sk-...",
    "provider": "openai",
    "model": "gpt-4o",
    "max_concurrent": 100
  }
}

Key Settings

• workspace -- filesystem root for all stored context
• embedding.dense -- vector model for semantic matching
• vlm -- vision-language model for L0/L1 generation and memory extraction
• max_concurrent -- parallel request limits (tune for your API tier)

# 1. Start Ollama with a model
ollama pull llama3.1
ollama serve

# 2. Configure OpenViking
# ~/.openviking/ov.conf
{
  "vlm": {
    "provider": "litellm",
    "model": "ollama/llama3.1",
    "api_base": "http://localhost:11434"
  },
  "embedding": {
    "dense": {
      "provider": "jina",
      "model": "jina-embeddings-v3",
      "api_key": "jina_...",
      "dimension": 1024
    }
  }
}

# 3. Launch
openviking-server

LiteLLM Auto-Detection

LiteLLM automatically routes based on model name prefix:

Strong Fit

• Agents that operate on large codebases or documentation sets
• Multi-session agents that need persistent memory
• Teams building agent frameworks who want a drop-in context layer
• Projects where token cost is a significant concern
• Systems requiring auditable context retrieval

Consider Alternatives If

• Your context fits comfortably in a single prompt (small projects)
• You need sub-millisecond retrieval (OpenViking trades latency for structure)
• You are building a simple chatbot without tool use or multi-step reasoning
• You want a pure vector database (use Pinecone, Weaviate, LanceDB)

Things to Watch

• VLM dependency -- L0/L1 generation quality depends heavily on your VLM choice. Weak models produce poor summaries.
• Processing latency -- adding a large repo triggers async VLM calls for every file. Initial indexing can be slow.
• Go + C++ requirements -- AGFS needs Go 1.22+ and a C++ compiler. Not trivial for all environments.
• Young ecosystem -- 17.3k stars but still early. API may evolve.

Discussion Points

• How does the filesystem paradigm scale to millions of files?
• Can L0/L1 summaries be incrementally updated without full reprocessing?
• How does multi-agent contention work in server mode?
• What happens when memory extraction captures incorrect patterns?
• How does this compare to emerging standards like MCP for context management?