OpenViking Context Database

Skill by ara.so — Daily 2026 Skills collection.

OpenViking is an open-source context database for AI Agents that replaces fragmented vector stores with a unified filesystem paradigm. It manages agent memory, resources, and skills in a tiered L0/L1/L2 structure, enabling hierarchical context delivery, observable retrieval trajectories, and self-evolving session memory.

Installation

Python Package

pip install openviking --upgrade --force-reinstall

Optional Rust CLI

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

# Or build from source (requires Rust toolchain)
cargo install --git https://github.com/volcengine/OpenViking ov_cli

Prerequisites

• Python 3.10+
• Go 1.22+ (for AGFS components)
• GCC 9+ or Clang 11+ (for core extensions)

Configuration

Create ~/.openviking/ov.conf:

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

Note: OpenViking reads api_key values as strings; use environment variable injection at startup rather than literal secrets.

Provider Options

LiteLLM VLM Examples

{
  "vlm": {
    "provider": "litellm",
    "model": "claude-3-5-sonnet-20240620",
    "api_key": "$ANTHROPIC_API_KEY"
  }
}

{
  "vlm": {
    "provider": "litellm",
    "model": "ollama/llama3.1",
    "api_base": "http://localhost:11434"
  }
}

{
  "vlm": {
    "provider": "litellm",
    "model": "deepseek-chat",
    "api_key": "$DEEPSEEK_API_KEY"
  }
}

Core Concepts

Filesystem Paradigm

OpenViking organizes agent context like a filesystem:

workspace/
├── memories/          # Long-term agent memories (L0 always loaded)
│   ├── user_prefs/
│   └── task_history/
├── resources/         # External knowledge, documents (L1 on demand)
│   ├── codebase/
│   └── docs/
└── skills/            # Reusable agent capabilities (L2 retrieved)
    ├── coding/
    └── analysis/

Tiered Context Loading (L0/L1/L2)

• L0: Always loaded — core identity, persistent preferences
• L1: Loaded on demand — relevant resources fetched per task
• L2: Semantically retrieved — skills pulled by similarity search

This tiered approach minimizes token consumption while maximizing context relevance.

Python API Usage

Basic Setup

import os
from openviking import OpenViking

# Initialize with config file
ov = OpenViking(config_path="~/.openviking/ov.conf")

# Or initialize programmatically
ov = OpenViking(
    workspace="/home/user/openviking_workspace",
    vlm_provider="openai",
    vlm_model="gpt-4o",
    vlm_api_key=os.environ["OPENAI_API_KEY"],
    embedding_provider="openai",
    embedding_model="text-embedding-3-large",
    embedding_api_key=os.environ["OPENAI_API_KEY"],
    embedding_dimension=1536,
)

Managing a Context Namespace (Agent Brain)

# Create or open a namespace (like a filesystem root for one agent)
brain = ov.namespace("my_agent")

# Add a memory file
brain.write("memories/user_prefs.md", """
# User Preferences
- Language: Python
- Code style: PEP8
- Preferred framework: FastAPI
""")

# Add a resource document
brain.write("resources/api_docs/stripe.md", open("stripe_docs.md").read())

# Add a skill
brain.write("skills/coding/write_tests.md", """
# Skill: Write Unit Tests
When asked to write tests, use pytest with fixtures.
Always mock external API calls. Aim for 80%+ coverage.
""")

Querying Context

# Semantic search across the namespace
results = brain.search("how does the user prefer code to be formatted?")
for result in results:
    print(result.path, result.score, result.content[:200])

# Directory-scoped retrieval (recursive)
skill_results = brain.search(
    query="write unit tests for a FastAPI endpoint",
    directory="skills/",
    top_k=3,
)

# Direct path read (L0 always available)
prefs = brain.read("memories/user_prefs.md")
print(prefs.content)

Session Memory & Auto-Compression

# Start a session — OpenViking tracks turns and auto-compresses
session = brain.session("task_build_api")

# Add conversation turns
session.add_turn(role="user", content="Build me a REST API for todo items")
session.add_turn(role="assistant", content="I'll create a FastAPI app with CRUD operations...")

# After many turns, trigger compression to extract long-term memory
summary = session.compress()
# Compressed insights are automatically written to memories/

# End session — persists extracted memories
session.close()

Retrieval Trajectory (Observable RAG)

# Enable trajectory tracking to observe retrieval decisions
with brain.observe() as tracker:
    results = brain.search("authentication best practices")
    
trajectory = tracker.trajectory()
for step in trajectory.steps:
    print(f"[{step.level