github volcengine/OpenViking v0.3.17
on GitHub

3 hours ago

OpenViking v0.3.17 Release Notes / 发布说明

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

Full Changelog / 完整变更记录: v0.3.16...v0.3.17

Range / 范围: v0.3.16..v0.3.17, 80 commits, 494 files changed.

中文

版本概览

OpenViking v0.3.17 是一次面向 Agent 集成、数据迁移、可观测性和存储可靠性的综合发布。这个版本新增 LangChain / LangGraph 适配器、OVPack v2 迁移与备份能力、npm 原生 CLI 分发、Codex / OpenCode 插件改造，以及 Console 使用统计与请求审计 BFF；同时补强检索层级过滤、WebDAV 资源访问、VLM 失败切换、任务状态持久化和并发写入锁。

主要更新

  • LangChain / LangGraph 集成：新增 openviking.integrations.langchain，提供 OpenVikingRetriever、with_openviking_context()、OpenVikingChatMessageHistory、OpenVikingContextMiddleware、OpenVikingStore 和 create_openviking_tools()。仓库同步加入 LangChain RAG、上下文后端、消息历史、LangGraph agent、middleware 的可运行示例与集成测试。
  • OVPack v2 与完整备份恢复：ov export / ov import 支持 v2 manifest、文件校验、portable index scalar、可选 dense vector snapshot、冲突策略和导入前完整校验；新增 ov backup / ov restore 用于公共 scope 的完整迁移。
  • 原生 CLI 分发：新增 @openviking/cli npm 包，可通过 npm i -g @openviking/cli 或 npx @openviking/cli --help 使用 ov，并扩展 Rust CLI 的 Linux musl 构建、发布流水线和 CLI 集成测试。
  • Codex / OpenCode Agent 插件：Codex memory plugin 改为通过 Codex hooks 做自动召回、逐轮捕获和 PreCompact 前提交，并直接连接 OpenViking 原生 /mcp 端点，不再维护本地 stdio MCP server；同时新增 OpenCode plugin 示例与安装文档。
  • 检索与文件系统能力：find / search 新增 level 过滤，可限定 L0 abstract、L1 overview 或 L2 文件命中；资源文件增加 Phase 1 WebDAV 适配；observer.filesystem 暴露文件系统观测入口。
  • Console 与 Usage/Audit：新增 Usage/Audit 模块和 /api/v1/console/* BFF，基于现有 observability event bus 统计 token、检索次数、上下文提交热力图、请求审计和上下文库存。
  • 存储与并发可靠性：增强精确路径锁和生命周期锁，修复内容写入并发覆盖风险，把阻塞后端调用移出 event loop，补充 QueueFS SQLite 持久化与 task tracker 可持久化后端。

新功能用法

安装新的 npm CLI： 

npm i -g @openviking/cli
ov health
ov find "what did I learn about caching?"

使用 LangChain retriever： 

from openviking.integrations.langchain import OpenVikingRetriever

retriever = OpenVikingRetriever(
    url="http://localhost:1933",
    api_key="...",
    target_uri=["viking://user/memories", "viking://resources"],
    search_mode="find",
    limit=6,
)

docs = retriever.invoke("What did the user decide about deployment color?")

使用 OVPack 做资源迁移、向量快照和完整备份： 

ov export viking://resources/my-project ./exports/my-project.ovpack
ov import ./exports/my-project.ovpack viking://resources/imported/

ov export viking://resources/my-project ./exports/my-project.ovpack --include-vectors
ov import ./exports/my-project.ovpack viking://resources/imported/ --vector-mode auto

ov backup ./backups/openviking.ovpack --include-vectors
ov restore ./backups/openviking.ovpack --on-conflict overwrite --vector-mode auto

调试向量索引一致性： 

ov system consistency viking://resources/my-project

只检索特定层级： 

openviking find "authentication flow" --level 0
openviking search "best practices" -L 1,2

配置 VLM backup 和 provider-specific request body： 

{
  "vlm": {
    "provider": "openai",
    "api_key": "primary-key",
    "model": "gpt-5.4",
    "api_base": "https://api.openai.com/v1",
    "backup": {
      "provider": "volcengine",
      "api_key": "backup-key",
      "model": "doubao-seed-2-0-pro-260215",
      "api_base": "https://ark.cn-beijing.volces.com/api/v3"
    },
    "extra_request_body": {
      "think": false
    }
  }
}

查看文件系统观测信息： 

ov observer filesystem

体验与兼容性改进

  • storage.agfs.queuefs 现在可以显式配置 mode、backend、db_path、stale recovery 和 SQLite busy timeout；QueueFS 默认使用 SQLite，便于队列消息跨重启保留。
  • 新增 storage.task_tracker.backend，单实例可继续使用默认 memory；多实例或需要重启后查询 task_id 的部署可切换到 persistent。
  • vlm.backup 只支持一层 backup，且只在 rate limit、5xx、连接失败和 timeout 等可重试错误上触发；认证、权限和计费类错误不会自动切换。
  • vlm.extra_request_body 会合并到 OpenAI SDK / LiteLLM 的 extra_body，适合接入 Ollama、OpenAI-compatible gateway 或其他需要额外 JSON 字段的 provider。
  • Codex plugin 新部署建议使用 OPENVIKING_* 环境变量调优；旧的 ov.conf 中 codex.* 配置仍保留兼容，但不再推荐作为首选。
  • OVPack dense vector snapshot 只支持纯 dense index；embedding provider、model、input、参数和 dimension 不兼容时会回退重算或按 --vector-mode require 失败。

修复

  • 修复内容写入未使用精确路径锁导致的并发覆盖风险。
  • 修复语义刷新、路径锁和 subtree lock 的并发边界问题。
  • 修复阻塞后端调用占用 event loop 的问题，降低异步服务请求被拖慢的风险。
  • 修复 Memory schema override 优先级、child summary 语言识别、Codex session id 映射和 Codex 空 API key 本地无鉴权场景。
  • 修复 QueueFS SQLite payload bytes 保真、VikingDB __TOTAL__ 计数解析、PDF page cache 释放、ZIP 单根目录 source_name 保留等问题。
  • 修复资源上传文件加密、运行时 logger 统一、OpenClaw L2 内容读取、agent memory pipeline 可靠性等问题。

文档、测试与安全

  • 新增 Codex memory plugin、OpenCode plugin、LangChain / LangGraph、OVPack、filesystem observer、VLM backup、task tracker backend 等中英文文档。
  • 新增 CLI 集成测试、LangChain/LangGraph 单测与集成测试、OVPack import policy 测试、Usage/Audit 测试、VLM failover 测试、transaction exact path lock 测试。
  • CI 扩展 Rust CLI 构建、npm trusted publishing、API 测试和 oc2ov 测试去重。
  • 安全侧提升包括仓库上传文件加密、urllib3 依赖下限提升到 >=2.7.0、OVPack 导入校验和 WebDAV 内部派生文件隐藏。

English

Overview

OpenViking v0.3.17 is a broad release for agent integrations, migration, observability, and storage reliability. It adds LangChain / LangGraph adapters, OVPack v2 migration and backup support, native npm CLI distribution, revamped Codex / OpenCode plugins, Console usage/audit APIs, retrieval level filters, WebDAV resource access, VLM failover, persistent task tracking, and stronger concurrent write locking.

Highlights

  • LangChain / LangGraph integration: added openviking.integrations.langchain with OpenVikingRetriever, with_openviking_context(), OpenVikingChatMessageHistory, OpenVikingContextMiddleware, OpenVikingStore, and create_openviking_tools(). The repository now includes runnable examples and tests for RAG, context backend, message history, LangGraph agents, and middleware.
  • OVPack v2 and full backup/restore: ov export / ov import now support v2 manifests, file checksums, portable index scalar fields, optional dense vector snapshots, conflict policies, and full pre-write validation. ov backup / ov restore cover full public-scope migration.
  • Native CLI distribution: the new @openviking/cli npm package installs the platform ov binary. Rust CLI release infrastructure now includes Linux musl artifacts, npm trusted publishing, and a broader CLI integration test suite.
  • Codex / OpenCode agent plugins: the Codex memory plugin now uses Codex hooks for recall, capture, and PreCompact commit, and connects directly to OpenViking's native /mcp endpoint instead of a local stdio MCP server. OpenCode plugin examples and install docs were added.
  • Retrieval and filesystem: find / search now support level filters for L0 abstracts, L1 overviews, and L2 file hits. Resource files gained a Phase 1 WebDAV adapter, and observer.filesystem exposes filesystem-level observability.
  • Console and Usage/Audit: a new Usage/Audit module and /api/v1/console/* BFF aggregate token usage, retrieval counts, context commit heatmaps, request audit logs, and context inventory from the existing observability event bus.
  • Storage and concurrency reliability: exact path locks and lifecycle locks were strengthened, content-write races were fixed, blocking backend calls were moved off the event loop, QueueFS SQLite persistence was expanded, and task tracker persistence was added.

New Feature Usage

Install the npm CLI: 

npm i -g @openviking/cli
ov health
ov find "what did I learn about caching?"

Use the LangChain retriever: 

from openviking.integrations.langchain import OpenVikingRetriever

retriever = OpenVikingRetriever(
    url="http://localhost:1933",
    api_key="...",
    target_uri=["viking://user/memories", "viking://resources"],
    search_mode="find",
    limit=6,
)

docs = retriever.invoke("What did the user decide about deployment color?")

Migrate resources, include vector snapshots, and run full backups with OVPack: 

ov export viking://resources/my-project ./exports/my-project.ovpack
ov import ./exports/my-project.ovpack viking://resources/imported/

ov export viking://resources/my-project ./exports/my-project.ovpack --include-vectors
ov import ./exports/my-project.ovpack viking://resources/imported/ --vector-mode auto

ov backup ./backups/openviking.ovpack --include-vectors
ov restore ./backups/openviking.ovpack --on-conflict overwrite --vector-mode auto

Debug vector-index consistency: 

ov system consistency viking://resources/my-project

Limit retrieval by semantic level: 

openviking find "authentication flow" --level 0
openviking search "best practices" -L 1,2

Configure VLM backup and provider-specific request body fields: 

{
  "vlm": {
    "provider": "openai",
    "api_key": "primary-key",
    "model": "gpt-5.4",
    "api_base": "https://api.openai.com/v1",
    "backup": {
      "provider": "volcengine",
      "api_key": "backup-key",
      "model": "doubao-seed-2-0-pro-260215",
      "api_base": "https://ark.cn-beijing.volces.com/api/v3"
    },
    "extra_request_body": {
      "think": false
    }
  }
}

Inspect filesystem observability: 

ov observer filesystem

Improvements

  • storage.agfs.queuefs can now configure mode, backend, db_path, stale recovery, and SQLite busy timeout. QueueFS defaults to SQLite so queue messages can survive process restarts.
  • storage.task_tracker.backend now supports the default single-process memory backend and a persistent backend for multi-instance deployments or restart-surviving task lookup.
  • vlm.backup supports one backup level and fails over only on retryable errors such as rate limits, 5xx, connection failures, and timeouts. Auth, authorization, and billing failures are not retried automatically.
  • vlm.extra_request_body is merged into OpenAI SDK / LiteLLM extra_body, which helps with Ollama, OpenAI-compatible gateways, and provider-specific JSON fields.
  • New Codex plugin deployments should prefer OPENVIKING_* environment variables for tuning. The legacy codex.* block in ov.conf remains supported for compatibility but is no longer the recommended path.
  • OVPack dense vector snapshots require pure dense indexes and compatible embedding provider, model, input, parameters, and dimensions. Incompatible snapshots are recomputed by auto mode or rejected by require mode.

Fixes

  • Fixed concurrent content-write overwrite risk by using exact path locks.
  • Fixed semantic refresh, path lock, and subtree lock concurrency boundaries.
  • Moved blocking backend calls off the event loop to reduce async request stalls.
  • Fixed Memory schema override precedence, child-summary language detection, Codex session-id mapping, and unauthenticated local Codex plugin handling with empty API keys.
  • Fixed QueueFS SQLite payload byte preservation, VikingDB __TOTAL__ count parsing, PDF page-cache release, and ZIP single-root source_name preservation.
  • Fixed repository upload file encryption, runtime logger unification, OpenClaw L2 content recall, and agent memory pipeline reliability issues.

Docs, Tests, and Security

  • Added Chinese and English docs for the Codex memory plugin, OpenCode plugin, LangChain / LangGraph, OVPack, filesystem observer, VLM backup, and task tracker backend.
  • Added CLI integration tests, LangChain/LangGraph unit and integration tests, OVPack import policy tests, Usage/Audit tests, VLM failover tests, and transaction exact path lock tests.
  • Extended CI for Rust CLI builds, npm trusted publishing, API tests, and deduplicated oc2ov coverage.
  • Security-related improvements include encrypted repository upload files, an urllib3 >= 2.7.0 floor, OVPack import validation, and hidden WebDAV access to internal derived files.
Check out latest releases or
releases around volcengine/OpenViking v0.3.17

Don't miss a new OpenViking release

NewReleases is sending notifications on new releases.

Get notifications