github volcengine/OpenViking v0.4.23
on GitHub

latest releases: sdk/go/v0.0.5, python-sdk@0.1.13, cli@0.4.23...
4 hours ago

OpenViking v0.4.23

中文

亮点

  • 检索与排序：每条查询改为一次全局向量召回，再按模式统一 rerank，移除目录递归与父级分数传播，评分阈值在 rerank 之后应用（#5450）；移除热度加权及 retrieval.hotness_alpha（#5454）；find / search 新增事件时间衰减排序参数 events_time_decay_protection（#5214）；search 新增 search_type="keywords" BM25 关键词检索，覆盖 REST、MCP、CLI 与 Python / TypeScript / Go SDK（#5456）；Jev rerank 新增 Choice 模式，通过 rerank.mode: "choice" 启用，默认仍为 noul；Choice 分数是候选池内的相对概率，启用时需把 rerank.threshold 设为 0，MCP 调用同时传 min_score=0（#5486）；observer 报告向量度量与分数尺度（#5488）。
  • 文件系统与知识整理：ls / tree 返回 has_more 分页状态（#5330）；tree 支持 directories_only 目录过滤和 L0/L1 展示（#5334）；ls 支持 include_abstract / include_overview（#5434）；ov compile --skill memory 对记忆目录就地去重、合并与规范化（#5178）；reindex 迁移到 RFV planner，新增 force，异步任务可恢复，queue_workers.reindex.max_concurrent 默认 4（#5416）；snapshot 处理文件被目录替换的情况（#5441）；Markdown 解析保留首个一级标题之前的内容（#5427），飞书表格转义竖线与换行（#5435）。
  • MCP、权限与 Studio：MCP 工具声明行为注解（#5075），整次调用失败时返回 isError: true（#5078）；新增 list_users、list_groups、get_acl、set_acl 工具，write / add_resource 支持 acl 参数（#5466）；账号变更缺少注册表基线时拒绝写入，避免覆盖已有账号（#5483）；ovcli.conf 接受 oidc_token（#5448）；Studio 新增账号级记忆抽取规则编辑（#5495）。
  • 模型与向量服务：gpt-6 及之后的 OpenAI 模型按推理模型处理，修复 session commit 返回 400（#5398）；火山、Ark 媒体响应和 Anthropic（LiteLLM）支持透传额外请求体（#5432、#5440、#5447）；Gemini 异步客户端按请求创建，修复 attached to a different loop（#5428）；Jina 默认维度按模型推导（#5426）；内存 cache provider 拒绝 Lua 脚本（#5446）。
  • Agent 插件：采集过滤统一为「清洗 → 过滤 → 截断」，pi / Codex / DSH / OpenCode / Claude Code 共用（#5359、#5375）；Claude Code 与 Codex 召回钩子转发 recallExcludeUris（#5407），pi 支持 recallExcludeUris / recallQueryFilters（#5368）；Codex 采集排除宿主注入的启动上下文（#5392）；pi /viking commit 未归档时给出原因（#5468）；pi 与 OpenCode 随插件附带 OpenViking skills（#5525）；新增 ov-kanban skill 用于结构化任务交接（#5157、#5451）；DSH 增加插件卡片图标与多语言描述（#5362）、按会话解析 workspace peer 设置（#5380）；Hermes 修复召回绑定当前会话、setup 时保留 .env 其他内容等问题（#5372、#5374、#5449、#5455）。
  • 安装：安装器只从发布渠道安装，不再 git clone，改动前先列出并确认（#5464）；安装包改由文档站下载，docs.openviking.net 与 docs.openviking.ai 谁先响应用谁（#5477、#5487）；默认同时安装 ov CLI（#5498）；先询问语言并清理旧安装器遗留（#5490）；指南与插件 README 的安装入口统一为 openviking.ai/install（#5478）。
  • CLI、文档与品牌：CLI 采用 E 品牌标志与纯色配色（#5545）；README 改为 agent-first 快速开始，并加入火山 OpenViking Service 产品页入口（#5524）；文档站对照实现逐页校对（#5501–#5511、#5533、#5534）；开源字体排版（#5536、#5543）与 E 品牌（#5537、#5546）。
  • 其他修复：Windows + uv 等经中间启动器运行 Bot 时，就绪状态被误判导致主服务等待 900 秒（#5431）。

兼容性与迁移

  1. Session 自动 commit 配置项合并（#5363）：memory.session_auto_commit.default_enabled 与 idle_enabled 合并为 enabled（默认 false）。旧键名不兼容，会被忽略，启动日志只有一条 Ignoring unknown config field WARNING，不会报错；配过旧键的部署升级后自动 commit 会关闭，需要改成 enabled: true。同一配置下，scan_batch_size、scan_batch_pause_seconds 一并移除，由 scan_rate_limit_files_per_second（默认 2.0）取代；check_interval_seconds 默认值由 60 秒改为 600 秒。 

    { "memory": { "session_auto_commit": { "enabled": true } } }

  2. 已知问题：find 传非法参数返回 500，而不是 400：limit 为负数时，本地向量库后端和 VikingDB 后端都会返回 500（本地后端是 native 检索接口收到负数 topk 后整数溢出）；limit=0 在 VikingDB 后端返回 500，本地后端返回空结果（来自 #5450）。VikingDB 后端下 filter 条件不带 op 也会返回 500（v0.4.22 起已有）。后续版本会补参数校验；在此之前请由调用方保证 limit >= 1，且 filter 条件带 op。

  3. 检索评分与排序变化（#5450、#5454）：召回由逐层递归 + 父级分数传播改为单次全局召回；仅在启用 rerank 时候选池放大到 2 × limit，统一 rerank 一次，rerank 失败沿用向量分数。retrieval.hotness_alpha 与 score_propagation_alpha 配置已删除，配置中保留会被忽略并输出 WARNING；排序只取向量分数或 rerank 分数。同一查询的结果顺序和分数可能与 v0.4.22 不同，设置了 score_threshold 或按分数过滤的调用方需要重新校准。

  4. reindex 拒绝非递归的 semantic namespace 请求（#5395）：ov reindex viking://user/alice --mode semantic_and_vectors --recursive=false 以前会忽略 recursive=false 并递归重建整个命名空间，现在返回 INVALID_ARGUMENT。请对具体的 resource、memory 或 skill 目录发起请求。

  5. /health 对无效凭证返回认证错误（#5471）：不带凭证的请求仍返回 200；显式带了过期或无效 API key 时，以前返回匿名 200，现在返回认证错误。用无效 key 探活的脚本需要去掉凭证。

  6. Gemini SDK 最低版本（#5428、#5439）：gemini、gemini-async extras 的 google-genai 要求升到 >=1.39.0。更低版本的 SDK 会在 embed_async() 报 TypeError、close() 报 AttributeError。

  7. 安装器行为变化（#5464、#5477、#5498）：默认安装不再 git clone；--dist github、--source remote、OPENVIKING_REPO_URL/REF/BRANCH 仍被接受，但只打印提示。Claude Code 2.1.224+ 通过 URL marketplace 自动更新，Claude Code 2.0 以下会被跳过。默认会用 npm install -g @openviking/cli 安装 ov CLI，需要本机有 npm；不想安装时在勾选项里取消 CLI，或用 --harness 指定不含 cli 的列表。

English

Highlights

  • Retrieval and ranking: each query now does one global vector recall and then one unified rerank by mode; directory recursion and parent score propagation are removed, and score thresholds apply after rerank (#5450); hotness weighting and retrieval.hotness_alpha are removed (#5454); find / search add the event time-decay ranking parameter events_time_decay_protection (#5214); search adds search_type="keywords" for BM25 keyword retrieval across REST, MCP, CLI, and the Python / TypeScript / Go SDKs (#5456); Jev rerank adds a Choice mode, enabled with rerank.mode: "choice" (the default stays noul); Choice scores are relative probabilities within the candidate pool, so set rerank.threshold to 0 and pass min_score=0 for MCP calls (#5486); the observer reports the vector metric and score scale (#5488).
  • Filesystem and knowledge consolidation: ls / tree return a has_more pagination flag (#5330); tree supports directories_only and L0/L1 content (#5334); ls supports include_abstract / include_overview (#5434); ov compile --skill memory deduplicates, merges, and normalizes a memory directory in place (#5178); reindex moves to the RFV planner, adds force, makes async tasks recoverable, and queue_workers.reindex.max_concurrent defaults to 4 (#5416); snapshots handle files replaced by directories (#5441); Markdown parsing keeps content before the first top-level heading (#5427) and Feishu tables escape pipes and line breaks (#5435).
  • MCP, permissions, and Studio: MCP tools advertise behavior annotations (#5075) and whole-call failures return isError: true (#5078); adds the list_users, list_groups, get_acl, and set_acl tools, and write / add_resource accept acl (#5466); account mutations are refused when the registry baseline is missing, so existing accounts are not overwritten (#5483); ovcli.conf accepts oidc_token (#5448); Studio adds account-level memory extraction rule editing (#5495).
  • Models and vector services: gpt-6 and later OpenAI models are treated as reasoning models, fixing session commit 400 errors (#5398); extra request bodies are forwarded for Volcengine, Ark media responses, and Anthropic through LiteLLM (#5432, #5440, #5447); Gemini async clients are created per request, fixing attached to a different loop (#5428); the Jina default dimension is derived from the model (#5426); the in-memory cache provider rejects Lua scripts (#5446).
  • Agent plugins: capture filtering is unified as sanitize → filter → truncate across pi / Codex / DSH / OpenCode / Claude Code (#5359, #5375); Claude Code and Codex recall hooks forward recallExcludeUris (#5407) and pi honors recallExcludeUris / recallQueryFilters (#5368); Codex capture excludes host-injected startup context (#5392); pi /viking commit explains why nothing was archived (#5468); pi and OpenCode ship OpenViking skills (#5525); adds the ov-kanban skill for structured task handoff (#5157, #5451); DSH adds the plugin card icon and localized descriptions (#5362) and resolves workspace peer settings per session (#5380); Hermes fixes recall binding to the current session and preserves unrelated .env content during setup (#5372, #5374, #5449, #5455).
  • Installation: the installer installs from the release channel only, no longer runs git clone, and lists what it will change before changing anything (#5464); installer files are downloaded from the docs site, using whichever of docs.openviking.net and docs.openviking.ai answers first (#5477, #5487); the ov CLI is installed by default (#5498); the installer asks for the language first and clears old installers' leftovers (#5490); guides and plugin READMEs use openviking.ai/install as the install entry (#5478).
  • CLI, docs, and branding: the CLI adopts the E mark and solid colors (#5545); the README gets an agent-first Quick Start and an entry to the Volcengine OpenViking Service product page (#5524); the docs site is reviewed page by page against the implementation (#5501–#5511, #5533, #5534); open-font typography (#5536, #5543) and the E branding (#5537, #5546).
  • Other fixes: when the Bot runs through an intermediate launcher such as Windows + uv, its ready state was misjudged and the main server waited 900 seconds (#5431).

Compatibility and Migration

  1. Session auto-commit settings merged (#5363): memory.session_auto_commit.default_enabled and idle_enabled are merged into enabled (default false). The old key names are not compatible and are ignored, with only an Ignoring unknown config field WARNING in the startup log and no error. Deployments that set the old keys will have auto-commit turned off after upgrading and must set enabled: true. In the same block, scan_batch_size and scan_batch_pause_seconds are removed in favor of scan_rate_limit_files_per_second (default 2.0), and the default check_interval_seconds changes from 60 to 600 seconds. 

    { "memory": { "session_auto_commit": { "enabled": true } } }

  2. Known issue: find with invalid parameters returns 500 instead of 400: a negative limit returns 500 on both the local vector backend and the VikingDB backend (on the local backend the native search call overflows on a negative topk); limit=0 returns 500 on the VikingDB backend and an empty result on the local backend (introduced by #5450). On the VikingDB backend, a filter condition without op also returns 500 (already the case since v0.4.22). Parameter validation will be added in a later release; until then, callers should keep limit >= 1 and include op in every filter condition.

  3. Retrieval scoring and ordering changes (#5450, #5454): recall changes from per-level recursion with parent score propagation to a single global recall; the candidate pool grows to 2 × limit only when rerank is enabled, rerank runs once, and vector scores are used if rerank fails. The retrieval.hotness_alpha and score_propagation_alpha settings are removed; leftover entries are ignored with a WARNING, and ordering uses only vector or rerank scores. Result order and scores for the same query may differ from v0.4.22, so callers using score_threshold or score filters should recalibrate.

  4. reindex rejects non-recursive semantic namespace requests (#5395): ov reindex viking://user/alice --mode semantic_and_vectors --recursive=false used to ignore recursive=false and rebuild the whole namespace recursively; it now returns INVALID_ARGUMENT. Send the request to a specific resource, memory, or skill directory instead.

  5. /health returns an authentication error for invalid credentials (#5471): requests without credentials still get 200. Requests that explicitly present an expired or invalid API key used to get an anonymous 200 and now get an authentication error. Probes that send an invalid key should drop the credentials.

  6. Minimum Gemini SDK version (#5428, #5439): the gemini and gemini-async extras now require google-genai>=1.39.0. Older SDKs raise TypeError in embed_async() and AttributeError in close().

  7. Installer behavior changes (#5464, #5477, #5498): the default install no longer runs git clone; --dist github, --source remote, and OPENVIKING_REPO_URL/REF/BRANCH are still accepted but only print a notice. Claude Code 2.1.224+ updates through a URL marketplace, and Claude Code older than 2.0 is skipped. The ov CLI is installed by default with npm install -g @openviking/cli, which needs npm on the machine; to skip it, uncheck the CLI item or pass a --harness list without cli.

First-time Contributors

Full Changelog: v0.4.22...v0.4.23

Check out latest releases or
releases around volcengine/OpenViking v0.4.23

Don't miss a new OpenViking release

NewReleases is sending notifications on new releases.

Get notifications