春光不自留，莫怪东风恶。——莎士比亚

OpenViking

OpenViking: The Context Database for AI Agents

English / 中文 / 日本語

Website · GitHub · Issues · Docs






👋 Join our Community

📱 Lark Group · WeChat · Discord · X

volcengine%2FOpenViking | Trendshift

OpenViking：给 AI Agent 一座“可管理、可追踪、会自我进化”的上下文基地

如果 AI Agent 是一位在信息海里航行的维京人，那 OpenViking 就是他背后的“长屋”：
火塘不熄，地图清晰，物资整齐，战斗记录会自动归档；当你下次出征，他不仅记得你是谁，还记得你上次吃亏是在哪条岔路、该换哪把斧子。

仓库描述把他的性格说得很明确：

OpenViking is an open-source context database designed specifically for AI Agents(such as openclaw). OpenViking unifies the management of context (memory, resources, and skills) that Agents need through a file system paradigm, enabling hierarchical context delivery and self-evolving.

他不是一个“再来一个向量库”的项目；他更像一套专为 Agent 时代打造的上下文基础设施：把记忆、资源、技能统一起来，用文件系统范式去管理，并且支持分层投喂、让上下文自己长大。

Overview：他为什么出现？因为 Agent 开发正在被“上下文”折磨

OpenViking 在 Overview 里先抛出现实：
在 AI 时代，数据很多，但高质量上下文很难。

他看着开发者一边写代码一边喊痛，于是把常见困境列出来：

  • Fragmented Context：记忆在代码里、资源在向量库里、技能散落各处，难统一管理
  • Surging Context Demand：长任务每一步都产出上下文，截断/压缩很容易丢信息
  • Poor Retrieval Effectiveness：传统 RAG 是扁平存储，缺少全局视野，很难理解“信息在哪一片森林里”
  • Unobservable Context：检索链路像黑盒，出错难排查
  • Limited Memory Iteration：记忆只记录交互，缺少 Agent 任务相关的“经验记忆”

这些痛点堆在一起，Agent 就像一个背着破麻袋打仗的人：东西多、找不到、拿错了还不知道为什么错。

The OpenViking Solution：他用“文件系统范式”把上下文收拾得服服帖帖

OpenViking 的自我定位很直接：

OpenViking is an open-source Context Database designed specifically for AI Agents.

他想定义一种极简的上下文交互范式，让开发者告别上下文管理的烦恼。
做法也很激进：放弃传统 RAG 的碎片化向量存储，改用 “file system paradigm”，把 Agent 需要的记忆、资源、技能统一组织起来。

于是你管理 Agent 的“脑子”，就像管理本地文件一样顺手：

  • Filesystem Management Paradigm → Solves Fragmentation
  • Tiered Context Loading → Reduces Token Consumption（L0/L1/L2 三层按需加载）
  • Directory Recursive Retrieval → Improves Retrieval Effect（目录定位 + 语义检索，递归精准获取）
  • Visualized Retrieval Trajectory → Observable Context（检索轨迹可视化，能看、能调、能 debug）
  • Automatic Session Management → Context Self-Iteration（会话自动压缩/抽取长记忆，越用越聪明）

他像一个强迫症整理师：不允许上下文散落在各个角落，而是让一切都有目录、有路径、有层级、有来龙去脉。

Quick Start：把 OpenViking 放进你的工作台

Prerequisites

在他开工之前，你得先给他备齐工具：

  • Python：3.10+
  • Go：1.22+（构建 AGFS 组件需要）
  • C++ Compiler：GCC 9+ 或 Clang 11+（构建核心扩展需要）
  • OS：Linux / macOS / Windows
  • Network：需要稳定网络下载依赖和访问模型服务

他对你点点头：
“装备齐了，我们就出发。”

1) Installation：先把他请进来

Python Package

1
pip install openviking --upgrade --force-reinstall

Rust CLI（可选）

一条脚本安装：

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

或者从源码装：

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

2) Model Preparation：让他有眼睛、有“语义指南针”

OpenViking 需要两类能力：

  • VLM Model：用于图片与内容理解
  • Embedding Model：用于向量化与语义检索

Supported VLM Providers

他目前支持三种 VLM provider：

Provider Description Get API Key
volcengine Volcengine Doubao Models Volcengine Console
openai OpenAI Official API OpenAI Platform
litellm Unified access to various third-party models (Anthropic, DeepSeek, Gemini, vLLM, Ollama, etc.) LiteLLM Providers

他对 litellm 的态度像“万能转接头”：你只要按 LiteLLM 的格式写 model，就能接各种模型；系统还能自动识别一些常见命名（比如 claude-*、deepseek-*、gemini-*、hosted_vllm/*、ollama/*）。

3) Environment Configuration：给他一份“航海日志”（ov.conf）

Server Configuration Template

创建配置文件 ~/.openviking/ov.conf（复制前要把注释去掉）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{
  "storage": {
    "workspace": "/home/your-name/openviking_workspace"
  },
  "log": {
    "level": "INFO",
    "output": "stdout"                 // Log output: "stdout" or "file"
  },
  "embedding": {
    "dense": {
      "api_base" : "<api-endpoint>",   // API endpoint address
      "api_key"  : "<your-api-key>",   // Model service API Key
      "provider" : "<provider-type>",  // Provider type: "volcengine" or "openai" (currently supported)
      "dimension": 1024,               // Vector dimension
      "model"    : "<model-name>"      // Embedding model name (e.g., doubao-embedding-vision-250615 or text-embedding-3-large)
    },
    "max_concurrent": 10               // Max concurrent embedding requests (default: 10)
  },
  "vlm": {
    "api_base" : "<api-endpoint>",     // API endpoint address
    "api_key"  : "<your-api-key>",     // Model service API Key
    "provider" : "<provider-type>",    // Provider type (volcengine, openai, deepseek, anthropic, etc.)
    "model"    : "<model-name>",       // VLM model name (e.g., doubao-seed-2-0-pro-260215 or gpt-4-vision-preview)
    "max_concurrent": 100              // Max concurrent LLM calls for semantic processing (default: 100)
  }
}

Provider-Specific Notes（他会主动递上可用样例）

Volcengine（Doubao）——推荐用 model name：

1
2
3
4
5
6
7
8
{
  "vlm": {
    "provider": "volcengine",
    "model": "doubao-seed-2-0-pro-260215",
    "api_key": "your-api-key",
    "api_base": "https://ark.cn-beijing.volces.com/api/v3"
  }
}

也可用 endpoint ID：

1
2
3
4
5
6
7
8
{
  "vlm": {
    "provider": "volcengine",
    "model": "ep-20241220174930-xxxxx",
    "api_key": "your-api-key",
    "api_base": "https://ark.cn-beijing.volces.com/api/v3"
  }
}

OpenAI：

1
2
3
4
5
6
7
8
{
  "vlm": {
    "provider": "openai",
    "model": "gpt-4o",
    "api_key": "your-api-key",
    "api_base": "https://api.openai.com/v1"
  }
}

也支持 OpenAI 兼容端点：

1
2
3
4
5
6
7
8
{
  "vlm": {
    "provider": "openai",
    "model": "gpt-4o",
    "api_key": "your-api-key",
    "api_base": "https://your-custom-endpoint.com/v1"
  }
}

LiteLLM（示例：Claude / Qwen）：

1
2
3
4
5
6
7
{
  "vlm": {
    "provider": "litellm",
    "model": "claude-3-5-sonnet-20240620",
    "api_key": "your-anthropic-api-key"
  }
}
1
2
3
4
5
6
7
8
{
  "vlm": {
    "provider": "litellm",
    "model": "dashscope/qwen-turbo",
    "api_key": "your-dashscope-api-key",
    "api_base": "https://dashscope.aliyuncs.com/compatible-mode/v1"
  }
}

如果你用本地模型（例如 Ollama），他也给你一条“点火指令”：

1
2
# Start Ollama
ollama serve

然后这样写：

1
2
3
4
5
6
7
{
  "vlm": {
    "provider": "litellm",
    "model": "ollama/llama3.1",
    "api_base": "http://localhost:11434"
  }
}

Set Server Configuration Environment Variable

Linux/macOS：

1
export OPENVIKING_CONFIG_FILE=~/.openviking/ov.conf # by default

Windows PowerShell：

1
$env:OPENVIKING_CONFIG_FILE = "$HOME/.openviking/ov.conf"

Windows cmd.exe：

1
set "OPENVIKING_CONFIG_FILE=%USERPROFILE%\.openviking\ov.conf"

CLI/Client 配置：给 CLI 一条“去哪里找服务器”的路（ovcli.conf）

例如访问本地 server 的 ~/.openviking/ovcli.conf：

1
2
3
4
5
{
  "url": "http://localhost:1933",
  "timeout": 60.0,
  "output": "table"
}

并设置环境变量（Linux/macOS）：

1
export OPENVIKING_CLI_CONFIG_FILE=~/.openviking/ovcli.conf # by default

Windows PowerShell：

1
$env:OPENVIKING_CLI_CONFIG_FILE = "$HOME/.openviking/ovcli.conf"

Windows cmd.exe：

1
set "OPENVIKING_CLI_CONFIG_FILE=%USERPROFILE%\.openviking\ovcli.conf"

4) Run Your First Example：让他第一次“记住世界”

Launch Server

1
openviking-server

或者后台跑：

1
nohup openviking-server > /data/log/openviking.log 2>&1 &

Run the CLI（像在 viking:// 里走路一样）

1
2
3
4
5
6
7
ov status
ov add-resource https://github.com/volcengine/OpenViking # --wait
ov ls viking://resources/
ov tree viking://resources/volcengine -L 2
# wait some time for semantic processing if not --wait
ov find "what is openviking"
ov grep "openviking" --uri viking://resources/volcengine/OpenViking/docs/zh

当你敲下这些命令，他就像一个勤快的档案官：

  • 把资源搬进 viking://resources/
  • 为目录与内容生成语义层
  • 让你能 ls、能 tree、能 find、能 grep
    像操作文件一样操作上下文。

VikingBot Quick Start：让“维京人”真的开口说话

VikingBot 是构建在 OpenViking 之上的 AI agent framework。

1
2
3
4
5
6
7
8
9
10
11
# Option 1: Install VikingBot from PyPI (recommended for most users)
pip install "openviking[bot]"

# Option 2: Install VikingBot from source (for development)
uv pip install -e ".[bot]"

# Start OpenViking server with Bot enabled
openviking-server --with-bot

# In another terminal, start interactive chat
ov chat

他像在说：
“我不仅能整理脑子，我还能把脑子装进一个能聊天的身体里。”

Server Deployment Details：他希望你把他当成长期服务

OpenViking 推荐在生产环境把自己作为独立 HTTP service 运行，给 AI Agents 提供持久、高性能的上下文支撑。
并且建议在 Volcengine ECS、veLinux 上部署，配好了更稳。

入口也给你了：

👉 Server Deployment & ECS Setup Guide：./docs/en/getting-started/03-quickstart-server.md

Core Concepts：OpenViking 的“五件武器”，把上下文从黑盒变成透明工具

当你跑完第一个例子，他会邀请你继续深入，因为他的哲学就在这五件事里。

1) Filesystem Management Paradigm → Solves Fragmentation

他把上下文抽象成虚拟文件系统，通过 viking:// 协议组织：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
viking://
├── resources/              # Resources: project docs, repos, web pages, etc.
│   ├── my_project/
│   │   ├── docs/
│   │   │   ├── api/
│   │   │   └── tutorials/
│   │   └── src/
│   └── ...
├── user/                   # User: personal preferences, habits, etc.
│   └── memories/
│       ├── preferences/
│       │   ├── writing_style
│       │   └── coding_habits
│       └── ...
└── agent/                  # Agent: skills, instructions, task memories, etc.
    ├── skills/
    │   ├── search_code
    │   ├── analyze_data
    │   └── ...
    ├── memories/
    └── instructions/

像给 Agent 发了一套“确定性的操作系统”：
上下文不再靠“模糊语义碰碰运气”，而是靠路径、目录、命令定位。

2) Tiered Context Loading → Reduces Token Consumption

他把内容写入时自动分三层：

  • L0（Abstract）：一句话摘要，快速判断相关性
  • L1（Overview）：核心信息与使用场景，便于规划
  • L2（Details）：原文细节，需要时再深读

示例结构像“每个目录都带简介与概览”：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
viking://resources/my_project/
├── .abstract               # L0 Layer: Abstract (~100 tokens) - Quick relevance check
├── .overview               # L1 Layer: Overview (~2k tokens) - Understand structure and key points
├── docs/
│   ├── .abstract
│   ├── .overview
│   ├── api/
│   │   ├── .abstract
│   │   ├── .overview
│   │   ├── auth.md        # L2 Layer: Full content - Load on demand
│   │   └── endpoints.md
│   └── ...
└── src/
    └── ...

他像一个懂得省钱的军需官：不把所有粮草一次塞进背包，而是按需取用。

3) Directory Recursive Retrieval → Improves Retrieval Effect

他不满足于单次向量检索，而是设计了目录递归检索策略：

  1. Intent Analysis
  2. 初步定位高分目录
  3. 在目录内二次检索、更新候选
  4. 逐层递归下钻
  5. 聚合结果返回

像先锁定“最可能的城邦”，再进城挨家挨户搜线索。

4) Visualized Retrieval Trajectory → Observable Context

他保留每次检索的目录浏览、文件定位轨迹，让你看清“他为什么找到这个”或“为什么没找到”。
上下文管理不再是黑盒，而是可观察、可调参、可优化的工程链路。

5) Automatic Session Management → Context Self-Iteration

他有会话结束后的“记忆自迭代”机制：压缩、抽取、更新到 user 与 agent 的记忆目录里，让 Agent 越用越聪明：

  • User Memory Update：更懂用户偏好
  • Agent Experience Accumulation：沉淀操作技巧与工具经验

OpenClaw Memory Plugin：一段“战果报告”

OpenViking 在 README 里还展示了 OpenClaw memory plugin 的效果测试数据（基于 LoCoMo10 长对话数据集），并给出结论：集成 OpenViking 后任务完成率提升、输入 token 成本显著下降。

他们把链接也摆出来：

  • examples/openclaw-memory-plugin/README.md
  • examples/opencode-memory-plugin/README.md

Advanced Reading：他有完整文档，也在招募同伴

  • Full Documentation：./docs/en/
  • About Us：./docs/en/about/01-about-us.md
  • 社区入口：Lark、WeChat、Discord、X
    他像一艘正在扩编的船：愿意带更多开发者一起定义 Agent 上下文管理的未来。

License

Apache License 2.0（见 LICENSE）