volcengine OpenViking

OpenViking：面向 AI 代理的上下文数据库中文 / 日本語 · 网站 · 在线演示 · GitHub · Issues · 文档

👋 加入我们的社区 📱 Lark 群组 · 微信 · Discord · X

什么是 OpenViking

OpenViking 是一个开源的 AI 代理上下文数据库。它将记忆、资源和技能存储为 viking:// 协议下的一个虚拟文件系统，因此代理可以通过 ls、tree 和 find 来浏览自己的上下文，而无需查询黑盒向量存储。内容被处理为三个层级——L0 摘要、L1 概览、L2 详情——并按需加载。每次检索都会留下可查看和调试的轨迹。

完整介绍：[快速开始](https://github.com/volcengine/OpenViking)。

OpenViking Studio 游乐场——一个可在浏览器中打开的在线演示，无需安装。

为什么选择 OpenViking

一个文件系统承载所有上下文。 记忆、资源和技能各自拥有 viking:// URI。代理可以确定性地定位和操作上下文，就像开发人员处理文件一样。 → [Viking URI · 上下文类型](https://github.com/volcengine/OpenViking)

分层加载降低 Token 消耗。 每个条目在写入时被处理为 L0（摘要）、L1（概览）和 L2（详情），然后仅按任务需要的深度加载。 → [上下文层级](https://github.com/volcengine/OpenViking)

目录递归检索。 向量搜索首先定位得分最高的目录，然后逐层深入，因此结果会连同其周围上下文一起完整返回。 → [检索](https://github.com/volcengine/OpenViking)

可观测的检索。 每次查询都会保留其目录浏览轨迹。当结果看起来不对时，你可以准确看到是哪条路径产生了它。 → [检索](https://github.com/volcengine/OpenViking)

会话沉淀为记忆。 会话提交后，OpenViking 会异步提取用户偏好和代理经验到长期记忆中。 → [会话](https://github.com/volcengine/OpenViking)

各组件如何协同工作：[架构](https://github.com/volcengine/OpenViking)。设计背后的思考：[上下文工程的数据库范式](https://github.com/volcengine/OpenViking)。

viking://
├── resources/          # 资源：项目文档、代码仓库、网页等
│   └── 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/

三个加载层级：

L0（摘要）：一句话摘要，用于快速相关性检查。
L1（概览）：核心信息和使用场景，用于规划。
L2（详情）：完整的原始数据，仅在需要时读取。

每个目录都带有自己的 L0/L1 层级，因此可以在读取任何完整文件之前判断相关性：

viking://resources/my_project/
├── .abstract          # L0：约 100 tokens - 快速相关性检查
├── .overview          # L1：约 2k tokens - 结构和要点
└── docs/
    ├── .abstract
    ├── .overview
    └── api/
        ├── auth.md    # L2：完整内容，按需加载
        └── endpoints.md

有效性验证

OpenViking 0.3.22 已在长对话用户记忆（LoCoMo）和多轮代理任务（tau2-bench）上进行了评估。完整结果和设置细节（包括知识库问答）见[基准测试报告](https://github.com/volcengine/OpenViking)；复现脚本位于 ./benchmark。

用户记忆（LoCoMo）：使用 OpenViking 后，三种代理集成的准确率均达到 80–83%——而它们原生记忆的准确率仅为 24–57%——同时输入 token 减少 34.3–91.0%，查询延迟降低 58.45–66.10%。

代理经验（tau2-bench）：与没有记忆的同一 LLM 相比，经验记忆使任务成功率提升 +6.87 个百分点（零售）和 +11.87 个百分点（航空）。

快速开始

💡 想先看看实际效果？试试 OpenViking Studio——一个托管的在线实例，包含上下文游乐场、语义搜索和多代理中心。无需安装。

需要 Python 3.10 或更高版本。

pip install openviking --upgrade
openviking-server init    # 交互式向导：提供商、模型、ov.conf
openviking-server doctor  # 验证设置
openviking-server         # 启动（后台运行：nohup openviking-server > openviking.log 2>&1 &）

init 会引导你完成提供商设置并写入 ~/.openviking/ov.conf。它支持火山引擎、OpenAI、Codex OAuth、Kimi、GLM 以及本地 Ollama——对于 Ollama，它可以检测并安装运行时，并拉取适合你硬件的模型。

doctor 检查配置文件、Python 版本、提供商连通性和磁盘空间，无需运行服务器。

手动 ov.conf 模板、各提供商示例、环境变量和 Windows 设置：[配置指南](https://github.com/volcengine/OpenViking) · [快速开始文档](https://github.com/volcengine/OpenViking)。

安装已包含 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

后续步骤：客户端配置（ov config）、独立 CLI 安装（npm / cargo）以及高级用法（如索引重建）：[CLI 设置](https://github.com/volcengine/OpenViking)

Docker 和生产部署：[部署指南](https://github.com/volcengine/OpenViking)

与你的代理一起使用

集成可将 OpenViking 召回注入代理的上下文，并自动提交会话记忆：

Claude Code
Codex
OpenClaw
Hermes
Cursor
TRAE / TRAE CN / TraeCode CLI 2.0
OpenCode
pi Agent
Plugins 1.0
MCP 客户端
LangChain / LangGraph

每个代理的设置说明：[代理集成概览](https://github.com/volcengine/OpenViking)。

OpenViking Helper（测试版）

OpenViking Helper 是一个桌面控制台，目前处于 macOS 和 Windows x64 的测试阶段：

可视化本地代理设置：检测 OpenViking CLI、Claude Code、Codex、Cursor、Trae 和 OpenCode，然后配置支持的插件、MCP、Hook 和 CLI 集成。
会话轨迹检查：解析 Claude Code、Codex 和 Trae 会话，显示 OpenViking 召回、提示注入、MCP 调用、捕获和提交事件。
本地记忆和技能管理：查看本地记忆 / 规则文件和 SKILL.md 技能，然后同步到 OpenViking。

下载：[macOS Apple Silicon (arm64)](https://github.com/volcengine/OpenViking) · [macOS Intel (x64)](https://github.com/volcengine/OpenViking) · [Windows (x64)](https://github.com/volcengine/OpenViking)

VikingBot

VikingBot 是一个构建在 OpenViking 之上的 AI 代理框架：

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

官方文档：[https://github.com/volcengine/OpenViking](https://github.com/volcengine/OpenViking)