OpenViking Documentation

An open-source context database designed for AI Agents with filesystem-based management, hierarchical context loading, and semantic retrieval.

OpenViking

The Context Database for AI Agents

Unify memory, resources, and skills through a filesystem paradigm. Enable hierarchical context delivery and self-evolving agents.

Why OpenViking?

In the AI era, data is abundant, but high-quality context is scarce. OpenViking solves the critical challenges developers face when building AI Agents:

Context Fragmentation

Memory in code, resources in vector databases, skills scattered everywhere — OpenViking unifies them all under a single filesystem paradigm.

Context Explosion

Long-running Agent tasks generate massive context. OpenViking’s L0/L1/L2 hierarchical loading prevents information loss while saving tokens.

Poor Retrieval Quality

Traditional RAG uses flat storage. OpenViking’s directory recursive retrieval understands complete context with global perspective.

Context Opacity

Black-box retrieval makes debugging impossible. OpenViking provides visualized retrieval trajectories for full observability.

Core Features

Filesystem Paradigm

Organize all context (Memory, Resources, Skills) as a virtual filesystem with viking:// URIs. Use familiar commands like ls, find, grep to navigate context.

Hierarchical Loading

Automatic L0/L1/L2 context processing: abstracts (~100 tokens), overviews (~2k tokens), and full details — loaded on demand to save costs.

Directory Recursive Retrieval

Intent analysis → directory positioning → fine exploration → recursive descent. Find semantically best-matching fragments with full context awareness.

Session Management

Built-in memory self-iteration. Extract 6-category memories (profile, preferences, entities, events, cases, patterns) from sessions automatically.

Get Started in Minutes

Quickstart

Install OpenViking and run your first example in 5 minutes

Architecture

Understand OpenViking’s dual-layer storage and retrieval design

API Reference

Explore the complete API for filesystem, search, and sessions

Installation

pip

pip install openviking --upgrade

Quick Example

from openviking import OpenViking

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

# Add resources
client.add_resource("https://github.com/volcengine/OpenViking")

# Semantic search
results = client.find("what is openviking")

# Filesystem operations
client.ls("viking://resources/")
client.tree("viking://resources/volcengine/OpenViking", depth=2)

# Session management
session = client.session()
session.add(role="user", content="How do I configure OpenViking?")
session.add(role="assistant", content="You can configure OpenViking using ov.conf...")
session.commit()  # Extracts memories automatically

Community & Support

GitHub

Star the repo, report issues, and contribute

Discord

Join our community for support and discussions

X (Twitter)

Follow us for updates and announcements

Integration Examples

OpenViking integrates seamlessly with popular AI agent frameworks:

OpenClaw Plugin

Boost OpenClaw task completion by 49% with 91% lower token costs

Claude Desktop MCP

Connect OpenViking to Claude Desktop as a Model Context Protocol server

OpenCode Integration

Use OpenViking as context management for coding agents

MCP Server

Expose OpenViking functionality through Model Context Protocol

What Makes OpenViking Different?

Traditional RAG systems treat context as flat text chunks. OpenViking treats context as a hierarchical filesystem:

Traditional RAG	OpenViking
Flat vector chunks	Hierarchical directory structure
Single-pass retrieval	Directory recursive retrieval
Fixed context window	L0/L1/L2 progressive loading
Opaque retrieval	Visualized retrieval trajectories
Static memory	Self-evolving 6-category memory

Real-World Performance

Based on LoCoMo10 benchmark (1,540 long-range dialogue cases):

Configuration	Task Completion	Input Tokens
OpenClaw (baseline)	35.65%	24.6M
OpenClaw + LanceDB	44.55%	51.6M
OpenClaw + OpenViking	52.08%	4.3M

Results: 49% improvement over baseline with 83% reduction in token costs.

Open Source & Apache 2.0

OpenViking is fully open source under the Apache 2.0 license. We welcome contributions from the community.

4,761 GitHub stars and growing. Join the community building the future of AI Agent context management.

Next Steps

1. Install OpenViking

   Follow the Quickstart Guide to install and configure OpenViking

2. Learn Core Concepts

   Understand Architecture, Context Types, and Viking URI

3. Explore Integrations

   Connect OpenViking to OpenClaw or Claude Desktop

4. Deploy to Production

   Follow the Server Deployment Guide for production setup