OpenViking 上下文数据库：用 viking:// 虚拟文件系统统一 AI Agent 的 Memory、Knowledge RAG 与 Skills

OpenViking 是一个开源的 AI Agent 上下文数据库，它把记忆（memories）、资源（resources）与技能（skills）统一挂载在 viking:// 协议下的虚拟文件系统中，让 Agent 用 ls、tree、find 这类文件系统操作确定性地浏览自己的上下文，而不是查询一个黑盒向量库。本文基于仓库根 README（README.md）完整展开：先讲清其核心设计——L0/L1/L2 三级分层加载与目录递归检索，再给出从 pip install、init 向导、doctor 体检到 ov CLI 语义检索的完整实操流程，并结合源码剖析分层与检索的实现依据。读完本文，你可以独立部署一个 OpenViking 服务，并用 CLI 与 Python SDK 完成资源写入、层级浏览和可观测检索。

一、核心设计：一个文件系统承载全部上下文

README 将 OpenViking 概括为五个特性，它们共同构成"上下文即文件"的设计范式：

1. 一个文件系统承载所有上下文：记忆、资源、技能各自拥有 viking:// URI，Agent 像开发者操作文件一样确定性地定位和操作上下文；
2. 分层加载削减 token 消耗：每条内容在写入时被处理为 L0（摘要）、L1（概览）、L2（详情）三层，按需加载到任务所需的深度；
3. 目录递归检索：向量搜索先定位得分最高的目录，再逐层向下钻取，使结果携带完整周边上下文；
4. 可观测检索：每次查询保留目录浏览轨迹（trajectory），结果异常时能看到是哪条路径产生的；
5. 会话即记忆：Session 提交后，OpenViking 异步抽取用户偏好与 Agent 经验，沉淀为长期记忆。

README 中给出的标准目录结构如下，它是理解整个项目的骨架：

viking://
├── resources/              # Resources: project docs, repos, web pages, etc.
│   └── 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/

可以看到三类顶层命名空间：resources/ 存放项目文档、代码仓库、网页等共享资源；user/{user_id}/memories/、resources/、skills/ 分别存放该用户的偏好记忆、私有资源与技能；peers/ 则用于多租户/多访客场景下的对端上下文。

L0/L1/L2 三层加载：写入时分层，读取时按需

README 对三层的定义：

• L0（Abstract 摘要）：一句话摘要，用于快速相关性判断；
• L1（Overview 概览）：核心信息与使用场景，用于任务规划；
• L2（Details 详情）：完整原始数据，仅在需要时读取。

关键细节是：每个目录都携带自己的 L0/L1 层，因此在读取任何完整文件之前就能判断相关性。README 示例：

viking://resources/my_project/
├── .abstract               # L0: ~100 tokens - quick relevance check
├── .overview               # L1: ~2k tokens - structure and key points
└── docs/
    ├── .abstract
    ├── .overview
    └── api/
        ├── auth.md         # L2: full content, loaded on demand
        └── endpoints.md

仓库源码印证了这一结构。openviking/core/context.py 中定义了上下文层级枚举：

class ContextLevel(int, Enum):
    """Context level (L0/L1/L2) for vector indexing"""
    ABSTRACT = 0  # L0: abstract
    OVERVIEW = 1  # L1: overview
    DETAIL   = 2  # L2: detail/content

即三层直接对应向量索引的三个粒度。检索器 openviking/retrieve/hierarchical_retriever.py 中同样定义了层级到 URI 后缀的映射，说明 .abstract/.overview 在存储层是实体文件：

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

目录递归检索的实现参数

"先定位高分目录、再逐层下钻"不是概念描述，而是有具体收敛策略的检索算法。从 hierarchical_retriever.py 中 HierarchicalRetriever 的类常量可以看出其工程取舍：

常量	默认值	含义
MAX_CONVERGENCE_ROUNDS	3	topk 连续多轮不变即停止递归，防止无限下钻
DIRECTORY_DOMINANCE_RATIO	1.2	目录得分必须超过其最高子项 1.2 倍，才沿该目录继续下钻
GLOBAL_SEARCH_TOPK	10	全局检索候选数（候选越多，rerank 精度越高）
MAX_PARALLEL_CHILD_SEARCHES	4	限制单请求对远端向量库的扇出并发，保护后端

检索器构造时接收 RerankConfig 与 RetrievalConfig，支持 dense/sparse 混合的 Embedder；未配置 rerank 时回退为纯向量检索。这与 README"向量搜索先定位目录、再逐层下钻、结果带周边上下文"的描述一一对应。而"可观测检索"则由 openviking/observability/ 下的 trace 桥接与事件模块承载，每次查询的目录浏览轨迹被完整保留供调试。

二、快速上手：安装、init 向导与 ov CLI

环境要求与安装

README 明确 要求 Python 3.10 及以上。仓库 pyproject.toml 中 requires-python = ">=3.10"，classifiers 覆盖 3.10–3.14，包名为 openviking（描述为 "An Agent-native context database"），主依赖中可见 FastAPI、Uvicorn、tree-sitter 多语言解析、litellm、OpenTelemetry 等，说明服务端是 FastAPI 应用并内置代码/文档解析管线。安装命令：

pip install openviking --upgrade

三个命令完成部署

README 给出的最小部署序列（服务端默认监听端口为 1933，见 openviking/server/config.py 中 port: int = 1933 的默认值）：

openviking-server init      # 交互式向导：选择 provider、模型，生成 ov.conf
openviking-server doctor    # 校验配置
openviking-server           # 启动服务（后台：nohup openviking-server > openviking.log 2>&1 &）

• init：交互式向导，引导完成 provider 配置并写入 ~/.openviking/ov.conf。支持的 provider 包括 Volcengine、OpenAI、Codex OAuth、Kimi、GLM 与本地 Ollama；对 Ollama 场景还能检测并安装运行时、拉取适配硬件的模型。
• doctor：无需运行中的服务即可检查配置文件、Python 版本、provider 连通性与磁盘空间，适合部署前体检。
• 入口映射：从 pyproject.toml 的 [project.scripts] 可见，ov 与 openviking 命令均指向 Rust CLI 入口 openviking_cli.rust_cli:main，openviking-server 指向 openviking_cli.server_bootstrap:main。也就是说安装即附带 ov 客户端 CLI，CLI 本体是 Rust 实现（对应 crates/ov_cli），Python 侧保留 SDK 与服务端。

ov CLI：像操作文件一样操作上下文

服务运行后，README 给出了完整的上下文操作序列：

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 拉取 URL 并进入解析/语义处理管线）、浏览（ls/tree -L 2 限制深度）、语义检索（find 走分层向量检索）、精确过滤（grep --uri 限定作用域）。add-resource 的 --wait 选项对应服务端异步语义处理：不加则资源先落盘、后台生成 L0/L1 摘要，加则阻塞至可检索。

Python SDK 等价操作

仓库提供可直接运行的示例 examples/quick_start.py，演示了与 CLI 对应的 SDK 调用（默认连接 http://localhost:1933）：

from openviking_sdk import SyncHTTPClient

client = SyncHTTPClient(url="http://localhost:1933")
client.initialize()

# 写入资源并等待语义处理完成
res = client.add_resource(
    path="https://raw.githubusercontent.com/volcengine/OpenViking/refs/heads/main/README.md",
    wait=True,
)
root_uri = res["root_uri"]

print(client.ls(uri=root_uri))                       # 浏览资源树
print(client.glob(pattern="**/*.md", uri=root_uri))   # glob 定位文件
print(client.read(uri=...))                           # 读取 L2 全文
print(client.abstract(uri=root_uri))                  # 读取 L0
print(client.overview(uri=root_uri))                  # 读取 L1
results = client.find(query="what is openviking", target_uri=root_uri)  # 语义检索
client.close()

abstract/overview/read 三个 API 正是 L0/L1/L2 三层加载在客户端的投影，find 则对应前述 HierarchicalRetriever 的目录递归检索。仓库中另有 examples/basic-usage/basic_usage.py 与 examples/cloud/（多用户云部署示例：alice.py、bob.py、setup_users.py）可进一步参考。

三、Benchmark 证据：分层记忆带来的实际收益

README 指出 OpenViking 0.3.22 版本在两类基准上完成评测（完整结果与知识库问答结果见其官方 benchmark 报告，复现脚本在仓库 benchmark 目录）：

• 用户记忆（LoCoMo 长对话基准）：接入 OpenViking 后，三种 Agent 集成方案的准确率落在 80%–83%，而其原生记忆仅为 24%–57%；同时输入 token 下降 34.3%–91.0%，查询延迟下降 58.45%–66.10%。具体地，README 图表数据为：OpenClaw 24.20% → 82.08%、Hermes 33.38% → 82.86%、Claude Code 57.21% → 80.32%；
• Agent 经验（tau2-bench 多轮任务基准）：经验记忆使任务成功率提升 +6.87pp（retail 场景，70.94% → 77.81%）与 +11.87pp（airline 场景，54.38% → 66.25%），对照为同一 LLM 无记忆基线。

评测配置：记忆评测使用 Doubao 2.0 Pro 作为 VLM、Doubao-embedding-vision-251215 作为嵌入模型。仓库 benchmark/ 下按基准组织了可复现脚本：benchmark/locomo/（按 openclaw、hermes、claudecode、openviking 等分目录）、benchmark/tau2/、benchmark/RAG/ 与 benchmark/longmemeval/，读者可以按 README 声明的口径自行复跑验证。这些数字是 README 声明的官方评测结果，引用时建议注明版本（0.3.22）与模型配置前提。

四、与 Agent 集成：recall 注入与记忆自动提交

README 强调各集成统一做两件事：把 OpenViking 的 recall 注入 Agent 上下文，并在会话结束自动提交 session 记忆（对应"会话即记忆"特性）。README 列出的集成清单及仓库内对应实现目录：

集成	仓库内对应物
Claude Code	examples/claude-code-memory-plugin/（含 hooks、53 个 scripts、skills）
Codex	examples/codex-memory-plugin/
Cursor	examples/cursor-memory-plugin/（含 rules 与 hooks）
OpenClaw	examples/openclaw-plugin/（TS 插件，含 58 个测试文件）
OpenCode	examples/opencode-plugin/
pi	examples/pi-coding-agent-extension/
TRAE / TRAE CN / TraeCode CLI	examples/trae-memory-hooks/、examples/trae-cli-memory-hooks/
MCP 客户端	服务端 openviking/server/mcp_endpoint.py
LangChain / LangGraph	integrations/langchain/（独立可发布包）
通用共享库	examples/memory-plugin-shared/（recall 核心、workspace 身份、sync 等 23 个模块 + 测试）

多数插件遵循同一形态：hooks/ 定义触发时机、servers/ 提供 MCP 服务、scripts/ 实现 recall/commit 动作、skills/ 存放 SKILL.md 技能定义，共享逻辑收敛在 examples/memory-plugin-shared/lib/。另有面向 Cordis 的 examples/dsh-memory-plugin/ 与 zcode 的 examples/zcode-memory-plugin/。Agent Plugins 1.0 的形态则对应仓库 agent-plugins/（含 mcp-proxy 与 shared 模块）。

五、VikingBot、OpenViking Helper 与生产部署

VikingBot：构建于 OpenViking 之上的 Agent 框架

README 给出三行启动方式：

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

[bot] 是一个 PEP 621 extras，pyproject.toml 中该选项拉入完整能力：websockets、Gradio、prompt-toolkit、Langfuse、Telegram/Lark/DingTalk/Slack/QQ 多渠道 SDK、沙箱（opensandbox/agent-sandbox/FUSE）与 MCP 等。框架代码位于 bot/vikingbot/，模块划分包括 agent/、channels/（19 个渠道实现）、cron/、heartbeat/、sandbox/、providers/ 等，测试覆盖在 bot/tests/。官方 Docker 镜像默认捆绑 VikingBot，与 server 和控制台 UI 一起启动（构建脚本见 Dockerfile、docker-compose.yml 与 docker/openviking-entrypoint.sh）。

OpenViking Helper（Beta）

README 还提到桌面控制台 OpenViking Helper，当前 beta 版本支持 macOS（Apple Silicon / Intel）与 Windows x64，能力包括：自动检测 OpenViking CLI、Claude Code、Codex、Cursor、Trae、OpenCode 并配置插件/MCP/Hook 集成；解析 Claude Code/Codex/Trae 会话以检查 OpenViking recall、prompt 注入、MCP 调用、capture 与 commit 事件；查看本地记忆/规则文件与 SKILL.md 技能并同步到 OpenViking。下载渠道以官方发布页为准。

生产部署与商业版本

生产环境建议将 OpenViking 作为独立 HTTP 服务运行（README 指向官方部署指南；仓库内 deploy/helm/openviking/ 提供 Helm Chart，bot/deploy/ 下另有 Docker/ECS/VKE 部署脚本与配置）。

README 明确强调开源版本不受限：AGPLv3 完整开源，无功能开关、无账号要求、无激活密钥，可直接上生产。其商业版本（托管 SaaS 与自管部署）回答的是"谁来运维、跑在哪里"，而非"能不能用"：SaaS 托管在火山引擎，个人版含免费试用（最多 50 个文件，基于 VikingDB 可扩展）；自管版支持部署到自有云账号/VPC（BYOC）乃至完全离线环境，在开源版之上增加分布式部署与官方支持，通过 license key 激活。

研究背景与授权

OpenViking 开源了 VikingMem 论文（《VikingMem: A Memory Base Management System for Stateful LLM-based Applications》，arXiv:2605.29640，2026，被 VLDB 2026 接收）中核心能力的一个子集，论文中描述的记忆基管理系统是该项目分层、生命周期与检索设计的学术背景。

授权方面，README 声明各组件采用不同协议：主项目 AGPLv3（LICENSE）；crates/ov_cli 为 Apache 2.0（crates/LICENSE）；examples 为 Apache 2.0（examples/LICENSE）；third_party 沿用各自原始许可。

六、小结

OpenViking 的关键贡献是把 Agent 上下文管理从"黑盒向量检索"拉回到"文件系统"的心智模型：viking:// URI 提供确定性寻址（openviking/core/uri_validation.py、openviking/core/directories.py），L0/L1/L2 分层在写入期生成（openviking/core/context.py），目录递归检索在读取期按需加载（openviking/retrieve/hierarchical_retriever.py），Session 提交后异步沉淀长期记忆。对读者而言，落地路径非常短：pip install openviking --upgrade → openviking-server init / doctor / 启动 → ov add-resource + ov find，即可在自己的 Agent 中跑起一套可观测、可分层、可复现的上下文数据库。