智能体上下文数据库 volcengine/OpenViking

给 AI 智能体用的上下文数据库

English / / 日本語

官网 · 在线演示 · GitHub · Issues · 文档 · 博客

飞书 · 微信 · Discord · X

OpenViking 是什么

OpenViking 是面向 AI 智能体的开源上下文数据库——用一套文件系统装下智能体知道的一切：知识、记忆和技能。

大多数智能体记忆都是黑盒：文本进去，向量出来，没人看得见到底存了什么。OpenViking 换了个做法，把上下文组织成 viking:// 下的虚拟文件系统。智能体像操作文件一样浏览它——ls、tree、read、write、grep——你也可以打开任意目录，查看和编辑智能体知道的内容。每个目录都带一份生成的摘要，智能体可以先扫摘要，再决定读什么。

直接在浏览器里试用 OpenViking Studio，无需安装。自托管 Web Studio。

为什么选 OpenViking

- 一套文件系统装下知识、记忆和技能。 资源存放文档和代码；记忆保留用户偏好和经验；技能定义任务怎么做——不只是抽取出来的事实，而是完整上下文，每一项都有 viking:// URI，可浏览、可检索。→ Viking URI · 上下文类型
- 搜目录，而不是搜整个索引。 把语义搜索限定在某个项目或记忆子树里，不必扫描扁平的向量池。find 直接执行查询；search 根据会话上下文规划检索。→ 检索
- 先读摘要，再读原文。 生成的目录摘要（L0）和概览（L1）让智能体在打开完整内容（L2）之前先判断相关性。→ 上下文分层
- 会话变成可读的文件。 提交会话会把对话归档，并抽取记忆存成 Markdown，你可以查看、编辑、合并。启用 VikingBot 后，ov compile 会把素材整理成 wiki、知识图谱或报告。→ 会话 · 上下文编译

架构 · 设计思路

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/

三级加载：

- L0（摘要）：一句话总结，用来快速判断相关性。
- L1（概览）：核心信息与使用场景，供规划时参考。
- L2（详情）：完整原始数据，只在需要时读取。

做过语义处理的目录带有 L0/L1 摘要，智能体读完摘要就能判断相关性，再决定要不要读完整文件：

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

效果验证

OpenViking 0.3.22 已在长对话用户记忆（LoCoMo）和多轮智能体任务（tau2-bench）上做过评测。完整结果与搭建细节（含知识库问答）见基准测试报告；复现脚本在 ./benchmark。

想自己跑实验，按 RAG 与记忆评测指南操作，里面覆盖常规 VikingBot 记忆评测、已发布的 LoCoMo 复现、单独的 mem0 提示词对比，以及 RAG 评测。

记忆评测用 Doubao 2.0 Pro 作 VLM，用 Doubao-embedding-vision-251215 作嵌入模型。

- 用户记忆（LoCoMo）：接入 OpenViking 后，三个智能体集成的准确率都落在 80–83%，而它们原生记忆只有 24–57%；同时输入 token 减少 34.3–91.0%，查询延迟降低 58.45–66.10%。
- 智能体体验（tau2-bench）：经验记忆让同一个 LLM 的任务成功率提升 +6.87pp（零售）和 +11.87pp（航空）。

快速开始

先搭好 OpenViking 服务；如果已经有了，直接跳到配合你的智能体使用。自己部署需要 uv、Python 3.10+，以及一个带嵌入模型和 VLM 的模型服务商。

让你的智能体来部署按照本指南为我安装并启动 OpenViking Server：

https://docs.openviking.ai/en/getting-started/04-setup-for-agent

向我询问模型服务商、模型、工作区目录，以及其他机器是否需要访问服务器；不要猜。询问模型 API key 时，告诉我如果不想把它粘贴到这个聊天里，可以怎样交给我，并且永远不要把它复述出来。

运行起来后，告诉我服务器地址，以及是否开启了认证。

你的智能体会先询问使用哪个模型服务商，以及它的 API key。

自行部署

安装 OpenViking 并运行安装向导，由它配置模型：

uv tool install openviking --upgrade && openviking-server init

init 会写入 ~/.openviking/ov.conf，支持 Volcengine、OpenAI、Codex OAuth、Kimi、GLM 和本地 Ollama；参见配置指南。服务器在前台运行，所以请保持这个终端打开。

使用 OpenViking Service（由 Volcengine 托管）

同样的 OpenViking 服务，由 Volcengine 为你运行。前 50 个文件免费。在 Volcengine 产品页激活，然后在控制台的 User Management → API Key 下创建 API key。服务器地址是 https://api.vikingdb.cn-beijing.volces.com/openviking；连接智能体时你需要它和 API key。

用命令行探索

openviking 包包含 ov 命令行。服务器运行后，导入一个仓库并搜索它：

ov status
ov add-resource https://github.com/volcengine/OpenViking
Replace TASK_ID with the returned task_id; repeat until status is completed
ov task status TASK_ID
ov ls viking://resources/
ov tree viking://resources/volcengine -L 2
ov find "what is openviking"
ov grep "openviking" --uri viking://resources/volcengine/OpenViking/docs/en

ov find 返回匹配的上下文，附带可供查看的 URI。客户端配置（ov config）、独立命令行安装和索引维护，参见命令行设置。

用 Python、Go 或 TypeScript SDK，或者 HTTP API 构建你自己的集成。

与你的智能体配合使用

把你的编码智能体连接到 OpenViking，获得跨会话记忆。记忆插件安装器覆盖 Claude Code、Codex、Cursor、TRAE、OpenCode 等，并能检测你装了哪些。

让你的智能体来安装

安装 OpenViking 记忆插件，并帮你开始使用。OpenViking 是面向 AI 智能体的上下文数据库（https://github.com/volcengine/OpenViking）；下面的命令和链接来自它的官方文档。

1. 运行官方安装脚本。它需要联网，并且会写入你的主目录；如果你的沙箱拦截了这些操作，请向我申请授权：
curl -fsSL https://openviking.ai/install | bash -s -- --yes --lang en --url <SERVER_URL> --api-key <API_KEY>
2. 安装完成后，阅读 OpenViking 的上手指南，并照着它带你完成设置。指南会要求你在导入历史记录、添加工作规则这类选择前先征求你的意见。docs.openviking.ai 和 docs.openviking.net 是同一个文档站点；哪个能打开就用哪个： https://docs.openviking.ai/agents/en/onboarding.md

API key 是我在该服务器上为自己创建的用户密钥；安装脚本会把它存到本机的 ~/.openviking/ovcli.conf。命令里照原样使用即可；回复中不必展示它，也不要把它写进任何其他文件或规则。用英语和我交流。

发送前，把 <SERVER_URL> 换成你的服务器地址，把 <API_KEY> 换成用户密钥；根密钥无法读写记忆。如果服务器关闭了鉴权，请使用 --api-key ''。

自行安装

运行安装脚本，然后在提示时选择工具和服务器：本机服务器选 Self-hosted / local，OpenViking Service 选 Volcengine OpenViking Cloud，其他地址选 Custom URL。如果开启了鉴权，请输入用户密钥，而不是根密钥。

curl -fsSL https://openviking.ai/install | bash
AI agents: not sure about running this? The script's header says what it does and how to verify it.

然后重启你的智能体。安装脚本结尾会给出每个工具的后续步骤，例如：

Claude Code
Next: restart Claude Code
⋮
Verify: run /openviking-memory:ov in a session

Codex 首次启动时会停在 Hooks need review；选择 Trust all and continue。

试一试：让它记住你的某个偏好，稍后在新会话里再问它。记忆在后台处理，所以刚说完时查不到属于正常现象。

安装脚本需要 macOS 或 Linux、Node.js 18+ 和 curl，无需 sudo。Windows 上请使用桌面应用。

各集成的设置指南：

Claude
Hooks + MCP

Codex
钩子 + MCP

Cursor
钩子 + MCP

TRAE
钩子 + MCP

OpenClaw
上下文引擎

Hermes
内置

OpenCode
插件 + MCP

pi
原生扩展

DeerFlow
插件 + MCP

DSH
插件 + MCP

Doubao Work
连接器

LangChain
工具 + 存储

通用集成

Agent Plugins 1.0

MCP clients

安装步骤与集成细节见 Integrations。

框架应用见 LangChain/LangGraph 与 Microsoft Agent Framework 包，其中还说明了如何添加其他适配器。

桌面应用（Beta）

桌面应用是面向 macOS 与 Windows x64 的控制台（beta）。你可以用它配置受支持的本地智能体集成、查看会话中的召回与捕获事件，并把本地记忆和技能同步到 OpenViking。

下载：

- macOS Apple Silicon (arm64)
- macOS Intel (x64)
- Windows (x64)

VikingBot

VikingBot 是构建在 OpenViking 之上的 AI 智能体框架：

pip install "openviking[bot]"
openviking-server --with-bot
ov chat # in another terminal

官方 Docker 镜像内置 VikingBot，默认随服务端和控制台 UI 一起启动。详情见 VikingBot 指南。

生产环境部署

在你自己的环境里运行开源服务端，遵循 AGPLv3。无需激活密钥。从服务端安装或 Docker 与部署指南开始。
服务器支持账号与用户隔离，也支持按需开启资源 ACL。把服务暴露到 localhost 之外前，先配置身份认证。

商业版本

☁️ 托管 SaaS 火山引擎托管并运营 OpenViking。个人版和企业版覆盖个人与团队使用场景，并提供开源部署的迁移工具。套餐与限额见服务文档。中国境外的托管计划在 BytePlus 上线。

🏢 自托管部署到你自己的云账号 / VPC（BYOC）或离线环境。这个版本增加分布式部署和官方支持，用许可证密钥激活。联系团队。

研究

随智能体一起演进的记忆。 VikingMem 研发事件驱动的方法，用来抽取、更新、整合长期记忆，让有状态智能体在交互不断累积时保留有用的经验。OpenViking 开源了其中一部分核心能力。

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. Presented at VLDB 2026 in September.
📄 在 arXiv 上阅读论文 · 阅读 PDF

把目录结构当作检索上下文。 这篇论文给出 OpenViking 目录感知检索背后的形式化基础、索引设计与实验证据。它定义了目录范围内的查询与维护操作，并提出 TrieHI；OpenViking 集成 TrieHI，在向量排序之前解析目录范围。这样就把文件系统范式接上了检索：智能体可以搜索某个项目或记忆子树，保留其周边上下文，并在知识演进时重新组织它。

Directory-Aware Query and Maintenance in Vector Databases
Mengzhao Wang, Zheng Gong, Jingpei Hu, Jiajie Fu, Maojia Sheng, Junwen Chen, and Yifan Zhu.
arXiv:2606.16903, 2026. Accepted by ICDE.
📄 在 arXiv 上阅读论文 · 阅读 PDF 用更少的 token 检索到需要的证据。 VikingRAG 把语义搜索和文档结构结合起来，在证据缺口出现时，把相关的目录片段作为证据暴露出来。核心机制已经集成进 OpenViking。论文进一步探索复用检索轨迹，只在需要时才升级到多轮检索，减少重复探索，同时保持答案质量。

VikingRAG: Accurate and Token-efficient Retrieval-augmented Generation over Structured Documents
Peiyuan Gao, Gaoyuan Zhang, Haojie Qin, Yahui Sun, Qianyi Zhang, Yunhao Zhang, Zeyu Wang, and Wei Lu.
arXiv:2609.11390, 2026. Submitted.
📄 Read the paper on arXiv · Read PDF

合作伙伴项目

- deer-flow - 开源长程 SuperAgent harness
- NoKV - AI 原生分布式文件系统
- loopx - 轻量级 loop 工程状态内核
- Hermes Agent - 与你一起成长的智能体
- NVIDIA cuVS - GPU 加速的向量搜索与聚类库

想提合作，请开 issue。

社区与贡献

- 文档：docs.openviking.ai · FAQ
- 博客：blog.openviking.ai
- 团队：关于我们
- 聊天： Lark · WeChat · Discord · X
- 贡献：bug 修复和新功能都欢迎——见 CONTRIBUTING.md

安全与隐私

漏洞上报和支持的版本，见 SECURITY.md

许可证

Copyright © 2026 Volcano Engine (火山引擎) and the OpenViking contributors.

OpenViking 项目对不同组件使用不同许可证：

- 主项目：AGPLv3 - 详见 LICENSE 文件
- crates/ov\_cli：Apache 2.0，详见 LICENSE
- examples：Apache 2.0，详见 LICENSE。examples/hermes-plugin 里的 Hermes 插件保留其 MIT 许可证。
- integrations/frameworks：LangChain/LangGraph 适配器使用 AGPLv3，Microsoft Agent Framework 适配器使用 MIT；详见各包的 LICENSE。它们的可运行示例保留 Apache 2.0；详见各包的 examples/LICENSE。
- third\_party：遵循第三方项目各自的原始许可证

另请注意：禁止对本项目做整体重写，再以开源形式重新发布；如需将项目代码全部或大部分翻译成另一种编程语言，须事先获得火山引擎的书面授权。申请授权请联系火山引擎团队，联系方式见 社区与贡献。