🔥 volcengine/OpenViking
英文标题：🔥 volcengine/OpenViking
OpenViking 是一个面向 AI Agent 的开源上下文数据库，将记忆、资源与技能统一为 `viking://` 虚拟文件系统，使 Agent 可通过 `ls`、`tree`、`find` 等方式确定性地浏览上下文。系统将内容分为 L0 摘要、L1 概览和 L2 详情三层，按需加载以减少 Token 开销，并保留可观测、可调试的检索轨迹。其在 LoCoMo 长对话用户记忆评测中，将多个 Agent 集成的准确率提升至约 80% 至 83%，同时降低输入 Token 和查询延迟；在 tau2-bench 中也提高了任务成功率。项目提供 CLI、桌面版 OpenViking Helper、VikingBot、Docker 与生产部署支持，并以 AGPLv3 开源核心版本。
252.0 KB
1.7 KB
767 B
579 B
582 B
574 B
585 B
5.1 KB
115.8 KB
6.4 KB
6.4 KB
287.3 KB
283.3 KB
66.9 KB
中文
OpenViking 是一个面向 AI Agent 的开源上下文数据库。它将记忆、资源和技能存储为 viking:// 协议下的统一虚拟文件系统，因此 Agent 可以使用 ls、tree 和 find 浏览自身上下文，而非查询一个黑盒向量数据库。内容会被处理为三个层级——L0 摘要、L1 概览和 L2 详情——并按需加载。每一次检索都会留下可查看和调试的轨迹。完整介绍请参阅：快速入门。
OpenViking Studio 体验场——可直接在浏览器中打开的在线演示，无需安装。
- 一个文件系统容纳所有上下文。 记忆、资源和技能各自拥有一个
viking://URI。Agent 可以像开发者操作文件一样，以确定性的方式定位和处理上下文。→ Viking URI · 上下文类型 - 分层加载降低 Token 开销。 每一条目在写入时都会被处理为 L0（摘要）、L1（概览）和 L2（详情），并且只会加载任务所需深度的内容。→ 上下文层级
- 目录递归检索。 向量搜索会先定位得分最高的目录，再逐层向下深入，因此结果会连同其周边上下文一并返回。→ 检索
- 可观测检索。 每个查询都会保留其目录浏览轨迹。当结果看起来不正确时，你可以准确查看是哪条路径产生了该结果。→ 检索
- 会话沉淀为记忆。 会话提交后，OpenViking 会异步提取用户偏好和 Agent 经验，写入长期记忆。→ 会话
各组件如何协同工作：架构。该设计背后的思考：上下文工程的数据库范式。
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 Token——快速相关性检查
├── .overview # L1：约 2k Token——结构与要点
└── docs/
├── .abstract
├── .overview
└── api/
├── auth.md # L2：完整内容，按需加载
└── endpoints.md
OpenViking 0.3.22 已在长对话用户记忆（LoCoMo）和多轮 Agent 任务（tau2-bench）上接受评估。包括知识库问答在内的完整结果和配置细节，请参阅基准测试报告；复现脚本位于 ./benchmark。
- 用户记忆（LoCoMo）：使用 OpenViking 后，三种 Agent 集成的准确率均达到 80%–83%——相比其原生记忆机制的 24%–57% 有明显提升；同时，输入 Token 降低 34.3%–91.0%，查询延迟降低 58.45%–66.10%。
- Agent 经验（tau2-bench）：相较于不使用记忆的同一 LLM，经验记忆将任务成功率提高了 +6.87 个百分点（零售）和 +11.87 个百分点（航空）。
💡 想先看看实际效果？ 试试 OpenViking Studio——一个提供上下文体验场、语义搜索和多 Agent 中心的在线托管实例。无需安装。
需要 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。它支持 Volcengine、OpenAI、Codex OAuth、Kimi、GLM 和本地 Ollama——对于 Ollama，它可以检测并安装运行时，并拉取适合你硬件的模型。doctor 无需运行服务器即可检查配置文件、Python 版本、服务提供商连接状态和磁盘空间。手动 ov.conf 模板、各服务提供商示例、环境变量及 Windows 配置，请参阅：配置指南 · 快速入门文档。
安装包已包含 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
后续步骤：
集成可将 OpenViking 召回内容注入 Agent 的上下文，并自动提交会话记忆：
各 Agent 的设置说明：Agent 集成概览。
OpenViking Helper 是一款桌面控制台，目前面向 macOS 和 Windows x64 提供 Beta 版本：
- 可视化本地 Agent 设置：检测 OpenViking CLI、Claude Code、Codex、Cursor、Trae 和 OpenCode，然后配置受支持的插件、MCP、Hook 和 CLI 集成。
- 会话轨迹检查：解析 Claude Code、Codex 和 Trae 会话，展示 OpenViking 召回、提示词注入、MCP 调用、捕获和提交事件。
- 本地记忆与技能管理：查看本地记忆/规则文件及
SKILL.md技能，然后将其同步至 OpenViking。
下载：
VikingBot 是构建于 OpenViking 之上的 AI Agent 框架：
pip install "openviking[bot]"
openviking-server --with-bot
ov chat # 在另一个终端中运行
官方 Docker 镜像集成了 VikingBot，并默认与服务器和控制台 UI 一同启动。详情请参阅：VikingBot 指南。
对于生产环境，请将 OpenViking 作为独立 HTTP 服务运行——参阅服务器部署和部署指南。
开源版本不是功能受限版。 此仓库中的 OpenViking 以 AGPLv3 完全开源：没有功能门槛、无需账户、无需激活密钥。按照上文的生产部署方式自行在生产环境中运行即可——这一点将始终保持不变。
下面两个版本回答的是“由谁运营、部署在何处”，而不是“我能否使用它”。
官方托管于 Volcano Engine。无需配置，无需运维。
- 个人版——面向个人开发者。最多 50 个文件可免费试用，并可通过 VikingDB 扩展至远超本地硬件能力的规模。
- 企业版——提供多用户上下文管理、团队协作与权限控制、企业 SLA 和技术支持。
现有开源用户可使用迁移工具进行迁移。→ Volcano Engine 产品页面 · 文档 面向中国大陆以外地区的全球托管服务即将登陆 BytePlus。 | 
运行在你自己的环境中。数据不会离开该环境。
- 在线版——部署至你自己的云账户 / VPC，支持 BYOC，并通过出站网络访问进行更新和许可证验证。
- 离线版——适用于完全隔离、无互联网访问的环境，面向受监管行业。
在开源版本基础上增加分布式部署和官方支持，通过许可证密钥激活。→ 咨询自主管理部署方案
---|---
只想运行开源版本？完全可以——无需联系任何人。请直接前往快速入门。
OpenViking 开源了 VikingMem 论文中描述的部分核心能力：
VikingMem：面向有状态 LLM 应用的记忆库管理系统 Jiajie Fu、Junwen Chen、Mengzhao Wang、Aoxiang He、Maojia Sheng、Xiangyu Ke、Yifan Zhu 和 Yunjun Gao。arXiv:2605.29640，2026。已被 VLDB 2026 接收。📄 在 arXiv 阅读论文
OpenViking 欢迎与其他开源项目合作，共同建设上下文数据生态系统。已确认的合作伙伴包括：
- deer-flow - 开源长周期 SuperAgent 框架
- NoKV - AI 原生分布式文件系统
- loopx - 轻量级循环工程状态内核
- Hermes Agent - 与你共同成长的 Agent
有意加入合作伙伴名单？请在社区提交 Issue 申请。
社区与贡献
OpenViking 仍处于早期阶段，仍有大量工作有待完成。
该项目高度重视安全性。有关漏洞报告和受支持版本，请参阅 SECURITY.md。
OpenViking 项目针对不同组件采用不同许可证：
English / 原文
OpenViking is an open-source context database for AI agents. It stores memories, resources, and skills as one virtual filesystem under the viking:// protocol, so an agent browses its own context with ls, tree, and find instead of querying a black-box vector store. Content is processed into three tiers — L0 abstract, L1 overview, L2 details — and loaded on demand. Every retrieval leaves a trajectory you can watch and debug. Full introduction: Getting started.
TheOpenViking Studio playground — a live demo you can open in the browser, no installation required.
- One filesystem for all context. Memories, resources, and skills each get a
viking://URI. Agents locate and manipulate context deterministically, like a developer working with files. → Viking URI · Context types - Tiered loading cuts token spend. Every entry is processed into L0 (abstract), L1 (overview), and L2 (details) on write, then loaded only as deep as the task requires. → Context layers
- Directory recursive retrieval. Vector search first locates the highest-scoring directory, then drills down layer by layer, so results arrive with their surrounding context intact. → Retrieval
- Observable retrieval. Each query preserves its directory-browsing trajectory. When a result looks wrong, you can see exactly which path produced it. → Retrieval
- Sessions become memory. After a session commits, OpenViking asynchronously extracts user preferences and agent experience into long-term memory. → Session
How the pieces fit together: Architecture. The thinking behind the design: The Database Paradigm for Context Engineering.
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/
The three loading tiers:
- L0 (Abstract) : a one-sentence summary for quick relevance checks.
- L1 (Overview) : core information and usage scenarios for planning.
- L2 (Details) : the full original data, read only when needed.
Each directory carries its own L0/L1 layers, so relevance can be judged before any full file is read:
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 0.3.22 has been evaluated on long-conversation user memory (LoCoMo) and multi-turn agent tasks (tau2-bench). Full results and setup details, including knowledge-base QA, are in the benchmark report; reproduction scripts live in ./benchmark.
- User memory (LoCoMo) : with OpenViking, all three agent integrations land at 80–83% accuracy — up from 24–57% on their native memory — while input tokens drop by 34.3–91.0% and query latency by 58.45–66.10%.
- Agent experience (tau2-bench) : experience memory lifts task success by +6.87pp (retail) and +11.87pp (airline) over the same LLM without memory.
💡 Want to see it in action first? Try OpenViking Studio — a live hosted instance with a context playground, semantic search, and a multi-agent hub. No installation required.
Requires Python 3.10 or higher.
pip install openviking --upgrade
openviking-server init # interactive wizard: providers, models, ov.conf
openviking-server doctor # validate setup
openviking-server # start (background: nohup openviking-server > openviking.log 2>&1 &)
init walks you through provider setup and writes ~/.openviking/ov.conf. It supports Volcengine, OpenAI, Codex OAuth, Kimi, GLM, and local Ollama — for Ollama it can detect and install the runtime and pull models suited to your hardware. doctor checks the config file, Python version, provider connectivity, and disk space without a running server. Manual ov.conf templates, per-provider examples, environment variables, and Windows setup: Configuration guide · Quick start docs.
The install already includes the ov client CLI. With the server running:
ov status
ov add-resource https://github.com/volcengine/OpenViking # --wait
ov ls viking://resources/
ov tree viking://resources/volcengine -L 2
# wait some time for semantic processing if not --wait
ov find "what is openviking"
ov grep "openviking" --uri viking://resources/volcengine/OpenViking/docs/en
Next steps:
- Client configuration (
ov config), standalone CLI installs (npm / cargo), and advanced usage such as index rebuilding: CLI setup - Docker and production deployment: Deployment guide
Integrations inject OpenViking recall into your agent's context and auto-commit session memory:
Setup instructions for each agent: Agent integrations overview.
OpenViking Helper is a desktop console, currently in beta for macOS and Windows x64:
- Visual local agent setup : detects OpenViking CLI, Claude Code, Codex, Cursor, Trae, and OpenCode, then configures supported plugin, MCP, Hook, and CLI integrations.
- Session trace inspection : parses Claude Code, Codex, and Trae sessions to show OpenViking recall, prompt injection, MCP calls, capture, and commit events.
- Local memory and skill management : views local memory / rule files and
SKILL.mdskills, then syncs them to OpenViking.
Download:
VikingBot is an AI agent framework built on top of OpenViking:
pip install "openviking[bot]"
openviking-server --with-bot
ov chat # in another terminal
The official Docker image bundles VikingBot and starts it by default alongside the server and console UI. Details: VikingBot guide.
For production, run OpenViking as a standalone HTTP service — see Server deployment and the Deployment guide.
The open-source edition is not crippled. OpenViking in this repo is fully open source under AGPLv3: no feature gates, no account required, no activation key. Follow Deploy in production above and run it in production yourself — and that will stay true.
The two editions below answer "who operates it and where it runs", not "can I use it".
Officially hosted on Volcano Engine. Nothing to set up, nothing to operate.
- Personal — for individual developers. Free trial for up to 50 files, and scales far beyond local hardware with VikingDB.
- Enterprise — multi-user context management, team collaboration and permissions, enterprise SLA and support.
Existing open-source users can move over with the migration tool. → Volcano Engine product page · Documentation Global hosting for regions outside China is coming to BytePlus. | Runs inside your own environment. Data never leaves it.
- Online — deployed into your own cloud account / VPC, BYOC supported, with outbound access for updates and licensing.
- Offline — fully air-gapped environments with no internet access, for regulated industries.
Adds distributed deployment and official support on top of the open-source edition, activated by license key. → Talk to us about self-managed deployment
---|---
Just want to run the open-source edition? Go ahead — you don't need to contact anyone. Head to Quick start.
OpenViking open-sources a subset of the core capabilities described in the VikingMem paper:
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. 📄 Read the paper on arXiv
OpenViking welcomes collaboration with other open-source projects to build the context data ecosystem. Our confirmed partners include:
- deer-flow - Open-source long-horizon SuperAgent harness
- NoKV - AI native distributed file system
- loopx - Lightweight loop engineering state kernel
- Hermes Agent - The agent that grows with you
Interested in joining our partner list? Please submit an issue to our community to apply.
Community & contributing
OpenViking is still in its early stages, and there is plenty left to build.
This project takes security seriously. For vulnerability reporting and supported versions, see SECURITY.md
The OpenViking project uses different licenses for different components: