github volcengine/OpenViking v0.4.14
on GitHub

latest releases: cli@0.4.14, python-sdk@0.1.8
2 hours ago

OpenViking v0.4.14 Release Notes / 发布说明

Release date / 发布日期: 2026-08-17

Full Changelog / 完整变更记录: [v0.4.13...v0.4.14](v0.4.13...v0.4.14)

This release contains 82 commits. / 本版本包含 82 个提交。

中文

版本概览

v0.4.14 让 viking:// 更接近 Agent 可直接使用的工作区：MCP 新增目录树浏览、文本写入和精确编辑，资源导入扩展到固定 Git commit、私有仓库、飞书云盘目录与文件，Session 则获得事件标签和可更新的自动提交策略。

本版本也收敛了客户端和记忆架构。Python 调用统一迁移到 HTTP SDK，记忆抽取统一使用 V3，Qdrant 和 openGauss 向量后端被移除。升级前请重点阅读“升级与兼容性”。

主要更新

  • Agent 可直接读写 viking://：MCP 新增 tree、write 和 edit。write 支持创建、覆盖和追加，edit 执行精确字符串替换并在匹配不明确时保持文件不变；wait=true 可等待语义和向量索引刷新。当前用户还可以使用 viking://user/... 短路径保存普通文本文件。
  • 可移植 Agent Plugins 1.0 包：新增 agent-plugins/，包含标准清单、零 npm 运行时依赖的 stdio-to-HTTP MCP 代理和 openviking-memory Skill。它适用于遵循 Agent Plugins 1.0、但没有专属 hooks 集成的客户端；自动会话捕获和 prompt 前自动召回不在该规范范围内。
  • 插件生态扩展：新增 DeepSeek Harness（DSH）记忆插件，提供自动召回、Session 捕获、离线重放和模型可调用工具；OpenCode 新增仅 Hooks 模式。Codex、Claude Code、Cursor、OpenClaw、OpenCode、pi、TRAE 和 ZCode 等集成会在 Session commit 日志或确认信息中保留 trace_id。
  • 资源导入与同步增强：OpenViking Assets 支持固定的 40 位 Git commit、显式 to 目标和 HTTPS 私有仓库凭据；普通 add_resource 和 Watch 也支持私有 Git 鉴权。飞书/Lark 导入新增 Drive 文件与递归目录支持。Web Studio 补齐远程资源选项和 Watch 的查看、编辑、暂停、恢复、触发与历史流程。
  • Session 与 Memory 能力收敛：记忆抽取统一走 V3。Session 可在创建时设置事件记忆默认标签，之后通过配置接口更新，并在单次 commit 时覆盖或清空；自动提交策略也可动态更新或禁用。配置 experiences 会一起启用 cases 和 trajectories，且只有实际产生 case 时才继续生成 Agent Evolution 派生记忆。
  • 检索标签与 Agent Evolution 查询：reindex 可用 replace 或 append 模式更新本次成功重建记录的标签。Experience 的 Trajectory 列表和结果分布接口新增 UTC 日期范围过滤。
  • Studio 与管理体验：Web Studio 新增账号删除流程、按作用域分组的 Skill 视图，并改进资源导入和定时同步管理；删除用户时会立即撤销身份，再由持久队列清理用户数据。

新功能用法

把 viking:// 当作 Agent 工作区

以下调用由支持 OpenViking MCP 的 Agent 发起： 

tree(uri="viking://user", level_limit=3, include_abstract=true)
write(uri="viking://user/notes/release.md", content="# Release notes", mode="create", wait=true)
edit(uri="viking://user/notes/release.md", old_string="Release notes", new_string="v0.4.14 notes", wait=true)

设置 Session 事件标签和自动提交

ov session new --session-id s1 --event-tags team=search,channel=web \
  --auto-commit-policy-json '{"message_count_threshold":25}'

ov session config set s1 --event-tags team=search,channel=app
ov session commit s1 --event-tags team=search,channel=web

标签必须是 key=value。使用 ov session commit s1 --no-event-tags 可让本次 commit 不继承 Session 默认标签。

在 Reindex 时更新检索标签

ov reindex viking://resources/docs --mode vectors_only \
  --tag team=search --tag env=prod --tag-mode replace

省略 --tag 会保留已有标签。CLI 不发送空标签数组；需要清空标签时，请通过 HTTP 或 SDK 传 tags: [] 和 tag_mode: "replace"。

固定 Git commit 并指定资源位置

protocol: openviking-assets/1

catalog:
  - name: openviking-v0.4.14
    connector: git
    to: viking://resources/repos/openviking-v0.4.14
    watch_interval: 0
    params:
      repo_url: https://github.com/volcengine/OpenViking
      commit: 6e77291265be8ea29e8d89b19fdd09a5b3100ad0
ov add-resource --manifest manifest.yaml --args dry_run:true
ov add-resource --manifest manifest.yaml

branch 与 commit 互斥，commit 必须是完整的 40 位 SHA。OpenViking Assets 仍是实验性功能。

升级与兼容性

  • Python 嵌入式客户端已移除：OpenViking、SyncOpenViking、AsyncOpenViking、LocalClient 及对应嵌入式实现不再导出。服务端安装 openviking 并独立运行；只需要连接现有服务的应用可单独安装 openviking-sdk： 

    pip install openviking
openviking-server init
openviking-server

# 仅 HTTP 客户端
pip install openviking-sdk
    from openviking_sdk import SyncHTTPClient

client = SyncHTTPClient(url="http://127.0.0.1:1933", api_key="your-key")
client.initialize()

  • Qdrant 和 openGauss 后端已移除：storage.vectordb.backend 当前内置支持 local、cuvs、http、volcengine 和 vikingdb。仍使用 qdrant 或 opengauss 的部署应在升级前迁移数据并修改配置。

  • MinerU 接口切换到官方协议：mineru_endpoint 现在是 base URL，OpenViking 调用 POST {endpoint}/file_parse；mineru_params 改为 mineru_bodys，mineru_api_key 已移除。strategy="mineru" 会在服务初始化时强制检查 {endpoint}/health；strategy="auto" 检查失败时记录警告，并保留本地解析优先的回退行为。

  • Memory V3 成为唯一抽取链路：memory.version 已废弃并被忽略，配置值不会再选择 V2；memory.v2_lock_retry_interval_seconds 和 memory.v2_lock_max_retries 不再受支持。SessionCommit worker 默认并发从 4 调整为 8。

体验与可靠性改进

  • 语义向量化任务改为流式调度，并延迟加载完整 embedding 内容；父目录语义刷新保持异步，降低大批量入库时的内存和队列压力。
  • PathLock 在高竞争时退避重试，并增强 lease handoff、保活和 adopt capability 轮换，减少长任务误失锁。
  • Session 后续归档不再占用 worker 等待前序归档；记忆 patch 移出事件循环，V3 link 更新扩大锁覆盖并报告真实失败的 patch block。
  • MCP Streamable HTTP 改为无状态模式，避免多实例、负载均衡部署中出现间歇性 Session not found。
  • VikingBot compile 在运行超时或迭代上限时尽量保留工作区中的部分产物，并增加运行时 deadline 与输出限制保护。

修复

  • Markdown YAML frontmatter 默认不再从最终正文中静默丢失；强制拆分的 Markdown chunk 保持在 token 预算内，标题锚点与 GitHub 标点处理一致。
  • 超大图片在送入 VLM 或多模态 Embedding 前临时缩放，AGFS 中保存的原始图片不变。
  • L1 overview 现在能进入 Rerank 输入；首次 Session 检索会被正确记录，空检索不再被健康检查误判为故障。
  • OVPack 账号恢复不再删除目标端独有数据；目录移动会完整枚举条目，LocalFS 的 ENOENT 会正确映射为 NotFound，零字节文件不会被误判为缺失索引。
  • Session JSONL 只按换行符拆分，不再把 Unicode 行分隔符当作记录边界；assistant-only event range 会保留正确 owner。
  • Stats、Debug 和 Session 的错误响应现在返回与错误码一致的 HTTP 状态；VikingDB 日期范围会统一规范化，非法写入标签会被丢弃。

文档、测试与安全

  • 新增 Agent Plugins、DSH、DeerFlow、OpenViking Assets、MCP 写入工具、Session 标签和 Agent Evolution 日期过滤文档，并同步中英文 API/配置示例。
  • Agent Plugins 包加入规范一致性测试；DSH 插件覆盖注册结构、捕获、离线队列与可选真实服务召回测试。
  • 私有 Git token 仅允许用于 HTTPS，并与仓库 URL 绑定保存在 Watch 私有状态中，不进入普通队列或 Watch API 输出。未启用 VikingFS 加密时，该服务端控制文件仍包含明文 token 状态。
  • Watch 刷新补齐鉴权校验，服务端 API key 只读副本可通过 store watcher 刷新；过期持久化任务会被清理。

English

Overview

v0.4.14 makes viking:// a more complete agent workspace. MCP can now browse trees, write text, and apply exact edits; resource ingestion supports pinned Git commits, private repositories, and Feishu Drive folders and files; Sessions gain event tags and mutable auto-commit policies.

The release also consolidates the client and memory architecture. Python consumers move to the HTTP SDK, memory extraction always uses V3, and the Qdrant and openGauss vector backends have been removed. Review the upgrade notes before deploying.

Highlights

  • Agent-writable viking:// workspace: MCP adds tree, write, and edit. Writes support create, replace, and append; exact edits leave the file unchanged when the match is missing or ambiguous. wait=true waits for semantic and vector index refreshes, and viking://user/... addresses the authenticated user's workspace.
  • Portable Agent Plugins 1.0 package: the new agent-plugins/ package contains a standard manifest, a zero-runtime-dependency stdio-to-HTTP MCP proxy, and the openviking-memory Skill. It targets conforming clients without a dedicated hooks integration; the specification does not provide automatic session capture or pre-prompt recall.
  • Broader plugin ecosystem: a DeepSeek Harness (DSH) memory plugin adds automatic recall, Session capture, offline replay, and model-callable tools. OpenCode gains a hooks-only mode. Integrations including Codex, Claude Code, Cursor, OpenClaw, OpenCode, pi, TRAE, and ZCode now preserve Session commit trace_id values in logs or user-visible confirmations.
  • Resource ingestion and synchronization: OpenViking Assets supports full pinned Git commit SHAs, explicit to targets, and private HTTPS Git credentials. Regular add_resource and Watch flows support private Git authentication as well. Feishu/Lark ingestion now accepts Drive files and recursive folders. Web Studio adds richer remote import options and complete Watch management flows.
  • Unified Session and Memory behavior: memory extraction now has one V3 path. Sessions can define default event-memory tags, update them later, and override or clear them for one commit; auto-commit policies can also be updated or disabled. Selecting experiences enables cases and trajectories, and Agent Evolution derivatives run only when extraction actually produces a case.
  • Search tags and Agent Evolution queries: reindex can replace or append tags on successfully rebuilt records. Experience trajectory and outcome endpoints accept inclusive UTC date ranges.
  • Studio and administration: Web Studio adds account deletion, scope-grouped Skills, improved resource imports, and scheduled synchronization management. Removing a user now revokes identity immediately and delegates data cleanup to a durable queue.

New Feature Usage

Use viking:// as an agent workspace

These calls are issued by an agent connected to OpenViking MCP: 

tree(uri="viking://user", level_limit=3, include_abstract=true)
write(uri="viking://user/notes/release.md", content="# Release notes", mode="create", wait=true)
edit(uri="viking://user/notes/release.md", old_string="Release notes", new_string="v0.4.14 notes", wait=true)

Configure Session event tags and auto-commit

ov session new --session-id s1 --event-tags team=search,channel=web \
  --auto-commit-policy-json '{"message_count_threshold":25}'

ov session config set s1 --event-tags team=search,channel=app
ov session commit s1 --event-tags team=search,channel=web

Tags must use key=value. Run ov session commit s1 --no-event-tags to skip the Session defaults for one commit.

Update search tags during reindex

ov reindex viking://resources/docs --mode vectors_only \
  --tag team=search --tag env=prod --tag-mode replace

Omitting --tag preserves existing tags. The CLI does not send an empty tag array; use HTTP or an SDK with tags: [] and tag_mode: "replace" to clear tags.

Pin a Git commit and choose its resource target

protocol: openviking-assets/1

catalog:
  - name: openviking-v0.4.14
    connector: git
    to: viking://resources/repos/openviking-v0.4.14
    watch_interval: 0
    params:
      repo_url: https://github.com/volcengine/OpenViking
      commit: 6e77291265be8ea29e8d89b19fdd09a5b3100ad0
ov add-resource --manifest manifest.yaml --args dry_run:true
ov add-resource --manifest manifest.yaml

branch and commit are mutually exclusive, and commit must be a full 40-character SHA. OpenViking Assets remains experimental.

Upgrade Notes

  • Python embedded clients were removed: OpenViking, SyncOpenViking, AsyncOpenViking, LocalClient, and their embedded implementations are no longer exported. Install and run openviking as the server; applications that only connect to an existing server can install the standalone openviking-sdk: 

    pip install openviking
openviking-server init
openviking-server

# HTTP client only
pip install openviking-sdk
    from openviking_sdk import SyncHTTPClient

client = SyncHTTPClient(url="http://127.0.0.1:1933", api_key="your-key")
client.initialize()

  • Qdrant and openGauss backends were removed: built-in storage.vectordb.backend values are now local, cuvs, http, volcengine, and vikingdb. Deployments using qdrant or opengauss must migrate their data and configuration before upgrading.

  • MinerU now uses the official API contract: mineru_endpoint is a base URL and OpenViking calls POST {endpoint}/file_parse; mineru_params becomes mineru_bodys, and mineru_api_key has been removed. strategy="mineru" requires {endpoint}/health to pass during service initialization. strategy="auto" logs a warning on preflight failure and retains local-first fallback behavior.

  • Memory V3 is the only extraction path: memory.version is deprecated and ignored, so it no longer selects V2. memory.v2_lock_retry_interval_seconds and memory.v2_lock_max_retries are no longer supported. The default SessionCommit worker concurrency increases from 4 to 8.

Improvements

  • Semantic vectorization is streamed and full embedding content is materialized later; parent semantic refresh stays asynchronous, reducing queue and memory pressure during large ingestions.
  • PathLock adds contention backoff, lease handoff keepalive, and adopt-capability rotation for safer long-running work.
  • Later Session archives no longer occupy workers while waiting for earlier archives. Memory patch work moves off the event loop, while V3 link updates use broader lock coverage and report the actual failing patch block.
  • MCP Streamable HTTP is stateless, preventing intermittent Session not found failures behind load balancers and multi-instance deployments.
  • VikingBot compile salvages partial workspace output when runtime timeouts or iteration limits are reached, with stronger deadline and output-limit enforcement.

Fixes

  • Markdown YAML frontmatter is no longer silently removed from stored content by default. Forced Markdown chunks stay within the token budget, and heading anchors match GitHub punctuation behavior.
  • Oversized images are temporarily downsampled for VLM and multimodal embedding requests while the original AGFS bytes remain unchanged.
  • L1 overviews now reach Rerank input. First-turn Session recalls are recorded correctly, and empty retrievals are no longer treated as health failures.
  • Account-level OVPack restore preserves target-only data. Directory moves enumerate every entry, LocalFS ENOENT maps to NotFound, and zero-byte files are excluded from index expectations.
  • Session JSONL splits only on newline characters rather than Unicode line boundaries, and assistant-only event ranges retain the correct owner.
  • Stats, Debug, and Session error envelopes now return the matching HTTP status. VikingDB date ranges are normalized consistently, and invalid write-time tags are discarded.

Docs, Tests, and Security

  • Added or refreshed bilingual documentation for Agent Plugins, DSH, DeerFlow, OpenViking Assets, MCP write tools, Session tags, and Agent Evolution date filters.
  • The Agent Plugins package includes specification-conformance tests. The DSH plugin covers registration shape, capture, offline queues, and an optional live-server recall gate.
  • Private Git tokens are restricted to HTTPS and stored in repository-bound private Watch state rather than normal queues or Watch API output. Without VikingFS encryption, that server-side control file still contains plaintext token state.
  • Watch refresh authorization is enforced, read-replica API-key indexes refresh through a store watcher, and expired persisted task records are deleted.
Check out latest releases or
releases around volcengine/OpenViking v0.4.14

Don't miss a new OpenViking release

NewReleases is sending notifications on new releases.

Get notifications