Back to Details

openviking-context-database

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

OpenViking Context Database

OpenViking 上下文数据库

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.
由ara.so提供的技能指南 — 2026每日技能合集。
OpenViking是一款面向AI Agents的开源上下文数据库，它以统一的文件系统范式取代了碎片化的向量存储。它采用L0/L1/L2分层结构管理智能体的记忆、资源与技能，支持分层上下文交付、可观测的检索轨迹，以及自我演化的会话记忆。

Installation

安装

Python Package

Python 包

bash
pip install openviking --upgrade --force-reinstall
bash
pip install openviking --upgrade --force-reinstall

Optional Rust CLI

可选 Rust CLI

bash
undefined
bash
undefined

Install via script

通过脚本安装

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

Or build from source (requires Rust toolchain)

或从源码构建（需要Rust工具链）

cargo install --git https://github.com/volcengine/OpenViking ov_cli
undefined
cargo install --git https://github.com/volcengine/OpenViking ov_cli
undefined

Prerequisites

前置依赖

  • Python 3.10+
  • Go 1.22+ (for AGFS components)
  • GCC 9+ or Clang 11+ (for core extensions)
  • Python 3.10+
  • Go 1.22+（用于AGFS组件）
  • GCC 9+ 或 Clang 11+（用于核心扩展）

Configuration

配置

Create 
~/.openviking/ov.conf
:
json
{
  "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.
创建
~/.openviking/ov.conf
：
json
{
  "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
  }
}
注意： OpenViking会将
api_key
值读取为字符串；请在启动时使用环境变量注入，而非直接写入明文密钥。

Provider Options

提供商选项

RoleProvider ValueExample 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
角色提供商值示例模型
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

LiteLLM VLM 示例

json
{
  "vlm": {
    "provider": "litellm",
    "model": "claude-3-5-sonnet-20240620",
    "api_key": "$ANTHROPIC_API_KEY"
  }
}
json
{
  "vlm": {
    "provider": "litellm",
    "model": "ollama/llama3.1",
    "api_base": "http://localhost:11434"
  }
}
json
{
  "vlm": {
    "provider": "litellm",
    "model": "deepseek-chat",
    "api_key": "$DEEPSEEK_API_KEY"
  }
}
json
{
  "vlm": {
    "provider": "litellm",
    "model": "claude-3-5-sonnet-20240620",
    "api_key": "$ANTHROPIC_API_KEY"
  }
}
json
{
  "vlm": {
    "provider": "litellm",
    "model": "ollama/llama3.1",
    "api_base": "http://localhost:11434"
  }
}
json
{
  "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/
OpenViking像管理文件系统一样组织智能体上下文：
workspace/
├── memories/          # 智能体长期记忆（L0始终加载）
│   ├── user_prefs/
│   └── task_history/
├── resources/         # 外部知识、文档（L1按需加载）
│   ├── codebase/
│   └── docs/
└── skills/            # 可复用智能体能力（L2检索获取）
    ├── coding/
    └── analysis/

Tiered Context Loading (L0/L1/L2)

分层上下文加载（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.
  • L0：始终加载 — 核心身份、持久化偏好
  • L1：按需加载 — 针对任务获取相关资源
  • L2：语义检索 — 通过相似性搜索获取技能
这种分层方法在最大化上下文相关性的同时，最小化了令牌消耗。

Python API Usage

Python API 使用

Basic Setup

基础设置

python
import os
from openviking import OpenViking
python
import os
from openviking import OpenViking

Initialize with config file

使用配置文件初始化

ov = OpenViking(config_path="~/.openviking/ov.conf")
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, )
undefined
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, )
undefined

Managing a Context Namespace (Agent Brain)

管理上下文命名空间（智能体大脑）

python
undefined
python
undefined

Create or open a namespace (like a filesystem root for one agent)

创建或打开一个命名空间（相当于单个智能体的文件系统根目录）

brain = ov.namespace("my_agent")
brain = ov.namespace("my_agent")

Add a memory file

添加记忆文件

brain.write("memories/user_prefs.md", """
brain.write("memories/user_prefs.md", """

User Preferences

用户偏好

  • Language: Python
  • Code style: PEP8
  • Preferred framework: FastAPI """)
  • 编程语言：Python
  • 代码风格：PEP8
  • 偏好框架：FastAPI """)

Add a resource document

添加资源文档

brain.write("resources/api_docs/stripe.md", open("stripe_docs.md").read())
brain.write("resources/api_docs/stripe.md", open("stripe_docs.md").read())

Add a skill

添加技能

brain.write("skills/coding/write_tests.md", """
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. """)
undefined
当被要求编写测试时，使用pytest及夹具。 始终模拟外部API调用。目标覆盖率80%以上。 """)
undefined

Querying Context

查询上下文

python
undefined
python
undefined

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])
results = brain.search("用户偏好的代码格式是什么？") 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, )
skill_results = brain.search( query="为FastAPI端点编写单元测试", directory="skills/", top_k=3, )

Direct path read (L0 always available)

直接路径读取（L0始终可用）

prefs = brain.read("memories/user_prefs.md") print(prefs.content)
undefined
prefs = brain.read("memories/user_prefs.md") print(prefs.content)
undefined

Session Memory & Auto-Compression

会话记忆与自动压缩

python
undefined
python
undefined

Start a session — OpenViking tracks turns and auto-compresses

启动会话 — OpenViking会跟踪对话轮次并自动压缩

session = brain.session("task_build_api")
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...")
session.add_turn(role="user", content="为待办事项构建一个REST API") session.add_turn(role="assistant", content="我将创建一个带CRUD操作的FastAPI应用...")

After many turns, trigger compression to extract long-term memory

多轮对话后，触发压缩以提取长期记忆

summary = session.compress()
summary = session.compress()

Compressed insights are automatically written to memories/

压缩后的见解会自动写入memories/目录

End session — persists extracted memories

结束会话 — 持久化提取的记忆

session.close()
undefined
session.close()
undefined

Retrieval Trajectory (Observable RAG)

检索轨迹（可观测RAG）

python
undefined
python
undefined

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

---
with brain.observe() as tracker: results = brain.search("身份验证最佳实践")
trajectory = tracker.trajectory() for step in trajectory.steps: print(f"[{step.level}] {step.path} → score={step.score:.3f}") # 输出示例： # [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

模式1：带持久化记忆的智能体

python
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.
python
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:
    # 检索相关上下文
    context_results = brain.search(user_message, top_k=5)
    context_text = "\n\n".join(r.content for r in context_results)
    
    # 构建包含检索上下文的提示词
    system_prompt = f"""你是一个编程助手。

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
undefined
{context_text} """ # ... 在此处调用LLM，传入system_prompt + conversation_history response = call_llm(system_prompt, conversation_history, user_message)
# 存储交互内容以用于未来记忆
brain.session("current").add_turn("user", user_message)
brain.session("current").add_turn("assistant", response)

return response
undefined

Pattern 2: Hierarchical Skill Loading

模式2：分层技能加载

python
undefined
python
undefined

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())
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)
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 = "重构此类以使用依赖注入" skills = get_relevant_skills(task)

Returns only DI-related skills, not all registered skills

仅返回与依赖注入相关的技能，而非所有已注册技能

undefined
undefined

Pattern 3: RAG over Codebase

模式3：针对代码库的RAG

python
import subprocess
import pathlib

brain = ov.namespace("codebase_agent")
python
import subprocess
import pathlib

brain = ov.namespace("codebase_agent")

Index a codebase

索引代码库

def index_codebase(repo_path: str): for f in pathlib.Path(repo_path).rglob("*.py"): content = f.read_text(errors="ignore") # Store with relative path as key rel = f.relative_to(repo_path) brain.write(f"resources/codebase/{rel}", content)
index_codebase("/home/user/myproject")
def index_codebase(repo_path: str): for f in pathlib.Path(repo_path).rglob("*.py"): content = f.read_text(errors="ignore") # 以相对路径为键存储 rel = f.relative_to(repo_path) brain.write(f"resources/codebase/{rel}", content)
index_codebase("/home/user/myproject")

Query with directory scoping

按目录范围查询

def find_relevant_code(query: str) -> list: return brain.search( query=query, directory="resources/codebase/", top_k=5, )
hits = find_relevant_code("database connection pooling") for h in hits: print(h.path, "\n", h.content[:300])
undefined
def find_relevant_code(query: str) -> list: return brain.search( query=query, directory="resources/codebase/", top_k=5, )
hits = find_relevant_code("数据库连接池") for h in hits: print(h.path, "\n", h.content[:300])
undefined

Pattern 4: Multi-Agent Shared Context

模式4：多智能体共享上下文

python
undefined
python
undefined

Agent 1 writes discoveries

智能体1写入发现的内容

agent1_brain = ov.namespace("researcher_agent") agent1_brain.write("memories/findings/api_rate_limits.md", """
agent1_brain = ov.namespace("researcher_agent") agent1_brain.write("memories/findings/api_rate_limits.md", """

API Rate Limits Discovered

发现的API速率限制

  • Stripe: 100 req/s in live mode
  • SendGrid: 600 req/min """)
  • Stripe：生产环境100次请求/秒
  • SendGrid：600次请求/分钟 """)

Agent 2 reads shared workspace findings

智能体2读取共享工作区中的发现

agent2_brain = ov.namespace("coder_agent")
agent2_brain = ov.namespace("coder_agent")

Cross-namespace read (if permitted)

跨命名空间读取（如果允许）

shared = ov.namespace("shared_knowledge") rate_limits = shared.read("memories/findings/api_rate_limits.md")

---
shared = ov.namespace("shared_knowledge") rate_limits = shared.read("memories/findings/api_rate_limits.md")

---

CLI Commands (ov_cli)

CLI 命令（ov_cli）

bash
undefined
bash
undefined

Check version

查看版本

ov --version
ov --version

List namespaces

列出命名空间

ov namespace list
ov namespace list

Create a namespace

创建命名空间

ov namespace create my_agent
ov namespace create my_agent

Write context file

写入上下文文件

ov write my_agent/memories/prefs.md --file ./prefs.md
ov write my_agent/memories/prefs.md --file ./prefs.md

Read a file

读取文件

ov read my_agent/memories/prefs.md
ov read my_agent/memories/prefs.md

Search context

搜索上下文

ov search my_agent "how to handle authentication" --top-k 5
ov search my_agent "如何处理身份验证" --top-k 5

Show retrieval trajectory for a query

显示查询的检索轨迹

ov search my_agent "database migrations" --trace
ov search my_agent "数据库迁移" --trace

Compress a session

压缩会话

ov session compress my_agent/task_build_api
ov session compress my_agent/task_build_api

List files in namespace

列出命名空间中的文件

ov ls my_agent/skills/
ov ls my_agent/skills/

Delete a context file

删除上下文文件

ov rm my_agent/resources/outdated_docs.md
ov rm my_agent/resources/outdated_docs.md

Export namespace to local directory

将命名空间导出到本地目录

ov export my_agent ./exported_brain/
ov export my_agent ./exported_brain/

Import from local directory

从本地目录导入

ov import ./exported_brain/ my_agent_restored

---
ov import ./exported_brain/ my_agent_restored

---

Troubleshooting

故障排除

Config Not Found

配置文件未找到

bash
undefined
bash
undefined

Verify config location

验证配置文件位置

ls -la ~/.openviking/ov.conf
ls -la ~/.openviking/ov.conf

OpenViking also checks OV_CONFIG env var

OpenViking也会检查OV_CONFIG环境变量

export OV_CONFIG=/path/to/custom/ov.conf
undefined
export OV_CONFIG=/path/to/custom/ov.conf
undefined

Embedding Dimension Mismatch

嵌入维度不匹配

If you switch embedding models, the stored vector dimensions will conflict:
python
undefined
如果切换嵌入模型，存储的向量维度会冲突：
python
undefined

Check current dimension setting vs stored index

检查当前维度设置与存储的索引

Solution: re-index after model change

解决方案：更换模型后重新索引

brain.reindex(force=True)
undefined
brain.reindex(force=True)
undefined

Workspace Permission Errors

工作区权限错误

bash
undefined
bash
undefined

Ensure workspace directory is writable

确保工作区目录可写

chmod -R 755 /home/user/openviking_workspace
chmod -R 755 /home/user/openviking_workspace

Check disk space (embedding indexes can be large)

检查磁盘空间（嵌入索引可能很大）

df -h /home/user/openviking_workspace
undefined
df -h /home/user/openviking_workspace
undefined

LiteLLM Provider Not Detected

LiteLLM 提供商未被检测到

python
undefined
python
undefined

Use explicit prefix for ambiguous models

对模糊模型使用显式前缀

{ "vlm": { "provider": "litellm", "model": "openrouter/anthropic/claude-3-5-sonnet", # full prefix required "api_key": "$OPENROUTER_API_KEY", "api_base": "https://openrouter.ai/api/v1" } }
undefined
{ "vlm": { "provider": "litellm", "model": "openrouter/anthropic/claude-3-5-sonnet", # 需要完整前缀 "api_key": "$OPENROUTER_API_KEY", "api_base": "https://openrouter.ai/api/v1" } }
undefined

High Token Usage

令牌使用量过高

Enable tiered loading to reduce L1/L2 fetches:
python
undefined
启用分层加载以减少L1/L2的获取量：
python
undefined

Scope searches tightly to avoid over-fetching

严格限定搜索范围以避免过度获取

results = brain.search( query=user_message, directory="skills/relevant_domain/", # narrow scope top_k=2, # fewer results min_score=0.75, # quality threshold )
undefined
results = brain.search( query=user_message, directory="skills/relevant_domain/", # 缩小范围 top_k=2, # 减少结果数量 min_score=0.75, # 质量阈值 )
undefined

Slow Indexing on Large Codebases

大型代码库索引缓慢

python
undefined
python
undefined

Increase concurrency in config

在配置中增加并发数

{ "embedding": { "max_concurrent": 20 # increase from default 10 }, "vlm": { "max_concurrent": 50 } }
{ "embedding": { "max_concurrent": 20 # 从默认10增加 }, "vlm": { "max_concurrent": 50 } }

Or batch-write with async

或使用异步批量写入

import asyncio
async def index_async(files): tasks = [brain.awrite(f"resources/{p}", c) for p, c in files] await asyncio.gather(*tasks)

---
import asyncio
async def index_async(files): tasks = [brain.awrite(f"resources/{p}", c) for p, c in files] await asyncio.gather(*tasks)

---

Environment Variables Reference

环境变量参考

VariablePurpose
OV_CONFIG
Path to 
ov.conf
override
OPENAI_API_KEY
OpenAI API key for VLM/embedding
ANTHROPIC_API_KEY
Anthropic Claude via LiteLLM
DEEPSEEK_API_KEY
DeepSeek via LiteLLM
GEMINI_API_KEY
Google Gemini via LiteLLM
OV_LOG_LEVEL
Override log level (
DEBUG
, 
INFO
, 
WARN
)
OV_WORKSPACE
Override workspace path
变量用途
OV_CONFIG
覆盖
ov.conf
的路径
OPENAI_API_KEY
用于VLM/嵌入的OpenAI API密钥
ANTHROPIC_API_KEY
通过LiteLLM使用Anthropic Claude
DEEPSEEK_API_KEY
通过LiteLLM使用DeepSeek
GEMINI_API_KEY
通过LiteLLM使用Google Gemini
OV_LOG_LEVEL
覆盖日志级别（
DEBUG
, 
INFO
, 
WARN
）
OV_WORKSPACE
覆盖工作区路径

Resources

资源