OpenViking: The Context Database for AI Agents

English / 中文

Website · GitHub · Issues · Docs

👋 Join our Community

📱 Lark Group · WeChat · Discord · X

---

Overview

Challenges in Agent Development

In the AI era, data is abundant, but high-quality context is hard to come by. When building AI Agents, developers often face these challenges:

• Fragmented Context: Memories are in code, resources are in vector databases, and skills are scattered, making them difficult to manage uniformly.
• Surging Context Demand: An Agent's long-running tasks produce context at every execution. Simple truncation or compression leads to information loss.
• Poor Retrieval Effectiveness: Traditional RAG uses flat storage, lacking a global view and making it difficult to understand the full context of information.
• Unobservable Context: The implicit retrieval chain of traditional RAG is like a black box, making it hard to debug when errors occur.
• Limited Memory Iteration: Current memory is just a record of user interactions, lacking Agent-related task memory.

The OpenViking Solution

OpenViking is an open-source Context Database designed specifically for AI Agents.

We aim to define a minimalist context interaction paradigm for Agents, allowing developers to completely say goodbye to the hassle of context management. OpenViking abandons the fragmented vector storage model of traditional RAG and innovatively adopts a "file system paradigm" to unify the structured organization of memories, resources, and skills needed by Agents.

With OpenViking, developers can build an Agent's brain just like managing local files:

• Filesystem Management Paradigm → Solves Fragmentation: Unified context management of memories, resources, and skills based on a filesystem paradigm.
• Tiered Context Loading → Reduces Token Consumption: L0/L1/L2 three-tier structure, loaded on demand, significantly saving costs.
• Directory Recursive Retrieval → Improves Retrieval Effect: Supports native filesystem retrieval methods, combining directory positioning with semantic search to achieve recursive and precise context acquisition.
• Visualized Retrieval Trajectory → Observable Context: Supports visualization of directory retrieval trajectories, allowing users to clearly observe the root cause of issues and guide retrieval logic optimization.
• Automatic Session Management → Context Self-Iteration: Automatically compresses content, resource references, tool calls, etc., in conversations, extracting long-term memory, making the Agent smarter with use.

---

Quick Start

Prerequisites

Before starting with OpenViking, please ensure your environment meets the following requirements:

• Python Version: 3.9 or higher
• Operating System: Linux, macOS, Windows
• Network Connection: A stable network connection is required (for downloading dependencies and accessing model services)

1. Installation

pip install openviking

2. Model Preparation

OpenViking requires the following model capabilities:

• VLM Model: For image and content understanding
• Embedding Model: For vectorization and semantic retrieval

OpenViking supports various model services:

• OpenAI Models: Supports GPT-4V and other VLM models, and OpenAI Embedding models.
• Volcengine (Doubao Models): Recommended for low cost and high performance, with free quotas for new users. For purchase and activation, please refer to: Volcengine Purchase Guide.
• Other Custom Model Services: Supports model services compatible with the OpenAI API format.

3. Environment Configuration

Configuration Template

Create a configuration file ov.conf:

{
  "embedding": {
    "dense": {
      "api_base" : "<api-endpoint>",   // API endpoint address
      "api_key"  : "<your-api-key>",   // Model service API Key
      "backend"  : "<backend-type>",   // Backend type (volcengine or openai)
      "dimension": 1024,               // Vector dimension
      "model"    : "<model-name>"      // Embedding model name (e.g., doubao-embedding-vision-250615 or text-embedding-3-large)
    }
  },
  "vlm": {
    "api_base" : "<api-endpoint>",     // API endpoint address
    "api_key"  : "<your-api-key>",     // Model service API Key
    "backend"  : "<backend-type>",     // Backend type (volcengine or openai)
    "model"    : "<model-name>"        // VLM model name (e.g., doubao-seed-1-8-251228 or gpt-4-vision-preview)
  }
}

Configuration Examples

👇 Expand to see the configuration example for your model service:

Example 1: Using Volcengine (Doubao Models)

{
  "embedding": {
    "dense": {
      "api_base" : "https://ark.cn-beijing.volces.com/api/v3",
      "api_key"  : "your-volcengine-api-key",
      "backend"  : "volcengine",
      "dimension": 1024,
      "model"    : "doubao-embedding-vision-250615"
    }
  },
  "vlm": {
    "api_base" : "https://ark.cn-beijing.volces.com/api/v3",
    "api_key"  : "your-volcengine-api-key",
    "backend"  : "volcengine",
    "model"    : "doubao-seed-1-8-251228"
  }
}

Example 2: Using OpenAI Models

{
  "embedding": {
    "dense": {
      "api_base" : "https://api.openai.com/v1",
      "api_key"  : "your-openai-api-key",
      "backend"  : "openai",
      "dimension": 3072,
      "model"    : "text-embedding-3-large"
    }
  },
  "vlm": {
    "api_base" : "https://api.openai.com/v1",
    "api_key"  : "your-openai-api-key",
    "backend"  : "openai",
    "model"    : "gpt-4-vision-preview"
  }
}

Set Environment Variable

After creating the configuration file, set the environment variable to point to it:

export OPENVIKING_CONFIG_FILE=ov.conf

💡 Tip: You can also place the configuration file in other locations, just specify the correct path in the environment variable.

4. Run Your First Example

📝 Prerequisite: Ensure you have completed the environment configuration in the previous step.

Now let's run a complete example to experience the core features of OpenViking.

Create Python Script

Create example.py:

import openviking as ov

# Initialize OpenViking client with data directory
client = ov.SyncOpenViking(path="./data")

try:
    # Initialize the client
    client.initialize()

    # Add resource (supports URL, file, or directory)
    add_result = client.add_resource(
        path="https://raw.githubusercontent.com/volcengine/OpenViking/refs/heads/main/README.md"
    )
    root_uri = add_result['root_uri']

    # Explore the resource tree structure
    ls_result = client.ls(root_uri)
    print(f"Directory structure:\n{ls_result}\n")

    # Use glob to find markdown files
    glob_result = client.glob(pattern="**/*.md", uri=root_uri)
    if glob_result['matches']:
        content = client.read(glob_result['matches'][0])
        print(f"Content preview: {content[:200]}...\n")

    # Wait for semantic processing to complete
    print("Wait for semantic processing...")
    client.wait_processed()

    # Get abstract and overview of the resource
    abstract = client.abstract(root_uri)
    overview = client.overview(root_uri)
    print(f"Abstract:\n{abstract}\n\nOverview:\n{overview}\n")

    # Perform semantic search
    results = client.find("what is openviking", target_uri=root_uri)
    print("Search results:")
    for r in results.resources:
        print(f"  {r.uri} (score: {r.score:.4f})")

    # Close the client
    client.close()

except Exception as e:
    print(f"Error: {e}")

Run the Script

python example.py

Expected Output

Directory structure:
...

Content preview: ...

Wait for semantic processing...
Abstract:
...

Overview:
...

Search results:
  viking://resources/... (score: 0.8523)
  ...

Congratulations! You have successfully run OpenViking 🎉

---

Core Concepts

After running the first example, let's dive into the design philosophy of OpenViking. These five core concepts correspond one-to-one with the solutions mentioned earlier, together building a complete context management system:

1. Filesystem Management Paradigm → Solves Fragmentation

We no longer view context as flat text slices but unify them into an abstract virtual filesystem. Whether it's memories, resources, or capabilities, they are mapped to virtual directories under the viking:// protocol, each with a unique URI.

This paradigm gives Agents unprecedented context manipulation capabilities, enabling them to locate, browse, and manipulate information precisely and deterministically through standard commands like ls and find, just like a developer. This transforms context management from vague semantic matching into intuitive, traceable "file operations". Learn more: Viking URI | Context Types

viking://
├── resources/              # Resources: project docs, repos, web pages, etc.
│   ├── my_project/
│   │   ├── docs/
│   │   │   ├── api/
│   │   │   └── tutorials/
│   │   └── src/
│   └── ...
├── user/                   # User: personal preferences, habits, etc.
│   └── memories/
│       ├── preferences/
│       │   ├── writing_style
│       │   └── coding_habits
│       └── ...
└── agent/                  # Agent: skills, instructions, task memories, etc.
    ├── skills/
    │   ├── search_code
    │   ├── analyze_data
    │   └── ...
    ├── memories/
    └── instructions/

2. Tiered Context Loading → Reduces Token Consumption

Stuffing massive amounts of context into a prompt all at once is not only expensive but also prone to exceeding model windows and introducing noise. OpenViking automatically processes context into three levels upon writing:

• L0 (Abstract): A one-sentence summary for quick retrieval and identification.
• L1 (Overview): Contains core information and usage scenarios for Agent decision-making during the planning phase.
• L2 (Details): The full original data, for deep reading by the Agent when absolutely necessary.

Learn more: Context Layers

viking://resources/my_project/
├── .abstract               # L0 Layer: Abstract (~100 tokens) - Quick relevance check
├── .overview               # L1 Layer: Overview (~2k tokens) - Understand structure and key points
├── docs/
│   ├── .abstract          # Each directory has corresponding L0/L1 layers
│   ├── .overview
│   ├── api/
│   │   ├── .abstract
│   │   ├── .overview
│   │   ├── auth.md        # L2 Layer: Full content - Load on demand
│   │   └── endpoints.md
│   └── ...
└── src/
    └── ...

3. Directory Recursive Retrieval → Improves Retrieval Effect

Single vector retrieval struggles with complex query intents. OpenViking has designed an innovative Directory Recursive Retrieval Strategy that deeply integrates multiple retrieval methods:

1. Intent Analysis: Generate multiple retrieval conditions through intent analysis.
2. Initial Positioning: Use vector retrieval to quickly locate the high-score directory where the initial slice is located.
3. Refined Exploration: Perform a secondary retrieval within that directory and update high-score results to the candidate set.
4. Recursive Drill-down: If subdirectories exist, recursively repeat the secondary retrieval steps layer by layer.
5. Result Aggregation: Finally, obtain the most relevant context to return.

This "lock high-score directory first, then refine content exploration" strategy not only finds the semantically best-matching fragments but also understands the full context where the information resides, thereby improving the globality and accuracy of retrieval. Learn more: Retrieval Mechanism

4. Visualized Retrieval Trajectory → Observable Context

OpenViking's organization uses a hierarchical virtual filesystem structure. All context is integrated in a unified format, and each entry corresponds to a unique URI (like a viking:// path), breaking the traditional flat black-box management mode with a clear hierarchy that is easy to understand.

The retrieval process adopts a directory recursive strategy. The trajectory of directory browsing and file positioning for each retrieval is fully preserved, allowing users to clearly observe the root cause of problems and guide the optimization of retrieval logic. Learn more: Retrieval Mechanism

5. Automatic Session Management → Context Self-Iteration

OpenViking has a built-in memory self-iteration loop. At the end of each session, developers can actively trigger the memory extraction mechanism. The system will asynchronously analyze task execution results and user feedback, and automatically update them to the User and Agent memory directories.

• User Memory Update: Update memories related to user preferences, making Agent responses better fit user needs.
• Agent Experience Accumulation: Extract core content such as operational tips and tool usage experience from task execution experience, aiding efficient decision-making in subsequent tasks.

This allows the Agent to get "smarter with use" through interactions with the world, achieving self-evolution. Learn more: Session Management

---

Project Architecture

The OpenViking project adopts a clear modular architecture design. The main directory structure is as follows:

OpenViking/
├── openviking/              # Core source code directory
│   ├── core/               # Core modules: client, engine, filesystem, etc.
│   ├── models/             # Model integration: VLM and Embedding model encapsulation
│   ├── parse/              # Resource parsing: file parsing, detection, OVPack handling
│   ├── retrieve/           # Retrieval module: semantic retrieval, directory recursive retrieval
│   ├── storage/            # Storage layer: vector DB, filesystem queue, observers
│   ├── session/            # Session management: history, memory extraction
│   ├── message/            # Message processing: formatting, conversion
│   ├── prompts/            # Prompt templates: templates for various tasks
│   ├── utils/              # Utilities: config, helpers
│   └── bin/                # Command line tools
├── docs/                    # Project documentation
│   ├── zh/                 # Chinese documentation
│   ├── en/                 # English documentation
│   └── images/             # Documentation images
├── examples/                # Usage examples
├── tests/                   # Test cases
│   ├── client/             # Client tests
│   ├── engine/             # Engine tests
│   ├── integration/        # Integration tests
│   ├── session/            # Session tests
│   └── vectordb/           # Vector DB tests
├── src/                     # C++ extensions (high-performance index and storage)
│   ├── common/             # Common components
│   ├── index/              # Index implementation
│   └── store/              # Storage implementation
├── third_party/             # Third-party dependencies
├── pyproject.toml           # Python project configuration
├── setup.py                 # Setup script
├── LICENSE                  # Open source license
├── CONTRIBUTING.md          # Contributing guide
├── AGENT.md                 # Agent development guide
└── README.md                # Project readme

---

Advanced Reading

For more details, please visit our Full Documentation.

---

Community & Team

About Us

OpenViking is an open-source project initiated and maintained by the ByteDance Volcengine Viking Team.

The Viking team focuses on unstructured information processing and intelligent retrieval, accumulating rich commercial practical experience in context engineering technology:

• 2019: VikingDB vector database supported large-scale use across all ByteDance businesses.
• 2023: VikingDB sold on Volcengine public cloud.
• 2024: Launched developer product matrix: VikingDB, Viking KnowledgeBase, Viking MemoryBase.
• 2025: Created upper-layer application products like AI Search and Vaka Knowledge Assistant.
• Oct 2025: Open-sourced MineContext, exploring proactive AI applications.
• Jan 2026: Open-sourced OpenViking, providing underlying context database support for AI Agents.

For more details, please see: About Us

---

Join the Community

OpenViking is still in its early stages, and there are many areas for improvement and exploration. We sincerely invite every developer passionate about AI Agent technology:

• Light up a precious Star for us to give us the motivation to move forward.
• Visit our Website to understand the philosophy we convey, and use it in your projects via the Documentation. Feel the change it brings and give us feedback on your truest experience.
• Join our community to share your insights, help answer others' questions, and jointly create an open and mutually helpful technical atmosphere:
  • 📱 Lark Group: Scan the QR code to join → View QR Code
  • 💬 WeChat Group: Scan the QR code to add assistant → View QR Code
  • 🎮 Discord: Join Discord Server
  • 🐦 X (Twitter)：Follow us
• Become a Contributor, whether submitting a bug fix or contributing a new feature, every line of your code will be an important cornerstone of OpenViking's growth.

Let's work together to define and build the future of AI Agent context management. The journey has begun, looking forward to your participation!

---

Star Trend

---

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.