v0.4.10

OpenViking v0.4.10 发布说明

OpenViking v0.4.10 重点增强了资源导入、重建索引、会话持久化、MCP 兼容性、媒体解析、记忆插件写入性能和 usage reporting 能力。本次发版包含较多代码层面的稳定性修复：reindex 会保留内容 owner，可清理孤儿向量；Session commit 的第二阶段改为 QueueFS 持久队列；MCP 对外暴露的 tool schema 更适配严格 function-calling API；Connector 导入、memory plugin 批量写入和 VectorDB 批量 upsert 也都有实质增强。

重点变化

Reindex 与资源一致性

• Reindex 现在会按配置的 VLM 并发数创建 SemanticProcessor，避免维护任务绕过全局并发控制。(#3220)
• Reindex 写回语义和向量记录时会根据目标 URI 切换到内容 owner 上下文，避免 admin 或维护任务把用户资源、memory、skill 的 owner 改写掉。该改动同时为 Python、TypeScript、Go 客户端暴露了 dry_run 参数。(#3096)
• 新增 prune_orphans reindex 模式，可扫描 resource、memory、skill 向量记录，识别源文件、.abstract.md、.overview.md 或 memory chunk 已不存在的孤儿记录，并支持 dry-run 预览待删除数量。(#3096)
• 修复资源 auto-naming 预约失败时吞掉锁竞争/背压错误的问题，避免并发导入时误报为普通命名失败。(#3201)
• 一致性检查拒绝 file:// URI，避免本地文件路径被误用到 VikingFS 资源一致性流程。(#3133)
• 子目录 overview summary 改为批量处理，减少重复生成和队列侧不一致。(#3154)

Connector 导入

• 新增外部 Connector 集成：当 [connector] 开启且 source scheme 命中 allowed_add_types 时，add_resource 可把导入委托给 Connector 的 doc/add 和 task/info 接口。(#3084)
• Connector 导入会创建 connector_import TaskRecord，并在后台轮询 Connector 任务状态，把 succeeded、failed、cancelled、timeout 等状态同步回 OV 任务系统。(#3084)
• 对 tos:// 等 Connector-only source 做了显式校验：Connector 未启用、目标不在 viking://resources/...、wait=true、to= 精确目标、watch、strict、include/exclude 等不支持参数都会提前报错，而不是走标准 pipeline 后再失败。(#3084)

Session、Snapshot 与 Usage Reporting

• Session commit 的 Phase 2 从 asyncio.create_task() 改为 QueueFS 持久队列：归档后写入 session_commit 队列，服务重启后可从 archive 继续执行 memory extraction、relation 写入和 .done/.failed.json 标记更新。(#3254)
• 生成的 session ID 更可读，降低排查和人工操作时只面对随机 ID 的成本。(#3287)
• Session compressor 和 trajectory analyzer 增加来源追踪，snapshot/experience 更新时能保留更明确的来源信息。(#3221)
• 新增可扩展 usage reporter 子系统，支持从 session 消息里的 search_experience、read_experience tool part 提取 memory.recalled、memory.injected 事件，并通过自定义 sink 上报。(#3222)
• Usage reporter 生命周期做了容错：extractor 和 sink 失败不会打断 session commit，sink 写入和关闭都带 timeout。(#3222)

MCP 与 Agent/Plugin 兼容性

• MCP search 类工具新增 context_type filter，客户端可直接按 resource、memory、skill 等上下文类型筛选。(#3181)
• MCP 对外 advertised tool schema 会被重写成 plain-typed schema：内联 $ref、移除 anyOf/$defs、去掉 null 分支，并确保每个 schema node 都有显式 type，以兼容 Gemini、n8n 等严格 function-calling/OpenAPI 子集。运行时参数校验仍保留原函数签名能力。(#3288)
• OpenClaw 插件恢复 peer_role 路由，区分消息归属 peer 与请求 actor peer，修复 assistant/person 模式下消息和数据面请求都被路由成同一身份的问题。(#3252)
• PI coding agent 的 recall 改为先排队再异步查询，避免用户消息渲染被 recall 请求阻塞。(#3233)
• Codex memory plugin 的 type-quota recall 结果支持压缩：从 endpoint entries 中构造待压缩 item，必要时回退 digest，减少注入上下文过长的问题。(#3248)
• Memory plugins 新增共享 async-writer 和 batch-send，Claude Code、Codex、OpenCode、Cursor、Trae 等插件可批量调用 /messages/batch，失败时按连续前缀入 pending queue，避免中间消息丢失。(#3261)

Bot 体验

• VikingBot 默认启用 OpenViking session context，并把默认保留最近消息数从 5 调整为 10。(#3236)
• Bot 从 OV 拉取历史时会按 token budget 裁剪，避免大量 tool output 把 prompt 撑爆；裁剪后的消息会带截断提示。(#3236)
• Bot 现在会保存中间 assistant turn 及其 tool calls/results，并在同步到 OV 时拆成结构化 text/tool parts，而不是只把最终回答和扁平 tools_used 写入。(#3236)
• Bot 请求依赖兼容 chardet 7，并增加依赖兼容性测试。(#3282)

媒体解析与检索/rerank

• 解析器新增 AC-3 音频支持：补充 audio/ac3 MIME 映射、.ac3 扩展名、AC-3 magic bytes，并把 AC-3 纳入音频 parser 支持列表。(#3229)
• 多模态资源集成测试覆盖图片、音频、视频、文档等 31 个导入 case，便于用真实 OpenViking 服务验证端到端解析和队列处理。(#3229)
• 媒体向量化扩展名与 parser 支持范围同步，补齐 .mkv、.webm、.ogg、.m4a、.opus、.ac3 等格式识别。(#3241)
• 空文档 rerank 场景保留 fallback，避免 hierarchical retriever 因空内容丢掉原始检索结果。(#3231)
• Recall 结果隐藏 memory fields metadata，减少内部字段泄露到最终上下文。(#3240)
• Retrieval observer 统计聚合检索 yield 时会把 aggregate retrieval 也计入，修正观测数据偏差。(#3158)
• LiteLLM rerank 兼容 Voyage：documents 改为传 plain string list，并兼容 dict/object 两种 result item 结构，避免 Voyage 400 或 rerank silently no-op。(#3291)

VectorDB 与 Benchmark

• VectorDB 后端新增 upsert_many 批量写入路径，批量校验 account、context_type、重复 ID 和返回 ID 顺序，再通过一次 adapter upsert 调用写入完整记录。(#3264)
• VectorDB benchmark ingestion 从逐条 upsert 改为批量 upsert，并在 benchmark 事件中标记 upsert_rows_batch。(#3264)
• WIKI-Dir benchmark 支持加载 corpus path mapping，区分 base queries 和 directory queries，并增加 query scope/path diagnostics，避免缺少目录约束时跑出 root-only 的误导性 Directory benchmark。(#3279)

文档、测试与清理

• 新增 sales-opportunity-order-builder agent skill 文档，覆盖销售机会转订单的 DSL 生成流程。(#3227)
• 移除自动 pre-commit hooks 相关配置与贡献文档说明，避免本地提交流程被自动 hook 绑定。(#3228)
• OC2OV 测试在 OpenClaw CLI 输出为空时 fail fast，并补充诊断工具，减少空输出导致的误判。(#3250)
• Trusted admin target 允许 root key 访问，并补充认证测试。(#3249)
• 优化 preferences/profile memory prompt 模板，使生成内容更稳定。(#3242)
• 移除 embedding 中未使用的 batch APIs，清理多个 provider embedder 的废弃批量入口和相关测试。(#3260)
• 大规模清理未使用和已废弃 API，包括旧 bot channel、watch manager、旧 parse/accessor、旧 telemetry、部分 vectordb project/validation、setup wizard、redo log 等代码路径。(#3272)
• Trace 文档补充本地 trace 文件路径、产生和上传排查说明，并新增离线 trace 上传脚本。(#3263)

新贡献者

感谢以下新贡献者首次参与 OpenViking：

• @WeiJiacheng271：#3227
• @pppobear：#3233
• @zihengli-bytedance：#3084
• @michaeltarleton：#3291

完整变更

完整 Changelog：

v0.4.9...v0.4.10

What's Changed

• Add sales-opportunity-order-builder skill under docs/images/agents/skills by @WeiJiacheng271 in #3227
• chore: remove automatic pre-commit hooks by @qin-ctx in #3228
• fix(reindex): honor configured VLM concurrency by @huangruiteng in #3220
• feat: track trajectory sources and snapshot experience updates by @heaoxiang-ai in #3221
• feat(parse): support AC-3 audio resources and add multimodal integration tests by @Hao-Yu-la in #3229
• fix(resource): preserve lock contention during auto-naming by @huangruiteng in #3201
• fix(mcp): expose context_type filter by @huangruiteng in #3181
• fix(observer): account for aggregate retrieval yield by @huangruiteng in #3158
• fix: batch child directory overview summaries by @huangruiteng in #3154
• fix: reject file URI for consistency check by @huangruiteng in #3133
• fix(retrieve): preserve rerank fallback for empty documents by @huangruiteng in #3231
• fix: sync media vectorization extensions by @Hao-Yu-la in #3241
• feat(bot): Opt doc add workspace desc, change the type of messages appended to ov by @yeshion23333 in #3236
• fix(recall): hide memory fields metadata by @huangruiteng in #3240
• Fix/reindex preserve owners by @zhoujh01 in #3096
• test(oc2ov): fail fast on empty OpenClaw output by @huangruiteng in #3250
• fix(auth): allow root key on trusted admin targets by @huangruiteng in #3249
• preferences/profile template improvement by @fujiajie666 in #3242
• fix(pi): avoid blocking user message rendering on recall by @pppobear in #3233
• fix(codex): compress type-quota rec...

v0.4.9

中文/English

版本概览

v0.4.9 扩展了 OpenViking 的智能体接入与多模态检索能力：新增 Cursor、TRAE 和 TRAE CN 记忆集成，完善 OpenCode 与 pi 的自动召回、捕获和上下文接管，并支持以图片作为 find / search 查询。VikingBot 现在可通过统一网关接入 OpenViking 认证与路由；cuVS 后端则补充了并发、过滤、后台重建、显存控制和遥测优化。

主要更新

更多智能体记忆集成

• 新增 Cursor 集成：安装器一次配置生命周期 Hooks、MCP、Rule 和 memory Skill，实现会话启动与请求前召回、响应后捕获。
• 新增 TRAE 与 TRAE CN 集成：支持 SessionStart、UserPromptSubmit、PreToolUse 和 Stop Hooks，在短会话结束时也会立即提交记忆。
• OpenCode 插件升级为 MCP 与生命周期 Hooks 的混合模式，支持仓库上下文、自动召回、会话捕获和共享凭证配置。
• pi 扩展新增上下文接管：在达到 Token 阈值后将已提交历史替换为 OpenViking 归档概览，同时保留最近对话；失败时保留本地历史或使用 pi 默认压缩。
• Claude Code、Codex、OpenCode 和 pi 共享记忆插件核心模块与统一安装器。
• 工作区默认可派生独立 peer；可通过 OPENVIKING_PEER_ID 指定 peer，或使用 recallPeerScope: "actor" 将召回限制为全局记忆与当前工作区。

图片检索

• find 与 search 支持本地文件、字节、Data URI、HTTP(S) URL 和 viking:// URI 图片查询。
• CLI 新增 --image，Python 与 Go SDK 同步支持图片输入。
• 图片查询默认检索目标范围内的 L2 资源叶子节点；结果可包含与图片语义相关的文本或图片资源。
• 文本与图片可以组合查询；search 收到图片时会走直接图片检索并跳过会话查询规划。

VikingBot 统一网关与认证

• openviking-server --bot 可随 OpenViking Server 启动 VikingBot 网关；--with-bot 可将 Bot API 代理到已运行的 VikingBot。
• ov chat 默认从 ovcli.conf 的 url 推导 <url>/bot/v1，并复用 API Key、peer 与额外请求头配置。
• 新增独立的 gateway_token / X-Gateway-Token，避免网关凭证混入上游 OpenViking 请求头。
• 网关会校验 OpenViking 的实际认证模式。公开监听必须配置网关 Token；dev 模式仅允许网关与 OpenViking 都位于 localhost。

cuVS 性能与可观测性

• 新增不可变 GPU 快照、每线程 cuVS resources/CUDA streams，以及可配置的 max_concurrent_gpu_searches。
• 支持显式 float16 GPU 数据与查询，降低设备侧向量占用；默认仍为 float32。
• 自动模式可按显存预算、过滤候选数和索引状态回退到原生索引，并在多 collection 间协调同一 GPU 上的构建准入。
• 可选后台重建会合并连续写入，构建期间查询使用原生索引，完成后原子切换 GPU 快照。
• 缓存过滤位图和原生路由决定，并新增 cuVS 路由、缓存、构建、显存与分阶段耗时遥测。

新功能用法

升级

pip install -U openviking==0.4.9
npm i -g @openviking/cli

安装 Cursor 或 TRAE 记忆集成

# Cursor
bash <(curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/memory-plugin-shared/install.sh) \
  --harness cursor

# TRAE 与 TRAE CN
bash <(curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/memory-plugin-shared/install.sh) \
  --harness trae,trae-cn

安装后请完全退出并重启对应客户端。OpenCode 与 pi 可分别使用 --harness opencode 和 --harness pi。

使用图片检索

# 本地图片
openviking find --image ./query.png \
  --uri "viking://resources/images" --limit 5

# 文本与图片组合
openviking search "相似的红色海报" --image ./poster.png \
  --uri "viking://resources/images"

import openviking as ov

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

results = client.find(image="/path/to/query.png")

图片查询需要多模态 Embedding 模型。现有图片资源不会自动重算向量，需要重新索引后才能使用图片向量召回。

启动 VikingBot 网关并对话

openviking-server --config ~/.openviking/ov.conf --bot
ov chat

当网关监听非本地地址时，在 ov.conf 的 bot.gateway.token 与 ovcli.conf 的 gateway_token 中配置相同凭证。OpenViking 使用 api_key 模式时，VikingBot 的记忆与文件工具需要 User/Admin API Key；ROOT API Key 不能代替它访问数据 API。

启用 cuVS 后台重建与 float16

{
  "storage": {
    "vectordb": {
      "backend": "local",
      "cuvs": {
        "auto_enable": true,
        "dtype": "float16",
        "max_concurrent_gpu_searches": 1,
        "auto_background_rebuild": true,
        "auto_rebuild_debounce_ms": 500
      }
    }
  }
}

cuVS 仍为可选能力，默认本地 CPU 后端不变。cuVS 26.06 wheel 需要 Python 3.11 或更高版本；并发数、重建延迟和 float16 应根据目标 GPU、召回率与工作负载实测调整。

体验与兼容性改进

• OpenViking Helper Beta 新增 Windows x64 支持，并更新 macOS 安装包。
• 用户技能与智能体技能检索改为并行执行，降低组合搜索延迟。
• OpenViking CLI 的聊天界面改进连接信息、认证告警、双语提示和错误展示。
• Grafana + Prometheus 运维指南新增完整英文版；cuVS 文档补充自动路由、显存、并发与遥测说明。
• litellm 依赖范围更新为 >=1.83.7,<1.91.2。

修复

• 修复上游模型认证失败被 CLI 错报为 OpenViking API Key 错误的问题；多凭证场景中，部分凭证认证失败时仍允许可重试凭证继续故障转移。
• 修复带签名参数的视频 URL 解析路由，以及扩展名标记错误的 OOXML Word 文件路由。
• 修复 memory Markdown 链接重复嵌套与含空格目标路径的问题。
• 修复 OpenClaw 会话消息缺少 peer_id，以及 Agent memory 被错误写入 peer 范围的问题。
• 修复 VikingDB 与本地向量库字段差异：仅 VikingDB 后端写入 content 字段。
• 修复 Windows 11 上 platform.machine() 为空时的向量引擎选择与初始化循环导入问题。
• 修复本地 collection 懒加载并发竞争，并让 benchmark 严格遵守配置的搜索并发数。
• 修复 Slack 与 Email 通道缺少 sender_name，以及缺少 ovcli identity 时 VLM-only 配置被丢弃的问题。

文档、测试与安全

• Git 仓库解析不再递归克隆 submodule，防止恶意 submodule URL 触发 SSRF；Git 错误输出也不再暴露完整命令参数。
• 新增并扩充图片检索、cuVS、VikingBot 认证、Cursor/TRAE Hooks、共享安装器、peer 隔离、解析器和发布流程测试。
• 组件发布工作流相互隔离，并新增 controlplane MCP 的 PyPI 发布工作流。

---

English

Overview

OpenViking v0.4.9 expands agent integrations and multimodal retrieval. It adds memory integrations for Cursor, TRAE, and TRAE CN; upgrades OpenCode and pi with automatic recall, capture, and context takeover; and lets find and search use images as queries. VikingBot gains unified gateway routing and OpenViking authentication, while the cuVS backend receives concurrency, filtering, background rebuild, memory-admission, and telemetry improvements.

Highlights

More agent memory integrations

• New Cursor integration installs lifecycle Hooks, MCP, a Rule, and a memory Skill for recall before requests and capture after responses.
• New TRAE and TRAE CN integrations use SessionStart, UserPromptSubmit, PreToolUse, and Stop Hooks, including immediate commit for short completed sessions.
• The OpenCode plugin now combines MCP tools with lifecycle Hooks for repository context, automatic recall, session capture, and shared credentials.
• The pi extension adds context takeover: committed local history can be replaced by an OpenViking archive overview after a token threshold while recent turns remain live. Failure paths retain local history or pi's normal compaction.
• Claude Code, Codex, OpenCode, and pi now share memory-plugin modules and one installer.
• Workspaces can derive distinct peers by default. Use OPENVIKING_PEER_ID for an explicit peer or recallPeerScope: "actor" to restrict recall to global memory plus the current workspace.

Image retrieval

• find and search accept local files, bytes, Data URIs, HTTP(S) URLs, and viking:// image URIs.
• The CLI adds --image, with corresponding Python and Go SDK support.
• Image queries search L2 resource leaves in the target scope by default; multimodal similarity may return related text or image resources.
• Text and image can be combined. When search receives an image, it performs direct image retrieval and skips session query planning.

Unified VikingBot gateway and authentication

• openviking-server --bot starts the VikingBot gateway with OpenViking Server; --with-bot enables the Bot API proxy for an already running VikingBot.
• ov chat derives <url>/bot/v1 from ovcli.conf and reuses its API key, peer, and extra-header settings.
• A separate gateway_token / X-Gateway-Token keeps gateway credentials out of upstream OpenViking headers.
• The gateway validates the effective OpenViking authentication mode. Public listeners require a gateway token, and dev mode is limited to localhost on both sides.

cuVS performance and observability

• Immutable GPU snapshots, per-thread cuVS resources/CUDA streams, and configurable max_concurrent_gpu_searches improve concurrency control.
• Explicit float16 GPU datasets and queries reduce device vector storage; float32 remains the default.
• Auto mode can fall back to the native index based on memory budget, filter candidate count, and index state, with per-GPU build admission across collections.
• Optional background rebuild coalesces mutations, serves dirty queries through the native index, and atomically installs the completed GPU snapshot.
• Filter bitsets and native-routing decisions are cached, with new cuVS route, cache, build, memory, and stage-timing telemetry.

New Feature Usage

Upgrade

pip install -U openviking==0.4.9
npm i -g @openviking/cli

Install Cursor or TRAE memory integration

# Cursor
bash <(curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/memory-plugin-shared/install.sh) \
  --harness cursor

# TRAE and TRAE CN
bash <(curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/memory-plugin-shared/install.sh) \
  --harness trae,trae-cn

Quit and restart the client after installation. OpenCode and pi use --harness opencode and --harness pi, respectively.

Search by image

# Local image
openviking find --image ./query.png \
  --uri "viking://resources/images" --limit 5

# Combined text and image query
openviking search "similar red poster" --image ./poster.png \
  --uri "viking://resources/images"

import openviking as ov

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

results = client.find(image="/path/to/query.png")

Image queries require a multimodal embedding model. Existing image resources keep their old vectors and must be reindexed before image-vector recall can find them.

Start the VikingBot gateway and chat

openviking-server --config ~/.openviking/ov.conf --bot
ov chat

For a non-loopback gateway, configure the same credential in bot.gateway.token in ov.conf and gateway_token in ovcli.conf. In OpenViking api_key mode, VikingBot memory and file tools require a User/Admin API key; a ROOT API key cannot replace it for data API access.

Enable cuVS background rebuild and float16

{
  "storage": {
    "vectordb": {
      "backend": "local",
      "cuvs": {
        "auto_enable": true,
        "dtype": "float16",
        "max_concurrent_gpu_searches": 1,
        "auto_background_rebuild": true,
        "auto_rebuild_debounce_ms": 500
      }
    }
  }
}

cuVS remains opt-in and the default local CPU backend is unchanged. cuVS 26.06 wheels require Python 3.11 or newer. Tune concurrency, rebuild delay, and float16 only aft...

python-sdk@0.1.4: fix(reindex): honor configured VLM concurrency (#3220)

Co-authored-by: huangruiteng <huangruiteng@bytedance.com>

cli@0.4.9: fix(reindex): honor configured VLM concurrency (#3220)

Co-authored-by: huangruiteng <huangruiteng@bytedance.com>

v0.4.8

OpenViking v0.4.8 Release Notes / 发布说明

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

Full Changelog / 完整变更记录: v0.4.7...v0.4.8

---

中文

版本概览

v0.4.8 是一次偏工程能力和稳定性的发布：新增 NVIDIA cuVS GPU 向量检索后端，重做普通网页导入为可控的递归爬取，默认切到 v3 记忆抽取与流式 patch-merge 更新，并整理 Codex / Claude Code 记忆插件的远程 marketplace 安装和 stdio MCP 代理。

这版也包含一批面向生产使用的修复：CLI 不再把远端网页 401/403 报错误判成本地 API Key 错误，RAGFS glob 语义和分页下推到后端，OVPack 导入导出权限放宽到普通用户可用，Feishu、OpenClaw、Web Studio、VikingBot 和文档接入都有跟进。

主要更新

• cuVS GPU 向量检索后端：新增 storage.vectordb.backend = "cuvs"，支持 cuVS brute-force 精确检索和 CAGRA 近似检索；也可以在 backend = "local" 下启用 cuvs.auto_enable，让系统在 GPU 内存足够时自动使用 cuVS，否则回退到原生 CPU 索引。
• 递归网页导入：普通网页导入改为 Scrapy 驱动的同站 BFS 爬取，支持 depth、max_pages、include_paths、exclude_paths、allow_external_links、skip_download_links；正文抽取切换到 trafilatura，并保留 sitemap/RSS 的整站导入路径。
• 记忆 v3 与训练框架：OpenViking 现在始终使用 v3 记忆抽取链路；新增流式记忆更新器，将并发提交按 peer 和 memory type 分组合并，再用 patch-merge 应用。cases、trajectories、experiences 可以参与 session train 流程，Tau2 train/eval 也有专门入口。
• Codex / Claude Code 记忆插件：插件安装支持远程 marketplace；stdio MCP proxy 直接读取 ~/.openviking/ovcli.conf 或 OPENVIKING_* 环境变量，不再需要渲染带 URL 和 header 的 .mcp.json。Codex 与 Claude Code 共享安装器和一批核心脚本。
• VikingBot 简化和子 Agent：openviking[bot] 现在包含原来分散在 bot extras 里的能力；bot.agents.thinking 配置已文档化，subagent_enabled 可开关 spawn 工具，子 Agent 的上下文、技能和结果投递也更稳。
• RAGFS / 文件系统改进：glob 下推到 Rust 后端并分页返回，LocalFS/S3FS/MountableFS 都支持稳定结果；目录列表改为目录优先再按名称排序；移动、加密、S3、锁和目录操作的边界也做了修复。
• OpenViking Helper for macOS beta：README 增加 macOS 桌面端下载说明，用于本地 Agent 接入检测、会话轨迹检查、记忆和技能同步。

新功能用法

启用 cuVS 精确检索：

pip install -e .
pip install cuvs-cu12 'cupy-cuda12x[ctk]' --extra-index-url=https://pypi.nvidia.com
python examples/cuvs_smoke.py

{
  "storage": {
    "workspace": "/data/openviking",
    "vectordb": {
      "backend": "cuvs",
      "distance_metric": "cosine",
      "cuvs": {
        "algorithm": "brute_force",
        "fallback_to_native": true,
        "filter_cache_size": 16
      }
    }
  }
}

在默认本地后端上启用内存感知的 cuVS auto mode：

{
  "storage": {
    "vectordb": {
      "backend": "local",
      "cuvs": {
        "auto_enable": true,
        "algorithm": "brute_force",
        "auto_memory_reserve_mb": 1024,
        "auto_filter_native_threshold": 2000,
        "auto_path_filter_native_threshold": 200
      }
    }
  }
}

递归导入网页：

ov add-resource "https://docs.openviking.ai/getting-started/01-introduction" \
  --args="depth:1,max_pages:10"

ov add-resource "https://docs.openviking.ai/" \
  --args='{"depth":2,"max_pages":50,"include_paths":["/docs/"],"exclude_paths":["/changelog"]}'

从 Codex 远程 marketplace 安装记忆插件：

codex plugin marketplace add volcengine/OpenViking
codex plugin add openviking-memory@openviking

运行 Tau2 VikingBot train/eval：

bash benchmark/tau2/train/restart_vikingbot_train_eval.sh \
  --epochs 2 \
  --trials 8 \
  --train-trials 1 \
  --skip-final-eval

体验与兼容性改进

• cuVS 是 opt-in；默认 local CPU 索引不变。显式 backend = "cuvs" 会保留 fail-fast 行为，auto_enable 模式才会按 GPU 内存和过滤候选规模回退到 native。
• cuVS Python wheel 要求 Python 3.11+，并需要匹配 CUDA 主版本的 cuvs-cu12 或 cuvs-cu13 包。
• memory.version 已废弃且会被忽略；旧配置仍可加载，但实际总是使用 v3 记忆抽取。
• openviking[bot-full]、openviking[bot-langfuse]、openviking[bot-feishu] 等旧 bot extras 已合并到 openviking[bot]。安装脚本和部署文档应改为安装 openviking[bot]。
• glob 现在使用标准的相对路径匹配语义。只匹配当前目录用 *.md，递归匹配用 **/*.md。
• 普通网页导入默认跳过页面里的下载链接，避免把 llms.txt、PDF 等旁路文件意外导入；需要时设置 skip_download_links=false。
• OpenClaw 插件要求提升到 OpenClaw 2026.5.27。

修复

• CLI 在服务器包装远端抓取 401/403 为 5xx 时，不再误报 “OpenViking rejected the API key”；403 报错也改为更接近访问限制或反爬场景的提示。
• CLI 表格输出保留混合结果中的 status、root_uri、task_id 和 warnings 等字段。
• reindex 不再为 memory body 额外生成 chunk 向量，避免记忆检索出现重复或偏离当前 v3 结构的记录。
• Feishu 导入会持久化文档图片，并且权限错误会被更清晰地展示。
• Web crawler 删除 Playwright 渲染路径，robots.txt 拒绝时给出合规提示。
• OpenClaw 插件支持 config headers，并修复安装 manifest、setup probe 和请求头相关契约。
• Web Studio 的身份健康探测、会话排序、用量面板和 request logs 有多处修复。
• VikingDB api_key 模式信任 OpenViking schema，避免 schema 推断问题。

文档、测试与安全

• 新增 cuVS 配置文档、GPU 内存说明、benchmark README、collection/service benchmark、初步结果和 post-merge 回归守卫。
• 更新 Codex、Claude Code、MCP Clients、OpenCode、community plugins、TOS 安装和 agent authentication 文档。
• 增加 recursive web crawler、trafilatura HTML 抽取、Feishu 图片、type-quota recall、streaming memory updater、compressor v3、Tau2 train/eval、RAGFS glob、cuVS backend 等测试。
• 新增 VikingDB content backfill 维护脚本，用于从本地 AGFS 回填 VikingDB content 字段。

---

English

Overview

v0.4.8 focuses on GPU vector search, safer web ingestion, the v3 memory pipeline, and cleaner agent-plugin installation. It adds an opt-in NVIDIA cuVS vector backend, recursive web crawling for ordinary pages, streaming patch-merge memory updates, Codex / Claude Code remote marketplace install paths, and backend-paged filesystem glob.

The release contains 43 first-parent commits since v0.4.7.

Highlights

• NVIDIA cuVS vector backend: storage.vectordb.backend = "cuvs" supports cuVS brute-force exact search and CAGRA approximate search. cuvs.auto_enable can keep the default local backend while using idle GPU memory when it is safe to do so.
• Recursive web crawler: ordinary web-page imports now support bounded same-host BFS through Scrapy, with depth, max_pages, path-prefix filters, optional external links, and download-link skipping. HTML extraction now uses trafilatura.
• Memory v3 and train/eval: OpenViking always uses the v3 memory extraction pipeline. Concurrent commits can batch through the streaming memory updater, then merge by peer and memory type. Extracted cases, trajectories, and experiences can feed the session training framework and Tau2 train/eval pipeline.
• Agent memory plugins: Codex and Claude Code plugins can be installed from remote marketplaces. Their stdio MCP proxy reads ovcli.conf or OPENVIKING_* at runtime, so MCP tools and hooks share one credential chain.
• VikingBot cleanup: openviking[bot] now includes the previous optional bot features, bot.agents.thinking is documented, and subagent_enabled controls the spawn tool.
• Filesystem and RAGFS: glob is delegated to backends with pagination, standard relative-path semantics, stable ordering, and directory-first listing.
• OpenViking Helper beta: README now links the macOS desktop helper for local agent setup inspection, session trace review, and local memory/skill sync.

New Feature Usage

Enable cuVS exact search:

pip install -e .
pip install cuvs-cu12 'cupy-cuda12x[ctk]' --extra-index-url=https://pypi.nvidia.com
python examples/cuvs_smoke.py

{
  "storage": {
    "workspace": "/data/openviking",
    "vectordb": {
      "backend": "cuvs",
      "distance_metric": "cosine",
      "cuvs": {
        "algorithm": "brute_force",
        "fallback_to_native": true,
        "filter_cache_size": 16
      }
    }
  }
}

Use memory-aware cuVS auto mode with the default local backend:

{
  "storage": {
    "vectordb": {
      "backend": "local",
      "cuvs": {
        "auto_enable": true,
        "algorithm": "brute_force",
        "auto_memory_reserve_mb": 1024,
        "auto_filter_native_threshold": 2000,
        "auto_path_filter_native_threshold": 200
      }
    }
  }
}

Recursively import web pages:

ov add-resource "https://docs.openviking.ai/getting-started/01-introduction" \
  --args="depth:1,max_pages:10"

ov add-resource "https://docs.openviking.ai/" \
  --args='{"depth":2,"max_pages":50,"include_paths":["/docs/"],"exclude_paths":["/changelog"]}'

Install the Codex memory plugin from the remote marketplace:

codex plugin marketplace add volcengine/OpenViking
codex plugin add openviking-memory@openviking

Run Tau2 VikingBot train/eval:

bash benchmark/tau2/train/restart_vikingbot_train_eval.sh \
  --epochs 2 \
  --trials 8 \
  --train-trials 1 \
  --skip-final-eval

Improvements

• cuVS remains opt-in. The default local CPU backend is unchanged; only auto mode falls back by GPU-memory and filtered-candidate heuristics.
• cuVS Python wheels require Python 3.11+ and the CUDA-matched cuvs-cu12 or cuvs-cu13 package.
• memory.version is deprecated and ignored. Existing configs still load, but extraction always uses v3.
• Old bot extras such as openviking[bot-full], openviking[bot-langfuse], and openviking[bot-feishu] are folded into openviking[bot].
• glob now uses standard full-relative-path matching. Use *.md for the current directory and **/*.md for recursive matches.
• Ordinary web imports skip download links by default; set skip_download_links=false to fetch same-host files linked from pages.
• OpenClaw plugin support now requires OpenClaw 2026.5.27.

Fixes

• The CLI no longer reports remote page 401/403 fetch failures wrapped in server 5xx responses as local API-key failures.
• CLI table output preserves scalar fields when a response also contains warning lists.
• Reindexing memory records no longer generates extra body chunks.
• Feishu imports persist document images and surface permission errors clearly.
• The web crawler removed the Playwright rendering path and gives clearer robots.txt denial guidance.
• OpenClaw plugin setup, config headers, install manifests, and probe contracts were tightened.
• Web Studio health identity probes, session sorting, usage panels, and request logs received follow-up fixes.
• VikingDB api_key mode now trusts the OpenViking schema.

Docs, Tests, and Security

• Added cuVS docs, GPU memory notes, benchmark harnesses, preliminary results, and post-merge regression guards....

v0.4.7

v0.4.7 发布概要

本次发布继续围绕 Agent 集成、MCP 本地文件链路、存储与多版本管理可靠性、Bot/OpenClaw 兼容性、Web Studio 配置体验和生产可运维性做增强。

重点更新

• MCP 与本地文件集成增强：MCP 新增 compact description mode，降低工具描述带来的上下文 token 开销；本地文件上传支持通过签名 temp_upload token 自动入库，让 MCP 客户端处理本地文件更顺滑。
• Agent / Bot / OpenClaw 生态改进：Codex 插件增强 upstream marketplace 安装与 recall 稳定性；OpenClaw tool parts 现在会以 assistant messages 形式保存；Bot 增加超时配置，并修复飞书主动消息 metadata、工具调用顺序、thinking mode 和图片上传等问题。
• 存储、加密写入与 QueueFS 稳定性：加密写入改为 temp-file publish + 双路径锁保护，并进一步优化 temp-write 元数据开销；QueueFS 修复 sidecar、图片 rewrite 等路径的锁复用问题，挂载时跳过控制插件缓存；delete/write-protected root 的移动和删除保护语义进一步对齐。
• 文件系统与多版本管理能力扩展：新增 filesystem attrs 元信息接口；多版本管理支持账号级 .ovgitignore 风格忽略规则，并修复 git 多版本接口中的路径问题；session no-op commit 现在会明确标记为 skipped。
• SDK 与 API Surface 补齐：Go SDK 暴露 target_uri skill scoping，并支持 grep level_limit 控制遍历深度；认证新增 seeded API key 生成；OAuth DCR client scope 会持久化，修复 MCP client invalid_scope 问题。
• 模型、Embedding 与指标修复：Volcengine 模型请求会正确转发 headers；VLM 请求会省略未设置的默认 max_tokens；Embedding 鉴权错误不再无限重入队；零结果检索不再对 RESULTS_TOTAL 做无意义的 0 增量。
• Web Studio 与初始化体验：Web Studio 重新设计 Connection & Identity 设置页，并将 assumed account 固定到 admin key 所属账号；初始化流程新增 TUI 风格 setup wizard，可分别配置 embedding 与 VLM。
• 文档与社区更新：同步 legacy agent_id 迁移行为说明，补充 bot agents.thinking 配置文档，README 增加 OpenViking Studio 在线 demo 链接，并更新微信群二维码。

升级说明

• 使用 MCP 客户端、本地文件上传或 OpenClaw/Bot 集成的用户建议升级，以获得更低上下文开销、更稳定的文件入库和更完整的消息保存语义。

• 使用火山引擎向量库作为后端时，需要在向量库 schema 中新增字段：

  {"FieldName": "content", "FieldType": "text"}
  {"FieldName": "search_tags", "FieldType": "list<string>"}

• 使用多版本管理的部署可以开始使用账号级 .ovgitignore 规则控制 commit 范围。

• 依赖 OAuth MCP client、Embedding 队列、加密存储或 QueueFS cache 的生产环境建议升级，相关路径包含多项可靠性修复。

• 使用 Web Studio 管理身份和连接的用户升级后会看到新的 Connection & Identity 页面。

New Contributors

• @lg320531124
• @dfwgj
• @xiaochen-zhou

Full Changelog: v0.4.6...v0.4.7

What's Changed

• feat(server): add user add target defaults by @qin-ctx in #2888
• feat(mcp): add compact description mode to reduce context token overhead by @lg320531124 in #2853
• fix(codex): support upstream marketplace install and robust recall by @LinQiang391 in #2879
• docs(codex): revert #2879 doc changes; demote marketplace install to local-only by @t0saki in #2901
• feat(ingest): replay local agent-harness logs into OpenViking sessions by @t0saki in #2892
• fix(storage): honor delete-protected roots on mv source (parity with #2873) by @r266-tech in #2898
• feat(sdk/go): expose target_uri skill scoping (parity with #2813) by @r266-tech in #2897
• chore(opencode-plugin): scope package and bump to 0.1.6 by @ZaynJarvis in #2895
• docs(migration): sync legacy agent_id behavior after #2839 by @r266-tech in #2861
• fix: opencode plugin package targets by @ZaynJarvis in #2851
• feat(web-studio): redesign connection & identity settings by @ZaynJarvis in #2896
• fix(bot): Check workspace path restriction, include agent path and config path by @yeshion23333 in #2908
• fix(web-studio): pin assumed account to admin key's own account by @ZaynJarvis in #2910
• Generate resource L0 summaries from overview prompt by @heaoxiang-ai in #2890
• feat(bot):Add timeout config by @yeshion23333 in #2917
• feat(encrypt): Protect encrypted writes with temp-file publish and dual-path locking by @baojun-zhang in #2894
• feat(fs): 新增 attrs 元信息接口 by @qin-ctx in #2906
• fix(volcengine): forward model request headers by @qin-ctx in #2909
• fix(storage): block deleting the write-protected viking://agent root (parity with #2873) by @r266-tech in #2914
• feat(sdk/go): expose grep level_limit to control traversal depth by @r266-tech in #2915
• Feat/understand api queue by @chenxiaobin-lang in #2889
• fix(bot): preserve Feishu delivery metadata for proactive messages by @yeshion23333 in #2924
• feat(mcp): auto-ingest local-file uploads via signed temp_upload token by @t0saki in #2925
• fix(session): mark no-op commits as skipped by @qin-ctx in #2931
• Store OpenClaw tool parts as assistant messages by @wlff123 in #2934
• feat(auth): support seeded API key generation by @qin-ctx in #2932
• feat(encrypt):reduce encrypted temp-write metadata overhead by caching(url) temp-root readiness and turning the temp-file path into TTL fast path + NotFound fallback + AlreadyExists cleanup . by @baojun-zhang in #2933
• feat: support ignoring certain files in the multi-version management function, similar to the git ignore feature by @Hao-Yu-la in #2930
• WeChat QR code update by @Lumos088 in #2942
• fix(metrics): stop incrementing RESULTS_TOTAL by 0 on zero-result retrievals (#2922) by @r266-tech in #2940
• fix(embedding): stop re-enqueueing auth errors forever (#2916) by @khou in #2919
• fix(bot): Tool-call ordering, thinking mode, and image uploads by @yeshion23333 in #2944
• fix(vlm): omit unset default max_tokens by @qin-ctx in #2946
• fix(queuefs-cache): Skip caching control plugins during mount by @tuofang in #2948
• fix(server): persist OAuth DCR client scope to fix invalid_scope for MCP clients by @dfwgj in #2921
• fix(queuefs): reuse outer lock_handle for sidecar, image rewrite and … by @baojun-zhang in #2953
• fix(vlm): omit unset default max_tokens by @qin-ctx in #2949
• feat(init): TUI-style setup wizard with separate embedding/VLM config by @t0saki in #2952
• docs: add OpenViking Studio live demo link to READMEs by @t0saki in #2960
• fix: 修复 git 多版本管理接口遇到的路径问题 by @Hao-Yu-la in #2963
• chore(deps): update litellm requirement from <1.89.3,>=1.83.7 to >=1.83.7,<1.90.3 by @dependabot[bot] in #2965
• Watch sync followup by @myysy in #2962
• chore(deps): bump openclaw/clawhub/.github/workflows/package-publish.yml from 0.12.0 to 0.23.1 by @dependabot[bot] in #2964
• fix(memory): remove duplicate name field in identity template by @xiaochen-zhou in #2943
• docs(bot): document agents.thinking config option by @r266-tech in #2954

New Contributors

• @lg320531124 made their first contribution in #2853
• @dfwgj made their first contribution in #2921
• @xiaochen-zhou made their first contribution in #2943

Full Changelog: v0.4.6...v0.4.7

python-sdk@0.1.3

fix(sdk/go): stop sending empty args on AddResource (#2878)

AddResource unconditionally attached args: {} to every request body. Against
instances that predate #2549 (which added the args field to the resources
route under model_config=ConfigDict(extra="forbid")), the empty args object
is rejected with "body.args: Extra inputs are not permitted", so add-resource
fails entirely on older / hosted endpoints.

Only attach args when arguments were actually provided (len(opts.Args) > 0),
mirroring the Python SDK _compact_request_body (#2834) and the Rust CLI
compact_request_body (#2799). Other fields, including directly_upload_media,
are unchanged. Scope is args-only, matching #2834.

Tests cover the three arg states: omitted when unset, omitted when explicitly
empty (server defaults args to {} on this create route, so absent and
present-but-empty are equivalent), and forwarded when populated.

v0.4.6

Release date / 发布日期: 2026-06-29

Compare range / 对比范围: v0.4.5..v0.4.6 (33 first-parent commits)

Full Changelog / 完整变更记录: v0.4.5...v0.4.6

---

中文

版本概览

v0.4.6 是 0.4 系列的一次功能型发布：新增 VikingFS 多版本管理、整站 sitemap/RSS/Atom 导入、VikingDB BM25 grep、Web Studio 使用指标视图，并重新启用 viking://agent/skills 作为账号级共享 skill 目录。

本版本也收窄了 legacy agent_id 的兼容边界。对于还停留在 0.3.x、并且仍有旧 viking://agent/<agent_id> 或 viking://session/... 数据的部署，不建议把 0.4.6 作为直接迁移落点。先升到 0.4.5 完成迁移和 cleanup，再升 0.4.6。

0.3.x 升级与迁移说明

全新部署、已经在 0.4.x 上运行的部署，或已经清理完 legacy agent/session 数据的部署，可以直接升级到 0.4.6。

如果从 0.3.x 升级，且数据目录里仍有 legacy agent/session 数据，推荐路径是：

# 1. 在 0.3.x 侧先备份，推荐使用最后一个 0.3.x 版本
pip install openviking==0.3.24 --upgrade --force-reinstall
ov backup ./backups/openviking-before-0.4.ovpack

# 2. 先升级到 0.4.5，完成迁移
pip install openviking==0.4.5 --upgrade --force-reinstall
openviking-server --config ov.conf
ov --sudo admin migrate --output json
ov --sudo task status <task_id>

# 3. 验证新路径后，清理旧 namespace
ov --sudo admin migrate --cleanup --output json
ov --sudo task status <cleanup_task_id>

# 4. 再升级到 0.4.6
pip install openviking==0.4.6 --upgrade --force-reinstall

原因：0.4.6 重新使用 viking://agent/skills 作为共享 skill 目录，并在迁移/cleanup 中保留 skills、endpoints、tools、payments 等新的 agent 保留子目录。0.4.5 的 cleanup 会删除整个旧 /agent 根，更适合作为 0.3.x legacy 数据迁移完成后的清理版本。

同时，0.4.6 不再把 search/find 请求体里的 agent_id 或 agent_uri 当作 peer selector。升级时请同步升级 server、CLI、SDK；需要 peer 视图时使用 actor_peer_id、X-OpenViking-Actor-Peer，或显式 target_uri。

主要更新

• VikingFS 多版本管理：新增 Git-backed snapshot 能力，支持 commit、log、show、restore。HTTP API、Python SDK、Rust CLI 均可使用；Git 对象可存本地 .ovgit，也可使用 S3/TOS 兼容后端。
• 整站导入：add_resource 支持 sitemap、sitemap index、RSS 2.0 和 Atom。sitemap/feed URL 会生成一棵资源树；对 feed 设置 watch_interval 可以持续刷新整站内容。
• 共享 Agent Skills：viking://agent/skills 重新成为账号级共享 skill 根；默认仍安装到当前用户的 viking://user/<user_id>/skills，可通过 -p/--uri 选择共享目录。
• VikingDB BM25 Grep：grep 引擎可在 auto 模式下使用 VikingDB BM25 做关键词召回，并保留 fs 强制本地搜索模式。
• Web Studio 指标开放给用户：首页补充 token trend、context commits、heatmap 等用户可见指标，并拆分 heavy chunks 改善前端加载。

新功能用法

多版本管理最小流程：

ov snapshot commit -m "initial import" -o json
ov snapshot log --limit 10 -o json
ov snapshot show <commit_oid> --path viking://resources/project/guide.md --out-file ./guide.md
ov snapshot restore <commit_oid> viking://resources/project --dry-run -o json
ov snapshot restore <commit_oid> viking://resources/project -m "restore project" -o json

整站导入：

# 直接导入 sitemap / RSS / Atom
ov add-resource https://example.com/sitemap.xml --watch-interval 60 --wait

# 对普通域名强制整站发现
ov add-resource https://example.com --args site:true --wait

共享 skill：

# 安装到账号级共享 skill 目录
ov skills add ./skills/search-web -p viking://agent/skills --wait

# 只列出共享 skill
ov skills list --uri viking://agent/skills

# 默认会合并用户私有 skill 与共享 agent skill
ov skills list

Grep 引擎配置：

{
  "grep": {
    "engine": "auto",
    "switch_to_remote_threshold": 10000
  }
}

体验与兼容性改进

• add_resource 增强了 parent / create_parent 语义，CLI 增加 --parent-auto-create。
• SDK 和 CLI 会避免向旧服务端发送不必要的新字段，提高跨版本请求兼容性。
• 服务端会把 0.0.0.0、:: 这类监听地址映射成 loopback client URL，避免派生出的本地客户端 URL 不可连接。
• Session memory diff 会过滤未变化的更新，空 message range 会回退到当前日期。
• Bot 增加 temperature 配置，并修正 search tool 结果和 iteration-limit 回答。

修复

• 修复 VikingDB grep fallback、exclude URI 过滤、text 字段大小限制、旧 collection schema 兼容、embedding metadata schema version 等问题。
• 修复 content-write 后语义刷新锚点和递归刷新，减少写入后索引不一致。
• 禁止删除受保护的 VikingFS 根目录。
• .jsonl 现在按文本文件处理，上传编码归一化会覆盖该格式。
• 修复 RAGFS backup 默认工作区导致的递归同步循环，并重命名相关配置键。
• OpenCode plugin 支持 tokenless npm publish。

文档、测试与安全

• 新增 snapshot API / guide / examples，以及 Git version control 设计文档。
• 新增 VikingDB BM25 grep 效果与性能 benchmark。
• 补充 reindex mode 文档、0.4.3 到 0.4.5 changelog、community plugin 文档更新。
• 更新 litellm 依赖范围。

---

English

Overview

v0.4.6 is a feature release for the 0.4 line. It adds VikingFS snapshot versioning, whole-site sitemap/RSS/Atom ingestion, VikingDB BM25 grep, user-visible Web Studio metrics, and restores viking://agent/skills as an account-shared skill root.

This release also narrows legacy agent_id compatibility. If you are still on 0.3.x and still have legacy viking://agent/<agent_id> or viking://session/... data, do not use 0.4.6 as the direct migration landing version. Upgrade to 0.4.5 first, migrate and clean up, then upgrade to 0.4.6.

0.3.x Upgrade And Migration

Fresh installs, existing 0.4.x deployments, and deployments that have already cleaned up legacy agent/session data can upgrade directly to 0.4.6.

For 0.3.x deployments with legacy agent/session data, use this path:

# 1. Back up on a 0.3.x-compatible version
pip install openviking==0.3.24 --upgrade --force-reinstall
ov backup ./backups/openviking-before-0.4.ovpack

# 2. Upgrade to 0.4.5 first and run migration
pip install openviking==0.4.5 --upgrade --force-reinstall
openviking-server --config ov.conf
ov --sudo admin migrate --output json
ov --sudo task status <task_id>

# 3. Verify new paths, then clean legacy namespaces
ov --sudo admin migrate --cleanup --output json
ov --sudo task status <cleanup_task_id>

# 4. Upgrade to 0.4.6
pip install openviking==0.4.6 --upgrade --force-reinstall

Reason: 0.4.6 reuses viking://agent/skills as the shared skill directory, and migration/cleanup now preserves new reserved agent subdirectories such as skills, endpoints, tools, and payments. 0.4.5 cleanup removes the whole legacy /agent root, so it is the safer cleanup stop for 0.3.x data.

Also note that 0.4.6 no longer treats request-body agent_id or agent_uri on search/find as a peer selector. Upgrade server, CLI, and SDK together; use actor_peer_id, X-OpenViking-Actor-Peer, or explicit target_uri when you need a peer-scoped view.

Highlights

• VikingFS snapshot versioning: new Git-backed commit, log, show, and restore primitives across HTTP API, Python SDK, and Rust CLI. Git objects can live in local .ovgit storage or an S3/TOS-compatible backend.
• Whole-site ingestion: add_resource can ingest sitemaps, sitemap indexes, RSS 2.0, and Atom feeds. A sitemap/feed URL becomes one resource tree, and watch_interval keeps the site refreshed.
• Shared Agent Skills: viking://agent/skills is available again as an account-shared skill root. User-private viking://user/<user_id>/skills remains the default.
• VikingDB BM25 Grep: grep can use VikingDB BM25 keyword recall in auto mode while keeping fs as the forced local-search option.
• Web Studio metrics for users: the home view adds token trend, context commits, and heatmap metrics, with heavy chunks split for faster loading.

New Feature Usage

Snapshot flow:

ov snapshot commit -m "initial import" -o json
ov snapshot log --limit 10 -o json
ov snapshot show <commit_oid> --path viking://resources/project/guide.md --out-file ./guide.md
ov snapshot restore <commit_oid> viking://resources/project --dry-run -o json
ov snapshot restore <commit_oid> viking://resources/project -m "restore project" -o json

Whole-site ingestion:

ov add-resource https://example.com/sitemap.xml --watch-interval 60 --wait
ov add-resource https://example.com --args site:true --wait

Shared skills:

ov skills add ./skills/search-web -p viking://agent/skills --wait
ov skills list --uri viking://agent/skills
ov skills list

Grep config:

{
  "grep": {
    "engine": "auto",
    "switch_to_remote_threshold": 10000
  }
}

Improvements

• add_resource has clearer parent / create_parent behavior, and the CLI adds --parent-auto-create.
• SDK and CLI clients omit unnecessary newer fields when talking to older servers.
• Server bind hosts such as 0.0.0.0 and :: are mapped to loopback addresses for generated local client URLs.
• Session memory diff updates skip unchanged output, and empty message ranges fall back to the current date.
• Bot flows gain temperature configuration and fixes for search-tool results and iteration-limit answers.

Fixes

• Fixed VikingDB grep fallback, exclude-URI filtering, text field size limits, legacy collection schema compatibility, and embedding metadata schema-version handling.
• Fixed content-write semantic refresh anchoring and recursive refresh behavior.
• Blocked deletion of protected VikingFS roots.
• .jsonl is now recognized as text for upload encoding normalization.
• Prevented recursive backup sync loops by moving the default backup workspace and renaming the related config key.
• OpenCode plugin publishing now supports tokenless npm publish.

Docs, Tests, And Security

• Added snapshot API / guide / examples and the Git version-control design doc.
• Added VikingDB BM25 grep effectiveness and performance benchmarks.
• Documented reindex modes and added v0.4.3 through v0.4.5 changelog entries.
• Updated the litellm dependency range.

v0.4.5

This hotfix release prioritizes role handling and trusted-auth reliability, while also rolling up the current main fixes since v0.4.4.

Highlights

• Fixed auth role serialization so request identity roles are consistently serialized as string roles across storage, resource, session, queue, watch, summarizer, and semantic-processing paths. (#2728)
• Improved user-management setup in the CLI config wizard and stabilized Web Studio account selection. (#2721, #2722)
• Simplified VikingBot auth handling and added trusted auth_mode support for OpenViking-backed bot flows. (#2769)
• Made failed session archives skippable and tuned OpenClaw auto-commit behavior. (#2775)
• Added session-aware recall for Codex/OpenCode integrations and consolidated OpenCode plugin documentation around the single maintained plugin. (#2729, #2540, #2801)
• Hardened storage/session behavior, including queuefs semantic processing for non-directory memory URIs, glob URI scheme preservation, event-summary fallback, memory abstract truncation, and path-lock progress logs. (#2735, #2804, #2806, #2774, #2768)
• Improved CLI and SDK surfaces: clearer CLI validation errors, safer request field emission for older servers, Go SDK set_tags, and the standalone Python HTTP SDK extraction. (#2762, #2799, #2782, #2736)
• Added OpenWebUI and Pi coding-agent integration examples. (#2640, #2314)

Upgrade Notes

• Deploy this release for the role serialization fix if you run authenticated or trusted-mode multi-tenant deployments.
• Python package version is derived from the v0.4.5 tag.
• Docker images are published with v0.4.5 and latest tags by the release workflow.

New Contributors

• @BenSharir made their first contribution in #2754
• @blackdeathdrow made their first contribution in #2745
• @Kashkovsky made their first contribution in #2735
• @hammerhoundai made their first contribution in #2314

Full Changelog: v0.4.4...v0.4.5

python-sdk/v0.1.2

v0.1.2