OpenViking：AI Agent 的上下文数据库，让 Agent 像管理文件一样管理记忆

发表于 更新于 分类于

一个反常识的事实：大多数 AI Agent 的”记忆”其实是碎片化的 —— 记忆存在代码里、资源在向量数据库里、工具散落各处。这就是为什么用 Agent 做事时，它经常”失忆”或者找不到上下文。OpenViking 做了件事：把 AI Agent 的所有上下文（记忆、资源、技能）统一成虚拟文件系统，用 viking:// 协议访问，像管理本地文件一样管理 Agent 的大脑。

一、项目概述

OpenViking 是字节跳动火山引擎开源的上下文数据库（Context Database），专门为 AI Agent 设计。它用文件系统范式统一管理 Agent 需要的所有上下文类型（记忆、资源、技能），实现层级化上下文加载和自进化。

指标数据
GitHubvolcengine/OpenViking
Stars23,397
Created2026-01-05
LanguagePython
LicenseAGPL-3.0
最新版本0.3.14

核心解决的问题

  1. 上下文碎片化：记忆在代码里，资源在向量数据库里，技能散落各处
  2. 上下文爆炸：长时运行的 Agent 任务产生大量上下文，简单截断会丢失信息
  3. 检索效果差：传统 RAG 用扁平存储，缺乏全局视野
  4. 上下文不透明：传统 RAG 的隐式检索链是黑盒，调试困难
  5. 记忆迭代有限：现有记忆只记录用户交互，缺乏 Agent 相关任务记忆

二、架构设计

2.1 系统分层架构

graph TB
    subgraph "用户层"
        CLI["📱 CLI / SDK"]
        Bot["🤖 VikingBot"]
        Agent["🔌 OpenClaw Plugin"]
    end

    subgraph "服务层"
        Server["⚙️ OpenViking Server"]
    end

    subgraph "核心服务"
        Retrieve["🔍 Retrieve\nContext Retrieval"]
        Session["📋 Session\nSession Management"]
        Parse["📄 Parse\nContext Extraction"]
        Extract["🧠 Extract\nMemory Extraction"]
    end

    subgraph "存储层"
        VF["🗂️ VikingFS\nURI 抽象层"]
        VI["📊 Vector Index\n向量索引"]
        AG["💾 AGFS/RAGFS\n内容存储"]
    end

    CLI --> Server
    Bot --> Server
    Agent --> Server
    Server --> Retrieve
    Server --> Session
    Server --> Parse
    Server --> Extract
    Retrieve --> VF
    Parse --> VF
    Extract --> VF
    VF --> VI
    VF --> AG

    style CLI fill:#C7CEEA,stroke:#9FA8DA,stroke-width:2px,color:#333
    style Bot fill:#E8D5F5,stroke:#CE93D8,stroke-width:2px,color:#333
    style Agent fill:#FFDAB9,stroke:#FFAB76,stroke-width:2px,color:#333
    style Server fill:#FFF9C4,stroke:#F9A825,stroke-width:2px,color:#333
    style Retrieve fill:#B5EAD7,stroke:#80CBC4,stroke-width:2px,color:#333
    style Session fill:#B5EAD7,stroke:#80CBC4,stroke-width:2px,color:#333
    style Parse fill:#B5EAD7,stroke:#80CBC4,stroke-width:2px,color:#333
    style Extract fill:#B5EAD7,stroke:#80CBC4,stroke-width:2px,color:#333
    style VF fill:#FFB3C6,stroke:#F48FB1,stroke-width:2px,color:#333
    style VI fill:#FFB3C6,stroke:#F48FB1,stroke-width:2px,color:#333
    style AG fill:#FFB3C6,stroke:#F48FB1,stroke-width:2px,color:#333

2.2 三种上下文类型

OpenViking 将上下文抽象为三种基本类型，映射自人类认知模式：

类型用途生命周期主动性
Resource外部知识（文档、代码、网页）长期、相对静态用户添加
MemoryAgent 认知（学到的知识）长期、动态更新Agent 记录
Skill可调用能力（工具、指令）长期、静态Agent 调用

Resource（资源）

用户主动添加的外部知识，如产品手册、代码仓库、研究论文。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
import openviking as ov

client = ov.OpenViking(path="./data")

# 添加资源
res = client.add_resource(
    path="https://raw.githubusercontent.com/volcengine/OpenViking/main/README.md"
)
root_uri = res["root_uri"]

# 浏览资源树
res = client.ls(root_uri)
print(res)

# 语义搜索
results = client.find("what is openviking", target_uri=root_uri)
for r in results.resources:
    print(f"  {r.uri} (score: {r.score:.4f})")

Memory（记忆）

Agent 从交互中主动提取和记录的信息，分为用户记忆和 Agent 记忆。

8 大记忆类别：

类别路径描述更新策略
profileuser/memories/profile.md用户基本信息✅ 合并到单一文件
preferencesuser/memories/preferences/用户偏好✅ 合并
entitiesuser/memories/entities/实体（人、地点、组织）✅ 合并
eventsuser/memories/events/事件记录✅ 合并
casesuser/memories/cases/案例/经验✅ 合并
patternsuser/memories/patterns/行为模式✅ 合并
toolsagent/memories/tools.md工具使用经验✅ 合并
skillsagent/memories/skills.md技能知识✅ 合并

Skill（技能）

Agent 可调用的能力抽象，包括工具调用、指令模板等。

2.3 三层上下文加载（L0/L1/L2）

传统 RAG 把所有上下文一股脑塞进 prompt，既贵又容易超出窗口。OpenViking 在写入时自动将上下文处理成三层：

graph TB
    subgraph "L0 Abstract"
        A["📝 Abstract\n~100 tokens"]
    end
    subgraph "L1 Overview"
        O["📋 Overview\n~2k tokens"]
    end
    subgraph "L2 Detail"
        D["📄 Detail\n无限长度"]
    end

    Query["🔍 查询"] --> A
    Query --> O
    Query -.->|"按需"| D

    A -->|"向量检索"| VectorIndex["📊 向量索引"]
    O -->|"重排/导航"| Rerank["🔄 重排"]
    D -->|"完整读取"| FullContent["📄 完整内容"]

    style A fill:#FFF9C4,stroke:#F9A825,stroke-width:2px,color:#333
    style O fill:#FFDAB9,stroke:#FFAB76,stroke-width:2px,color:#333
    style D fill:#C7CEEA,stroke:#9FA8DA,stroke-width:2px,color:#333
    style Query fill:#FFB3C6,stroke:#F48FB1,stroke-width:2px,color:#333
    style VectorIndex fill:#B5EAD7,stroke:#80CBC4,stroke-width:2px,color:#333
    style Rerank fill:#B5EAD7,stroke:#80CBC4,stroke-width:2px,color:#333
    style FullContent fill:#B5EAD7,stroke:#80CBC4,stroke-width:2px,color:#333
层级名称Token 限制用途
L0Abstract~100 tokens向量检索、快速过滤
L1Overview~2k tokens重排、内容导航
L2Detail无限按需加载完整内容

2.4 VikingURI 虚拟文件系统

所有上下文通过 viking:// 协议组织成虚拟目录结构：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
viking://
├── resources/              # 资源：项目文档、代码仓库、网页等
│   └── volcengine/
│       └── OpenViking/
│           ├── docs/
│           │   ├── api/
│           │   └── tutorials/
│           └── src/
├── user/                   # 用户：个人偏好、习惯等
│   └── memories/
│       ├── preferences/
│       │   ├── writing_style/
│       │   └── coding_habits/
│       └── profile.md
└── agent/                  # Agent：技能、指令、任务记忆等
    ├── skills/
    │   ├── search_code/
    │   └── analyze_data/
    └── memories/

VikingFS 的核心 API：

方法描述
read(uri)读取文件内容
write(uri, data)写入文件
mkdir(uri)创建目录
rm(uri)删除文件/目录
abstract(uri)读取 L0 摘要
overview(uri)读取 L1 概览
find(query)语义搜索

2.5 双层存储架构

graph LR
    subgraph "VikingFS (URI 抽象层)"
        URI["🔗 URI 映射\n层级访问\n关系管理"]
    end

    subgraph "存储层"
        VI["📊 Vector Index\n向量索引"]
        AG["💾 AGFS/RAGFS\n内容存储"]
    end

    URI --> VI
    URI --> AG

    VI -->|"仅存 URI/向量/元数据"| VI
    AG -->|"L0/L1/L2 全量内容"| AG

    style URI fill:#FFB3C6,stroke:#F48FB1,stroke-width:2px,color:#333
    style VI fill:#C7CEEA,stroke:#9FA8DA,stroke-width:2px,color:#333
    style AG fill:#B5EAD7,stroke:#80CBC4,stroke-width:2px,color:#333
层级职责内容
AGFS/RAGFS内容存储L0/L1/L2 全部内容、多媒体文件、关系
Vector Index索引存储URI、向量、元数据（无文件内容）

设计优势：

  • 职责清晰：向量索引管检索，AGFS 管存储
  • 内存优化：向量索引不存文件内容，节省内存
  • 单一数据源：所有内容从 AGFS 读取，向量索引只存引用
  • 独立扩展：向量索引和 AGFS 可独立扩容

三、核心机制原理

3.1 目录递归检索（Directory Recursive Retrieval）

传统 RAG 的扁平向量检索难以处理复杂查询意图。OpenViking 设计了目录递归检索策略：

flowchart TD
    START["🚀 查询"] --> INTENT["🧠 Intent Analysis\n生成多个检索条件"]
    INTENT --> INITIAL["🎯 Initial Positioning\n向量检索定位高分目录"]
    INITIAL --> REFINE["🔎 Refined Exploration\n在目录内二次检索"]
    REFINE --> CHECK{"存在子目录?"}
    CHECK -->|"是"| RECURSE["🔄 递归进入子目录"]
    RECURSE --> REFINE
    CHECK -->|"否"| AGGREGATE["📦 Result Aggregation\n结果聚合"]
    INITIAL -.-> AGGREGATE
    AGGREGATE --> END["✅ 返回最相关上下文"]

    style START fill:#C7CEEA,stroke:#9FA8DA,color:#333
    style INTENT fill:#FFF9C4,stroke:#F9A825,color:#333
    style INITIAL fill:#FFDAB9,stroke:#FFAB76,color:#333
    style REFINE fill:#FFDAB9,stroke:#FFAB76,color:#333
    style CHECK fill:#E8D5F5,stroke:#CE93D8,color:#333
    style RECURSE fill:#E8D5F5,stroke:#CE93D8,color:#333
    style AGGREGATE fill:#B5EAD7,stroke:#80CBC4,color:#333
    style END fill:#B5EAD7,stroke:#80CBC4,color:#333

检索流程：

  1. 意图分析：通过意图分析生成多个检索条件
  2. 初始定位：向量检索快速定位高分目录
  3. 精细探索：在目录内二次检索，更新候选集
  4. 递归下探：若有子目录，递归重复二次检索
  5. 结果聚合：返回最相关上下文

这种”先锁定高分目录，再精细探索内容”的策略，既能找到语义最匹配的片段，也能理解信息所在的完整上下文。

3.2 记忆提取与自进化

每个 Session 结束时，开发者可主动触发记忆提取机制：

1
2
3
4
5
6
# Session 结束时的记忆提取
client.extract_memory(
    session_id="session_xxx",
    categories=["profile", "preferences", "entities", "events", 
               "cases", "patterns", "tools", "skills"]
)

系统会异步分析任务执行结果和用户反馈，自动更新到用户和 Agent 记忆目录：

  • 用户记忆更新：更新用户偏好相关记忆，使 Agent 响应更符合用户需求
  • Agent 经验积累：从任务执行经验中提取核心内容（操作技巧、工具使用经验），辅助后续任务高效决策

3.3 完整的 Python SDK 使用示例

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
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
import openviking as ov

# 初始化客户端（本地模式）
client = ov.OpenViking(path="./data")
# 或 HTTP 模式：连接远程服务器
# client = ov.SyncHTTPClient(url="http://localhost:1933")

try:
    client.initialize()

    # 添加资源（URL、文件或目录）
    res = client.add_resource(
        path="https://raw.githubusercontent.com/volcengine/OpenViking/refs/heads/main/README.md"
    )
    root_uri = res["root_uri"]

    # 浏览资源树
    res = client.ls(root_uri)
    print(f"Directory structure:\n{res}\n")

    # 用 glob 查找 markdown 文件
    res = client.glob(pattern="**/*.md", uri=root_uri)
    if res["matches"]:
        content = client.read(res["matches"][0])
        print(f"Content preview: {content[:200]}...\n")

    # 等待语义处理完成
    print("Wait for semantic processing...")
    client.wait_processed()

    # 获取摘要和概览
    abstract = client.abstract(root_uri)
    overview = client.overview(root_uri)
    print(f"Abstract:\n{abstract}\n\nOverview:\n{overview}\n")

    # 语义搜索
    results = client.find("what is openviking", target_uri=root_uri)
    print("Search results:")
    for r in results.resources:
        print(f"  {r.uri} (score: {r.score:.4f})")

    client.close()

except Exception as e:
    print(f"Error: {e}")

3.4 OpenClaw 插件集成

OpenViking 可作为 OpenClaw 的上下文引擎插件使用，显著提升 Agent 任务完成率并降低 token 成本：

graph LR
    subgraph "OpenClaw Agent"
        AC["🤖 Agent Core"]
        MC["💭 Memory Core\n(原生记忆)"]
    end

    subgraph "OpenViking Plugin"
        OV["🔌 OpenViking\nContext Engine"]
    end

    AC <-->|"上下文读写"| OV
    AC <-->|"可选同步"| MC

    style AC fill:#E8D5F5,stroke:#CE93D8,color:#333
    style MC fill:#FFDAB9,stroke:#FFAB76,color:#333
    style OV fill:#B5EAD7,stroke:#80CBC4,color:#333

实验数据（基于 LoCoMo10 长程对话数据集，1540 个案例）：

实验组任务完成率输入 Token 成本
OpenClaw (memory-core)35.65%24,611,530
OpenClaw + LanceDB44.55%51,574,530
OpenClaw + OpenViking52.08%4,264,396

集成 OpenViking 后：

  • 相比原生 OpenClaw：任务完成率提升 43%，输入 token 成本降低 91%
  • 相比 LanceDB：任务完成率提升 17%，输入 token 成本降低 92%

四、与同类项目对比

维度OpenVikingMem0LettaRAGFlow
核心定位Agent 上下文数据库通用记忆层Agent 记忆服务器RAG 流程编排
存储范式文件系统范式图/向量混合时序数据库文档解析+向量
上下文类型Resource/Memory/Skill 统一用户记忆为主聊天记忆+事实文档知识库
分层加载✅ L0/L1/L2 三层❌ 扁平❌ 扁平✅ 分片
检索方式目录递归检索语义向量实体链接+向量混合检索+重新排序
可观测性✅ 检索轨迹可视化❌ 黑盒✅ 会话管理可视化✅ 流程可视化
自进化✅ 自动记忆提取✅ 自动记忆更新✅ 实体更新❌
多租户✅❌✅❌
开源协议AGPL-3.0Apache-2.0MITApache-2.0

关键设计差异

1. 存储范式的根本差异

传统方案（Mem0、Letta）采用数据库思维：记忆是数据库记录，通过 ID 或向量检索。

OpenViking 采用文件系统范式：所有上下文是虚拟文件树的节点，通过 URI 路径定位。这带来的核心优势是：

  • Agent 可以像操作文件一样操作上下文（ls、cd、cat）
  • 上下文有了自然的层级结构和导航价值
  • 检索路径完全可追踪和可视化

2. 分层加载 vs 扁平检索

Mem0 和 Letta 的记忆是一维的，检索时全部返回或按向量相似度截断。

OpenViking 的 L0/L1/L2 三层结构实现了渐进式上下文加载：先看摘要判断是否相关，再看概览了解结构，最后按需加载详细内容。Token 消耗大幅降低。

3. 检索 vs 记忆的侧重点

RAGFlow 等 RAG 方案侧重检索（Retrieval），核心是找到最相关的文档片段。

OpenViking 侧重上下文管理（Context Management），检索只是其中一个环节。它更关注：上下文如何组织、如何加载、如何自进化、如何被 Agent 操作。

五、优缺点分析

优点

维度说明
架构简洁性VikingFS 抽象层极简，URI 即上下文，上下一致
上下文组织文件系统范式直观，符合开发者直觉
层级加载省成本L0/L1/L2 三层按需加载，token 消耗降低 90%+
可观测性强检索轨迹完全可视化，调试不再黑盒
自进化能力自动记忆提取，Agent 越用越聪明
多模态支持支持 VLM 模型处理图片等多模态内容
多租户支持支持团队协作，资源隔离
生态完善OpenClaw 插件、VikingBot 框架，开箱即用

缺点与局限

维度说明
学习成本VikingURI 范式需要时间理解，与传统 RAG 思路不同
AGPL 许可AGPL-3.0 协议，商业使用需注意开源传递
Rust 依赖RAGFS 等核心组件用 Rust 实现，构建门槛稍高
生态年轻2026 年 1 月才创建，社区和插件生态还在成长
重度云厂商绑定文档和默认配置偏向火山引擎，第三方云部署有门槛
不是通用 RAG面向 Agent 场景，不适合作为通用文档问答的后端

六、快速上手

6.1 安装

1
2
3
4
5
# Python 包
pip install openviking --upgrade --force-reinstall

# Rust CLI（可选）
curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/crates/ov_cli/install.sh | bash

6.2 配置模型

OpenViking 支持多种 VLM 提供者：

1
2
3
4
# 交互式初始化（推荐）
openviking-server init

# 或手动配置 ~/.openviking/ov.conf

支持的 VLM 提供者：

提供者说明
volcengine火山引擎豆包模型
openaiOpenAI 官方 API
openai-codexCodex VLM (OAuth)
kimiKimi Coding 订阅
glmGLM Coding Plan

6.3 启动服务

1
2
3
4
5
6
7
8
# 检查配置
openviking-server doctor

# 启动服务器
openviking-server

# 或后台运行
nohup openviking-server > /data/log/openviking.log 2>&1 &

6.4 基本使用

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
# 检查状态
ov status

# 添加资源
ov add-resource https://github.com/volcengine/OpenViking

# 浏览资源
ov ls viking://resources/

# 查看树形结构
ov tree viking://resources/volcengine -L 2

# 语义搜索
ov find "what is openviking"

# 启动聊天机器人
pip install "openviking[bot]"
openviking-server --with-bot
ov chat

七、总结

OpenViking 正在重新定义 Agent 的记忆管理范式。它不只是一个向量数据库，而是一个完整的上下文操作系统 —— 用文件系统思维管理 Agent 的记忆、资源和技能。

核心创新：

  • 文件系统范式：统一 URI 抽象，让上下文像文件一样可操作
  • 三层加载：L0/L1/L2 按需渐进加载，token 成本降低 90%+
  • 目录递归检索：先定位目录再精细探索，检索质量显著提升
  • 自进化记忆：自动提取和迭代，越用越聪明

OpenViking 的出现填补了”记忆管理”和”检索系统”之间的鸿沟。它告诉我们：Agent 需要的不只是 RAG，而是一个完整的上下文数据库。

💡 开源的意义：当 RAG 成为标配、Agent 框架百花齐放的时候，上下文管理反而成了被忽视的角落。OpenViking 的开源，为整个 Agent 生态提供了一个被验证过的、架构清晰的上下文数据库参考实现。