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
- Role
- Provider Value
- Example Model
- VLM
- openai
- gpt-4o
- VLM
- volcengine
- doubao-seed-2-0-pro-260215
- VLM
- litellm
- claude-3-5-sonnet-20240620
- ,
- ollama/llama3.1
- Embedding
- openai
- text-embedding-3-large
- Embedding
- volcengine
- doubao-embedding-vision-250615
- Embedding
- jina
- jina-embeddings-v3
- 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 } ] { step . path } → score= { step . score : .3f } " )
Output:
[L0] memories/user_prefs.md → score=0.82
[L1] resources/security/auth.md → score=0.91
[L2] skills/coding/jwt_auth.md → score=0.88
Common Patterns Pattern 1: Agent with Persistent Memory import os from openviking import OpenViking ov = OpenViking ( config_path = "~/.openviking/ov.conf" ) brain = ov . namespace ( "coding_agent" ) def agent_respond ( user_message : str , conversation_history : list ) -
str :
Retrieve relevant context
context_results
brain . search ( user_message , top_k = 5 ) context_text = "\n\n" . join ( r . content for r in context_results )
Build prompt with retrieved context
system_prompt
f"""You are a coding assistant.
Relevant Context
{ context_text } """
... call your LLM here with system_prompt + conversation_history
response
call_llm ( system_prompt , conversation_history , user_message )
Store interaction for future memory
brain . session ( "current" ) . add_turn ( "user" , user_message ) brain . session ( "current" ) . add_turn ( "assistant" , response ) return response Pattern 2: Hierarchical Skill Loading
Register skills from a directory structure
import pathlib skills_dir = pathlib . Path ( "./agent_skills" ) for skill_file in skills_dir . rglob ( "*.md" ) : relative = skill_file . relative_to ( skills_dir ) brain . write ( f"skills/ { relative } " , skill_file . read_text ( ) )
At runtime, retrieve only relevant skills
def get_relevant_skills ( task : str ) -
list [ str ] : results = brain . search ( task , directory = "skills/" , top_k = 3 ) return [ r . content for r in results ] task = "Refactor this class to use dependency injection" skills = get_relevant_skills ( task )