# OpenViking - Agent 上下文数据库

> 字节跳动开源的 AI Agent 记忆管理系统
>
> 归档：2026-04-22

---

## 基本信息

| 项目 | 说明 |
|------|------|
| GitHub | https://github.com/volcengine/OpenViking |
| 官网 | https://www.openviking.ai |
| Stars | ⭐ 22,714 |
| Forks | 1,651 |
| 许可证 | AGPL-3.0 |
| 语言 | Python |
| 更新 | 2026-04-21 |

---

## 核心定位

**专为 AI Agent 设计的上下文数据库**

解决传统 RAG 的问题：
- 碎片化上下文：记忆在代码里，资源在向量数据库，技能分散
- 上下文需求暴涨：Agent 长任务产生大量上下文，简单截断会丢失信息
- 检索效果差：传统 RAG 平面存储，缺乏全局视图
- 检索链不可观测：传统 RAG 是黑盒，难以调试
- 记忆迭代有限：当前记忆只是用户交互记录

---

## 核心架构

### 文件系统范式

```
viking://
├── resources/   # 外部资源（文档、代码、URL）
├── user/       # 用户上下文
└── agent/      # Agent 记忆和技能
```

### L0 / L1 / L2 三层加载

| 层级 | 内容 | Token 消耗 | 用途 |
|------|------|-----------|------|
| **L0** | 摘要 | ~100 tokens | 快速扫描，判断相关性 |
| **L1** | 概览 | ~2k tokens | 理解架构，制定计划 |
| **L2** | 全文 | 按需加载 | 深读具体文件 |

### Token 节省效果

| 方案 | Token 消耗 |
|------|-----------|
| 全量加载（传统 RAG） | ~50,000 |
| L0 扫描 + L1 概览 | ~3,000 |
| L0 + L1 + L2 按需 | ~8,000 |
| **节省比例** | **83%~96%** |

---

## 核心功能

| 功能 | 说明 |
|------|------|
| 文件系统协议 `viking://` | 统一管理 resources/user/agent 三类上下文 |
| 分层摘要 | L0/L1/L2 按需加载 |
| 目录递归检索 | 语义检索 + 目录定位 |
| 会话记忆 | 自动提取长期记忆，跨会话保持 |
| Token 追踪 | 可视化检索轨迹，追踪每个操作的 token 消耗 |

---

## 安装

### OpenClaw Skill 安装

```bash
# 使用 clawhub 安装 openviking-context skill
clawhub install openviking-context

# 在 OpenClaw 中说 "refresh skills" 即可发现
```

### OpenViking 本体安装

```bash
# 自动检测 Python >= 3.10，安装 openviking 包
bash scripts/install.sh

# 可选：安装 Rust CLI (ov)
```

### 配置支持的模型

| 提供商 | VLM 模型 | Embedding 模型 |
|--------|---------|---------------|
| OpenAI | gpt-4o | text-embedding-3-large (dim=3072) |
| Volcengine | doubao-seed-2-0-pro-260215 | doubao-embedding-vision-250615 (dim=1024) |
| LiteLLM | claude-3-5-sonnet / deepseek-chat | - |
| NVIDIA NIM | meta/llama-3.3-70b-instruct | nvidia/nv-embed-v1 (dim=4096) |

**注意**：避免使用推理模型（kimi-k2.5, deepseek-r1），它们的 reasoning 字段与 OpenViking 不兼容。

---

## 核心操作

```bash
# 启动服务器
openviking-server

# 添加资源
python3 scripts/viking.py add ./docs/
python3 scripts/viking.py add https://github.com/volcengine/OpenViking

# 语义搜索
python3 scripts/viking.py search "用户认证 鉴权"

# 浏览目录
python3 scripts/viking.py ls viking://resources/
python3 scripts/viking.py tree viking://resources/ -L 2

# 分层读取
python3 scripts/viking.py abstract viking://resources/proj    # L0 ~100 tokens
python3 scripts/viking.py overview viking://resources/proj   # L1 ~2k tokens
python3 scripts/viking.py read viking://resources/proj/api.md # L2 全文

# 状态和统计
python3 scripts/viking.py info    # 检查服务状态
python3 scripts/viking.py stats    # 查看 token 消耗统计
python3 scripts/viking.py commit   # 提取当前会话记忆
```

---

## 工作流示例

收到开发需求时：

1. **L0 快速扫描**（~300 tokens）
   ```bash
   python3 scripts/viking.py search "用户认证 鉴权 登录"
   ```
   用 L0 摘要判断哪些资源相关，过滤无关内容。

2. **L1 概览决策**（~2k tokens/资源）
   ```bash
   python3 scripts/viking.py overview viking://resources/auth-docs
   ```
   理解架构和技术选型，制定实现计划。

3. **L2 按需深读**（仅必要文件）
   ```bash
   python3 scripts/viking.py read viking://resources/auth-docs/jwt-config.md
   ```
   只加载写代码需要的具体文件。

---

## Token 节省演示

```bash
python3 scripts/demo-token-compare.py ./your-project-docs/
```

输出示例：
```
方案                    Token 消耗  说明
─────────────────────────────────────────────────────
全量加载 (传统 RAG)     ~50,000    所有文档塞进 prompt
L0 扫描 + L1 概览       ~3,000     分层按需，仅摘要和概览
L0 + L1 + L2 按需       ~8,000     最终只深读 2-3 个必要文件
─────────────────────────────────────────────────────
节省比例                84%~94%    相比全量加载
```

---

## 相关资源

| 资源 | 链接 |
|------|------|
| OpenViking GitHub | https://github.com/volcengine/OpenViking |
| OpenViking 官网 | https://www.openviking.ai |
| ClawHub Skill | openviking-context |

---

## 替代方案对比

| 方案 | 说明 |
|------|------|
| **OpenViking** | 字节跳动开源，上下文数据库，AGPL 许可 |
| Elite Longterm Memory | 高级长期记忆，ClawHub Skill |
| Memory Tiering | 记忆分层，ClawHub Skill |
| Fluid Memory | 流动记忆，ClawHub Skill |

---

*整理：知识库管理员 | 来源：GitHub / OpenViking 官网 | 归档：2026-04-22*