What is OpenViking ?

TL;DR

OpenViking is an open-source context database for AI agents that replaces flat vector storage with a filesystem paradigm. It organizes context (memories, resources, skills) under viking:// URIs with three layers: L0 (~100 tokens), L1 (~2k tokens), and L2 (full content). Benchmarks show 91% token cost reduction and 43% better task completion versus traditional RAG.

Try Apidog today

Introduction

Your AI agent keeps forgetting things. It asks for the same API endpoint twice, ignores a staging-environment preference, or loses track of tests that passed yesterday.

Most teams address this with a mix of RAG pipelines, vector databases, and custom memory code. That often creates fragmented context, rising token costs, and retrieval failures that are difficult to debug.

In LoCoMo10 benchmark tests, traditional RAG systems achieved 35–44% task completion while consuming 24–51 million input tokens.

OpenViking takes a different approach. Created by ByteDance’s OpenViking team, it replaces flat vector storage with a filesystem paradigm. Context lives under viking:// URIs and is loaded hierarchically through L0/L1/L2 layers. In the reported benchmark, this produced 52% task completion with 91% fewer tokens.

💡 If you are building API-testing agents with Apidog, OpenViking can help retain context across test runs, store user environment preferences, and make API documentation semantically searchable.

In this guide, you will learn how OpenViking addresses context fragmentation, how the L0/L1/L2 model works, and how to deploy a server.

The Agent Context Problem

An API-testing agent may need to retain context across many sessions:

• User preferences: “use the staging environment” or “prefer curl over Python”
• Project context: endpoints, authentication methods, and previous test results
• Tool patterns: frequently failing endpoints or recurring schema errors
• Task history: completed tests and surfaced bugs

Traditional RAG typically stores this data as flat chunks in a vector database. A query returns top-K similar fragments, but it does not provide hierarchy, structure, or visibility into missed context.

Five Core Challenges

Challenge	Traditional RAG	OpenViking approach
Fragmented context	Memories, resources, and skills are stored separately	Unified filesystem under viking://
Surging demand	Long tasks create massive context	L0/L1/L2 hierarchical loading reduces tokens
Poor retrieval	Flat vector search lacks a global view	Directory-recursive retrieval with intent analysis
Unobservable behavior	Retrieval chains are black boxes	Search trajectories can be visualized
Limited iteration	Usually limited to interaction history	Automatic session management with six memory categories

The goal is to move from “store everything, retrieve vaguely” to “structure everything, retrieve precisely.”

What Is OpenViking?

OpenViking is an open-source context database for AI agents, created by ByteDance’s OpenViking team under the Apache 2.0 license.

It maps memories, resources, and skills into a virtual filesystem where every item has a unique URI:

viking://
├── resources/              # External knowledge: docs, code, web pages
│   ├── my_project/
│   │   ├── docs/
│   │   │   ├── api/
│   │   │   └── tutorials/
│   │   └── src/
│   └── ...
├── user/                   # User-specific: preferences, habits
│   └── memories/
│       ├── preferences/
│       │   ├── writing_style
│       │   └── coding_habits
│       └── ...
└── agent/                  # Agent capabilities: skills, task memories
    ├── skills/
    │   ├── search_code
    │   ├── analyze_data
    │   └── ...
    ├── memories/
    └── instructions/

Agents can manipulate context through filesystem-style operations:

# Navigate context
ls viking://resources/my_project/docs/

# Search semantically
find "authentication methods"

# Read full content
read viking://resources/docs/auth.md

# Get a short summary
abstract viking://resources/docs/

The key difference is that the agent can identify a relevant directory before loading individual files.

Core Feature 1: Filesystem Management

The filesystem model unifies context types under one namespace.

Three Context Types

Type	Purpose	Lifecycle	Initiative
Resource	External knowledge such as docs, code, and FAQs	Long-term, static	User adds
Memory	Agent cognition such as preferences and experiences	Long-term, dynamic	Agent extracts
Skill	Callable capabilities such as tools and MCP	Long-term, static	Agent invokes

A typical layout looks like this:

• viking://resources/: product manuals, repositories, and documentation
• viking://user/memories/: user preferences, entities, and events
• viking://agent/skills/: tool definitions and MCP configurations
• viking://agent/memories/: learned patterns and case studies

Use the Unix-Like API

Use the Python SDK to search, list, read, and summarize context:

from openviking import OpenViking

client = OpenViking(path="./data")

# Semantic search across context types
results = client.find("user authentication")

# List a directory
contents = client.ls("viking://resources/")

# Read L2: full content
doc = client.read("viking://resources/docs/auth.md")

# Read L0: quick summary
abstract = client.abstract("viking://resources/docs/")

# Read L1: detailed overview
overview = client.overview("viking://resources/docs/")

The API is available through the Python SDK or an HTTP server, allowing integration with different agent frameworks.

Core Feature 2: L0/L1/L2 Hierarchical Context Loading

Loading large documents directly into prompts is expensive and can reduce retrieval quality. OpenViking processes context into three layers:

Layer	Name	File	Token limit	Purpose
L0	Abstract	.abstract.md	~100 tokens	Vector search and quick filtering
L1	Overview	.overview.md	~2k tokens	Reranking and navigation
L2	Detail	Original files	Unlimited	Full content loaded on demand

How Resource Processing Works

When you add a resource, such as PDF documentation, OpenViking:

1. Parses the document into text without LLM calls.
2. Builds a directory tree in AGFS storage.
3. Queues semantic processing asynchronously.
4. Generates L0 abstracts and L1 overviews from the bottom up.

The resulting structure can look like this:

viking://resources/my_project/
├── .abstract.md               # L0: short summary
├── .overview.md               # L1: detailed navigation summary
├── docs/
│   ├── .abstract.md
│   ├── .overview.md
│   ├── auth.md                # L2: full content
│   ├── endpoints.md
│   └── rate-limits.md
└── src/
    └── ...

Load Context Progressively

Instead of loading every matching document, start with L1 and fetch L2 only when necessary:

# Traditional RAG: potentially load all matching content
full_docs = retrieve_all("authentication")  # 50k tokens

# OpenViking: inspect the L1 overview first
overview = client.overview("viking://resources/docs/auth/")  # ~2k tokens

if needs_more_detail(overview):
    content = client.read(
        "viking://resources/docs/auth/oauth.md"
    )  # Load only the required L2 content

In benchmark tests, this approach reduced input token costs by 91% compared with traditional RAG while improving task completion by 43%.

Core Feature 3: Directory-Recursive Retrieval

A single vector search can struggle with complex queries. OpenViking uses a directory-recursive retrieval strategy:

1. Intent analysis
   ↓
2. Initial positioning
   ↓
3. Refined exploration
   ↓
4. Recursive descent
   ↓
5. Result aggregation

Example: Find Authentication Documentation

For the query, “How do I authenticate users?”, the retrieval flow is:

1. Intent analysis
   
   Identify a procedural question, relevant entities such as “authenticate” and “users,” and likely content including OAuth flows and authentication guides.

2. Initial positioning
   
   Locate relevant directories:
   

   viking://resources/docs/auth/      score: 0.92
   viking://resources/docs/security/  score: 0.78

1. Refined exploration Search inside the highest-ranking directory:

   viking://resources/docs/auth/oauth.md  score: 0.95
   viking://resources/docs/auth/jwt.md    score: 0.88

1. Recursive descent
   
   Repeat the process for subdirectories such as auth/providers/.

2. Result aggregation
   
   Return ranked contexts along with retrieval traces.

This “lock the directory, then explore content” strategy uses the surrounding context of a file rather than evaluating chunks in isolation.

Core Feature 4: Visualized Retrieval Traces

Traditional RAG can be difficult to debug. If a result is wrong, it may be unclear whether the problem is chunking, embedding similarity, missing source data, or a score threshold.

OpenViking can expose the filesystem traversal:

Retrieval Trace for query: "OAuth token refresh"

├── viking://resources/docs/
│   ├── [SCORE: 0.45] .abstract.md: skipped (low relevance)
│   └── [SCORE: 0.89] auth/: selected (high relevance)
│       ├── [SCORE: 0.92] oauth.md: RETURNED
│       ├── [SCORE: 0.34] jwt.md: skipped
│       └── [SCORE: 0.78] providers/
│           └── [SCORE: 0.85] google.md: RETURNED

Use these traces to answer practical debugging questions:

• Which directories did retrieval inspect?
• Why was a file selected or skipped?
• Did the agent search the wrong path?
• Does a directory need a better L0 abstract?
• Was relevant content filtered by a score threshold?

Core Feature 5: Automatic Session Management

OpenViking includes a memory self-iteration loop. At the end of a session, it can extract memories and update the agent’s stored knowledge.

Six Memory Categories

Category	Owner	Location	Description	Update strategy
profile	User	user/memories/.overview.md	Basic user information	Appendable
preferences	User	user/memories/preferences/	Preferences by topic	Appendable
entities	User	user/memories/entities/	People, projects, organizations	Appendable
events	User	user/memories/events/	Decisions and milestones	No update
cases	Agent	agent/memories/cases/	Learned cases	No update
patterns	Agent	agent/memories/patterns/	Learned patterns	No update

Commit a Session to Extract Memory

# Start a session
session = client.session()

# Add conversation turns
await session.add_message("user", [{
    "type": "text",
    "text": "I prefer dark mode in the UI"
}])

await session.add_message("assistant", [{
    "type": "text",
    "text": "Got it. I'll use dark mode for all future screenshots."
}])

# Record tool usage
await session.add_usage({
    "tool": "screenshot",
    "parameters": {"theme": "dark"},
    "result": "success"
})

# Commit to trigger memory extraction
await session.commit()

On commit, OpenViking can:

• Compress the session by retaining recent turns and archiving older ones.
• Extract memories with LLM analysis.
• Update the appropriate memory directories.
• Generate L0 and L1 content for the new memories.

Architecture Overview

OpenViking separates content storage from the vector index.

Dual-Layer Storage

Layer	Technology	Stores
AGFS	Custom filesystem	L0/L1/L2 content, multimedia files, and relations
Vector index	Vector DB	URIs, embeddings, and metadata without file content

This architecture means:

• Content reads come from AGFS as the source of truth.
• The vector index stores lightweight references.
• Large text blobs are not duplicated in vector storage.

Quick Start: Deploy an OpenViking Server

Prerequisites

Install the following before starting:

• Python 3.10+
• Go 1.22+ for AGFS components
• GCC 9+ or Clang 11+
• Linux, macOS, or Windows

Step 1: Install OpenViking

pip install openviking --upgrade --force-reinstall

Optionally install the Rust CLI:

curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/crates/ov_cli/install.sh | bash

Step 2: Configure Models

OpenViking requires:

• A VLM model for image and content understanding
• An embedding model for vectorization and semantic search

Create ~/.openviking/ov.conf:

{
  "storage": {
    "workspace": "/home/your-name/openviking_workspace"
  },
  "log": {
    "level": "INFO",
    "output": "stdout"
  },
  "embedding": {
    "dense": {
      "api_base": "https://api.openai.com/v1",
      "api_key": "your-openai-api-key",
      "provider": "openai",
      "dimension": 3072,
      "model": "text-embedding-3-large"
    },
    "max_concurrent": 10
  },
  "vlm": {
    "api_base": "https://api.openai.com/v1",
    "api_key": "your-openai-api-key",
    "provider": "openai",
    "model": "gpt-4o",
    "max_concurrent": 100
  }
}

Supported provider options include:

Provider	Embedding models	VLM models
volcengine	doubao-embedding-vision	doubao-seed-2.0-pro
openai	text-embedding-3-large	gpt-4o, gpt-4-vision
litellm	Via LiteLLM proxy	Claude, Gemini, DeepSeek, Qwen, Ollama, vLLM

LiteLLM support can connect OpenViking to Anthropic, Google, local Ollama models, or other OpenAI-compatible endpoints.

Store API keys in environment variables or a secret manager rather than committing them to configuration files.

Step 3: Start the Server

openviking-server

To run it in the background:

nohup openviking-server > /data/log/openviking.log 2>&1 &

Step 4: Add a Resource

Use the CLI:

ov add-resource https://docs.example.com/api-guide.pdf

Or use the Python SDK:

from openviking import OpenViking

client = OpenViking(path="./data")
client.add_resource("https://docs.example.com/api-guide.pdf")

Step 5: Search and Inspect Context

Wait for semantic processing, then use the CLI:

# Search semantically
ov find "authentication methods"

# List context
ov ls viking://resources/

# Inspect directory structure
ov tree viking://resources/docs -L 2

# Search for specific text
ov grep "OAuth" --uri viking://resources/docs/

Step 6: Enable VikingBot (Optional)

VikingBot is an AI agent framework built on OpenViking:

pip install "openviking[bot]"

# Start the server with the bot
openviking-server --with-bot

# In another terminal
ov chat

Performance Benchmarks

OpenViking was benchmarked against traditional RAG using LanceDB and native memory systems using the LoCoMo10 dataset, which contains 1,540 long-range dialogue cases.

Task Completion Rates

System	Completion rate	Input tokens
OpenClaw (native memory)	35.65%	24.6M
OpenClaw + LanceDB	44.55%	51.6M
OpenClaw + OpenViking	52.08%	4.3M

Key Findings

• 43% improvement over native memory with 91% token reduction
• 17% improvement over LanceDB with 92% token reduction
• Hierarchical retrieval found more relevant context while using fewer tokens

These reported results came from integrating OpenViking as a plugin with OpenClaw, an open-source AI coding assistant, using long-range dialogues where memory retention is critical.

Integrating OpenViking with Apidog

If you are building an API-testing agent with Apidog, use OpenViking to retain conversation context, store API documentation, and remember user preferences across sessions.

Step 1: Deploy OpenViking

Follow the quick-start steps above and configure the VLM and embedding providers you want to use.

Step 2: Import Apidog Documentation

Add documentation as a resource:

ov add-resource https://docs.apidog.com/overview?utm_source=dev.to&utm_medium=wanda&utm_content=blog-sync
ov add-resource https://docs.apidog.com/api-testing?utm_source=dev.to&utm_medium=wanda&utm_content=blog-sync

This imports the documentation into viking://resources/ and starts L0/L1/L2 processing.

Step 3: Persist Environment Preferences

Capture a user’s preferred API-test environment in a session:

from openviking import OpenViking

client = OpenViking(path="./apidog-agent-data")
session = client.session()

await session.add_message("user", [{
    "type": "text",
    "text": "Always use the staging environment for API tests"
}])

await session.commit()

After commit, OpenViking can extract this as a preference memory.

Step 4: Retrieve Context During Tests

Search API documentation before selecting or running a test:

# Find relevant endpoints
results = client.find("authentication endpoints")

for ctx in results.resources:
    print(f"Found: {ctx.uri}")

# Retrieve user-specific environment preferences
prefs = client.find(
    "staging environment preference",
    target_uri="viking://user/memories/"
)

Step 5: Connect Your Agent Framework

Use either the Python SDK or the HTTP API:

# Python SDK
from openviking import OpenViking

client = OpenViking(path="./data")

# HTTP API
import httpx

response = httpx.post(
    "http://localhost:1933/api/v1/search/find",
    json={"query": "authentication endpoints"},
    headers={"X-API-Key": "your-api-key"}
)

Advanced Techniques and Best Practices

Pre-Warm Frequently Accessed Context

Generate semantic layers during off-peak hours for documentation that agents access frequently:

ov add-resource https://docs.example.com --wait

Archive Stale Session Data

Set a retention strategy for old session data:

# Archive sessions older than seven days
await session.archive(max_age_days=7)

Monitor Index Health

Inspect index size and query statistics:

ov debug stats

Avoid Common Mistakes

• Loading L2 too early: Start with L0 or L1 and fetch L2 only when needed.
• Skipping session commits: Memory extraction occurs on commit().
• Overloading directories: Split large resources into topic-based subdirectories.
• Ignoring retrieval traces: Use traversal output to diagnose poor retrieval.

Performance Optimization

Scenario	Recommendation
High query volume	Run OpenViking as an HTTP server with connection pooling
Large documents	Split content into topic-based chunks before importing
Low-latency requirements	Pre-generate L0/L1 for frequently accessed content
Multi-tenant setup	Use separate workspaces per tenant

Security Checklist

• Store API keys in environment variables or secret managers.
• Enable HTTPS for HTTP deployments.
• Add rate limiting to public endpoints.
• Use separate API keys for development and production.

Real-World Use Cases

1. AI Coding Assistants

A development team integrated OpenViking into an internal coding assistant. The agent can:

• Navigate source code through viking://resources/my_project/src/
• Remember coding preferences such as naming conventions and testing frameworks
• Retrieve relevant API documentation during code generation

Reported result: a 67% reduction in “forgetful” agent behaviors and 43% token cost savings.

2. Customer Support Agents

A SaaS company deployed OpenViking for a support chatbot:

• Product documentation in viking://resources/product/
• Customer history in viking://user/memories/past_issues/
• Support playbooks in viking://agent/skills/

Reported result: first-contact resolution improved from 52% to 71%.

3. Research Assistants

A research lab uses OpenViking to organize papers and notes:

• Papers grouped by topic, such as viking://resources/papers/nlp/
• Research methodologies stored as skills
• Key findings extracted automatically into memory

Reported result: researchers found relevant papers three times faster through semantic search.

OpenViking vs. Traditional RAG

Aspect	Traditional RAG	OpenViking
Storage model	Flat vector chunks	Hierarchical filesystem
Retrieval	Top-K similarity	Directory-recursive retrieval with intent analysis
Observability	Black box	Visualized search traces
Token efficiency	Load all content or truncate	L0/L1/L2 progressive loading
Memory iteration	Manual or absent	Automatic session management
Context types	Documents only	Resources, memories, and skills
Debugging	Guesswork	Directory traversal logs

OpenViking vs. LangChain Memory

Aspect	LangChain Memory	OpenViking
Persistence	Conversation buffer	Filesystem with L0/L1/L2
Scalability	Limited by context window	Hierarchical loading
Retrieval	Linear search	Directory-recursive semantic retrieval
Memory types	Single buffer	Six categories, including profile, preferences, and events

When to Consider Alternatives

Use a traditional vector database if:

• You need sub-100 ms retrieval latency.
• Your use case is simple keyword search.
• You already have a RAG pipeline with no significant pain points.

Use OpenViking if:

• You are building long-running agent conversations.
• You need multiple context types, such as docs, preferences, and tools.
• Token cost optimization matters.
• You need observable and debuggable retrieval.

Production Deployment

For production, run OpenViking as a standalone HTTP service.

Recommended Infrastructure

• Cloud: Volcengine ECS or an equivalent service
• OS: veLinux or Ubuntu 22.04+
• Storage: SSD-backed volume for AGFS
• Network: low-latency connectivity to model APIs

Security Considerations

• Store API keys in environment variables or a secret manager.
• Enable authentication for HTTP endpoints.
• Use HTTPS for client-server communication.
• Implement rate limiting to prevent abuse.

Logging and Monitoring

Configure file logging:

{
  "log": {
    "level": "INFO",
    "output": "file",
    "path": "/var/log/openviking/server.log"
  }
}

Monitor:

• Semantic processing queue depth
• Vector search latency
• AGFS read and write operations
• Memory extraction success rates

Limitations and Considerations

Current Limitations

• Python-centric: The primary SDK is Python; other languages need HTTP integration.
• Model dependencies: External VLM and embedding models are required.
• Learning curve: The filesystem paradigm differs from a traditional vector database.
• Early stage: The project is under active development and APIs may change.

Good Fit

Use OpenViking for:

• Long-running conversations that require durable memory
• Multi-type context including docs, preferences, and tools
• Retrieval that must be observable and debuggable
• Workloads where token optimization matters

Consider alternatives for:

• Simple one-shot Q&A applications
• Existing RAG pipelines without meaningful pain points
• Cases requiring sub-100 ms retrieval latency, where OpenViking processing overhead may not fit

The Road Ahead

OpenViking is in early development, at version 0.1.x as of early 2025. Its roadmap includes:

• Multi-tenant support with isolated workspaces
• Retrieval quality metrics and memory usage dashboards
• A plugin ecosystem for agent frameworks
• Lightweight, local-first edge deployment
• Enhanced native Model Context Protocol support

The project is open source under Apache 2.0 and is actively seeking community contributors.

Conclusion

OpenViking organizes agent context as a filesystem rather than a collection of flat vector chunks. This gives agents a unified namespace for resources, memories, and skills while enabling progressive context loading and observable retrieval.

Key Takeaways

• Filesystem-based context: Store memories, resources, and skills under viking:// URIs.
• L0/L1/L2 loading: Start with lightweight summaries and load full content only when required.
• Directory-recursive retrieval: Identify relevant directories before exploring individual files.
• Retrieval traces: Debug why context was selected, skipped, or missed.
• Session commits: Extract preferences and learned patterns from completed conversations.