OpenViking
Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
原始仓库简介 · 中文摘要待补充 · agent-context / agent-memory / agent-plugins / agentic-rag / context-database / dsh-plugin
README / 项目原文
What is OpenViking
OpenViking is an open-source context database for AI agents — one filesystem for everything an agent knows: knowledge, memory, and skills.
Most agent memory is a black box: text goes in, embeddings come out, and nobody can see what was actually stored. OpenViking organizes context as a virtual filesystem under viking:// instead. Agents navigate it like files — ls, tree, read, write, grep — and you can open any directory to inspect and edit what your agent knows. Every directory carries a generated summary, so agents can scan summaries first and decide what to read.
Try OpenViking Studio in your browser, no installation required. Self-host Web Studio.
Why OpenViking
- One filesystem for knowledge, memory, and skills. Resources hold documents and code; memories retain user preferences and experience; skills define how to perform tasks — not just extracted facts, but the full context, each with a
viking://URI for browsing and retrieval. → Viking URI · Context types - Search a directory, not the whole index. Scope semantic search to a project or memory subtree instead of scanning a flat vector pool.
findruns a query directly;searchplans retrieval from session context. → Retrieval - Read the summary before the source. Generated directory abstracts (L0) and overviews (L1) let agents judge relevance before opening full content (L2). → Context layers
- Sessions become files you can read. Committing a session archives the conversation and extracts memories as Markdown you can inspect, edit, and merge. With VikingBot enabled,
ov compileorganizes source material into a wiki, knowledge graph, or report. → Sessions · Context compilation
Architecture · Design rationale
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.
Semantically processed directories carry L0/L1 summaries, so agents can judge relevance before reading full files:
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
Proof it works
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.
The memory evaluation used Doubao 2.0 Pro as the VLM and Doubao-embedding-vision-251215 as the embedding model.
- 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.
Quick start
Set up an OpenViking server first; if you already have one, skip to Use it with your agent. Deploying your own needs uv, Python 3.10+ and a model provider with an embedding model and a VLM.
Let your agent deploy it
Follow this guide to install and start an OpenViking Server for me:
https://docs.openviking.ai/en/getting-started/04-setup-for-agent
Ask me for the model provider, the models, the workspace directory and whether
other machines need to reach the server; don't guess. When you ask for the model
API key, tell me how to hand it over if I'd rather not paste it into this chat,
and never repeat it back.
When it's running, tell me the server's address and whether auth is turned on.
Your agent will first ask which model provider to use and for its API key.
Deploy it yourself
Install OpenViking and run the setup wizard, which configures the models:
uv tool install openviking --upgrade && openviking-server init
init writes ~/.openviking/ov.conf and supports Volcengine, OpenAI, Codex OAuth, Kimi, GLM and local Ollama; see the configuration guide. The server runs in the foreground, so keep this terminal open.
Use OpenViking Service (hosted by Volcengine)
The same OpenViking service, run for you by Volcengine. The first 50 files are free. Activate it on the Volcengine product page, then create an API key in the console under User Management → API Key. The server address is https://api.vikingdb.cn-beijing.volces.com/openviking; you'll need it and the API key when you connect your agent.
Explore with the CLI
The openviking package includes the ov CLI. With the server running, import a repository and search it:
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 returns matching context with URIs you can inspect. For client configuration (ov config), standalone CLI installs, and index maintenance, see CLI setup.
Build your own integration with the Python, Go, or TypeScript SDK, or the HTTP API.
Use it with your agent
Connect your coding agent to OpenViking for cross-session memory. The memory plugin installer covers Claude Code, Codex, Cursor, TRAE, OpenCode and more, and detects which ones you have.
Let your agent install it
Install the OpenViking memory plugin for me by running:
curl -fsSL https://openviking.ai/install | bash -s -- --yes --url <SERVER_URL>
<SERVER_URL> is the address of my OpenViking server; ask me for it, don't guess.
If the server has auth turned on, it needs a user key (a root key can't read or
write memories): check whether one is already saved; if not, ask me for it and
pass it with --api-key, and tell me how to hand it over if I'd rather not paste
it into this chat. Never repeat the key back. If auth is off, add --api-key ''
so an earlier saved key isn't reused.
The script needs network access and writes to my home directory; if a sandbox
blocks it, ask me to approve running it outside the sandbox.
When it finishes, tell me which tools it installed into and the next steps for
each, then ask whether I want it in any other tool.
Have your server's address ready, plus its API key if it has auth turned on.
Install it yourself
Run the installer, then pick the tools and a server when asked: Self-hosted / local for a server on this machine, Volcengine OpenViking Cloud for OpenViking Service, or Custom URL for any other address. If auth is on, enter a user key, not the root key.
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.
Then restart your agent. The installer ends with the next steps for each tool, for example:
Claude Code
Next: restart Claude Code
⋮
Verify: run /openviking-memory:ov in a session
On its first start Codex stops at Hooks need review; choose Trust all and continue.
Try it: ask it to remember one of your preferences, then ask about it in a new session a little later. Memories are processed in the background, so it's normal not to find one right after you say it.
The installer needs macOS or Linux, Node.js 18+ and curl, no sudo. On Windows, use the desktop app.
Setup guides for each integration:
 Claude Hooks + MCP |
 Codex Hooks + MCP |
 Cursor Hooks + MCP |
 TRAE Hooks + MCP |
 OpenClaw Context engine |
 Hermes Built-in |
 OpenCode Plugin + MCP |
 pi Native extension |
 DeerFlow Plugin + MCP |
 DSH Plugin + MCP |
 Doubao Work Connector |
 LangChain Tools + store |
General integrations
 Agent Plugins 1.0 |
 MCP clients |
For setup instructions and integration details, see Integrations.
For framework applications, see the LangChain/LangGraph and Microsoft Agent Framework packages, with a guide to adding other adapters.
Desktop App (Beta)
The desktop app is a console for macOS and Windows x64 (beta). It configures supported local agent integrations, inspects recall and capture events in sessions, and syncs local memories and skills to OpenViking.
Download:
VikingBot
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.
Deploy in production
Run the open-source server in your own environment under AGPLv3. It requires no activation key. Start with server setup or the Docker and deployment guide.
The server supports accounts and user isolation and opt-in resource ACLs. Configure authentication before exposing it beyond localhost.
Commercial editions
 ☁️ Managed SaaSVolcano Engine hosts and operates OpenViking. Personal and Enterprise plans cover individual and team use, with migration tooling for open-source deployments. See the service documentation for plans and limits. Hosting outside China is planned on BytePlus. |
 🏢 Self-ManagedDeploy in your own cloud account / VPC (BYOC) or an offline environment. This edition adds distributed deployment and official support, activated by a license key. Contact the team. |
Research
Memory that evolves with your agent. VikingMem develops an event-driven approach to extracting, updating, and consolidating long-term memory, giving stateful agents a way to retain useful experience as interactions accumulate. OpenViking open-sources a subset of these core capabilities.
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.
📄 Read the paper on arXiv · Read PDF
Directory structure as retrieval context. This paper provides the formal foundations, index design, and experimental evidence behind OpenViking’s directory-aware retrieval. It defines directory-scoped query and maintenance operations and introduces TrieHI, which OpenViking integrates to resolve directory scopes before vector ranking. This connects the filesystem paradigm to retrieval: agents can search a project or memory subtree, retain its surrounding context, and reorganize it as knowledge evolves.
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.
📄 Read the paper on arXiv · Read PDF
Retrieve the evidence you need with fewer tokens. VikingRAG combines semantic search with document structure, exposing relevant directory segments as evidence gaps arise. Its core mechanisms are integrated into OpenViking. The paper further explores reusing retrieval traces and escalating to multi-round retrieval only when needed, reducing repeated exploration while preserving answer quality.
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
Partner Projects
- 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
- NVIDIA cuVS - GPU-accelerated vector search and clustering library
To propose a partnership, open an issue.
Community & Contributing
- Docs: docs.openviking.ai · FAQ
- Blog: blog.openviking.ai
- Team: About us
- Chat:
Lark · 
WeChat · 
Discord · 
X - Contribute: bug fixes and new features are both welcome — see CONTRIBUTING.md
Security and privacy
For vulnerability reporting and supported versions, see SECURITY.md
License
Copyright © 2026 Volcano Engine (火山引擎) and the OpenViking contributors.
The OpenViking project uses different licenses for different components:
- Main Project: AGPLv3 - see the LICENSE file for details
- crates/ov_cli: Apache 2.0 - see the LICENSE for details
- examples: Apache 2.0 - see the LICENSE for details. The Hermes plugin in
examples/hermes-pluginretains its MIT license. - integrations/frameworks: adapters declare AGPLv3 in their package metadata and source headers; see each package's
LICENSE. Their runnable examples retain Apache 2.0; see each package'sexamples/LICENSE. - third_party: Respective original licenses of third-party projects
Please also note: any wholesale rewriting and subsequent re-open-sourcing of this project is prohibited; any request to translate all or a substantial portion of the project code into another coding language requires prior written authorization from Volcano Engine. For permission requests, please contact the Volcano Engine team — see Community & Contributing for contact channels.
OpenViking 是什么
OpenViking 是面向 AI 智能体的开源上下文数据库——用一个文件系统装下 Agent 所知道的一切：知识、记忆和技能。
大多数 Agent 记忆是个黑盒：文本进去，向量出来，没人看得到里面到底存了什么。OpenViking 换一种做法，把上下文组织成 viking:// 虚拟文件系统。Agent 像操作文件一样用 ls、tree、read、write、grep 浏览和修改；你也可以随时打开目录，查看和编辑 Agent 记住的内容。每个目录都带有自动生成的摘要，Agent 先扫摘要，再决定读哪些内容。
在线体验 OpenViking Studio，无需安装。 自行部署 Web Studio。
为什么用 OpenViking
- 一个文件系统，装下知识、记忆和技能。 资源存放文档和代码，记忆保留用户偏好与经验，技能定义任务的执行方式——不只是抽取出来的"记忆条目"，而是完整上下文，每一项都有
viking://URI 供浏览和检索。→ Viking URI · 上下文类型 - 在目录里检索，而不是在整个索引里捞。 把语义检索限定在某个项目或记忆子树内，而不是扫描一个扁平的向量池。
find直接执行查询，search结合会话上下文规划检索。→ 检索机制 - 先看摘要，再读原文。 自动生成的目录摘要（L0）和概览（L1）帮助 Agent 判断相关性，再决定是否读取全文（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 摘要，Agent 可以先判断相关性，再读取全文：
viking://resources/my_project/
├── .abstract.md # L0：约 100 tokens——快速判断相关性
├── .overview.md # L1：约 2k tokens——结构和要点
└── docs/
├── .abstract.md
├── .overview.md
└── api/
├── auth.md # L2：完整内容，按需加载
└── endpoints.md
评测结果
OpenViking 0.3.22 的评测覆盖长对话用户记忆（LoCoMo）和多轮智能体任务（tau2-bench）。完整结果和实验设置（含知识库问答）见评测报告，复现脚本在 ./benchmark。
记忆评测使用 Doubao 2.0 Pro 作为 VLM，使用 Doubao-embedding-vision-251215 作为 Embedding 模型。
- 用户记忆（LoCoMo）：接入 OpenViking 后，三种 Agent 集成的准确率都到 80–83%，原生记忆只有 24–57%；同时输入 token 减少 34.3%–91.0%，查询时延降低 58.45%–66.10%。
- 智能体经验（tau2-bench）：经验记忆让任务成功率在 Retail 提升 6.87pp、Airline 提升 11.87pp（对比同一 LLM 无记忆）。
快速开始
先准备一个 OpenViking 服务；已经有服务的话，直接跳到接入你的 Agent。自部署需要 uv、Python 3.10+，以及一个提供 embedding 模型和 VLM 的模型服务。
让 agent 帮你部署
按这份文档，帮我安装并启动 OpenViking Server：
https://docs.openviking.ai/zh/getting-started/04-setup-for-agent
模型提供商、模型、workspace 目录，以及服务要不要对其他机器开放，都先问我，
不要猜。向我要模型的 API key 时，告诉我不想把它贴进对话的话可以怎么给你；
不要复述。
服务启动后，告诉我服务地址，以及有没有开鉴权。
agent 会先问你用哪家模型服务，以及它的 API key。
自己动手部署
安装 OpenViking 并运行配置向导，在向导里配置模型：
uv tool install openviking --upgrade && openviking-server init
init 将配置写入 ~/.openviking/ov.conf，支持火山引擎、OpenAI、Codex OAuth、Kimi、GLM 和本地 Ollama 等选项，详见配置指南。服务在前台运行，终端不要关。
使用 OpenViking Service（火山引擎托管）
同一个 OpenViking 服务，由火山引擎替你运行。前 50 个文件免费。在火山引擎产品页开通后，到控制台的「用户管理 → API Key」创建一个 API key。服务地址是 https://api.vikingdb.cn-beijing.volces.com/openviking，接入 agent 时要用到它和 API key。
用 CLI 试一试
openviking 安装包包含 ov CLI。服务运行时，导入代码库并检索：
ov status
ov add-resource https://github.com/volcengine/OpenViking
# 将 TASK_ID 替换为返回的 task_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/zh
ov find 返回匹配的上下文及其 URI，可继续查看内容。客户端配置（ov config）、CLI 独立安装和索引维护，见 CLI 安装。
构建自己的应用，可使用 Python、Go、TypeScript SDK 或 HTTP API。
接入你的 Agent
把 coding agent 接入 OpenViking，跨会话保留记忆。记忆插件安装脚本支持 Claude Code、Codex、Cursor、TRAE、OpenCode 等，会自动检测本机装了哪些。
让 agent 帮你安装
帮我安装 OpenViking 记忆插件，运行：
curl -fsSL https://openviking.ai/install | bash -s -- --yes --url <SERVER_URL>
<SERVER_URL> 是我的 OpenViking 服务地址，向我要，不要猜。服务开了鉴权的话，
要一个 user key（root key 读写不了记忆）：先看看有没有已保存的，没有再向我要
（用 --api-key 传入），并告诉我不想把 key 贴进对话时可以怎么给你。
不要复述 key。没开鉴权就加 --api-key ''，免得沿用之前保存的 key。
脚本需要联网并写入主目录，如果被沙箱拦住，请求我批准后在沙箱外运行。
装完告诉我装进了哪些工具、各自的后续步骤，再问我要不要给其他工具也装。
准备好服务地址；服务开了鉴权的话，还要它的 API key。
自己在终端安装
运行安装脚本，按提示勾选工具、选择服务：本机的服务选「自建 / 本地」，OpenViking Service 选「火山引擎 OpenViking 云服务」，其他地址选「自定义 URL」。开了鉴权的话，填 user key，不是 root key。
curl -fsSL https://openviking.ai/install | bash
# AI agent 如不确定是否执行，可先阅读脚本头部，其中写明了它会做什么、如何核实。
装完后重启 agent。脚本结尾会列出每个工具的后续步骤，例如：
Claude Code
下一步： 重启 Claude Code
⋮
验证： 在会话中运行 /openviking-memory:ov
Codex 首次启动会停在 Hooks need review，选 Trust all and continue。
试一下：让它记住你的一个偏好，过一会儿开个新会话再问。记忆在后台整理，刚说完查不到是正常的。
安装脚本需要 macOS 或 Linux、Node.js 18+ 和 curl，不用 sudo。Windows 请使用桌面客户端。
各集成的接入文档：
|
Claude Hooks + MCP |
Codex Hooks + MCP |
Cursor Hooks + MCP |
TRAE Hooks + MCP |
OpenClaw 上下文引擎 |
Hermes 内置记忆 |
|
OpenCode Plugin + MCP |
pi 原生扩展 |
DeerFlow Plugin + MCP |
DSH Plugin + MCP |
豆包工作 连接器 |
LangChain 工具 + 存储 |
通用接入
|
Agent Plugins 1.0 |
MCP 客户端 |
详细接入方式请参考 Integrations。
框架应用请参考 LangChain/LangGraph 和 Microsoft Agent Framework 集成包，其中也介绍了如何添加其他框架适配器。
桌面客户端（Beta）
桌面客户端是面向 macOS 和 Windows x64 的控制台（Beta），用于配置支持的本地 Agent 接入、查看会话中的召回与捕获事件，并将本地记忆和技能同步到 OpenViking。
下载：
VikingBot
VikingBot 是构建在 OpenViking 之上的 AI 智能体框架：
pip install "openviking[bot]"
openviking-server --with-bot
ov chat # 在另一个终端运行
官方 Docker 镜像内置 VikingBot，默认随服务器和控制台 UI 一起启动。详情见 VikingBot 指南。
生产部署
开源服务器采用 AGPLv3，可在自己的环境部署，无需激活码。见服务器配置和 Docker 与部署指南。
服务器支持账号与用户隔离，并可按需启用资源 ACL。开放非本机访问前，需配置身份认证。
商业版本
☁️ 商业化 SaaS 版由火山引擎托管和运维，提供个人版、企业版，以及开源部署的迁移工具。套餐与额度见服务文档。中国以外地区的托管服务计划在 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, and Yunjun Gao.
arXiv:2605.29640, 2026。已于 2026 年 9 月在 VLDB 2026 完成演讲。
📄 在 arXiv 阅读论文 · 阅读 PDF
让目录结构成为检索上下文。 这篇论文为 OpenViking 的目录语义检索提供形式化基础、索引设计与实验验证。论文定义了目录范围查询与结构维护操作，并提出 TrieHI，OpenViking 已将其集成，用于在向量排序前确定目录检索范围。文件系统范式由此贯穿组织与检索：Agent 可以在项目或记忆子树内查找证据、保留周边上下文，并随知识演化调整目录结构。
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。已被 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。投递中。
📄 在 arXiv 阅读论文 · 阅读 PDF
合作伙伴
- deer-flow - 开源的长周期 SuperAgent 框架
- NoKV - AI 原生的分布式文件系统
- loopx - 轻量级循环工程状态内核
- Hermes Agent - 与用户共同成长的智能体
- NVIDIA cuVS - GPU 加速的向量搜索与聚类库
合作提议请提交 issue。
社区与贡献
- 文档：docs.openviking.ai · FAQ
- 博客：blog.openviking.ai
- 团队：关于我们
- 交流： 飞书 · 微信 · Discord · X
- 贡献：修 bug、加新功能都欢迎——见 CONTRIBUTING_CN.md
安全与隐私
漏洞报告方式和受支持的版本，见 SECURITY.md
许可证
OpenViking 各组件采用不同的许可证：