FAQ

Basic Concepts

What is OpenViking? What problems does it solve?

OpenViking is an open-source context database designed specifically for AI Agents. It solves core pain points when building AI Agents:

• Fragmented Context: Memories, resources, and skills are scattered everywhere, difficult to manage uniformly
• Poor Retrieval Effectiveness: Traditional RAG's flat storage lacks global view, making it hard to understand complete context
• Unobservable Context: Implicit retrieval chains are like black boxes, difficult to debug when errors occur
• Limited Memory Iteration: Lacks Agent-related task memory and self-evolution capabilities

OpenViking unifies all context management through a filesystem paradigm, enabling tiered delivery and self-iteration.

What's the fundamental difference between OpenViking and traditional vector databases?

What is the L0/L1/L2 layered model? Why is it needed?

L0/L1/L2 is OpenViking's progressive content loading mechanism, solving the problem of "stuffing massive context into prompts all at once":

This design allows Agents to browse abstracts for quick positioning, then load details on demand, significantly saving token consumption.

What is Viking URI? What's its purpose?

Viking URI is OpenViking's unified resource identifier, formatted as viking://{scope}/{path}. It enables precise location of any context:

viking://
├── resources/              # Knowledge base: documents, code, web pages, etc.
│   └── my_project/
├── user/
│   └── {user_id}/          # Private context for a user
│       ├── memories/       # User memories
│       ├── resources/      # Private user resources
│       ├── skills/         # Private user skills (default)
│       └── peers/{peer_id}/
│           ├── memories/   # Memories scoped to a peer
│           └── resources/  # Resources scoped to a peer
└── agent/                  # Optional account-wide Agent capabilities
    └── skills/             # Shared skills

Installation & Configuration

What are the environment requirements?

• Python Version: 3.10 or higher
• Build Tools (if installing from source or on unsupported platforms): Rust/Cargo, GCC 9+ or Clang 11+
• Required Dependencies: Embedding model (Volcengine Doubao recommended)
• Optional Dependencies:
  • VLM (Vision Language Model): For multimodal content processing and semantic extraction
  • Rerank model: For improved retrieval precision

How does OpenViking access the AGFS filesystem?

OpenViking runs the RAGFS filesystem in-process through the Rust binding (ragfs_python / RAGFSBindingClient). The binding executes filesystem logic directly within the Python process, giving extremely high performance and zero network latency. A compiled RAGFS shared library must be available locally (shipped in the prebuilt Wheel, or built from source).

[!WARNING] OpenViking no longer supports the AGFS HTTP client mode. AGFS / RAGFS filesystem access now happens only through the in-process Rust binding (RAGFSBindingClient). This does not affect the OpenViking server HTTP API, the ov CLI, or AsyncHTTPClient / SyncHTTPClient when they connect to an OpenViking server.

What should I do if I encounter "AGFS binding library not found"?

This usually means the RAGFS shared library is not available in your environment. Re-compile and install it by running pip install -e . --force-reinstall in the project root (requires a Rust toolchain).

How do I install/upgrade OpenViking?

pip install openviking --upgrade --force-reinstall

How do I configure OpenViking?

Create an ~/.openviking/ov.conf configuration file in your project directory:

{
  "embedding": {
    "dense": {
      "provider": "volcengine",
      "api_key": "your-api-key",
      "model": "doubao-embedding-vision-251215",
      "dimension": 1024,
      "input": "multimodal"
    }
  },
  "vlm": {
    "provider": "volcengine",
    "api_key": "your-api-key",
    "model": "doubao-seed-2-0-lite-260428",
    "api_base": "https://ark.cn-beijing.volces.com/api/v3"
  },
  "rerank": {
    "provider": "volcengine",
    "api_key": "your-api-key",
    "model": "doubao-rerank-250615"
  },
  "storage": {
    "workspace": "./data",
    "agfs": { "backend": "local" },
    "vectordb": { "backend": "local" }
  }
}

Config files at the default path ~/.openviking/ov.conf are loaded automatically; you can also specify a different path via the OPENVIKING_CONFIG_FILE environment variable or --config flag. See Configuration Guide for details.

What Embedding providers are supported?

Supports Dense, Sparse, and Hybrid embedding modes.

Usage Guide

How do I initialize the client?

import openviking as ov

# Async client - embedded mode (recommended)
client = ov.AsyncOpenViking(path="./my_data")
await client.initialize()

# Async client - HTTP client mode
client = ov.AsyncHTTPClient(url="http://localhost:1933", api_key="your-key")
await client.initialize()

The SDK constructor only accepts url, api_key, and path parameters. Other configuration (embedding, vlm, etc.) is managed through the ov.conf config file.

What file formats are supported?

How do I add resources?

# Add single file
await client.add_resource(
    "./document.pdf",
    reason="Project technical documentation",  # Describe resource purpose to improve retrieval quality
    to="viking://resources/docs/"  # Specify storage location
)

# Add web page
await client.add_resource(
    "https://example.com/api-docs",
    reason="API reference documentation"
)

# Wait for processing to complete
await client.wait_processed()

What's the difference between find() and search()? Which should I use?

# find(): Simple direct semantic search
results = await client.find(
    "OAuth authentication flow",
    target_uri="viking://resources/"
)

# search(): Complex tasks requiring intent analysis
results = await client.search(
    "Help me implement user login functionality",
    session_info=session
)

Selection Guide:

• Know exactly what you're looking for → Use find()
• Complex tasks needing multiple context types → Use search()

How do I use session management?

Session management is a core capability of OpenViking, supporting conversation tracking and memory extraction:

# Create session
session = client.session()

# Add conversation messages
await session.add_message("user", [{"type": "text", "text": "Help me analyze performance issues in this code"}])
await session.add_message("assistant", [{"type": "text", "text": "Let me analyze..."}])

# Mark used context (for tracking)
await session.used(["viking://resources/code/main.py"])

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

What memory types does OpenViking support?

OpenViking includes memory types such as profile, preferences, entities, events, identity, soul, cases, trajectories, experiences, tools, and skills. After a session is committed, the active memory policy determines which useful information to extract. Applications can also extend or adjust the memory types for their own needs.

Memories are stored in the current User or Peer namespace; there is no current writable viking://agent/memories directory. See Context Types for the complete type and path mapping.

How do I use Unix-like filesystem APIs?

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

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

# Get abstract (L0)
abstract = await client.abstract("viking://resources")

# Get overview (L1)
overview = await client.overview("viking://resources")

Retrieval Optimization

How do I improve retrieval quality?

1. Use Rerank model: Configuring Rerank significantly improves ranking effectiveness
2. Provide meaningful reason: Describe purpose when adding resources to help system understand resource value
3. Organize directory structure properly: Use target parameter to group related resources together
4. Use session context: search() leverages session history for intent analysis
5. Choose appropriate Embedding mode: Use multimodal input for multimodal content

How is the retrieval result score calculated?

OpenViking uses a score propagation mechanism:

Final Score = 0.5 × Embedding Similarity + 0.5 × Parent Directory Score

This design gives content under high-scoring directories a boost, reflecting the importance of "contextual environment".

What is directory recursive retrieval?

Directory recursive retrieval is OpenViking's innovative retrieval strategy:

1. Intent Analysis: Analyze query to generate multiple retrieval conditions
2. Initial Positioning: Vector retrieval to locate high-scoring directories
3. Refined Exploration: Secondary retrieval within high-scoring directories
4. Recursive Drill-down: Layer-by-layer recursion until convergence
5. Result Aggregation: Return the most relevant context

This strategy finds semantically matching fragments while understanding the complete context of the information.

Troubleshooting

Resources not being indexed after adding

Possible causes and solutions:

1. Didn't wait for processing to complete

   pythonCopy

   await client.add_resource("./doc.pdf")
   await client.wait_processed()  # Must wait
   

2. Embedding model configuration error

   • Check if api_key in ~/.openviking/ov.conf is correct
   • Confirm model name and endpoint are configured correctly

3. Unsupported file format

   • Check if file extension is in the supported list
   • Confirm file content is valid and not corrupted

4. View processing logs

   pythonCopy

   import logging
   logging.basicConfig(level=logging.DEBUG)
   

Search not returning expected results

Troubleshooting steps:

1. Confirm resources have been processed

   pythonCopy

   # Check if resources exist
   items = await client.ls("viking://resources/")
   

2. Check target_uri filter condition

   • Ensure search scope includes target resources
   • Try expanding search scope

3. Try different query approaches

   • Use more specific or broader keywords
   • Compare effects of find() and search()

4. Check L0 abstract quality

   pythonCopy

   abstract = await client.abstract("viking://resources/your-doc")
   print(abstract)  # Confirm abstract accurately reflects content
   

Memory extraction not working

Troubleshooting steps:

1. Ensure commit() was called

   pythonCopy

   await session.commit()  # Triggers memory extraction
   

2. Check VLM configuration

   • Memory extraction requires VLM model
   • Confirm vlm configuration is correct

3. Confirm conversation content is meaningful

   • Casual chat may not produce memories
   • Needs to contain extractable information (preferences, entities, events, etc.)

4. View extracted memories

   pythonCopy

   memories = await client.find("", target_uri="viking://user/memories/")
   

Performance issues

Optimization suggestions:

1. Batch processing: Adding multiple resources at once is more efficient than one by one
2. Set appropriate batch_size: Adjust batch processing size in Embedding configuration
3. Use local storage: Use local backend during development to reduce network latency
4. Async operations: Fully utilize AsyncOpenViking / AsyncHTTPClient's async capabilities

Deployment

What's the difference between embedded mode and service mode?

# Embedded mode
client = ov.AsyncOpenViking(path="./data")

# HTTP client mode (connects to a remote server)
client = ov.AsyncHTTPClient(url="http://localhost:1933", api_key="your-key")

Is OpenViking open source?

Yes, OpenViking main project is open source under the AGPL-3.0 license, and examples/ and crates/ov_cli are licensed under the Apache 2.0 license.

Related Documentation

• Introduction - Understand OpenViking's design philosophy
• Quick Start - 5-minute tutorial
• Architecture Overview - Deep dive into system design
• Retrieval Mechanism - Detailed retrieval process
• Configuration Guide - Complete configuration reference