How to Use OpenViking: A Complete Setup Guide for AI Agent Context Management

Mar 16, 2026

Cowrie

Dev @ Bswen

Purpose

When I started building AI agents, context management was my biggest challenge. My agents could access immediate context, but they had no persistent memory. Every session started from scratch. They couldn’t reference documentation I’d previously added, and there was no way to search through accumulated knowledge.

OpenViking solves this problem. It’s a context management database that gives your agents persistent, searchable memory. In this post, I’ll show you how to set it up and use it in under 5 minutes.

What is OpenViking?

OpenViking is a context management system for AI agents. It lets you:

• Add resources (URLs, PDFs, code repositories) to a persistent knowledge base
• Search those resources semantically (by meaning, not just keywords)
• Access everything through a Unix-like CLI or Python SDK

The key innovation is the virtual filesystem paradigm. You interact with context the same way you interact with files: list, read, find, grep. If you know ls and find, you already know OpenViking.

Environment

Before starting, I made sure I had:

• Python 3.10 or higher
• Go 1.22+ (for AGFS components)
• C++ Compiler: GCC 9+ or Clang 11+
• An API key from OpenAI or another LLM provider

Step 1: Installation

I installed OpenViking with pip:

Terminal

pip install openviking --upgrade --force-reinstall

This gives you three commands:

• openviking - Main CLI (alias for ov)
• ov - Short CLI alias
• openviking-server - The backend server

For the Rust CLI (optional but faster):

Terminal

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

Step 2: Model Configuration

OpenViking needs two types of models:

1. Embedding model - For semantic search
2. VLM (Vision Language Model) - For understanding content

I created the configuration file at ~/.openviking/ov.conf:

~/.openviking/ov.conf

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

Provider Options

OpenViking supports multiple providers:

Provider	Best For	Models
OpenAI	Default choice	GPT-4o, text-embedding-3-large
Volcengine	Chinese market	Doubao models
LiteLLM	Multi-provider	Anthropic, DeepSeek, Gemini, Qwen, vLLM, Ollama

For LiteLLM configuration:

LiteLLM Provider Example

{
  "vlm": {
    "api_base": "http://localhost:4000",
    "api_key": "your-litellm-key",
    "provider": "litellm",
    "model": "anthropic/claude-3-opus-20240229"
  }
}

Step 3: Start the Server

I started the OpenViking server:

Terminal

openviking-server

The server runs in the foreground. I keep it running in a separate terminal or use tmux:

Terminal (with tmux)

tmux new -s openviking
openviking-server
# Ctrl+B D to detach

Step 4: CLI Quick Commands

With the server running, I tested the CLI.

Check Status

Terminal

ov status

Output:

Server: running
Workspace: /home/cowrie/openviking_workspace
Resources: 0

Add a Resource

I added the OpenViking GitHub repository:

Terminal

ov add-resource https://github.com/volcengine/OpenViking --wait

The --wait flag blocks until indexing completes. Without it, indexing happens in the background.

Output:

Adding resource: https://github.com/volcengine/OpenViking
Cloning repository...
Processing files...
Creating embeddings...
Resource added: volcengine/OpenViking

List Resources

Terminal

ov ls viking://resources/

Output:

viking://resources/volcengine/
viking://resources/volcengine/OpenViking/

View Directory Tree

Terminal

ov tree viking://resources/volcengine -L 2

Output:

viking://resources/volcengine/
└── OpenViking/
    ├── docs/
    ├── src/
    ├── README.md
    └── pyproject.toml

Semantic Search

This is the key feature. I searched for what OpenViking is:

Terminal

ov find "what is openviking"

Output:

Found 5 results:

1. viking://resources/volcengine/OpenViking/README.md
   Score: 0.89
   Abstract: OpenViking is a context management database for AI agents...

2. viking://resources/volcengine/OpenViking/docs/intro.md
   Score: 0.85
   Abstract: OpenViking provides persistent memory for AI agents...

3. viking://resources/volcengine/OpenViking/docs/quickstart.md
   Score: 0.82
   Abstract: Get started with OpenViking in 5 minutes...

Grep Within Resources

For exact string matching:

Terminal

ov grep "openviking" --uri viking://resources/volcengine/OpenViking/docs

Output:

docs/intro.md:3:OpenViking is a context management database
docs/quickstart.md:1:# OpenViking Quick Start
docs/quickstart.md:5:Install OpenViking with pip...

Step 5: Python SDK Usage

For programmatic access, I used the Python SDK:

openviking_demo.py

from openviking.client import OpenViking

# Initialize client
client = OpenViking()

# Add a resource
client.add_resource(
    "https://docs.example.com/api.pdf",
    reason="API documentation for reference"
)

# Semantic search
results = client.find("authentication methods")

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

# Filesystem operations
files = client.ls("viking://resources/")
print(f"Available resources: {files}")

# Read specific file
content = client.read("viking://resources/docs/auth.md")
print(content)

Async Usage

openviking_async.py

import asyncio
from openviking.client import AsyncOpenViking

async def main():
    client = AsyncOpenViking()

    # Add multiple resources in parallel
    urls = [
        "https://github.com/volcengine/OpenViking",
        "https://docs.python.org/3/",
        "https://fastapi.tiangolo.com/"
    ]

    tasks = [client.add_resource(url) for url in urls]
    await asyncio.gather(*tasks)

    # Search
    results = await client.find("how to create a fastapi endpoint")
    for ctx in results.resources:
        print(f"Found in: {ctx.uri}")

asyncio.run(main())

Common Issues

Issue 1: Permission Denied on Workspace

When I started the server, I got:

Error: Cannot create workspace directory: /home/other/openviking_workspace
Permission denied

Fix: Ensure the workspace directory exists and is writable:

Terminal

mkdir -p ~/openviking_workspace
chmod 755 ~/openviking_workspace

Issue 2: API Key Not Found

When running semantic search:

Error: OPENAI_API_KEY not found in environment

Fix: Set the API key in the config file or environment:

Terminal

export OPENAI_API_KEY="sk-proj-xxxxx"

Or add it to ~/.openviking/ov.conf.

Issue 3: Server Not Running

When I ran CLI commands:

Error: Cannot connect to OpenViking server at localhost:8080

Fix: Start the server first:

Terminal

openviking-server
# Or check if it's already running
ps aux | grep openviking

Issue 4: Embedding Dimension Mismatch

When adding resources:

Error: Embedding dimension mismatch: expected 3072, got 1536

Fix: Update the dimension in your config to match the model:

{
  "embedding": {
    "dense": {
      "model": "text-embedding-3-small",
      "dimension": 1536
    }
  }
}

Best Practices

DO

Use meaningful resource names

Terminal

# Good: Descriptive naming
ov add-resource https://github.com/volcengine/OpenViking --name "openviking-source"

# Bad: Default naming can be unclear
ov add-resource https://github.com/volcengine/OpenViking

Organize with directories

Terminal

# Create structure for different projects
ov mkdir viking://resources/project-alpha/
ov mkdir viking://resources/project-beta/

Use specific search queries

Terminal

# Good: Specific query
ov find "how to configure embedding model in openviking"

# Less effective: Vague query
ov find "config"

DON’T

Don’t add duplicate resources

Terminal

# Bad: Adding same URL twice wastes storage and compute
ov add-resource https://github.com/volcengine/OpenViking
ov add-resource https://github.com/volcengine/OpenViking

# Good: Check first
ov ls viking://resources/ | grep OpenViking

Don’t skip the —wait flag for testing

Terminal

# Bad for scripts: Returns immediately, resource not ready
ov add-resource https://example.com/docs

# Good for scripts: Waits until indexing completes
ov add-resource https://example.com/docs --wait

Don’t use small embedding dimensions for large corpuses

Bad Configuration

{
  "embedding": {
    "dense": {
      "dimension": 256  // Too small for semantic search quality
    }
  }
}

Comparison with Alternatives

I tested OpenViking against other context management tools:

Feature	OpenViking	ChromaDB	Pinecone	Local Files
Setup Time	5 min	15 min	20 min	Instant
CLI Interface	Yes	No	No	Yes
Semantic Search	Yes	Yes	Yes	No
Virtual Filesystem	Yes	No	No	Yes
Self-Hosted	Yes	Yes	No	Yes
Cost	API only	Free	Paid	Free

OpenViking wins on developer experience. The Unix-like CLI makes it intuitive for anyone who knows basic shell commands.

Summary

In this post, I showed how to set up and use OpenViking for AI agent context management. The key points are:

• Install with pip install openviking
• Configure embedding and VLM models in ~/.openviking/ov.conf
• Start the server with openviking-server
• Use ov add-resource to add knowledge
• Use ov find for semantic search

The entire setup takes about 5 minutes. The virtual filesystem paradigm makes context management feel natural: list, read, find, grep. If you’re building AI agents that need persistent memory, OpenViking provides a clean, developer-friendly solution.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

• 👨‍💻 OpenViking GitHub Repository
• 👨‍💻 OpenViking Documentation

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!

Comments

Tags:

• ai-agents
• ai
• automation

Why Be Concise Fails with Claude: Use Hard Constraints Instead

LAP vs Context7: Which is Better for LLM API Context? (2026 Comparison)