github volcengine/OpenViking v0.3.21
OpenViking v0.3.21 Release Notes / 发布说明
on GitHub

3 hours ago

Release date / 发布日期: 2026-05-27

Full Changelog / 完整变更记录: v0.3.20...v0.3.21

Compare range / 对比范围: v0.3.20..v0.3.21

Commits / 提交数: 23

中文

版本概览

v0.3.21 主要强化 Memory V2 的 agent trajectory/experience 链路、批量会话写入、OpenClaw 工具命名、资源解析与文件系统错误处理，并修复 pip/pipx 安装下 /studio 静态资源缺失的问题。这个版本也补充了 tau2/VikingBot 自改进评测链路和一批文档、测试与安全清理。

主要更新

  • Trajectory 记忆更适合检索与复盘：trajectory schema 新增 retrieval_anchor 和 embedding_template，索引文本从完整内容收敛为 trajectory_name + retrieval_anchor；experience 与 trajectory 之间改为系统维护的 derived_from StoredLink，写入正向 links 与反向 backlinks，替代易丢失的 source_trajectories 元数据。
  • 会话消息支持批量写入：REST API 新增 POST /api/v1/sessions/{session_id}/messages/batch，CLI 新增 ov session add-messages，适合导入历史对话或一次写入多轮消息；ov add-memory 也复用同一套严格 JSON 消息解析。
  • OpenClaw 搜索工具改名为 ov_search：OpenViking OpenClaw 插件不再注册 memory_search，避免与 OpenClaw 内置工具冲突；导入 resource/skill 后的检索闭环统一使用 ov_search 和 /ov-search。
  • 资源解析与二进制 URL 判断增强：HTTP accessor 扩展图片、音频、视频和 Office/EPUB/zip 文档类型识别；当 HEAD 不可靠时会在 GET 后用响应头重新判断，减少签名 URL、无扩展名 URL 和二进制下载被误判为网页的情况。
  • 文档转换不再阻塞事件循环：Word、PowerPoint、Excel、EPUB、legacy doc 等本地转换路径改为线程中执行，降低大文件解析对异步服务的影响；PDF XObject 图片提取也修正为按目标对象读取。
  • 文件系统与 API 错误更稳定：AGFS typed exceptions 映射到更明确的 OpenViking error envelope；file URI reindex 的锁获取、单文件 grep、文件移动到目录 URI 的参数校验，以及 ov wait timeout 请求体传递都得到修复。
  • Web Studio 与安装包体验改进：Python build/wheel 会构建并打包 web-studio 静态资源，pip/pipx 安装后 /studio 可直接使用；Web Studio 预览 memory 文件时会读取 raw 内容并正确展示实际正文，而不是暴露内部 MEMORY_FIELDS 注释。
  • LiteLLM VLM 增加 NVIDIA NIM 路由：模型名中包含 nvidia_nim 或 nemotron 时可自动走 NVIDIA NIM 的 LiteLLM 前缀和 NVIDIA_NIM_API_KEY 环境变量。
  • tau2/VikingBot 评测升级：新增 benchmark/tau2/vikingbot 端到端 runner，支持 cold start、train trajectory commit、test 多次平均和跨 epoch 自改进评测；原 tau2 LLM harness 移到 benchmark/tau2/llm。

新功能用法

批量写入会话消息： 

ov session add-messages a1b2c3d4 '[{"role":"user","content":"Hello"},{"role":"assistant","content":"Hi"}]'
ov add-memory '[{"role":"user","content":"Hello"},{"role":"assistant","content":"Hi"}]'

对应 REST API： 

curl -X POST http://localhost:1933/api/v1/sessions/a1b2c3d4/messages/batch \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -d '{"messages":[{"role":"user","content":"Hello"},{"role":"assistant","content":"Hi"}]}'

OpenClaw 中检索已导入的资源或技能： 

/ov-search "OpenViking install" --uri viking://resources/openviking-readme
/ov-search "memory install skill" --uri viking://agent/skills

读取 memory 文件的原始存储内容： 

curl "http://localhost:1933/api/v1/content/read?uri=viking://agent/main/memories/experiences/demo.md&raw=true" \
  -H "X-API-Key: your-key"

NVIDIA NIM VLM 示例： 

{
  "vlm": {
    "provider": "nvidia_nim",
    "model": "nvidia/llama-3.1-nemotron-nano-vl-8b-v1",
    "api_key": "{your-nvidia-nim-api-key}",
    "temperature": 0.0
  }
}

体验与兼容性改进

  • pip/pipx 和 Docker 构建链路现在统一通过 Python build 流程产出 Web Studio bundle；如果本地开发不希望构建 Studio，可使用 OV_SKIP_STUDIO_BUILD=1 跳过。
  • Makefile 新增 build-studio target，clean 会清理 openviking/web_studio/dist/。
  • content.read 新增 raw=true 参数；默认行为仍会隐藏 memory 内部字段，兼容已有调用方。
  • OpenClaw 用户需要把旧的 /memory-search 和 memory_search 调用迁移到 /ov-search 与 ov_search。

修复

  • 修复 role_id_memory_isolation 开启时 role_id 处理导致的错误。
  • 修复 file URI reindex 锁路径被当成目录导致的 Not a directory 问题。
  • 修复 pip/pipx 安装后 /studio 不可用的问题。
  • 修复 URL 导入二进制内容在 GET 之后仍被当作网页的问题。
  • 修复 PDF XObject 图片提取没有定位到目标 image object 的问题。
  • 修复 Web Studio raw memory 预览无法按 agent 展示实际正文的问题。
  • 修复 ov wait timeout 被放进 URL query 而不是请求体的问题。
  • 修复 LiteLLM VLM 对 NVIDIA NIM model route 的 provider 识别问题。

文档、测试与安全

  • 重写 agent integrations 文档结构，新增 MCP clients、Hermes、LangChain/LangGraph、community plugins 等页面。
  • Prompt guide 补充 embedding_template memory schema 字段说明。
  • 新增 document parser threading、URL filename preservation、PDF bookmark/image extraction、file reindex lock、path lock、LiteLLM provider detection 等测试覆盖。
  • 移除陈旧 dependency lock 文件，减少关键依赖锁定带来的安全噪声。
  • README/README_CN 中修复 LangChain 文档链接和多处图片路径。

English

Overview

OpenViking v0.3.21 focuses on Memory V2 trajectory/experience quality, batch session ingestion, OpenClaw tool naming, parser and filesystem reliability, and a packaging fix that makes /studio available from pip and pipx installs. It also adds the tau2/VikingBot self-improvement benchmark runner plus documentation, tests, and security cleanup.

Highlights

  • More retrievable trajectory memory: the trajectory schema now has retrieval_anchor and an embedding_template, so vector indexing uses trajectory_name + retrieval_anchor instead of the full operation contract. Experiences and trajectories are connected with system-managed derived_from StoredLink records written as forward links and reverse backlinks, replacing fragile source_trajectories metadata.
  • Batch session message ingestion: POST /api/v1/sessions/{session_id}/messages/batch and ov session add-messages add multiple messages in one call, useful for history import and memory extraction workflows. ov add-memory now uses the same stricter JSON message parser.
  • OpenClaw search is now ov_search: the OpenViking OpenClaw plugin no longer registers memory_search, avoiding collisions with OpenClaw built-ins. Use ov_search or /ov-search after importing resources or skills.
  • Stronger URL and document parsing: HTTP import detection now recognizes image, audio, video, Office, EPUB, and zip downloads. When HEAD cannot be trusted, the downloader re-checks headers after GET, which helps signed URLs, extensionless URLs, and binary downloads route correctly.
  • Document conversion no longer blocks the event loop: local Word, PowerPoint, Excel, EPUB, and legacy document conversions now run in worker threads. PDF XObject image extraction now targets the actual image object.
  • More precise filesystem/API failures: AGFS typed exceptions map to clearer OpenViking error envelopes; fixes cover file URI reindex locks, single-file grep, invalid file move destinations, and ov wait timeout placement.
  • Web Studio ships with Python installs: setup/build now builds and bundles the Web Studio static assets, so /studio works from pip/pipx installs without Docker. The file preview reads raw memory files internally and displays user-facing content instead of exposing MEMORY_FIELDS.
  • NVIDIA NIM through LiteLLM VLM: model names containing nvidia_nim or nemotron now route through the NVIDIA NIM LiteLLM prefix and NVIDIA_NIM_API_KEY.
  • tau2/VikingBot benchmark runner: benchmark/tau2/vikingbot adds an end-to-end runner for cold start, train trajectory commits, repeated test averaging, and cross-epoch self-improvement. The previous tau2 LLM harness now lives under benchmark/tau2/llm.

New Feature Usage

Batch-add session messages: 

ov session add-messages a1b2c3d4 '[{"role":"user","content":"Hello"},{"role":"assistant","content":"Hi"}]'
ov add-memory '[{"role":"user","content":"Hello"},{"role":"assistant","content":"Hi"}]'

REST API equivalent: 

curl -X POST http://localhost:1933/api/v1/sessions/a1b2c3d4/messages/batch \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -d '{"messages":[{"role":"user","content":"Hello"},{"role":"assistant","content":"Hi"}]}'

Search imported resources or skills from OpenClaw: 

/ov-search "OpenViking install" --uri viking://resources/openviking-readme
/ov-search "memory install skill" --uri viking://agent/skills

Read raw stored memory content: 

curl "http://localhost:1933/api/v1/content/read?uri=viking://agent/main/memories/experiences/demo.md&raw=true" \
  -H "X-API-Key: your-key"

NVIDIA NIM VLM example: 

{
  "vlm": {
    "provider": "nvidia_nim",
    "model": "nvidia/llama-3.1-nemotron-nano-vl-8b-v1",
    "api_key": "{your-nvidia-nim-api-key}",
    "temperature": 0.0
  }
}

Improvements

  • pip/pipx and Docker builds now produce the Web Studio bundle through the Python build path. Local developers can set OV_SKIP_STUDIO_BUILD=1 to skip the Studio build.
  • Makefile adds a build-studio target, and clean removes openviking/web_studio/dist/.
  • content.read adds raw=true; default reads still hide memory internals for compatibility.
  • OpenClaw users should migrate /memory-search and memory_search calls to /ov-search and ov_search.

Fixes

  • Fixed role_id handling when role_id_memory_isolation is enabled.
  • Fixed file URI reindex lock acquisition that could fail with Not a directory.
  • Fixed /studio availability for pip and pipx installs.
  • Fixed binary URL imports still being treated as webpages after GET.
  • Fixed PDF XObject image extraction against the wrong image object.
  • Fixed Web Studio memory previews so raw memory files render readable content by agent.
  • Fixed ov wait so timeout is sent in the request body instead of the URL query.
  • Fixed NVIDIA NIM provider detection in the LiteLLM VLM backend.

Docs, Tests, and Security

  • Reworked agent integration docs and added MCP clients, Hermes, LangChain/LangGraph, and community plugin pages.
  • Documented the embedding_template memory schema field in the prompt guide.
  • Added or expanded tests for parser threading, URL filename preservation, PDF bookmark/image extraction, file reindex locks, path locks, and LiteLLM provider detection.
  • Removed stale dependency lock files to reduce critical dependency-lock security noise.
  • Fixed broken LangChain links and image paths in README/README_CN and docs.
Check out latest releases or
releases around volcengine/OpenViking v0.3.21

Don't miss a new OpenViking release

NewReleases is sending notifications on new releases.

Get notifications