OpenViking 上手：给 AI Agent 装一个跨会话不忘事的上下文数据库

教程 2026-09-15 15:41

如果你用 AI 编程助手或 Agent 干过稍微长一点的活，大概都遇到过同一件事：昨天聊得好好的上下文，今天重新打开，它又是白纸一张。项目背景要重讲一遍，你的偏好要再说一次，上次踩过的坑它不记得，下次照踩。

这不是模型不够聪明，是没人给它一个能长期放东西的地方。把整段历史对话全塞进 prompt 当然也能"记住"，但 token 账单会很难看，而且塞得越多、真正相关的信息被淹没得越厉害。

OpenViking 就是冲这件事来的。它是火山引擎（字节跳动 Viking 团队）2026 年 1 月开源的面向 AI Agent 的上下文数据库，目标是让 Agent 把知识、用户偏好、任务经验存下来，跨会话复用。

一、先说数据：这个项目现在什么量级

以下全部取自 GitHub 官方接口，查询时间 2026-09-15：

仓库	volcengine/OpenViking
Star / Fork	37,335 / 2,873
未关闭 Issue	739
首次开源	2026-01-05
最近提交	2026-09-15（当天）
最新版本	v0.4.20（2026-09-14 发布）
主要语言	Python（另有 Rust 组件）
许可证	主项目 AGPL-3.0；`crates/ov_cli` 与 `examples` 为 Apache-2.0
仓库文件数	4,250 个（用官方 tree 接口实测）

开源八个月做到三万多 Star，且当天还在提交、前一天刚发新版——是活跃维护的项目，不是发个新闻稿就搁置的那种。

二、它是什么：一个装上下文的"文件系统"

OpenViking 的核心设计只有一句话：把上下文当成文件来组织。

它给 Agent 划出了一个 viking:// 虚拟文件系统，里面按用途分成三类内容：

资源（resources）——项目文档、代码库、网页等外部知识；
记忆（memories）——用户偏好、写作风格、踩过的坑；
技能（skills）——任务该怎么执行。

每一项上下文都有自己唯一的 viking:// 地址。Agent 可以像在终端里一样，用 ls 看目录、tree 看结构、read 读内容、write 写内容，也可以在目录里做检索。

viking://
├── resources/              # 资源：项目文档、代码库、网页等
│   └── my_project/
│       ├── docs/
│       └── src/
└── user/
    └── {user_id}/
        ├── memories/       # 记忆：用户偏好与经验
        │   └── preferences/
        │       ├── writing_style
        │       └── coding_habits
        ├── skills/         # 技能：任务执行方式
        └── peers/          # 其他 Agent / 访客

这个设计的好处是可读、可审计。Agent 记住了什么，你直接 ls 一下就能看见，不用去猜某个向量库里黑了什么。想改？像改文件一样改掉。子目录还带 L0/L1 摘要，Agent 可以先看摘要判断相不相关，再决定要不要读全文。

三、省 token 的关键：三层加载 + 目录式检索

OpenViking 把每份内容按"吃多少 token"分成三层，Agent 按需取用：

层级	内容	体量	用途
L0	一句话摘要	约 100 tokens	快速判断相关性
L1	概览：核心信息与使用场景	约 2k tokens	规划阶段做决策
L2	完整原始内容	按需	真要读了才加载

对应到目录里长这样：

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

检索方式也不一样。常规 RAG 是"全文切片 → 算相似度 → 把最像的几片塞回去"，而 OpenViking 是先定位目录、再在目录里探索：向量检索先找出候选目录，再顺着目录结构往下找内容。项目方称这套机制为"目录式检索"，并为此发表了一篇论文（Directory-Aware Query and Maintenance in Vector Databases，已被 ICDE 接收）。

另外一条路径是从会话里自动沉淀记忆：你提交一次 Session，它会归档，然后后台按记忆策略提炼内容，和已有记忆比对——新的就新建、重复的就合并、没价值的就跳过。这部分能力对应论文 VikingMem（arXiv:2605.29640），已在 2026 年 9 月的 VLDB 2026 上做过报告。

四、上手：5 分钟跑起来

1. 环境

官方快速开始给出最低要求只有一条：Python 3.10+，操作系统支持 Linux / macOS / Windows。

需要留意的是，火山引擎的《OpenViking 火山方舟》文档在特定版本（0.4.15）的说明里还列出了 Go 1.22+ 和 C++ 编译器（GCC 9+ / Clang 11+）。这是从源码构建时才需要的，装 PyPI 上的现成包用不上——所以两个文档口径不同，按官方快速开始走即可。

2. 安装

# 推荐用 uv
uv tool install openviking --upgrade

# 或者 pip
pip install openviking --upgrade --force-reinstall

# 或者 pipx
pipx install openviking

装完会得到两个命令：客户端 ov（openviking 是它的别名）和服务端 openviking-server。

也可以走 Docker，镜像提供在 GHCR，默认端口 1933，同时自带 Web Studio 前端和 VikingBot：

docker run -d --name openviking \
  -p 1933:1933 \
  -v ~/.openviking:/app/.openviking \
  ghcr.io/volcengine/openviking:latest

3. 准备模型

OpenViking 自己不产出模型，它需要两样外部能力：

VLM 模型——理解图像和内容；
Embedding 模型——做向量化和语义检索。

官方支持火山引擎（豆包系列，官方推荐并结合新用户免费额度）、OpenAI、通过 OAuth 的 Codex，以及任何兼容 OpenAI API 格式的模型服务。

4. 初始化并启动

openviking-server init      # 选 provider，生成 ~/.openviking/ov.conf
openviking-server doctor    # 检查配置与连通性
openviking-server           # 启动服务

5. 导入资源并检索

换一个终端，用 CLI 把一份代码库丢进去再查：

ov status
ov add-resource https://github.com/volcengine/OpenViking
ov task status TASK_ID          # 换成上一步返回的 task_id，直到 status 为 completed
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

用 Python SDK 写进自己的程序也不复杂，核心就几个动作：add_resource 导入、get_task 轮询任务状态、ls / glob / read 浏览、abstract / overview 拿摘要、find 做语义检索。除了 Python，官方还提供 Go 和 TypeScript SDK，以及 HTTP API。

如果不想本地装任何东西，官网提供在线体验版 OpenViking Studio，可以直接浏览上下文、试语义检索。

五、接进你正在用的 Agent

OpenViking 提供了大量现成集成，接入方式分两类：一类是 Hooks + MCP（自动召回、自动采集会话），一类是内置支持。

官方列出的集成：Claude Code、Codex、Cursor、TRAE、OpenClaw（作为上下文引擎）、Hermes（内置记忆）、OpenCode、pi、DeerFlow、DSH（后几者为 Plugin + MCP），以及豆包工作（连接器）、LangChain / LangGraph（工具 + 存储）。

如果你用的工具不在名单里，还有两条通用路径：标准 MCP 客户端和 Agent Plugins 1.0。

不想碰命令行的，官方还发布了桌面客户端（Beta），提供 macOS（Apple Silicon / Intel）和 Windows x64 三个安装包，用来配置本地 Agent 接入、查看会话召回事件、同步本地记忆和技能。

六、评测数据：理论上能提升多少

以下是项目方自述的评测结果（基于 0.3.22 版本，完整结果与实验设置在项目博客里，复现脚本在仓库 ./benchmark）。记忆评测用 Doubao 2.0 Pro 作为 VLM、Doubao-embedding-vision-251215 作为 Embedding 模型：

Agent	原生记忆	接入 OpenViking
OpenClaw	24.20%	82.08%
Hermes	33.38%	82.86%
Claude Code	57.21%	80.32%

除了准确率，项目方还给出两项工程指标：输入 token 减少 34.3%–91.0%，查询时延降低 58.45%–66.10%。

另一组是智能体任务（tau2-bench）上的成功率：Retail 提升 6.87 个百分点、Airline 提升 11.87 个百分点（对比同一个 LLM 不用经验记忆）。

这些数字要怎么看：都来自项目方自己的评测，不是第三方复现。方向上有参考价值——"有没有长期记忆"对 Agent 的表现确实是数量级的差别；但具体到你的场景能提升多少，得自己试。另外评测基于 0.3.22，当前已是 0.4.20，后者没有对应评测数据。

七、开源版和商业版的区别

按官方文档，开源版和商业版（OpenViking Context）共用同一套代码内核，差别在托管、规模和运维支持：

维度	开源版	商业版（OpenViking Context）
部署	自行本地/服务器部署维护	官方全托管，开箱即用
数据规模	受本地硬件限制，默认本地存储 + 单机向量引擎	基于 VikingDB，官方称支持万亿级向量、百亿数据毫秒级检索
SLA	社区支持，无商业 SLA	Oncall 与技术支持
安全合规	自行配置	数据加密、访问审计、网络隔离
计费	AGPLv3 免费自用	套餐订阅，官方称费用低于云上自建

商业版分两路：火山引擎托管的 SaaS（个人版 / 企业版），以及部署在自己云账号或 VPC 里的私有化版本（BYOC，通过激活码启用）。

八、几个动手前要先知道的边界

1. 主项目是 AGPL-3.0，这不是可以忽略的细节。 这是传染性最强的开源协议之一——如果你把 OpenViking 改动后作为网络服务对外提供，按要求需要开放相应源码。自用、内部部署没问题；要做商业产品，建议先把这个想清楚。crates/ov_cli 和 examples 是 Apache-2.0，两者性质不同，别混着理解。

2. 它不是"装上就聪明"，你得先喂。 OpenViking 提供的是存放和检索上下文的基础设施，不是内容本身。目录被"语义处理"过才会有 L0/L1 摘要——也就是说导入之后需要等后台处理完成，才谈得上按需加载和目录检索。

3. 你必须自己有 VLM 和 Embedding 模型。 这是额外成本，官方默认推荐火山引擎豆包系列；也可以用 OpenAI 或任何兼容 OpenAI 接口的服务，或者本地跑（项目文档提到支持 Ollama）。本地跑的代价是硬件和速度。

4. 迭代很快，别把版本号当稳定契约。 从 v0.4.14 到 v0.4.20 只用了不到一个半月，主包、Python SDK、Go SDK、CLI 各自独立发版（tag 命名空间都不一样：vX.Y.Z / python-sdk@X.Y.Z / cli@X.Y.Z）。739 个未关闭 Issue 也说明它还在快速成型期。生产用之前，建议锁版本。

5. 有些文档口径会打架。 比如安装前提（官方快速开始只说 Python 3.10+，方舟文档还列了 Go 和 C++ 编译器）、版本号（README 的评测写 0.3.22，方舟文档的操作示例写 0.4.15）。遇到这种情况以官方快速开始和仓库实际代码为准——这也是本文核实数据时采用的方式。

一句话总结

OpenViking 想解决的是 Agent 的"失忆症"：把知识、偏好、经验用一个可读可改的文件系统管起来，按需供给上下文，少花 token 又不丢信息。它已经有了成熟的形态（三个 SDK、十几个 Agent 集成、桌面客户端、商业托管版），也还在快速迭代。如果你正在被"Agent 记不住事"困扰，或者单纯好奇"上下文数据库"到底长什么样，值得花半小时跑一遍——官网还有免安装的在线体验可以先看效果。

参考来源

GitHub 仓库（元数据、版本、许可证、目录结构均通过 GitHub 官方接口核实，查询时间 2026-09-15）：volcengine/OpenViking
项目官网与在线体验：openviking.ai ｜ OpenViking Studio ｜官方文档
官方文档《快速开始》：docs.openviking.ai/zh/getting-started/02-quickstart
火山引擎《OpenViking 产品介绍》（开源版与商业版差异）：volcengine.com/docs/84313/2374478
火山引擎开发者社区《OpenViking x OpenClaw：开箱即用解决 Agent 的长期记忆困局》

本文数据均取自官方仓库、官方文档与项目方公开评测，未做二次推算。评测类数字为项目方自述，文中已逐处标注口径与版本。