ghcr.io/volcengine/openviking:v0.4.23

AI 代理专用的上下文数据库

English / 中文 / 日本語

官网 · 在线演示 · GitHub · 问题反馈 · 文档 · 博客

 Lark ·  WeChat ·  *** ·  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/ # 资源：项目文档、代码仓库、网页等
│ └── 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：快速相关性校验
├── .overview.md # L1：结构与要点概览
└── docs/
    ├── .abstract.md
    ├── .overview.md
    └── api/
        ├── auth.md # L2：完整内容，按需加载
        └── endpoints.md

性能验证结果

OpenViking 0.3.22 已在长对话用户记忆基准测试（LoCoMo）和多轮代理任务基准测试（tau2-bench）中完成评估。包含知识库问答在内的完整测试结果与部署细节可查看基准测试报告；可复现测试脚本存放在 ./benchmark 目录下。

本次记忆评估使用的 VLM 模型为 https://console.volcengine.com/ark/region:cn-beijing/model/detail?Id=doubao-seed-2-0-pro，嵌入模型为 https://console.volcengine.com/ark/region:cn-beijing/model/detail?Id=doubao-embedding-vision。

• 用户记忆测试（LoCoMo）：接入 OpenViking 后，三类代理集成方案的准确率均达到 80–83%——远高于原生记忆方案的 24–57%，同时输入 Token 量降低 34.3–91.0%，查询延迟降低 58.45–66.10%。
• 代理经验测试（tau2-bench）：相比未搭载记忆能力的同类型 LLM，启用经验记忆后，零售场景任务成功率提升 6.87 个百分点，航空场景任务成功率提升 11.87 个百分点。

快速开始

你需要先部署 OpenViking 服务端；如果已经有可用服务端，可以直接跳转到将其接入你的代理。自建部署需要提前安装 uv、Python 3.10+，以及一个提供嵌入模型和 VLM 能力的模型服务商。

让你的代理帮你部署

请按照以下指引帮我安装并启动 OpenViking Server：

请主动向我确认模型服务商、所用模型、工作区目录，以及是否需要允许其他设备访问该服务；不要自行猜测参数。当你询问模型 API 密钥时，如果我不方便直接将密钥粘贴到对话中，请告知我其他交接方式，且绝对不要在回复中复述密钥内容。

服务启动完成后，请告知我服务端地址以及是否已开启身份验证。

你的代理会首先询问你要使用的模型服务商及对应的 API 密钥信息。

手动自行部署

安装 OpenViking 并运行配置向导，完成模型相关配置：

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

init 命令会生成配置文件 ~/.openviking/ov.conf，当前支持 Volcengine、OpenAI、Codex OAuth、Kimi、GLM 以及本地 Ollama 等多种模型接入方式；详细说明请参考配置指南。服务端默认在前台运行，请保持当前终端窗口开启。

使用 OpenViking 托管服务（由 Volcengine 提供）

你也可以直接使用由 Volcengine 托管的 OpenViking 服务，前 50 个文件完全免费。前往https://www.volcengine.com/product/openviking-service开通服务后，在控制台的「用户管理 → API 密钥」页面创建 API 密钥。服务端地址为 https://api.vikingdb.cn-beijing.volces.com/openviking，后续将服务接入代理时需要用到该地址和你创建的 API 密钥。

通过 CLI 探索功能

openviking 软件包内置了 ov 命令行工具。启动服务端后，你可以按以下步骤导入代码仓库并完成搜索测试：

ov status
ov add-resource https://github.com/volcengine/OpenViking
# 将 TASK_ID 替换为上一步返回的任务 ID；重复运行直到任务状态变为 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，你可以直接使用这些 URI 查看详情。关于客户端配置（ov config）、独立 CLI 安装以及索引维护的更多信息，请参考 CLI 配置指南。

你可使用 Python、Go 或 TypeScript SDK，或是 HTTP API 自行开发对接集成方案。

与你的 Agent 搭配使用

将你的编码 Agent 连接到 OpenViking 即可获得跨会话记忆能力。记忆插件安装器支持 Claude Code、Codex、Cursor、TRAE、OpenCode 等多款工具，还可自动检测你本机已安装的工具。

让你的 Agent 自动安装

请为我运行以下命令安装 OpenViking 记忆插件：

curl -fsSL https://openviking.ai/install | bash -s -- --yes --url

--url 参数后需要填写我的 OpenViking 服务器地址，请向我询问，不要自行猜测。
如果服务器开启了鉴权，还需要提供用户密钥（根密钥无法读写记忆）：请先检查本地是否已保存有效密钥，如果没有，请向我索要并通过 --api-key 参数传入，同时告知我如果我不想直接在聊天框粘贴密钥，应该如何交接。绝对不要在对话中完整输出密钥内容。如果服务器未开启鉴权，请添加 --api-key '' 参数，避免复用之前保存的旧密钥。

安装脚本需要网络访问权限，并且会写入我的用户主目录；如果沙箱拦截了该操作，请提示我批准在沙箱外运行脚本。

安装完成后，请告知我已成功将插件安装到哪些工具中，以及每个工具对应的后续操作步骤，然后询问我是否还需要在其他工具中安装该插件。

请提前准备好你的服务器地址，如果服务器开启了鉴权，还需准备好对应的 API 密钥。

手动自行安装

运行安装程序，随后根据提示选择目标工具和服务器类型：部署在本机的服务器选择「自托管/本地」，OpenViking 云服务选择「火山引擎 OpenViking Cloud」，其他自定义地址选择「自定义 URL」。如果服务器开启了鉴权，请输入用户密钥，而非根密钥。

curl -fsSL https://openviking.ai/install | bash
# AI 代理：不确定是否运行此脚本？脚本头部已明确说明其执行逻辑与校验方式

完成后重启你的 Agent。安装程序最后会输出每款工具对应的后续操作步骤，示例如下：

Claude Code
后续操作：重启 Claude Code
⋮
验证方式：在会话中运行 /openviking-memory:ov 指令

Codex 首次启动时会停在 Hooks need review 提示页面，请选择 Trust all and continue。

你可以进行如下验证：让 Agent 记住你的一项偏好设置，稍等片刻后在新会话中向它询问该偏好。由于记忆在后台异步处理，刚说完偏好就立刻查询时找不到记录属于正常现象。

[!NOTE] 该安装程序仅支持 macOS 或 Linux 系统，依赖 Node.js 18+ 和 curl，运行时不需要 sudo 权限。Windows 用户请使用 桌面应用（Beta）。

各集成方案的设置指南如下：

通用集成

• Agent Plugins 1.0
• MCP 客户端

如需查看设置说明与集成详情，请访问 集成方案页面。

桌面应用（Beta）

桌面应用是面向 macOS 和 Windows x64 平台的控制台工具（Beta 版本），可用于配置已支持的本地 Agent 集成方案、查看会话中的召回与捕获事件，还能将本地记忆和技能同步到 OpenViking。

下载地址：

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

VikingBot

VikingBot 是基于 OpenViking 构建的 AI Agent 框架：

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

官方 Docker 镜像已内置 VikingBot，默认会随服务端与控制台 UI 一同启动。详情请参考 VikingBot 指南。

生产环境部署

你可以在自有环境中基于 AGPLv3 协议运行开源版本的 OpenViking 服务端，该版本无需激活密钥。可从 服务端快速入门 或 Docker 与部署指南 开始上手。

商业版本

☁️ 托管 SaaS 由火山引擎运维托管 OpenViking 服务，提供个人版与企业版方案，覆盖个人与团队使用场景，附带开源部署迁移工具。可查看服务文档了解不同方案的功能与配额限制。BytePlus 平台正在推进中国以外区域的服务托管计划。

🏢 自托管 支持在你的自有云账号/VPC（BYOC，自带云资源）或离线环境中部署。该版本新增分布式部署能力与官方技术支持，通过许可证密钥激活。可联系团队获取更多信息。

相关研究

随 Agent 同步演进的记忆 VikingMem 提出了一种事件驱动的长期记忆提取、更新与整合方案，为有状态 Agent 提供了随交互积累持续留存有效经验的能力。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, Yunjun Gao arXiv:2605.29640, 2026 年。将于 2026 年 9 月的 VLDB 学术会议上展示。 📄 https://arxiv.org/abs/2605.29640 · https://arxiv.org/pdf/2605.29640

将目录结构作为检索上下文 该论文为 OpenViking 的目录感知检索能力提供了理论基础、索引设计方案与实验验证。论文定义了目录级别的查询与维护操作，提出了 TrieHI 算法，OpenViking 已集成该算法，可在向量排序前完成目录范围解析。该能力将文件系统范式与检索能力打通：Agent 可针对项目或记忆子树进行搜索，保留周边关联上下文，并可随着知识沉淀对其进行重组。

Directory-Aware Query and Maintenance in Vector Databases Mengzhao Wang, Zheng Gong, Jingpei Hu, Jiajie Fu, Maojia Sheng, Junwen Chen, Yifan Zhu arXiv:2606., 2026 年。已被 ICDE 学术会议录用。 📄 https://arxiv.org/abs/2606. · https://arxiv.org/pdf/2606.***

用更少的 Token 检索到你需要的证据 VikingRAG 将语义搜索与文档结构相结合，在出现证据缺口时可精准返回相关目录片段。其核心机制已集成到 OpenViking 中。该论文还进一步探索了检索轨迹复用方案，仅在必要时才升级为多轮检索，在保证回答质量的前提下减少了不必要的重复检索操作。

镜像名称：ghcr.io/volcengine/openviking 参考标签：latest

VikingRAG：面向结构化文档的高精度、低 Token 消耗检索增强生成 作者：Peiyuan Gao, Gaoyuan Zhang, Haojie Qin, Yahui Sun, Qianyi Zhang, Yunhao Zhang, Zeyu Wang, Wei Lu arXiv:2609.，2026 年，已提交 📄 https://arxiv.org/abs/2609. · https://arxiv.org/pdf/2609.***

合作项目

• https://github.com/bytedance/deer-flow — 开源长时序 SuperAgent 开发框架
• https://github.com/NoKV-Lab/NoKV — AI 原生分布式文件系统
• https://github.com/huangruiteng/loopx — 轻量级循环工程状态内核
• https://github.com/NousResearch/hermes-agent — 可与用户共同成长的智能体

若您有意提出合作意向，请https://github.com/volcengine/OpenViking/issues。

社区与贡献

• 文档：docs.openviking.ai · 常见问题
• 博客：blog.openviking.ai
• 团队：关于我们
• 交流渠道：飞书 · 微信 · *** · X
• 贡献指南：欢迎提交 Bug 修复和新特性，请参考 CONTRIBUTING.md

安全与隐私

关于漏洞上报渠道和当前支持的版本信息，请参阅 SECURITY.md。

许可协议

OpenViking 项目的不同组件采用不同的许可协议：

• 主项目：AGPLv3 — 详细内容请参考 LICENSE 文件
• crates/ov_cli：Apache 2.0 — 详细内容请参考 LICENSE 文件
• examples：Apache 2.0 — 详细内容请参考 LICENSE 文件。其中位于 examples/hermes-plugin 下的 Hermes 插件保留其原有 MIT 许可协议
• third_party：各第三方项目保留其对应的原始许可协议