OpenViking 架构解读:用 viking:// 虚拟文件系统与 L0/L1/L2 分层加载管理 AI Agent 的上下文

本文基于 OpenViking 仓库的日语版 README(README_JA.md)展开,系统介绍 OpenViking 作为“AI Agent 的上下文数据库”的核心设计:viking:// 统一 URI 地址空间、L0/L1/L2 三级上下文加载、可观察的层级检索、快速启动与 ov CLI 操作、Agent 集成与 VikingBot 等实战能力。读完后你可以完整理解 OpenViking 的架构思想,并能独立完成服务部署、资源导入、索引重建与检索调用的全流程操作。

OpenViking 将记忆(memory)、资源(resource)、技能(skill)三类上下文统一存放在一个虚拟文件系统中,让 Agent 不再面对黑盒向量库,而是像开发者操作文件一样,用 ls、tree、find 等命令确定性地浏览、定位自己的上下文。

一、OpenViking 是什么:上下文数据库范式

OpenViking 是一个开源的、面向 AI Agent 的上下文数据库(Context Database)。它的定位可以用三句话概括:

1. 一切上下文皆文件。记忆、资源、技能都获得 viking:// 形式的 URI,Agent 可以确定性地寻址和操作它们,而不是向一个不可见的向量存储发请求;
2. 分层加载省 token。每个条目在写入时就被加工成 L0(abstract)、L1(overview)、L2(details)三个层次,任务需要多深才加载多深;
3. 检索全程可观察。每次查询都会保留“目录浏览”式的轨迹(trace),结果异常时可以精确回放是哪条路径产生了该结果。

从源码结构看,这一范式在实现层有直接对应:openviking/core/context.py 中定义了统一的 Context 类,以及两个关键枚举:

• ContextType:SKILL / MEMORY / RESOURCE,对应 README 中“记忆、资源、技能”三类上下文;
• ContextLevel:ABSTRACT = 0(L0)、OVERVIEW = 1(L1)、DETAIL = 2(L2),注释明确写着 “Context level (L0/L1/L2) for vector indexing”,即分层不仅服务于加载,也直接进入向量索引维度。

viking:// 地址空间布局

README 给出的标准目录树如下,这也是理解整个系统的数据模型基础:

viking://
├── resources/              # 资源:项目文档、代码仓库、Web 页面等
│   └── my_project/
│       ├── docs/
│       │   ├── api/
│       │   └── tutorials/
│       └── src/
└── user/
    └── {user_id}/
        ├── memories/
        │   └── preferences/
        │       ├── writing_style
        │       └── coding_habits
        ├── resources/
        │   └── private_project/
        ├── skills/
        │   ├── search_code
        │   └── analyze_data
        └── peers/
            └── web-visitor-alice/

两个关键根目录:

• viking://resources/:全局共享资源,如导入的项目文档、代码仓库、网页;
• viking://user/{user_id}/:按用户隔离的私有空间,下辖 memories/(记忆,再细分 preferences 等类别)、resources/(用户私有资源)、skills/(技能)、peers/(peer 视图,用于多租户/共享会话场景)。

L0/L1/L2 三个加载层级

README 对三个层级的定义:

层级	名称	用途	典型体积
L0	Abstract	一句话摘要,用于快速相关性判断	~100 tokens
L1	Overview	核心信息与使用场景,用于计划制定	~2k tokens
L2	Details	完整原始数据,仅在需要时加载	完整内容

其精妙之处在于:每个目录都拥有自己的 L0/L1 层。以 README 中的示例:

viking://resources/my_project/
├── .abstract               # L0: ~100 tokens - 快速相关性判断
├── .overview               # L1: ~2k tokens - 结构与关键点
└── docs/
    ├── .abstract
    ├── .overview
    └── api/
        ├── auth.md         # L2: 完整内容,按需加载
        └── endpoints.md

因此在读取任何文件之前,系统可以先看目录级的 .abstract/.overview 判断相关性,从而避免把整棵文档树塞进上下文。

源码佐证:sidecar 文件与层级检索

这一“目录带 L0/L1”的设计在代码中有两处直接证据:

1. sidecar 文件规范。openviking/storage/abstract_overview.py 模块头部注释说明:“Only .abstract.md and .overview.md use this module”,并定义常量 ABSTRACT_OVERVIEW_FILENAMES = frozenset({".abstract.md", ".overview.md"})。这两个生成物采用带 frontmatter 的“OKF 文档”格式,metadata 字段(如 directory、source、generated_by、freshness)会被严格校验、未知字段被丢弃以保持前向兼容——这保证了 L0/L1 内容可以被机器可靠解析,而不是普通 Markdown。

2. 层级即检索维度。openviking/retrieve/hierarchical_retriever.py 中的 HierarchicalRetriever 定义:

   LEVEL_URI_SUFFIX = {0: ".abstract.md", 1: ".overview.md"}
   

   其 retrieve() 方法签名支持 level: Optional[List[int]] = None 参数(注释:“0=L0, 1=L1, 2=L2”),并内置 thinking / quick 两种模式。也就是说,上层可以显式要求“只搜 L0 做粗筛”或“搜到 L2 拿全文”,分层加载在检索 API 层面是一等公民。

二、为什么选择 OpenViking:五大能力点

README「OpenVikingを選ぶ理由」一节列出的五个卖点,每一条都有对应的实现支撑:

1. 所有上下文归入一个文件系统。记忆、资源、技能各有 viking:// URI,Agent 可以像开发者操作文件一样确定性地定位与操作上下文;
2. 层级加载削减 token 消耗。所有条目写入时即被加工成 L0/L1/L2,按需加载所需深度;
3. 目录递归检索。向量检索先锁定最高分的目录,再从该目录逐层下钻,返回的结果天然携带周边上下文;
4. 可观察的检索。每个查询保存目录浏览轨迹,便于排查“这条结果是从哪条路径来的”;
5. 会话即记忆。会话提交(commit)后,OpenViking 会异步抽取用户偏好与 Agent 经验,持久化为长期记忆。

从源码结构看,第 3 点由 HierarchicalRetriever._recursive_search() 实现(先全局检索候选,再对高优目录并行下钻,MAX_PARALLEL_CHILD_SEARCHES = 4 限制单请求扇出),第 5 点对应配置中的 memory.extraction_enabled 与队列 queue_workers.session_commit 的异步处理,详见下文配置小节。

三、实证数据:LoCoMo 与 tau2-bench 评测

OpenViking 0.3.22 在两个基准上完成评测:长对话用户记忆(LoCoMo)与多轮 Agent 任务(tau2-bench)。内存评测使用 Doubao 2.0 Pro 作为 VLM、Doubao-embedding-vision-251215 作为 Embedding 模型。

核心结论(以仓库 README 原文数据为准):

• 用户记忆(LoCoMo):接入 OpenViking 后,三个 Agent 集成(OpenClaw、Hermes、Claude Code)的精度均达到 80–83%,而原生记忆方案为 24–57%;同时输入 token 降低 34.3–91.0%,查询延迟降低 58.45–66.10%;
• Agent 经验(tau2-bench):引入经验记忆后,同一 LLM 相比无记忆基线,任务成功率在 Retail 场景提升 +6.87pp、Airline 场景提升 +11.87pp。

这些数字可通过仓库内的 benchmark 目录复现,例如 benchmark/locomo/(含 openclaw、hermes、mem0、openviking、vikingbot 等多个集成子目录)与 benchmark/longmemeval/,其中每个评测子目录均提供运行脚本与说明文档。

四、快速启动:从安装到第一次检索

4.1 安装与服务启动

前置要求:Python 3.10+。

pip install openviking --upgrade
openviking-server init      # 交互式向导:提供商、模型、ov.conf
openviking-server doctor    # 校验安装
openviking-server           # 启动服务

或后台运行:

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

init 会交互式引导提供商配置并写出 ~/.openviking/ov.conf,支持 Volcengine、OpenAI、Codex OAuth、Kimi、GLM 及本地 Ollama(对 Ollama 还包含运行时检测、安装与按硬件推荐模型的引导);doctor 则在不启动服务的前提下检查配置文件、Python 版本、提供商连通性与磁盘空间。

4.2 首次资源导入与检索

服务启动后,典型的 ov CLI 工作流:

ov status
ov add-resource https://github.com/volcengine/OpenViking # 可加 --wait
ov ls viking://resources/
ov tree viking://resources/volcengine -L 2
# 不加 --wait 时,需等待语义处理完成
ov find "what is openviking"
ov grep "openviking" --uri viking://resources/volcengine/OpenViking/docs/en

要点:

• add-resource 负责把外部内容(文档、仓库、网页)导入 viking://resources/ 并完成语义加工;不带 --wait 时是异步的,需稍等 .abstract/.overview 与向量生成完毕;
• ls/tree 对应 README 所强调的“用文件命令浏览上下文”;
• find 是语义检索入口,grep 则在指定 URI 范围内做内容级精确匹配。

客户端配置可通过 ov config 交互式初始化;管理多台服务器时用 ov config switch 切换。

4.3 索引重建:reindex 的三种模式

对已有索引的重建,README 明确给出了三种模式:

ov reindex <uri> --mode vectors_only            # 仅更新向量
ov reindex <uri> --mode semantic_and_vectors     # 重新生成 .abstract.md / .overview.md 后再更新向量
ov reindex <uri> --mode prune_orphans --dry-run  # 清理源文件已不存在的孤儿向量记录(可预演)

注意 README 特别提醒:不存在 semantic 或 full 这类模式别名。Rust 版 CLI 源码(crates/ov_cli/src/client.rs)中的 reindex 请求体正是以 processing_mode 字段携带 vectors_only / semantic_and_vectors 提交到 /api/v1/content/reindex,CLI 帮助文本(crates/ov_cli/src/help_ui.rs)也列出了 prune_orphans --dry-run 的官方示例用法。

4.4 其他安装方式

• Rust CLI:通过 npm i -g @openviking/cli 安装,或从源码 cargo install --git https://github.com/volcengine/OpenViking ov_cli;
• Docker:提供官方镜像;
• 配置文件模板:仓库中 examples/ov.conf.example 是完整的 ov.conf 参考样例,涵盖了 server、cache、storage、embedding、vlm、rerank、retrieval、parsers、ingest、bot、log、encryption 等全部配置段。

五、核心配置详解(基于 ov.conf.example)

以 examples/ov.conf.example 为基准,梳理与本文主题强相关的配置段及其默认取值:

5.1 语义分层与检索

"auto_generate_l0": true,
"auto_generate_l1": true,
"default_search_mode": "thinking",
"default_search_limit": 3,
"retrieval": {
    "hotness_alpha": 0.0,
    "score_propagation_alpha": 1.0,
    "recall_intent_timeout_s": 5.0,
    "recall_rewrite_timeout_s": 30.0
},
"grep": {"engine": "auto", "switch_to_remote_threshold": 10000}

• auto_generate_l0 / auto_generate_l1:控制写入时是否自动生成分层摘要——这正是 README 中“写入时即加工为 L0/L1”的开关;
• default_search_mode: "thinking" 对应 HierarchicalRetriever 的两种模式之一(thinking 模式在配置了 rerank 时为默认),另有 quick 快速模式;
• retrieval.hotness_alpha / score_propagation_alpha 分别控制“热度分”与“父目录分数向子节点传播”的权重,后者在源码中由 HierarchicalRetriever 直接读取(self.hotness_alpha、self.score_propagation_alpha),是层级检索打分融合的核心参数。

5.2 记忆与会话提取

"memory": {
    "version": "v2",
    "extraction_enabled": true,
    "session_skill_extraction_enabled": false
},
"enable_memory_decay": true,
"memory_decay_check_interval": 3600,
"queue_workers": {
    "session_commit": {"max_concurrent": 8}
}

这组配置支撑 README 中“会话是记忆”的能力:会话提交后由 session_commit 队列(默认 8 并发)异步完成用户偏好与经验的抽取;enable_memory_decay 开启记忆衰减机制,每小时检查一次。

5.3 模型与存储

• embedding.dense:示例为 doubao-embedding-vision-251215、1024 维、input: multimodal,并提供了 Ollama 本地部署示例(embedding_ollama_example,nomic-embed-text、768 维、纯文本);
• vlm:语义摘要生成使用的视觉语言模型,示例覆盖 Volcengine、Codex OAuth(openai-codex,token 存于 ~/.openviking/codex_auth.json)、Kimi、GLM 四种订阅制配置;
• storage:本地 workspace 默认 ./data,vectordb 后端可选 local 或 Volcengine VikingDB,agfs 提供 local/cachefs/queuefs/s3 多级文件系统抽象;
• encryption:默认本地主密钥文件(~/.openviking/master.key),亦提供 HashiCorp Vault 与 Volcengine KMS 两个集成示例段。

完整参数取值与 Windows 环境设置,建议直接以 examples/ov.conf.example 与官方配置指南为准。

六、与 Agent 生态集成

OpenViking 的集成机制是把 recall(检索注入)接进 Agent 的上下文,并把会话记忆自动 commit 回来。README 列出的官方集成面包括:Claude Code、Codex、OpenClaw、Hermes、Cursor、Trae、OpenCode、pi、Agent Plugins 1.0、MCP 客户端、LangChain/LangGraph。

这些集成在仓库中都有对应实现目录,可逐一查证:

• examples/claude-code-memory-plugin:Claude Code 记忆插件(含 hooks、servers、scripts);
• examples/codex-memory-plugin:Codex 插件(附设计文档 DESIGN.md);
• examples/openclaw-plugin:OpenClaw 插件(含 40+ 个测试文件);
• examples/cursor-memory-plugin 与 examples/trae-memory-hooks、examples/trae-cli-memory-hooks:Cursor 与 Trae 的 hook 集成;
• examples/opencode-plugin:OpenCode 插件;
• examples/pi-coding-agent-extension:pi 编码 Agent 扩展(含 recall、sync、takeover 模块);
• integrations/langchain:LangChain 集成包;
• agent-plugins:Agent Plugins 1.0 的 MCP 代理与共享服务。

此外,ov.conf.example 中的 ingest 配置段声明了各 harness(claude_code、codex、opencode、hermes、openclaw)的接入模式(both / backfill / watch),体现了服务端反向收割 Agent 会话数据的能力。

七、OpenViking Helper 与 VikingBot

OpenViking Helper(Beta)

面向开发者的桌面控制台,当前提供 macOS 与 Windows x64 的 Beta 版,三大能力:

• 本地 Agent 配置可视化:检测 OpenViking CLI、Claude Code、Codex、Cursor、Trae、OpenCode,自动配置对应的 plugin、MCP、Hook、CLI 集成;
• 会话轨迹查看:解析 Claude Code、Codex、Trae 的会话,展示 OpenViking 的 recall、prompt 注入、MCP 调用、capture、commit 事件——这与“可观察的检索”设计理念一脉相承;
• 本地记忆与技能管理:浏览本地 memory / rule 文件与 SKILL.md 技能,并同步到 OpenViking。

VikingBot

VikingBot 是构建在 OpenViking 之上的 AI Agent 框架,三条命令即可跑起来:

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

官方 Docker 镜像默认内置 VikingBot,随服务器和控制台 UI 一起启动。仓库内 bot/ 目录包含完整的 vikingbot 实现(agent、channels、sandbox、session 等子模块)、部署脚本(bot/deploy)与文档(bot/docs)。

八、生产部署与版本策略

生产环境建议将 OpenViking 作为独立的 HTTP 服务运行(可参考 deploy/helm 中的 Helm Chart 与 Dockerfile 构建产物)。版本策略上,README 明确指出:

• 开源版无任何功能限制:AGPLv3 协议下完整开源,无功能锁定、无账号注册、无激活码,可自行完成生产部署;
• 商业版(托管 SaaS 与私有化部署)解决的是“谁来运维、部署在哪里”的问题,而非“能不能用”的问题。

九、学术背景、社区与许可

学术研究:OpenViking 开源了 VikingMem 论文中记载的核心能力之一:

VikingMem: A Memory Base Management System for Stateful LLM-based Applications Jiajie Fu, Junwen Chen, Mengzhao Wang, Aoxiang He, Maojia Sheng, Xiangyu Ke, Yifan Zhu, and Yunjun Gao. arXiv:2605.29640, 2026. Accepted by VLDB 2026.

社区:项目处于早期阶段,欢迎通过 issue 参与贡献,贡献规范见 CONTRIBUTING_JA.md;安全漏洞报告流程与受支持版本见 SECURITY.md。

许可证:项目按组件区分协议——

• 主项目:AGPLv3,见 LICENSE;
• crates/ov_cli:Apache 2.0,见 crates/LICENSE;
• examples:Apache 2.0,见 examples/LICENSE;
• third_party:沿用各自第三方项目的原始协议。

十、小结

OpenViking 把“上下文工程”从向量库的黑盒查询,重构为一套开发者熟悉的文件系统操作:viking:// 统一寻址、L0/L1/L2 分层按需加载、目录递归检索加全程轨迹可观察、会话自动沉淀为长期记忆。源码中 ContextLevel 枚举、.abstract.md/.overview.md sidecar 规范、HierarchicalRetriever 的 level 过滤与两种检索模式,共同印证了这一设计并非仅停留在文档层面。配合 ov CLI 的 add-resource / find / grep / reindex 工作流与多 Agent 插件生态,它可以作为 AI Agent 系统中记忆、RAG 知识与技能管理的统一底座。