OpenViking：字节跳动开源的 38.5k Stars AI Agent 上下文数据库

OpenViking 真正做的不是再加一层 RAG，而是把 Agent 的记忆、资源和技能搬进同一个虚拟文件系统：上下文以 viking:// 路径组织，Agent 用 ls、find、grep 这样的文件操作取用上下文，开发者可以打开任意目录查看、修改 Agent「知道什么」。检索由此从黑盒相似度匹配，变成一条条可追踪的路径。

本文基于 volcengine/OpenViking，数据与机制以 2026 年 9 月的 v0.4.21 为口径。

一、项目概览

1.1 它是什么

OpenViking 是字节跳动旗下火山引擎 Viking 团队开源的 AI Agent 上下文数据库（context database），2026 年 1 月开放仓库，官方的一句话定位是：为 Agent 知道的一切——知识、记忆、技能——提供一个统一的文件系统。Viking 团队即 VikingDB 向量数据库的班底，2019 年起在字节内部做大规模向量检索，2024 年将 VikingDB、知识库、记忆库产品化，2025 年底开源 MineContext 探索主动式 AI，2026 年初推出 OpenViking，把上下文工程沉淀成独立的开源基础设施。

核心数据（2026-09-23 快照）：

注意许可条款：主项目在 2026 年 3 月 30 日由 Apache-2.0 改为 AGPL-3.0。自托管内部使用不触发传染条款，但若对修改版做网络分发，需要按 AGPLv3 开源源码；这层变化在选型时要算进去。

1.2 它要解决的问题

官方文档把痛点收敛为四条，都指向同一个根源——上下文散落在互不相通的系统里：

• 上下文碎片化：记忆在代码里，资源在向量库，技能又是另一套，没有统一的管理面。
• 检索缺全局视角：传统 RAG 扁平存储，召回的切片带着上下文被切走的前因后果。
• 检索链路黑盒：出错时说不清「为什么召回的是这几段」，难以调试和优化。
• 记忆不会成长：多数「记忆」只是聊天记录的堆积，缺少从任务执行中沉淀经验并反哺后续任务的机制。

1.3 解法：文件系统范式 + 分层加载 + 记忆自迭代

OpenViking 的回应可以拆成三条主线，后文逐一展开：

二、核心概念：先分清三类上下文

用 OpenViking 之前要先接受它的一个抽象：所有上下文只有三种类型，各管一件事。

这个划分决定了数据的归宿：知识进 resources/，习得的东西进 memories/，能力定义进 skills/。混着放会导致检索时按类型定位的根目录找错地方——OpenViking 的检索是按类型定根目录的，这一点在第三节展开。

2.1 viking:// 命名空间

所有内容挂在 viking://{scope}/{path} 下，公开 scope 有三个：

viking://
├── resources/                  # 账号级共享资源：项目文档、代码、网页
│   └── {project}/
├── user/{user_id}/             # 用户私有空间
│   ├── memories/               # 记忆：profile、preferences、events 等
│   ├── resources/              # 用户私有资源
│   ├── skills/                 # 用户技能（默认根）
│   ├── peers/{peer_id}/        # 交互对等体（如某个客户、某个子 Agent）的记忆与资源
│   └── sessions/{session_id}/  # 会话：messages.jsonl、摘要、归档
└── agent/                      # 账号级共享的能力定义
    └── skills/                 # 公共技能

两个设计值得注意。其一，~ 是服务端别名，viking://~/memories 会按请求身份展开为 viking://user/{user_id}/memories，同一段代码在不同用户身份下指向各自的目录，多用户隔离因此不用改路径。其二，resources/ 是账号内共享的，支持目录级 ACL；要私有就放 user/{user_id}/resources/ 下。

这里能看出 0.4.0 版本的一次大改：此前存在 viking://agent/{agent_id}/... 这样的 Agent 身份命名空间，0.4.0 引入 User/Peer 模型后，viking://agent/ 收缩为「账号共享的能力目录」，旧 Agent 数据迁到 user/{user_id}/peers/ 下。官方提供了 ov --sudo admin migrate 迁移命令，旧 viking://session/ 路径保留只读兼容。

2.2 L0/L1/L2：目录级的三层摘要

OpenViking 在语义处理时给目录（不是每个文件）生成两个隐藏的摘要文件：

生成顺序自底向上：文件摘要聚合成叶子目录的 L1，再从 L1 正文中抽出首段作为 L0，逐级向上冒泡。ls 默认隐藏这两个 sidecar，ov overview <uri> 可以直接读目录概览。这个机制直接决定了成本结构——Agent 浏览的是 256 字符的摘要层，只有确认相关才拉全文，token 消耗的大头被压在了 L2 的「按需」上。

三、核心机制：一次写入与一次检索的完整路径

3.1 系统架构

现行架构分四层：

┌──────────────────────────────────────────────────────────┐
│   Client（Python/Go/TS SDK · ov CLI · HTTP API · MCP）    │
├──────────────────────────────────────────────────────────┤
│   Service 层：FSService / SearchService / SessionService  │
│              ResourceService / PackService / DebugService │
├──────────────────────────────────────────────────────────┤
│   Retrieve（检索）  │  Session（会话）  │  Parse（解析）    │
│   意图分析/层级检索  │  压缩/记忆抽取    │  文档解析/树构建   │
│   + Rerank         │  Compressor       │  L0/L1 异步生成    │
├──────────────────────────────────────────────────────────┤
│   Storage：AGFS 内容存储（Rust 实现 RAGFS）+ 向量索引      │
└──────────────────────────────────────────────────────────┘

存储层是「双层」设计：内容只存在 AGFS 一处，向量索引只存 URI、向量和元数据，不存正文。删除或移动文件时 VikingFS 自动同步向量记录，保证两边不漂移。AGFS 原是 Go 实现并曾支持 HTTP 访问，现已用 Rust 重写为 RAGFS，通过进程内绑定（ragfs_python）挂进 Python 进程，HTTP 客户端模式已移除。向量索引后端可选本地持久化、HTTP 服务或火山引擎 VikingDB，v0.4.8 起还支持 NVIDIA cuVS 做 GPU 检索。

3.2 写入路径：ov add-resource 之后发生什么

以导入一个 GitHub 仓库为例，后台依次经过四步：

Parser → TreeBuilder → AGFS → SemanticQueue → 向量索引

1. Parser 解析文档（PDF/Markdown/HTML），建出目录结构，这一步不调 LLM；
2. TreeBuilder 把临时目录移入 AGFS，登记语义处理任务；
3. SemanticQueue 异步地自底向上生成各级 L0/L1——这就是导入后要等一会儿才能语义检索的原因；
4. 向量索引为目录摘要建立条目，供检索用。

所以 ov add-resource 返回的是任务 ID，要么加 --wait 等处理完成，要么拿 task_id 轮询 ov task status。没等语义处理完就 find，结果为空是正常现象，不是故障。

3.3 检索路径：find 与 search 是两条路

search() 的意图分析会把「帮我写份 RFC」拆成动词开头的能力查询、名词短语式的资料查询和「用户的 XX」式记忆查询，分别到对应类型的根目录下取材。真正的重活由层级递归检索完成：先全局向量搜索定位高分起始目录，再用优先队列在目录树内逐层下钻，子目录得分按可配置权重向父层传播（默认权重下只取子目录自身得分），连续 3 轮候选不再变化即收敛，最后经 Rerank（火山引擎 doubao-seed-rerank，配置了才启用，失败自动回落向量分）精排出结果。

「检索可观测」在现行版本有具体着落：检索轨迹可追溯，服务端支持把 OpenTelemetry trace 写到 OTLP 后端或本地 ~/.openviking/logs/traces.jsonl（滚动备份），另有 /metrics 端点可接 Prometheus/Grafana；Web Studio 里能直接浏览目录与摘要，看 Agent「知道什么」不再靠猜。

3.4 会话提交：记忆如何自迭代

会话生命周期是创建 → 交互 → 提交。session.commit() 分两个阶段：

• 同步阶段立即返回：消息写入归档目录 messages.jsonl，清空当前消息列表，给出 task_id；
• 异步后台接着做三件事：生成会话摘要（.abstract.md/.overview.md）、按记忆策略抽取长期记忆、把全部记忆变更写入 memory_diff.json 审计日志。

记忆抽取不是简单存原文：候选记忆先经向量预筛找相似项，再由 LLM 做去重裁决——跳过、新建，或对既有记忆做合并/删除。内置九类记忆（profile、preferences、entities、events、identity、soul、cases、trajectories、experiences），其中 experiences 一旦开启，会激活完整的 Agent Evolution 管线并连带启用 cases 与 trajectories——也就是从执行结果里蒸馏「下次遇到同类任务怎么办」的复用经验。memory_diff.json 记下每条记忆的前后内容，审计与回滚都有据可查。

四、上手：从安装到第一次检索

4.1 环境要求

• Python 3.10+（服务端）；
• 一个可访问的 Embedding 模型（官方推荐火山引擎豆包系）和一个 VLM（用于语义摘要与多模态理解），Rerank 模型可选；
• 仅从源码构建时需要 Rust/Cargo 工具链与 C++ 编译器（GCC 9+ 或 Clang 11+）。早期版本构建 AGFS 需要 Go 1.22，AGFS 改为 Rust 实现后这一依赖已不存在。

4.2 启动服务端

uv tool install openviking --upgrade
openviking-server init      # 交互向导：配置模型与密钥，写入 ~/.openviking/ov.conf
openviking-server doctor    # 检查配置与连通性
openviking-server           # 启动，默认监听 127.0.0.1:1933

用 curl http://127.0.0.1:1933/health 确认服务就绪；浏览器访问 /studio 即是内置的 Web Studio。init 向导支持火山引擎、OpenAI、Kimi、GLM，也可选 OpenAI Codex 走 OAuth 登录。不想装环境可以用官方 Docker 镜像（捆绑 VikingBot 与控制台 UI），或 Railway 一键部署。

最小配置长这样（向导会生成，手改亦可）：

{
  "embedding": {
    "dense": {
      "api_base": "https://ark.cn-beijing.volces.com/api/v3",
      "api_key": "<your-api-key>",
      "provider": "volcengine",
      "dimension": 1024,
      "model": "doubao-embedding-vision-251215"
    }
  },
  "vlm": {
    "api_base": "https://ark.cn-beijing.volces.com/api/v3",
    "api_key": "<your-api-key>",
    "provider": "volcengine",
    "model": "doubao-seed-2-0-lite-260428"
  }
}

Embedding 提供商目前支持 openai、azure、volcengine、vikingdb、jina、ollama、gemini、voyage、dashscope、minimax、cohere、litellm、local 十三种；VLM 经 litellm 还能转到 Anthropic、DeepSeek、Gemini、vLLM、Ollama 等任意兼容后端。

4.3 安装并连接 CLI

ov 是客户端工具，连自家服务器或火山引擎托管服务都走它：

npm i -g @openviking/cli    # 独立安装（需 Node.js）；装了服务端的机器自带 ov，无需重复装
ov language en              # v0.3.23 起首次使用需先选语言
ov config                   # 交互式配置连接与密钥，写入 ~/.openviking/ovcli.conf
ov health                   # 验证连通

偏爱 Rust 工具链的也可以从源码装：cargo install --git https://github.com/volcengine/OpenViking ov_cli。

4.4 导入并检索

ov add-resource https://github.com/volcengine/OpenViking --wait
# 不加 --wait 时记下返回的 task_id，用 ov task status <task_id> 轮询到 completed
ov ls viking://resources/
ov tree viking://resources/volcengine -L 2
ov overview viking://resources/volcengine/OpenViking          # 读目录的 L1 概览
ov find "what is openviking"
ov grep "openviking" --uri viking://resources/volcengine/OpenViking/docs/en
ov read "<find 返回的文件 URI>"

4.5 VikingBot：自带的对话入口

pip install "openviking[bot]"
openviking-server --with-bot
ov chat                      # 另开一个终端

VikingBot 是架在 OpenViking 之上的 Agent 框架，Docker 镜像默认捆绑并随服务启动。它带一个实用的 ov compile 命令：把导入的原始资料编译成 wiki、知识图谱或日报，属于「上下文编译」能力的一部分。

五、官方 benchmark 怎么读

README 用 v0.3.22 做了一轮评测，两组数据、三种 Agent 接入（VLM 为豆包 Doubao 2.0 Pro，Embedding 为 doubao-embedding-vision-251215）：

LoCoMo 一组同时报告输入 token 下降 34.3%–91.0%、查询延迟下降 58.45%–66.10%。

读这组数字要过三道判断。测的是跨会话记忆与经验复用：LoCoMo 考长对话中的用户记忆问答，tau2-bench 考客服类多轮任务，都不是检索质量榜单。数字主要反映记忆子系统的差距：三家 Agent 换上同一套外部记忆后准确率齐齐落在 80–83% 的窄带里，差异被抹平，说明瓶颈确实在原生记忆而非模型能力；token 大降则归功于 L0/L1 分层加载替代了原文全量注入。不能推出什么：这是官方自测，模型组合固定（自家豆包系），没有与 Mem0、Zep 等第三方记忆产品的横向对照；接进生产前的实际收益，应按自己的对话形态用 benchmark/ 目录的脚本复测。

六、生态与部署形态

接入方式按侵入度从低到高：

• 任意 MCP 客户端：服务端内建 /mcp 端点，Cursor、Trae、Manus、Claude Desktop 等按标准 mcpServers 格式填 URL 即可，无需装插件；
• 深度集成插件：Claude Code、Codex、Cursor、TRAE 走 hooks + MCP（自动召回与自动会话捕获），OpenClaw 直接以 OpenViking 为上下文引擎，Hermes Agent 内置支持，OpenCode、pi、DeerFlow、DSH 有专门插件，LangChain/LangGraph 提供工具与 store 适配，Doubao Work 以 connector 接入；
• SDK 与 HTTP API：Python、TypeScript/JavaScript、Go 三套 SDK，覆盖自研 Agent。

部署形态同样分层：本地或自托管（uv tool install 或 Docker，支持多账号隔离、资源 ACL、静态加密、认证配置）；火山引擎托管服务（Personal/Enterprise 套餐，含开源版迁移工具，海外计划经 BytePlus）；企业自管版（BYOC 部署在自有 VPC，分布式部署与官方支持靠 license key 激活）。另有 macOS/Windows 桌面端（Beta），用于配置本机 Agent 集成、查看召回事件、同步本地记忆与技能。学术侧，团队与中国人民大学、浙江大学、上海交通大学合作，README 列出的三篇论文——VikingMem 记忆管理（VLDB 2026）、目录感知向量检索（ICDE）、VikingRAG——分别对应本文的记忆、目录递归检索与结构化 RAG 三块机制，论文编号 arXiv:2605.29640、2606.16903、2609.11390，想深挖设计依据可以从这三篇读起。

七、适用边界与采用建议

适合现在就上的：给 Claude Code、Codex、Cursor 这类编码 Agent 加跨会话记忆的个人与团队——官方 hooks + MCP 插件开箱即用，成本主要是 embedding 与 VLM 的调用费；正在做需要长期用户记忆的助理、客服类 Agent，且被「记忆只是聊天记录堆积」困扰的开发者。

建议观望的：要在修改版基础上对外提供网络服务的团队，主项目 AGPL-3.0 的开源义务需要先过法务；期望稳定 API 的生产系统——项目仍在 0.x 快速迭代期，0.3→0.4 就发生过命名空间与数据模型的破坏性迁移，升级前先看迁移指南并备份（ov backup 导出 OVPack）；只想要轻量向量检索的场景，一套传统向量库加嵌入式 RAG 更简单，OpenViking 的价值要在「记忆 + 资源 + 技能统一管理」这件事成立时才兑现。

一条稳妥的路径：先在 openviking.ai/studio 的在线 Demo 里看目录与语义搜索的手感，再本地 Docker 起一个单机实例，挑一个 Agent（比如 Claude Code）接插件跑一两周真实任务，观察 ~/memories/ 下沉淀的记忆质量，最后再决定是否上托管或自建多租户。

八、结语

OpenViking 的赌注是：Agent 时代的上下文管理会像操作系统管理文件一样，收敛到「路径 + 目录 + 按需加载」这组朴素抽象上。它把向量检索降级为文件系统的索引机制，把记忆做成可审阅、可编辑、带审计日志的文件，把技能规范成 SKILL.md——Agent 知道什么因此第一次变得肉眼可查。38.5k Stars 与三个月 21 个 0.4.x 版本的迭代速度，说明这个赌注押中了社区的真实痛点；至于目录式上下文能否成为 Agent 基础设施的终局形态，还要看它在更多生产负载下的表现。

参考来源与口径说明

• 数据快照：2026-09-23，版本锚点 v0.4.21（2026-09-20 发布）；GitHub 数据取自 GitHub API。
• 本文初版基于 v0.1.x 时期的 README（2026-03-28），2026-09 按现行仓库全面校订：主项目许可已于 2026-03-30 由 Apache-2.0 变更为 AGPL-3.0；0.4.0 引入 User/Peer 模型并调整 viking://agent/ 语义；AGFS 已由 Go 实现重写为 Rust 实现并移除 HTTP 客户端模式；ov CLI 现以 npm 包 @openviking/cli 为主安装方式。
• L0/L1/L2 尺寸口径：docs/concepts/03-context-layers 给出默认字符上限（256/4000 字符），FAQ 给出近似 token 数（约 100/约 2k token），两者并存不矛盾。
• 第五节 benchmark 为官方自测口径（README “Proof it works” 节，v0.3.22），复现脚本在仓库 benchmark/ 目录，完整报告见 blog.openviking.ai。
• 机制描述对照仓库 docs/en/（architecture、context-types、context-layers、viking-uri、retrieval、session、storage）与 docs/en/migration/01-user-peer-model。

来源

• GitHub：https://github.com/volcengine/OpenViking
• 文档：https://docs.openviking.ai/
• 博客：https://blog.openviking.ai/

OpenViking 由字节跳动火山引擎 Viking 团队开源，主项目采用 AGPL-3.0 许可证，crates/ov_cli 与 examples/ 采用 Apache-2.0。