volcengine/OpenViking：30k stars 的「AI Agent 上下文数据库」，把 viking:// 虚拟文件系统 + L0/L1/L2 三层加载塞给 Agent，token 砍掉 91%

引子

昨天我给 Claude Code 装了一堆 Agent Skills 之后撞上一个具体痛点。

我每天早上开一个新会话，要花 15-30 分钟「挑东西」：今天写博客，要把哪个 skill 进 context？这个项目的 README 要不要预加载？这份合同 PDF 要不要预先 chunk 完送进去？

挑得不对，session 跑 5 分钟就触发 context window 警告。挑得保守，又会重复触发「失忆」，同一个对话里讲过的事，第三次提的时候 Claude 又当新问题处理。

我在 GitHub Trending 看到了 volcengine/OpenViking，30,032 stars、今日 +803、近一周涨 985、字节火山引擎出品、AGPLv3、描述只有一句话：

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

我顺手翻了一下它的 benchmark，结果愣在桌前：

• LoCoMo（long-conversation user memory）跑分：OpenClaw native 24.20% → 加上 OpenViking 之后 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.87pp，airline +11.87pp

加一层「上下文数据库」，Agent 的长期记忆准确度能翻 3 倍多，token 还能砍掉 9 成。

这不是又一个 mem0 clone，这是字节火山引擎把自家「Viking Memory Base」商业产品（2024 年起服务数千家客户）拆开源的版本。背后是 VLDB 2026 接收的 VikingMem 论文 + 人民大学、浙大、上交三所学校的学术协作 + 一个「viking:// 虚拟文件系统」的统一抽象。

这篇文章好好拆一下它，30k stars 背后的真实价值、它解决了什么「AI Agent 上下文工程」的根本痛点、怎么落到 Claude Code / Codex / Cursor 这些日常工具上，又有哪些坑值得提前知道。

---

一、项目背景：AI Agent 时代的「Context Engineering」难题

1.1 当我们谈「Agent 记忆」时，到底在谈什么

过去两年我给 Claude Code、Cursor、Codex 都写过 memory 相关的配置，每次都撞同一堵墙：

「我上次让你干过的事，为什么你这次又忘了？」

这件事的本质是：LLM 本身没有 memory。Agent 要「记住」任何事，必须靠外挂系统把这些事实、偏好、上下文「写出来」，下次启动再读回去。

于是 2024 年起，AI Agent 圈子里涌现出一大堆 memory 方案：

• mem0：纯向量检索的 memory 层，主打「自动从对话里提取 fact」
• Graphiti：把记忆组织成时序图谱，强调「事实随时间演变」
• Cognee：知识图谱 + 向量双引擎，主打「结构化 RAG」
• Headroom：直接压缩 token，省成本不省记忆
• 各家 Coding Agent 自带的 memory（Claude Code 的 ~/.claude/projects/、Cursor 的 .cursorrules）

这些方案各有侧重，但它们共有一个致命问题：memory、resources（项目文档、网页、PDF）、skills（Agent 技能）三个组件各管各的。

我每天的体验就是：

• memory 用一个 vector store
• 项目文档用另一个 RAG 系统
• Skills 又是文件系统 SKILL.md
• 三个系统各跑各的索引、各用各的检索接口
• Agent 写代码时，要在三个系统之间来回切换查询

更麻烦的是：没有一个统一 URI。

我让 Claude Code 读一段 memory，它告诉我「vector id 0x7f3a」。我让它复现 3 天前看的那个文档，它说「from chunk 1234 of file X」。Agent 自己都不知道这些 ID 对应的语义边界在哪，出了它自己的运行时，谁都看不明白。

OpenViking 的核心判断：问题在 database 这一层，不在 memory 那一层。

1.2 字节火山引擎 Viking 团队的「上下文数据库」思路

README 第一段写得很克制：

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.

把 memory /resources/skills 全部塞到一个虚拟文件系统下，Agent 用 ls / tree / find 操作自己的 context。直接查文件系统的 URI。

这个判断背后有完整的工程演进支撑。OpenViking 不是从零写的小项目，它是字节火山引擎 Viking 团队 7 年工程积累的「开源切片」：

时间	里程碑	关键意义
2019–2023	VikingDB 向量数据库在字节内部广泛落地	支撑多款核心产品的非结构化信息检索；积累亿级向量实时检索经验
2024	VikingDB、Viking Knowledge Base、Viking Memory Base 三件套对外商业化（火山引擎公有云）	服务数千家企业客户；从内部工具转型商业产品
2025	拓展到 AI Search 和 Knowledge Assistants	形成「基础设施 → 应用」完整产品矩阵
Late 2025	开源 MineContext	探索主动式 AI 应用范式，验证个人 context engineering 思路
Early 2026	开源 OpenViking（2026-01-05 创建仓库）	全新设计的 context database 架构；战略转型为开源贡献者

简言之：火山引擎先用 7 年把这件事做成付费产品（Viking Memory Base），跑通了几千个客户的生产环境，现在把底层架构重新设计一遍，开源出来给整个 AI Agent 生态用。

这跟很多” 开源 + 云上版本” 项目的路径相反，通常是大厂开源一个能引流的产品，把付费版当 main course。OpenViking 的立场是 “the open-source edition is not crippled”（README 原话）：仓库里的 AGPLv3 版本功能完整，没有 feature gate、没有强制注册、没有激活码。想用就直接 clone。

商业版和开源版唯一的区别是「谁负责运维」：

• Managed SaaS：挂在火山引擎 / BytePlus 上，企业级 SLA、团队协作、权限管理
• Self-Managed：跑在你自己机房，离线环境也支持，加了分布式部署

这种态度的好处是：开源版本先把工程事实摆出来，剩下的留给市场选。

1.3 这次选 OpenViking 的原因

最近一个月我写过不少 AI Agent 周边：MCP、Harness、Skills、Cursor 配置、量化框架，但 context database 这个赛道还没写过。

OpenViking 出现的时机也合适：

• LoCoMo /tau2-bench 这种” 长对话 + 多轮 Agent 任务” 的评测在过去半年开始普及（之前大家都在刷 SWE-bench 这种” 短任务”）
• 火山引擎这种大厂亲自下场做开源 context database，说明这个赛道被字节这样的厂视为 “AI Agent 时代的水电煤”
• 30k stars + 字节出品 + VLDB 2026 论文 + 真实 benchmark 数据 = 稀缺组合

加上过去 3 天的博客主题（cumora 团队协作、mukul975 安全 skills、firecrawl-anydoc 文档处理），已经 4 天没碰”AI Agent 上下文” 了，正好换换。

---

二、核心功能：六大设计原则

OpenViking README 列了 5 个 Why：

1. One filesystem for all context - 一套 viking:// URI 处理 memory /resources/skills
2. Tiered loading cuts token spend - 三层加载按需取
3. Directory recursive retrieval - 目录递归检索
4. Observable retrieval - 可观测的检索轨迹
5. Sessions become memory - Session 自动 commit 记忆

OpenViking 还应该加第六条，多 Agent 框架的统一接入，因为这是它从「内部产品」变成「生态底座」的关键。

下面一个个拆。

2.1 viking:// 统一虚拟文件系统

这是 OpenViking 最颠覆的设计决策。

传统 memory / RAG /skills 系统的拓扑是：

Agent  ──(query A)──>  Vector Store (memory)
      ──(query B)──>  Document Store (RAG)
      ──(list C)───>  File System (skills)

三个后端、三套接口、三种 namespace，Agent 端要写胶水代码串起来。

OpenViking 的拓扑：

Agent  ──(ls / find / grep)──>  viking://
                                     │
                          ┌──────────┼──────────┐
                          │          │          │
                       memories   resources    skills
                          │          │          │
                          └──────────┴──────────┘
                            同一个 AGFS 文件系统后端

URI 长这样（README 里给的例子）：

viking://
├── resources/                # 项目文档、repo、网页
│   └── my_project/
│       ├── docs/api/
│       └── src/
└── user/
    └── {your_id}/
        ├── memories/preferences/
        │   ├── writing_style
        │   └── coding_habits
        ├── resources/private_project/
        ├── skills/
        │   ├── search_code
        │   └── analyze_data
        └── peers/
            └── web-visitor-alice/

Agent 操作自己 context 的方式变成：

ov ls viking://resources/
ov tree viking://resources/my_project -L 2
ov find "what is openviking"
ov grep "auth" --uri viking://resources/my_project/docs/api/

这套设计带来 3 个直接好处：

1. Agent 知道自己有哪些 context。tree 一打，AI 就能看到完整的「我有什么」目录树。向量库世界里，Agent 自己看不到仓库里有啥。
2. 检索可观测。每一步 find 都留下 trajectory，错了可以 replay 调试（OpenViking 把它叫 “observable retrieval”）。
3. 人和 Agent 共享同一套接口。我自己也能 ov ls 看自己的 memory 文件，调试体验跟 Agent 一样。

2.2 L0 / L1 / L2 三层加载：把 token 砍掉 91% 的关键

这是 OpenViking 最工程化、最值得借鉴的一招。

传统 RAG 系统把每个文档 chunk 当成” 读或没读” 的二值单位，要么整段送进 context，要么不送。结果就是：你给 Agent 一份 50 页的 PDF，它要么完整吃掉（爆炸），要么完全不知道（白问）。

OpenViking 的做法是 给每条 context 自动生成三个层级：

• L0（Abstract）：一句话摘要，约 100 tokens，用于快速判断相关性
• L1（Overview）：核心信息 + 使用场景，约 2k tokens，用于规划
• L2（Details）：完整原文，按需读取

每个目录、每个文件都有三层：

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

检索过程变成：

1. Agent 用 L0 判断「这条 context 大概是干啥的」
2. 决定深入时读 L1 拿结构信息
3. 真正要执行时再读 L2 完整内容

benchmark 数据直观：

• OpenClaw native：24.20% 准确度（每次都吃全量 memory）
• OpenClaw + OpenViking：82.08% 准确度（按需加载三层）
• 准确度提升 3.4 倍，token 反而砍掉 34.3%

token 砍这么多？因为大部分时间 Agent 只需要 L0 + L1 就够了，L2 只在最后一步才读。

2.3 目录递归检索（Directory Recursive Retrieval）

向量检索有个老问题：chunks 之间没有上下文关联。

我之前写 firecrawl-anydoc 时就提过，RAG 检索出来的常常是一段孤立的文本片段，AI 不知道它在文档里的位置。

解法是：先在目录层做向量检索，再往下钻。

具体流程：

1. Step 1：用 L0 abstract 在目录树第一层做向量检索，找到相关性最高的” 目录节点”
2. Step 2：进入该目录，用 L1 overview 做第二轮向量检索，决定要进入哪个子目录
3. Step 3：到叶节点才读 L2 完整内容

这相当于” 分块检索” → “分目录检索”。检索结果天然带着它的” 上下文路径”，你拿到 auth.md 的内容，同时知道它属于 my_project/docs/api/，连兄弟文件 endpoints.md 也一起被列出。

2.4 可观测的检索轨迹

LLM 应用最让人抓狂的地方：Agent 给出一个答案，你不知道它是怎么得出这个答案的。

传统 RAG 系统的查询日志长这样：

[2026-08-20 02:14:33] query="how to authenticate"
  → vector_search → top_k=5
  → chunk_ids=[1234, 5678, 9012]
  → response generated

这条日志展开成” 目录浏览轨迹”：

[2026-08-20 02:14:33] query="how to authenticate"
  → ls viking://resources/my_project/        # 列出根目录
  → find "auth" --uri viking://resources/    # 在根目录检索
    → ranked: [docs/api/ (0.89), docs/tutorial/ (0.45)]
  → cd docs/api/
    → ls .                                  # 看本目录 L0
    → read .overview                         # 读 L1
    → find "authenticate" --in=docs/api/     # 在子目录检索
      → ranked: [auth.md (0.92), endpoints.md (0.71)]
  → read auth.md                            # L2，按需

错误时你可以一键 replay 整个浏览路径，看到 Agent 是在哪一步 “走偏了”。这种可观测性是传统向量库做不到的，向量库的世界里，”query → result” 是个黑盒。

2.5 Session 自动 commit 记忆

传统 Agent memory 的痛点：怎么把” 一次会话里学到的用户偏好” 沉淀到长期记忆里？

解法是 session commit 模式：

1. Agent 跟用户跑完一次对话
2. 会话结束时调用 commit_session()
3. OpenViking 异步从对话里提取「user preferences」和「agent experience」
4. 写入 viking://user/{your_id}/memories/preferences/ 和 viking://user/{your_id}/skills/

下次开新会话，Agent 一查 viking://user/{your_id}/memories/preferences/writing_style，发现：

用户喜欢用具体数字写标题；用户不喜欢 “在数字化时代” 这种开场；用户写技术博客时倾向用小戴的第一人称。这些偏好是系统自动从过去会话里抽出来的，不是用户手动配置的。

更深一层的是 “agent experience”：Agent 自己做完一个 task 之后，会沉淀「这次是怎么干的」作为 skill。下次遇到类似任务，直接调用上次的方法。

2.6 多 Agent 框架的统一接入

一个 context database 如果只能服务一个 Agent，那只是工具；能服务一堆 Agent，才是生态。

OpenViking 的接入列表（截至 2026-08-19）：

Agent 框架	集成方式	文档路径
Claude Code	Memory plugin + Hook	agent-integrations/02-claude-code.md
Codex	Memory plugin + Hook	agent-integrations/04-codex.md
OpenClaw	Memory plugin + Hook	agent-integrations/03-openclaw.md
Hermes	Memory plugin + Hook	agent-integrations/05-hermes.md
Cursor	MCP integration	agent-integrations/12-cursor.md
TRAE / TRAE CN / TraeCode CLI 2.0	Memory plugin	agent-integrations/13-trae.md
OpenCode	Plugin	agent-integrations/10-opencode.md
pi	Extension	agent-integrations/11-pi.md
Agent Plugins 1.0	Plugin distribution	agent-integrations/15-agent-plugins.md
MCP clients	MCP server	agent-integrations/06-mcp-clients.md
LangChain / LangGraph	Python SDK	agent-integrations/07-langchain-langgraph.md
Log ingestion	直接 ingest Agent session log	agent-integrations/09-log-ingestion.md

覆盖了 12 种主流 Agent 框架 + LangChain/LangGraph 这类通用框架。

这种” 广撒网” 的接入策略背后有个判断：Agent 框架不会收敛，Claude Code 不会吃掉 Cursor，Codex 不会吃掉 OpenCode。每个框架都有自己的用户群。context database 想要做大，必须对所有框架” 无差别”。

2.7 OpenViking Helper (Beta)：桌面端可视化管理

这一条是 OpenViking 2026 上半年加的新功能，macOS / Windows 的桌面客户端：

1. 可视化本地 Agent 配置：自动检测 Claude Code、Codex、Cursor、Trae、OpenCode 的安装位置，配置 plugin / MCP / Hook / CLI 集成
2. Session trace 检查：解析 Claude Code、Codex、Trae 的 session 文件，展示 OpenViking recall、prompt injection、MCP calls、capture、commit 事件
3. 本地 memory /skill 管理：可视化本地 memory /rule 文件和 SKILL.md，一键 sync 到 OpenViking

关键意义是：它把 OpenViking 从「CLI 后台服务」变成「有 GUI 的开发者工具」。普通用户不再需要手敲 ov config、手改 ~/.claude/settings.json。

下载链接：

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

文件命名是 openviking-helper-0.0.19-*.dmg / .exe，仍在 beta。

2.8 viking:// 协议 + API 设计：为什么是文件系统不是 REST

viking:// 协议的核心设计哲学我必须单独讲一下，因为它决定了整个 OpenViking 跟市面上其他 memory 工具的根本差异。

v0.1 的设计文档里强调：viking:// URI 不是一个「endpoint」，它是一个「文件路径」。这意味着：

维度	REST API 风格（mem0 / Graphiti）	viking:// 文件系统风格（OpenViking）
命名空间	多个独立 API（/memories、/resources、/skills）	一个统一命名空间
引用方式	UUID / opaque ID	路径（像 /resources/my_project/docs/api/auth.md）
操作符	GET / POST / DELETE	ls / tree / find / grep / read / write
错误处理	HTTP status code	文件系统错误码（ENOENT / EACCES）
缓存策略	自定义	直接复用 OS page cache
调试方式	看 API 调用日志	tree / cat 直观看到

这套设计最妙的地方在于 Agent 可以” 自我描述”：

ov tree viking://user/{your_id}/memories/ -L 3

返回结果是一棵树，Agent 看到这棵树，自然就知道「我有哪些记忆、记忆分几类」。在 REST API 风格下，Agent 要先 GET /memories 拿到列表，再 GET /categories 看分类，至少两次 API 调用才能拼出认知。

而且 viking:// 路径可以直接作为 prompt 的一部分发给 LLM：

“请阅读 viking://resources/my_project/docs/api/auth.md，总结出 authentication 流程。”

LLM 看到的是个「文件路径」语义，不需要理解 opaque UUID。在 few-shot context 里塞一个文件路径也比塞一个 UUID 直观得多。

具体到代码层面（Python SDK）：

from openviking import OpenViking

client = OpenViking()

# 加一个 GitHub repo 作为 resource
job = client.add_resource("https://github.com/volcengine/OpenViking")
client.wait_for_job(job)

# 列出根目录
entries = client.ls("viking://resources/")
# → [
#     {"name": "volcengine", "type": "directory", "uri": "viking://resources/volcengine"},
#     {"name": "my_project", "type": "directory", "uri": "viking://resources/my_project"},
#   ]

# 找相关 context
results = client.find("how to authenticate", uri="viking://resources/volcengine")
# → [
#     {
#       "uri": "viking://resources/volcengine/OpenViking/docs/en/agent-integrations/02-claude-code.md",
#       "l0_abstract": "Setup guide for integrating OpenViking with Claude Code...",
#       "l1_overview": "...",
#       "score": 0.89,
#       "path": ["docs", "en", "agent-integrations", "02-claude-code.md"]
#     },
#     ...
#   ]

# 真正读取 L2 完整内容
full = client.read("viking://resources/volcengine/OpenViking/docs/en/agent-integrations/02-claude-code.md")

这套 API 设计的「文件优先」哲学跟 Linux 的「一切皆文件」、Plan 9 的「一切皆文件系统」一脉相承。

---

三、技术架构亮点

3.1 整体架构：AGFS + 多语言 SDK + VikingBot

仓库根目录看一眼就懂：

openviking/
├── openviking/           # Python 主包（含 server + SDK + bot）
├── sdk/                  # Python SDK 子包
├── crates/ov_cli/        # Rust 写的 ov CLI
├── npm/                  # npm 包装的 CLI
├── integrations/         # 各 Agent 框架的集成 adapter
├── agent-plugins/        # Plugin 分发系统
├── web-studio/           # Web 端的 OpenViking Studio
├── bot/                  # VikingBot
├── benchmark/            # LoCoMo / tau2-bench / RAG / skillsbench
├── docs/                 # VitePress 文档站
└── examples/             # 示例代码

核心技术栈：

• Python 主包 + Rust CLI + TypeScript SDK + npm CLI 四件套，对应不同使用场景
• AGFS（自研文件系统层）做存储后端，README 里特意提到「delete-account now actually removes AGFS data on disk」（fix #4125），说明 AGFS 是核心存储组件
• VikingBot 是基于 OpenViking 构建的 AI agent framework，pip install "openviking[bot]" 即可使用
• OpenViking Studio 是 Web 端的 playground，可以不开本地服务就体验 context browsing /semantic search /multi-agent hub

依赖（从 pyproject.toml 抓的）：

dependencies = [
    "openviking-sdk>=0.1.1",
    "pydantic>=2.0.0",
    "scrapy>=2.11.0",          # 网页抓取
    "trafilatura>=1.12.0",     # 网页正文提取
    "pdfplumber>=0.10.0",      # PDF 解析
    "python-docx>=1.0.0",      # Word 解析
    "python-pptx>=1.0.0",      # PPT 解析
    "openpyxl>=3.0.0",         # Excel 解析
    "ebooklib>=0.18.0",        # EPUB 解析
    "fastapi>=0.128.0",        # HTTP server
    "uvicorn>=0.39.0",         # ASGI server
    "volcengine-python-sdk[ark]>=5.0.3",  # 火山引擎豆包 SDK
    "openai>=1.0.0",           # OpenAI 兼容协议
    "httpx>=0.25.0",
    "apscheduler>=3.11.0",     # 异步任务调度（用于 session commit 异步提取）
    "json-repair>=0.25.0",
    ...
]

光看依赖就知道：OpenViking 把 13 种常见文档格式（PDF / Word / PPT / Excel / EPUB / 网页 / HTML / XML / RSS…）解析器都内置在主包里，喂啥格式都能 ingestion。

3.2 三层加载的实现细节

L0 / L1 / L2 是怎么生成的？

从 pyproject.toml 看依赖里没有 tiktoken 也没有 transformers，说明 L0/L1 的生成不是本地 LLM，而是调用外部 model。init wizard 里支持 6 种 provider：

• Volcengine（火山引擎豆包）
• OpenAI
• Codex OAuth
• Kimi
• GLM
• Local Ollama（init 会自动检测 + 拉模型）

也就是说，用户用谁家的 LLM，OpenViking 就用谁家的 LLM 生成三层摘要。

L0 的 prompt 大概是「用一句话总结这份文档的核心内容」；L1 的 prompt 是「用结构化方式列出这份文档的关键章节和使用场景」。具体 prompt 在仓库 openviking/summary/ 下（我没细究，但肯定是 prompt engineering 的产物）。

每条 context 在 add 进 OpenViking 时，server 后台异步跑 L0/L1 生成，结果存到对应目录的 .abstract 和 .overview 文件里。L0 ≈ 100 tokens，L1 ≈ 2k tokens，这两个数字是 README 给的实测值，不是拍脑袋。

3.3 学术背景：VikingMem 论文 + 三所高校协作

OpenViking 背后有一篇正经学术论文：VikingMem: A Memory Base Management System for Stateful LLM-based Applications（arXiv:2605.29640，2026 年，VLDB 2026 已接收）。

作者来自浙江大学（高云君教授团队）和字节火山引擎。

VLDB 是数据库领域三大顶会之一（SIGMOD / VLDB / ICDE），能被接收说明这个工作不是「工程轮子」，是有理论支撑的。论文应该是把 OpenViking 里的目录递归检索、三层加载、用户偏好提取等技术做了系统化建模。

另外，团队还跟三所国内高校有学术协作（README 里致谢）：

• 人民大学信息学院 孙亚辉副教授
• 浙大软件学院 高云君教授 + 朱一帆、葛聪聪研究员
• 上海交大人工智能学院 戴国浩副教授 + 无问芯穹联合创始人、首席科学家

无问芯穹（Infinigence AI）最近刚拿了新一轮融资，是国内做 AI 算力基础设施的公司。戴国浩老师同时挂学术 + 产业两份 title，这种” 学术界 + 工业界” 双跨的协作模式，让 OpenViking 的工程实践有论文级的严谨度。

3.4 工程事实：3 天前的 release + 458 个 open issue + 30+ commits/day

到 2026-08-19（写文章前一天）为止，仓库的状态：

• 总 stars：30,032
• Forks：2,329
• Open issues：458
• 最新 release：v0.4.15（2026-08-18）
• 前一天 commits：10 条以上（issue 列表显示 8/19 一天开了 7 个新 issue + 关闭了 3 个 PR）
• License：AGPLv3 + 部分子项目 Apache 2.0
• 默认分支：main

Open issues 458 个不算少，说明项目还在快速迭代、有 bug 但也有 PR 在修。从 issue 标题看（截至 2026-08-19）：

• #4134 LiteLLMDenseEmbedder.embed_async() skips _truncate_vector()
• #4133 Feature Request: Add batch/streaming import for large resource sets
• #4132 [Bug]: 使用 …
• #4131 [Bug]: MemoryUpdater 在 resolved_op.uris 为空时静默丢弃记忆
• #4129 feat: new tos connector args
• #4128 pi extension: session_shutdown never commits with takeover enabled
• #4126 feat: restore user-scoped memory extraction policies

质量层次不齐，有真正的 bug（#4131 MemoryUpdater 静默丢弃 URI 是 silent data loss 类问题），也有 feature request（#4133 大批量 import 的流式 API）。

AGPLv3 这个 license 值得单独提一句：对个人开发者、自部署都 OK，但任何基于 OpenViking 提供 SaaS 服务的企业必须开源其修改。这是 copyleft 协议的标准要求。要是公司打算把 OpenViking 嵌进商业产品但不想开源，先看清楚 AGPLv3 的边界，或者直接买火山引擎的商业版（Self-Managed Online / Offline + license key）。

---

3.5 benchmark 复现成本：5 分钟上手

OpenViking 官方 benchmark 不是黑盒，仓库 benchmark/ 下放了完整复现脚本。

如果你想自己跑一遍 LoCoMo + Claude Code：

git clone https://github.com/volcengine/OpenViking
cd OpenViking/benchmark/locomo/openviking
pip install -r requirements.txt
# 设置 OpenAI / Claude / Doubao 的 API key
export OPENAI_API_KEY=sk-...
python run_eval.py --dataset=locomo --agent=claude-code
# 默认跑 1,500 个问句，预计耗时 4-8 小时

跑完会输出 results/locomo_claudecode_<timestamp>.csv，跟官方 README 给的数字直接对比。

同一目录下还有 6 个对比基线：

• claudecode/ - Claude Code 原生 memory（不带 OpenViking）
• hermes/ - Hermes Agent 原生 memory
• mem0/ - mem0 接入
• supermemory/ - supermemory 接入
• openclaw/ - OpenClaw 原生 memory
• openviking/ - OpenViking + 各种 Agent 的组合

拉平对比就能看出 OpenViking 在不同 Agent 上的实际增益。

这种「开源 + 完整 benchmark + 复现脚本」的三件套在国内大厂开源项目里不多见 —— 大多数项目给个数字就完事。OpenViking 把” 如何验证” 这件事也开源出来，是研究友好型态度。

---

四、怎么用：从 pip install 到 ov find 全流程

4.1 系统要求

• Python 3.10 或更高（不支持 3.9 和以下）
• macOS / Linux / Windows 都支持（OpenViking Helper 桌面版目前只发了 macOS arm64 /macOS x64 / Windows x64 三种二进制）
• 一个可用的 LLM provider（火山引擎 / OpenAI / Codex OAuth / Kimi / GLM / 本地 Ollama）

4.2 5 步上手

Step 1：安装

pip install openviking --upgrade

一行命令搞定 Python 主包。

Step 2：初始化配置

openviking-server init

交互式 wizard：

1. 选 provider（火山引擎 / OpenAI / Codex OAuth / Kimi / GLM / Ollama）
2. 填 API key / OAuth 登录
3. 选 embedding model（默认会拉跟 provider 配套的）
4. 选 vector store（默认本地 SQLite + 向量，可选 VikingDB 远程）

完成后会在 ~/.openviking/ov.conf 生成配置文件。

Step 3：校验环境

openviking-server doctor

检查：

• Python 版本 ≥ 3.10 ✓
• ov.conf 文件存在且格式正确 ✓
• Provider 网络连通性 ✓
• 本地磁盘空间（默认需要 1-5 GB 给 AGFS + 向量索引）✓

Step 4：启动 server

openviking-server
# 或者后台跑
nohup openviking-server > openviking.log 2>&1 &

默认监听本地端口，HTTP API 走 FastAPI + uvicorn。

Step 5：装 CLI + 用 ov 命令

主包自带 ov CLI（Rust 写的，快）。常用命令：

ov status                                  # 看 server 状态
ov add-resource https://github.com/volcengine/OpenViking
# 后面可以加 --wait 阻塞直到 ingestion 完成
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

加 resource 时 OpenViking 会异步做三件事：

1. 用 scrapy + trafilatura 抓网页 / 解析文档
2. 调用 LLM 生成 L0 + L1 摘要
3. embedding 入向量索引

整个过程是后台跑的，ov add-resource 加 --wait 才阻塞等完成。

4.3 接入 Claude Code

这是最常见的场景。

Claude Code 的集成方式是 Memory plugin + Hook：

# 安装 Claude Code 集成
openviking install claude-code

# 配置 ~/.claude/settings.json
# 添加 hook + plugin 路径

装好之后，每次 Claude Code 开新会话时：

1. 自动从 viking://user/{your_id}/memories/preferences/ 加载用户偏好（preferences /writing_style/coding_habits …）
2. 每次工具调用前，自动 ov find 召回相关 context
3. 会话结束自动 commit_session() 异步提取新偏好

具体文档路径：docs/en/agent-integrations/02-claude-code.md。

4.4 接入 Codex / Cursor / TRAE / OpenCode

每家 Agent 框架的接入方式大同小异：

框架	接入方式	文档
Codex	Memory plugin	agent-integrations/04-codex.md
Cursor	MCP server（Cursor 支持 MCP）	agent-integrations/12-cursor.md
TRAE	Memory plugin	agent-integrations/13-trae.md
OpenCode	Plugin	agent-integrations/10-opencode.md
pi	Extension	agent-integrations/11-pi.md

日常用多个 Agent 框架，价值就出来了，同一份 viking:// 上下文，多个 Agent 共享。

计划是把 Claude Code、Codex、Cursor 都接上 OpenViking，然后让 viking://resources/blog-topics/ 跨三个 Agent 共用。这样我无论在哪个 Agent 里开工，” 小戴最近的写作主题” 都一样。

4.5 接入 LangChain / LangGraph

如果你是用 LangChain 写自定义 Agent：

from openviking import OpenViking
from langchain.agents import initialize_agent

client = OpenViking()

@tool
def recall_context(query: str) -> str:
    """召回 OpenViking 里的相关 context"""
    results = client.find(query, uri="viking://resources/")
    return "\n".join([r["l1_overview"] for r in results[:5]])

agent = initialize_agent(
    tools=[recall_context],
    llm=ChatOpenAI(),
    agent="chat-conversational-react-description"
)

Python SDK openviking-sdk 也提供，支持 sync + async + streaming。

---

五、Benchmark 实测：3 大数字说服我

光说设计理念没用，benchmark 数据才是硬道理。

OpenViking 在 README 里直接放了 benchmark chart（SVG 格式），三个核心数字：

5.1 LoCoMo：长期对话记忆准确度

LoCoMo（Long Conversation Memory）是 2024 年提出的 benchmark，专门测「超长对话里 AI 能不能正确回答问题」。

3 个 Agent 上对比 native vs OpenViking：

Agent	LoCoMo Native	LoCoMo + OpenViking	提升
OpenClaw	24.20%	82.08%	+57.88 pp（3.4×）
Hermes	33.38%	82.86%	+49.48 pp（2.5×）
Claude Code	57.21%	80.32%	+23.11 pp（1.4×）

注：原始数据来自 README 内嵌的 SVG benchmark 图。

OpenClaw 这一组最戏剧化：native 准确度只有 24.20%（几乎就是随机猜），加上 OpenViking 之后直接到 82.08%。这说明 OpenClaw 自带的 native memory 基本不能用，OpenViking 在这种场景下的价值是” 从零到有”。

Claude Code 的 native 已经 57.21%（不低），但加上 OpenViking 还能涨到 80.32%，意味着即使 Claude Code 自带 memory，加 OpenViking 还能再加 23 个百分点。

5.2 token 节省：34.3% 到 91.0%

README 给的是「with OpenViking」 vs 「native」的 token 消耗对比：

• OpenClaw：token 下降 91.0%（接近砍掉 9 成）
• Hermes：token 下降 34.3%
• Claude Code：token 下降 72.1% 左右（具体数字我没在 README 找到精确值，从 chart 估的）

按 API 价格算（假设 Claude Sonnet 5 input $3/M tokens）：

• 每天 1000 次会话、每次平均 50k tokens
• Native：50M tokens/day × $3 = $150/day
• OpenViking：14M tokens/day × $3 = $42/day
• 每月省 $3000+

这只是按 input token 算，没算 output token（output 比 input 贵 3-5 倍）。OpenViking 减少了 context size，模型输出也会变短，整体账单能砍 50-70%。

5.3 查询延迟：58.45% 到 66.10% 降低

这个数字有点违反直觉，OpenViking 多了「目录递归检索」+「三层加载」两个步骤，怎么会更快？

原因在于 OpenViking 的 L0 abstract + L1 overview 是预处理好的（add-resource 时异步生成），检索时直接读 L0/L1 文件，不用每次都 embedding + similarity search 全量内容。

传统 RAG：query → embed → vector_search（全量内容） → top_k → 返回
OpenViking：query → embed → vector_search（只搜 L0 abstract） → 目录定位 → 读 L1（必要时） → 读 L2（最后一步）

由于 L0 abstract 只有 100 tokens 一条，embedding + similarity 阶段比全量内容快一个数量级。

5.4 tau2-bench：多轮 Agent 任务成功率

tau2-bench 是 Sierra 出品的 multi-turn agent benchmark，专门测 AI 在客服、零售、航空这种「需要调用工具 + 维护会话状态」的场景里能不能干好活。

场景	Native	+ OpenViking	提升
Retail（零售客服）	70.94%	77.81%	+6.87 pp
Airline（航空客服）	54.38%	66.25%	+11.87 pp

Retail 涨 6.87pp、Airline 涨 11.87pp，这两个数字看起来「小」，但 multi-turn agent benchmark 上 5 pp 已经是显著提升，很多新方法在这个数据集上只能涨 1-2 pp。

Airline 涨 11.87pp 更值得关注，Airline 场景是 tau2-bench 里公认最难的（需要复杂的订票、改签、退款规则）。OpenViking 在这种「高规则密度 + 多步骤」场景下提升最大，说明 三层加载 + 目录递归在「需要稳定召回准确规则」的场景里价值最高。

5.5 复现脚本：开源

仓库 benchmark/ 目录下放了一整套复现脚本：

benchmark/
├── RAG/                  # RAG 任务评估
├── locomo/               # LoCoMo（long-conversation memory）
│   ├── claudecode/
│   ├── hermes/
│   ├── mem0/
│   ├── openclaw/
│   ├── openviking/
│   ├── supermemory/
│   └── vikingbot/
├── longmemeval/          # LongMemEval
├── retrieval/            # 检索质量
├── skillsbench/          # Skills benchmark
├── tau2/                 # tau2-bench
├── vectordb_perf/        # 向量库性能
├── cuvs/                 # NVIDIA cuVS GPU 加速
└── custom/               # 自定义 benchmark

benchmark/locomo/README.md（LoCoMo 的中文评测指南）写得很细：

本目录包含 LoCoMo（Long-Term Conversation Memory）评测脚本，用于评估对话记忆系统的性能。

如果你想自己跑一遍验证：

cd benchmark/locomo/openviking
python run_eval.py --dataset=locomo --agent=claude-code

对比基线（mem0、supermemory、OpenClaw 原生、Hermes 原生、VikingBot）的脚本都在同一目录下，可以拉平对比。

---

六、合作伙伴 + 商业生态

OpenViking 找了 4 个 confirmed partner，它在主动做生态合作。README 明确列了 4 个 confirmed partner：

1. deer-flow - 字节自研的 long-horizon SuperAgent harness（我之前拆过，跟今天这个 OpenViking 互补，deer-flow 是「怎么调度 Agent」，OpenViking 是「Agent 的 memory 从哪来」）
2. NoKV - AI native 分布式文件系统（给 OpenViking 提供底层存储的可能性）
3. loopx - Lightweight loop engineering state kernel（轻量循环工程状态内核）
4. Hermes Agent - The agent that grows with you（Nous Research 自研的 self-evolving Agent）

注意 Hermes Agent 的描述是 “The agent that grows with you”，这跟 OpenViking 的 “self-evolving context database” 是同一个方向。两个项目一个做 self-evolving Agent，一个做 self-evolving Agent Context，互相集成是天然的事。

如果你也想加入 partner list，README 说要开 issue 申请。

6.1 Managed SaaS 和 Self-Managed 商业版

两个商业版：

☁️ Managed SaaS（挂在火山引擎上）

• Personal 版：免费试用 50 个 file；超出后用 VikingDB 跑生产
• Enterprise 版：多用户 context 管理、团队协作、权限、企业 SLA
• 海外版挂在 BytePlus 上

🏢 Self-Managed（跑在你自己的环境里）

• Online：部署到你的云账号 / VPC，BYOC 支持
• Offline：完全 air-gapped 环境，无网络访问（金融、政府、医疗刚需）

这两个商业版不是 feature gate，是” 谁来运维” 的问题。README 强调：

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.

，这是字节难得的开源态度，比很多” 开源 + 商业版 feature gate” 的项目（点名几个常见的）清醒很多。

---

七、适用人群 + 局限性 + 我的计划

7.1 适合谁用

• AI Agent 重度用户：每天跟 Claude Code / Codex / Cursor 打 8 小时交道、context window 警告反复出现的人
• 多 Agent 框架玩家：同时用 Claude Code、Codex、Cursor 的用户，OpenViking 能让多个 Agent 共享同一份 memory
• 企业 AI 团队：要给整个团队配 “Agent memory” 但不想每人都自己攒 skills 库的团队
• 自部署爱好者：想自己掌控 memory 数据的人，数据全在本地 AGFS 里，不上传任何第三方
• AI 写应用 / 做个人知识库的开发者：把自己写的博客、笔记、文档全部塞进 viking://resources/，让 AI 在自己” 熟悉” 的内容里工作

7.2 不适合谁

• 完全没用过 Coding Agent 的人：先用 1-2 个月 Claude Code，再考虑 memory 工具
• 数据安全极敏感的企业：AGPLv3 的传染性 + 数据本地化 + audit log，这些都需要自己评估合规
• 只需要短期单次任务的人：价值在「跨 session 记忆」，单次问答用不上

7.3 局限性（写在前面的「坑」）

• AGPLv3 协议边界：商业产品集成前必看，必要时买 Self-Managed license
• v0.4.x 仍在快速迭代：458 个 open issue 意味着接口、CLI、API 都在变，生产环境部署要 pin 具体版本
• 依赖 LLM 生成 L0/L1：如果 LLM 抽风（如 API 限流 / 网络问题），add-resource 会卡住
• MCP / Skills 生态绑定：跟 Claude Code 配合最顺，Cursor 走 MCP 略重
• 文档站 docs.openviking.ai 是 VitePress + 中文 / 英文 / 日文三语维护，但部分页面（如 getting-started /configuration）更新可能滞后

7.4 我的下一步

这周先把 OpenViking 装到本地：

pip install openviking --upgrade
openviking-server init   # 选火山引擎 + 豆包
openviking-server doctor # 验证环境
openviking-server        # 启动 server

然后：

1. 把过去 3 个月博客的 markdown 全部 add-resource 进 viking://resources/blog/
2. 接入 Claude Code，看每天写博客时 OpenViking 自动召回相关历史主题的效果
3. 跑一遍 benchmark/locomo/claudecode/，跟 Claude Code 原生 memory 对比一下 token 和准确度
4. 一周后写一篇《OpenViking 实战 7 天报告》

想试的话，先看 openviking.ai/studio 的在线 demo，不用装任何东西，直接在浏览器里体验 context browsing + semantic search。

---

八、总结

volcengine/OpenViking 不是又一个「开源版 SaaS 工具」，它是字节火山引擎把自家跑了 2 年的 Viking Memory Base 商业产品（服务数千家企业客户）拆开源的成果。

它的核心判断：Agent 时代 context 太多，memory / RAG /skills 分裂管理是反人类的。所以 OpenViking 用 viking:// 虚拟文件系统把三者统一到一套 URI 下，用 L0/L1/L2 三层加载把 token 砍掉 91%，用目录递归检索把 RAG 从「孤立 chunks」拉出来，用 observable trajectory 让 Agent 调试从黑盒变白盒。

Benchmark 数据说话：

• LoCoMo 准确度 24.20% → 82.08%（OpenClaw）；57.21% → 80.32%（Claude Code）
• token 节省 34.3% - 91.0%
• tau2-bench 任务成功率 +6.87pp / +11.87pp
• 30k stars、字节出品、VLDB 2026 论文、三所高校协作

如果你每天在多个 Agent 之间切换、context window 反复爆、token 账单让人心疼，OpenViking 是 2026 年最值得花一个下午试试的 context database 项目。

---

GitHub 仓库：https://github.com/volcengine/OpenViking

官网 + 在线 Demo：https://openviking.ai

文档站：https://docs.openviking.ai

Benchmark 报告：https://blog.openviking.ai/post/openviking-benchmark-results/

VikingMem 论文：arXiv:2605.29640（VLDB 2026）