Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

77.9 KB
Raw Blame

Agent 集成能力

本页对比各 OpenViking Agent 集成安装后的实际行为。依赖某个集成之前,可以先用本页回答三个问题:

  • Agent 能自己调用哪些 OpenViking 工具?
  • 哪些事情不需要 Agent 请求就会发生:每次提问前的召回、会话开场注入的上下文、对话捕获,以及把对话变成长期记忆的提交?
  • Agent 退出、崩溃、压缩上下文或连不上服务端时,哪些内容会保留,哪些会丢失?

安装请从选择 Agent 接入方式开始。下文的对比基于源码依据中列出的实现;一个集成能用哪些 MCP 工具,由所连的服务端决定。

两类能力

Agent 可调用的工具由模型决定是否调用,例如 search、read、remember。模型不调用,就不会发生任何事。只接 MCP 时,只有这一类能力。

自动生命周期行为由宿主事件触发,不需要模型请求,包括:提问到达模型前的召回、会话开场注入的 profile 和 skill 上下文、把每轮对话捕获到 OpenViking 会话,以及提交。hook、插件和原生扩展提供这类能力。

长期记忆只在提交(commit)之后才会从会话中抽取。已捕获但未提交的消息留在服务端会话里,要等之后的某次提交才会变成记忆。捕获与提交说明每个集成何时提交,以及退出时可能留下什么。

一览

可调用工具

“服务端 MCP 工具”指服务端 tools/list 返回的工具:当前服务端有 21 个,列在服务端 MCP 工具。

集成 接入方式 Agent 可调用的工具
Claude Code 插件:hook + MCP 代理 服务端 MCP 工具
Codex、TraeCode CLI 2.0 Codex 插件:hook + MCP 代理 服务端 MCP 工具
Cursor hook 与 MCP 配置,外加一条 rule 服务端 MCP 工具
TRAE、TRAE CN hook 与 MCP 配置 服务端 MCP 工具
ZCode hook 与 MCP 配置 服务端 MCP 工具
Kimi Code Kimi Code 插件:hook + MCP 代理 服务端 MCP 工具
CodeBuddy Code 插件:hook + MCP 代理,由统一安装器安装 服务端 MCP 工具
OpenCode npm 插件,自动添加 MCP 条目 服务端 MCP 工具,名为 openviking_<tool>
DSH 同进程 Cordis 插件 + MCP 代理 服务端 MCP 工具,名为 mcp__openviking__<tool>
pi 原生扩展,内置 MCP 客户端 服务端 MCP 工具;MCP 握手成功后注册为 openviking_<tool>
OpenClaw context-engine 插件 15 个原生工具,默认启用 14 个
Hermes Hermes memory provider 6 个原生 viking_* 工具
MCP 客户端、Agent Plugins 仅 MCP 服务端 MCP 工具
ov CLI 命令行客户端 每个操作都是显式命令,不经过 Agent

自动行为

集成 每次提问前召回 会话开场上下文 会话中的提交 正常退出时提交 宿主压缩
Claude Code 是,带会话 profile、记忆索引、skill 待提交 token 达到 20,000 是 先提交,再由宿主摘要
Codex 是,带会话 profile、记忆索引、skill 待提交 token 达到 20,000 Codex 0.145+;否则下次启动时 先提交,再由宿主摘要
TraeCode CLI 2.0 是,带会话 profile、记忆索引、skill 待提交 token 达到 20,000 仅当版本带 SessionEnd;否则下次启动时 同 Codex
Cursor 是,带会话 profile、记忆索引、skill 每捕获 8 条消息 否 先提交,再由宿主摘要
TRAE、TRAE CN 是,带会话 profile、记忆索引、skill 每轮 没有退出事件;每轮已提交 没有压缩前事件
ZCode 是,带会话 profile、记忆索引、skill 每轮 没有退出事件;每轮已提交 没有压缩前事件
Kimi Code 是,带会话 profile、记忆索引、skill,在首次提问时 每捕获 8 条消息 是 提交尚未提交的消息
CodeBuddy Code 是,带会话,仅限交互式 TUI profile、记忆索引、skill 每捕获 8 条消息 是,仅限交互式 TUI 提交尚未提交的消息
OpenCode 是,带会话 profile、记忆索引、skill、已索引的仓库 空闲时,待提交 token 达到 20,000 是,在宿主的清理时限内 在压缩前后提交
DSH 是,带会话 profile、记忆索引、skill,每个会话一次 待提交 token 达到 20,000 是,预算 3 秒 先提交,再由宿主摘要
pi 是,带会话 profile、记忆索引、skill,每轮 takeover 开:约 30,000 token;关:20,000 takeover 开:否;关:是 takeover 替换 pi 的摘要
OpenClaw 是,带会话 profile,每轮 token 预算的一半(默认 64,000) 否 插件接管压缩
Hermes(内置) 是,带会话,有回退路径 profile 与记忆清单 否;只在会话边界 是,前提是待上传内容在 10 秒内完成 fork 型压缩时提交
ov CLI 否 否 只有 ov session commit 不适用 不适用

标为 Hermes(内置) 的行描述旧版 Hermes 中固定提交的内置 provider。 使用目录插件的版本会加载外部插件,其不同的生命周期行为见 Hermes。

表格说明:

  • 带会话的召回会发送会话 ID,服务端借助对话内容理解查询。共享插件的 context 模式还会扩写查询,并记录最近注入过的记忆,避免重复注入。Hermes 用 list 模式,没有注入台账。OpenClaw 用 context search 并发送会话 ID,但关闭去重,因为它注入的上下文每轮重建,不写入历史。请求路径和回退见召回请求如何到达服务端。
  • 待提交 token 是服务端统计的、已捕获但未提交的消息量。多数阈值是客户端设置,见各集成何时提交。
  • 正常退出时提交指集成会发出提交请求。网络错误、宿主的退出时限或进程被终止仍可能打断它。Ctrl+C、信号和崩溃见退出时会发生什么。

Agent 可调用的工具

服务端 MCP 工具

所有基于 MCP 的集成都暴露同一组由服务端定义的工具,自己不维护工具目录。本地代理(pi 则是内置 MCP 客户端)读取 ~/.openviking/ovcli.conf,连接服务端的 /mcp,原样转发 tools/list 的结果。服务端升级可以直接增加工具,不需要插件发版;客户端重新连接后即可看到。各工具的参数见 MCP 工具与协议。

分组 工具
检索与浏览 find、search、read、download、list、tree、grep、glob
写入 remember、write、edit、add_resource、add_skill
删除 forget
监听资源 list_watches、cancel_watch(商业版暂不支持)
账户与权限 list_users、list_groups、get_acl、set_acl
状态 health

使用前需要了解的行为:

  • remember 会创建一个名为 mcp-store-<id> 的一次性会话,写入消息后立即提交。它是唯一会提交的 MCP 工具。提交被接受后它立刻返回,结果里带后台记忆提取任务的 task_id;提取过程再决定新建或更新哪些记忆。没有任何 MCP 工具会提交 Agent 当前的对话,那是自动 hook 的工作。
  • find 与 search:find 是不带会话上下文的快速检索。search 可以传 session_id,并做意图分析(retrieval.enable_intent,默认开启)。find 传 context_type="skill" 时,每个 skill 包只返回一条命中,指向它的 SKILL.md,范围包括用户自己的和账户共享的 skill。
  • write 与 edit 只能写 viking://resources、viking://user 和 viking://agent。新文件的扩展名必须是 .md、.txt、.json、.yaml、.yml、.toml、.py、.js 或 .ts。用户的 skills/、peers/、privacy/ 和 sessions/ 目录只读。写入 viking://agent/skills 不会被拒绝,但会跳过 skill 安装流程,skill 请用 add_skill。
  • add_resource 传本地路径时返回一个签名上传 URL(默认 600 秒有效)。模型需要把文件上传到这个 URL,例如用一条 shell 命令;上传后自动开始入库。远程 URL 会直接入库。
  • forget 删除传入的任意 URI,默认不递归。它不检查 URI 是记忆、资源还是 skill,见写入与删除限制。
  • Schema 在服务端启动时被展平,只接受 OpenAPI 3.0 子集的客户端(如 Gemini)也能加载。校验仍按原始签名进行,例如 read 也接受单个字符串。所有客户端拿到的 schema 相同。
  • 身份的解析方式与 REST 请求相同,见认证。

各宿主的差异:

  • OpenCode 给工具加 openviking_ 前缀;DSH 把工具命名为 mcp__openviking__<tool>。
  • DSH 每个 DSH profile 只运行一个 MCP 代理,所以工具调用带的是进程级 actor peer,remember 也不绑定 DSH 会话。召回、捕获和提交仍按会话解析 peer。
  • pi 只在以下条件都满足时注册工具:会话未被 bypass、健康检查通过、OpenViking 会话存在、/mcp 握手返回了工具列表。握手失败时,本次会话没有 OpenViking 工具,但召回、同步和 takeover 照常进行,后续轮次会重试握手。mcpEnabled: false 会关闭这条桥接。root API key 访问 /mcp 会得到 403,所以凭据链最终落到 ov.conf 的 server.root_api_key 时,会话里没有工具。
  • Codex 只把 .mcp.json 的 env_vars 中列出的环境变量传给 MCP 服务。

OpenClaw 工具

OpenClaw 注册自己的工具,不转发 MCP 工具。

分组 工具 说明
记忆 memory_recall、memory_store、memory_forget memory_recall 检索记忆;memory_store 通过临时会话提交
资源与 skill ov_search、ov_read、ov_multi_read、ov_list、add_skill、add_resource ov_search 默认检索资源和用户的 skill。add_resource 默认关闭,还需要开启 enableAddResourceTool
会话归档 ov_archive_search、ov_archive_expand 检索并展开已归档的历史
大块工具输出 openviking_tool_result_read、openviking_tool_result_search、openviking_tool_result_list 读取服务端单独存放的工具输出
诊断 ov_recall_trace 查看自动召回是如何构建的

Hermes 工具

Hermes 有 6 个工具:viking_search、viking_read、viking_browse、viking_remember、viking_forget 和 viking_add_resource,没有 skill 工具。viking_remember 通过独立会话提交一条事实,在抽取完成前就返回;抽取可能新增、合并或跳过这条事实。内置 provider 与外部插件的区别见 Hermes。

写入与删除限制

无论删除来自哪个工具或命令,服务端都做同样的检查:

  • 调用方需要对该 URI 有 manage 权限;正在被删除的用户会被拒绝。
  • viking://、viking://user 和 viking://agent 不能删除。删除 viking://resources 或整个用户根(如 viking://user/<id>)需要 ROOT 角色。非 root 调用方不能写 viking://temp 根。
  • 调用方的 actor-peer 视图中不可见的 URI 会被拒绝。

这些检查保护的是命名空间,不区分内容类型。按类型的限制来自客户端:

入口 能删除 客户端限制
MCP forget(所有 MCP 集成,含 CodeBuddy Code、DSH 与 pi) 传入的任意 URI 除非 recursive=true,否则不递归;不检查类型或分数
ov rm 任意 URI 不确认;-r 递归删除
ov tui 的 d 键 根目录和 scope 目录以外的任意 URI 需要确认
OpenClaw memory_forget 只能删记忆文件 URI 必须匹配用户、peer 或 agent 的记忆路径。按搜索删除时,只有唯一候选且分数不低于 0.85 才执行,否则列出候选。始终不递归
Hermes viking_forget 一个用户记忆 .md 文件 拒绝目录、非 .md 文件、自动生成的 .abstract.md 和 .overview.md,以及带 query 或 fragment 的 URI
LangChain viking_forget 任意 URI 只在 profile="admin" 或 allow_forget=True 时提供;recursive 由模型决定
Open WebUI 无 没有删除工具

skill 走单独的路径。创建、安装或替换 skill 用 MCP add_skill 工具、OpenClaw 的 add_skill、ov add-skill 或 POST /api/v1/skills;add_resource 拒绝 skill URI。删除 skill 用 ov skills remove 或 DELETE /api/v1/skills/{name}。MCP forget 和 ov rm 也能删掉 skill 目录,但会留下该 skill 的 privacy 配置。见技能。

自动召回与会话开场上下文

召回请求如何到达服务端

除 OpenClaw 和 Hermes 外,所有集成都使用共享插件代码,最多依次尝试三种请求:

  1. context 检索。POST /api/v1/search/search,带 mode: "context"、purpose: "coding" 和会话 ID。预算、配额、查询扩写和摘要选项只在你配置后才发送;否则使用服务端默认值,包括 1,600 token 的注入预算(max_tokens)。
  2. 旧版 recall。服务端版本较旧、拒绝 context 模式时,插件在 ~/.openviking/state/context-face.json 中记录这一结果,有效 6 小时,并改调 /api/v1/search/recall。这个文件由本机所有集成共享,一个集成的判断对所有集成生效。
  3. 普通 find。最后一步,插件对 viking://~/memories 和 viking://~/skills 执行 find,在本地排序,并按自己的 token 预算装填。recallTokenBudget、recallMaxContentChars 和 recallPreferAbstract 只在这一步生效。

共享插件的召回不包含资源;资源文档由模型自己调用 search 检索。Hermes 开启资源召回选项后可以包含资源。

服务端对会话 ID 有两种处理方式:

  • context 模式(context 检索和旧版 recall)根据对话扩写查询,并为每个会话维护一份已注入记忆的台账。扩写需要同时满足:retrieval.enable_intent 开启(默认开启)、会话中已有消息、存在归档概览或当前消息。原始查询始终排第一,后面最多追加三条规划出的查询。
  • list 模式(不传 mode 时的默认值)由意图分析替换查询,原始查询不一定保留,也不使用台账。Codex 的第二级回退、Hermes 的 viking_search(mode="deep") 以及 Hermes 召回的首选路径都走这里。它们会发送会话 ID,但得不到扩写和去重。

跨轮去重(dedup_turns):

  • 服务端在 context 模式下的默认值是 0,即关闭。共享插件发送 5(recallDedupTurns)。直接调用 API 时必须自己发送 dedup_turns,只带会话 ID 不会开启去重。
  • 窗口按消息条数计算,不按对话轮。同时捕获用户和助手消息时,5 大约覆盖两轮。
  • 关闭自动捕获但开启召回时,消息数不会增长,已注入过的记忆会在整个会话里一直被抑制。设置 OPENVIKING_RECALL_DEDUP_TURNS=0 可以关闭去重。

各集成的召回方式

下表是默认路径。开启召回摘要后,请求会有变化。

集成 触发时机 查询内容 上下文放在哪里
Claude Code 每次 UserPromptSubmit 去掉首尾空白的提问 additionalContext 中的 <openviking-context>
Codex、TraeCode CLI 2.0 每次 UserPromptSubmit;整个 hook 有 120 秒截止时间 提问 <openviking-context source="auto-recall">
Cursor beforeSubmitPrompt 提问;500 ms 内的重复事件复用上次结果 additional_context
TRAE、TRAE CN UserPromptSubmit 去掉之前注入块的提问 additionalContext
ZCode UserPromptSubmit 去掉三类注入块(含 <system-reminder>)的提问 additionalContext,严格 JSON
Kimi Code UserPromptSubmit 提问 纯文本上下文,不是 JSON
CodeBuddy Code UserPromptSubmit,仅交互式 TUI 提问 additionalContext 中的 <openviking-context>
OpenCode v1:每次 chat.message;v2:每次提问 消息的文本部分 v1 在消息前插入一个合成 part。v2 把结果存进消息 metadata,每个模型 step 在该消息前注入,不发新请求
DSH agent/pre-step 本批认领的所有消息,去掉自身注入的内容 追加为一条用户消息
pi 在 before_agent_start 排队,在 context 事件中执行 提问 前置到最后一条真实用户消息,本轮提问拿到本轮的记忆
OpenClaw 上下文组装时 传入的提问,清洗后截到 4,000 字符 <relevant-memories>,放在 system prompt 中,每轮重建。宿主不传提问时前置到最后一条用户消息
Hermes 每次模型调用前 5 个字符及以上的用户输入,去掉 skill 脚手架 <memory-context>,只追加到本次请求中的当前用户消息,不写入存储

会话开场上下文

使用共享插件代码的集成会在会话开始时注入一个 <openviking-context> 块,包含用户 profile(viking://user/<space>/memories/profile.md)、preferences/ 和 entities/ 记忆的索引,以及 <available-skills> skill 清单。会话带有 actor peer 时,还会加入 viking://user/<space>/peers/<peer>/memories/ 下的同名文件:profile、preferences 和 entities 没有消息范围,所以即使在 peer 会话中,抽取也会把用户本人的事实写到用户根目录。用户根目录在前;peer profile 是第二个 <user-profile> 元素,并去掉与用户 profile 相同的行;两个根目录共用同一份预算:

<openviking-context source="startup">
<user-profile uri="viking://user/default/memories/profile.md">...</user-profile>
<available-memories>...</available-memories>
<available-skills>
  OpenViking skills (stored in OpenViking, not local files). Before following one, read <dir>/<name>/SKILL.md with the OpenViking read tool.
  viking://user/default/skills/
    - pr-review — Review a pull request against the team checklist.
  viking://agent/skills/
    - deploy-runbook — Shared deployment runbook for the payments service.
</available-skills>
</openviking-context>

各集成的注入时机:

集成 时机
Claude Code SessionStart,所有 source
Codex SessionStart 的 startup、clear 和 resume
Cursor、TRAE、TRAE CN、ZCode SessionStart
Kimi Code 首次提问时;失败后在后续提问中重试,直到成功
CodeBuddy Code SessionStart,所有 source;同一会话内可能投递两次,因此 hook 是幂等的
OpenCode 每个会话的第一条消息;失败后不重试,子代理会话跳过。已索引仓库的列表同时进入 system prompt
DSH 每个会话一次;压缩后不再发送
pi 放在 system prompt 中,每轮重建
OpenClaw 放在 system prompt 中,每轮重建:<user-profile> 包含用户的 profile,设置了 peer_role 时还包含当前 actor peer 的 profile。不注入记忆索引和 skill 清单
Hermes 用自己的读取逻辑加载 profile 及 preferences、entities 清单,默认预算 6,000 token

预算与限制:

  • profileTokenBudget(默认 10,000 token)覆盖 profile 和记忆索引,profile 占一半:先放用户 profile,peer profile 使用剩余部分,剩余不足 200 token 时只放一行指向其 URI 的提示。两个根目录分摊索引预算。profile 超长时保留前 8 行和结尾;清单超长时以 ... +N more 结尾。token 估算中,CJK 字符按 1.5 token 计,其他文本按每 4 个字符 1 token 计。
  • skillCatalogTokenBudget(默认 1,200 token,OPENVIKING_SKILL_CATALOG_TOKEN_BUDGET)是 skill 清单的独立预算。skillCatalog(OPENVIKING_SKILL_CATALOG)或把预算设为 0 都会关闭清单。
  • 清单来自一次 GET /api/v1/skills 请求。用户自己的 skill 排在前面,与用户 skill 同名的账户 skill 不再列出。每条描述截到约 40 token。描述放不下时只列名称;名称也放不下时以 ... +N more 结尾,或缩成一行数量。服务端没有该接口时不注入清单。
  • sessionStartMaxBytes 按 UTF-8 字节限制整个块:Claude Code 和 Codex 为 9,500,因为这两个宿主会把超过约 10,000 字符的 hook 输出存成文件,只显示预览;ZCode 为 20,000,因为它会丢弃超过 32 KB 的输出;其他集成不设上限。超出上限时,先去掉记忆索引,再去掉 skill 清单。

恢复会话时,部分集成还会注入上一次归档的摘要,预算 32,000 token:Claude Code 在 resume 和 compact 时,Codex 在本地会话已清空后的 resume 时,OpenCode 在会话开始时,pi 在 takeover 关闭时。Claude Code 和 Codex 遇到与本会话已注入内容相同的 profile 块时会跳过。

超时与预算

服务端的查询扩写在 5 秒后停止(retrieval.recall_intent_timeout_s),摘要改写在 30 秒后停止(retrieval.recall_rewrite_timeout_s)。共享插件在开启扩写时把 context 请求超时提高到至少 15 秒,请求摘要时至少 45 秒,让客户端能等完服务端的每个阶段。宿主的截止时间仍可能先结束 hook。修改这些值见调整召回延迟。

集成 召回超时
Claude Code 15 秒,hook 上限 60 秒
Codex 整个 hook 120 秒截止,包括最长 110 秒的本地压缩器
Cursor、TRAE、TRAE CN、ZCode 15 秒,宿主上限 20 秒
OpenCode 30 秒
DSH 10 秒,开启查询扩写时至少 15 秒。召回会阻塞 pre-step
pi 15 秒
CodeBuddy Code 17 秒,hook 上限 60 秒
OpenClaw context search 默认 15 秒(autoRecallTimeoutMs),之前有一次 500 ms 健康检查
Hermes 总计 4 秒,单请求 3 秒;可配置

OpenClaw 和 Hermes 把注入的召回内容限制在 4,000 字符,放不下的条目整条跳过,不截断。

召回摘要

召回摘要让模型先把召回结果改写成一份带引用的简短要点,再交给 Agent。

服务端。context 检索接受 rewrite(false、true 或 "auto",默认 false)和 rewrite_max_bullets(默认 6,范围 1–20)。服务端使用 query_planner 模型;rewrite=true 且未配置 query_planner 时回退到主 vlm,"auto" 只在配置了 query_planner 时执行。摘要以 OpenViking memory digest: 开头,每个要点一行 - 。每个要点最多 500 字符,必须引用结果中的一个 viking:// URI;没有有效引用的要点会被丢弃。模型判断没有相关内容时,服务端返回 stats.rewrite="no_relevant" 和空块,这一轮不记入去重台账。超过 30 秒时,服务端返回未改写的块。

插件。OPENVIKING_RECALL_COMPRESS 或共享配置中的 recallCompress 选择模式,recallRewrite 仍可作为别名使用。

模式 行为
off 不生成摘要
server 发送 rewrite: true,优先使用服务端摘要
client 使用本地压缩器;仅 Claude Code 和 Codex
auto Claude Code 和 Codex 有本地压缩器时使用它,否则发送 rewrite: "auto"。其他集成发送 rewrite: "auto"

Claude Code 和 Codex 默认 auto,其他集成默认 off。支持服务端摘要的有 Claude Code、Codex、OpenCode、DSH、pi、Cursor、TRAE、TRAE CN、ZCode、OpenClaw 和 Hermes 外部插件,且需要服务端支持 context-search rewrite。Hermes 内置 provider 不支持召回摘要。旧值 1 和 0 分别等同于 auto 和 off。no_relevant 结果会取消本轮注入,插件不能回退到原始块。

本地压缩器:

  • Claude Code 用 claude --version 检测 claude(结果缓存 7 天),执行 claude -p --model sonnet --effort low --strict-mcp-config。子进程超时默认 110 秒(recallCompressTimeoutMs),但 60 秒的提问 hook 可能更早结束它。少于 1,500 字符的输入不压缩。引用的 URI 按编辑距离匹配回真实的结果 URI,无法匹配的要点会被丢弃。失败时注入本地格式化的结果,或注入渲染好的块。
  • Codex 从 ~/.codex/models_cache.json 选择模型(优先 gpt-5.3-codex-spark,其次低 effort 的 gpt-5.6-luna;缓存 7 天),在只读的临时沙箱中执行 codex exec,默认超时 110 秒。运行失败一次后,本地压缩停用到下一次 SessionStart。输出上限 4,000 字符;失败时的回退方式与 Claude Code 相同。

这些设置只作用于自动召回。模型显式调用 MCP search 时,使用它自己传入的参数。旧服务端的回退和宿主时间预算见共享插件说明和调整召回延迟。

避免注入内容被重复捕获

注入的上下文用固定标签包裹,例如 <openviking-context>。捕获时先去掉这些块再发送,召回的记忆就不会被当成新对话再次存储。共享捕获代码还会去掉摘要块、元数据围栏和时间戳前缀。TRAE 和 ZCode 使用各自的清理函数,ZCode 的清理函数会去掉三类注入块。OpenClaw 在捕获一轮对话和构造下一次召回查询时都会去掉 <relevant-memories>。Hermes 从捕获批次中丢弃三个只读工具的调用和结果,保留写入类工具的调用。

捕获与提交

服务端会话与提交机制

  • 会话隐式创建。服务端收到某个会话的第一条消息时创建该会话;带该会话 ID 的第一次 context 模式召回也会创建。DSH 是唯一显式创建会话的集成。
  • 提交分两个阶段。POST /api/v1/sessions/{id}/commit 在第一阶段归档消息后返回。响应中带有第二阶段(记忆抽取)的 task_id,抽取在后台运行。提交请求成功不代表抽取已经完成。
  • keep_recent_count 决定提交后会话中保留多少条最近的消息。服务端默认 0,即全部归档。Claude Code、Codex、OpenCode、DSH、Cursor、TRAE、TRAE CN、ZCode 和 Hermes 发送 0;pi 在 takeover 模式下发送最近 3 个用户轮对应的确切消息数,其他情况发送 0;OpenClaw 在阈值提交时发送 10,在 reset、memory_store 和压缩时发送 0。
  • 服务端自动提交默认关闭。memory.session_auto_commit.enabled 默认 false,关闭时空闲扫描器不会启动。新会话仍可以从 server.user_config_defaults.auto_commit_policy 获得策略,也可以通过 POST /api/v1/sessions、PATCH /api/v1/sessions/{id}/config、SDK,或 ov session new --auto-commit-policy-json 与 ov session config set 显式设置。策略的默认值是:待提交 token 150,000(严格大于)、100 条消息、86,400 秒空闲超时、keep_recent_count 0、无最小间隔。空闲超时还需要 memory.session_auto_commit.enabled=true。记忆插件不发送策略,所以没有上述设置时,只有客户端会提交。
  • 批量写入。共享插件每次 POST /messages/batch 最多发送 100 条消息,与服务端上限一致;批量接口返回 404 或 405 时改为逐条发送。
  • 大块工具输出单独存放。服务端把超过 20,000 字符的工具输出移到单独的记录中,留下 tool_output_ref。插件把自己的上限(captureToolMaxChars)提高到 1,000,000,只作为兜底。
  • 部分写入在后台运行。Claude Code、Codex 和 ZCode 默认把 Stop 的写入交给一个分离的 worker(OPENVIKING_WRITE_PATH_ASYNC),宿主不用等待。worker 启动后,关闭终端不影响它,但网络错误或进程被终止仍可能打断它。开启这项设置时,Stop 不再输出 appended N turn(s) 提示。

各集成何时提交

表中的阈值都在客户端判断;除非另有说明,读取的是服务端的待提交 token 数。

集成 会话中 显式操作或会话边界 压缩前后
Claude Code Stop 时待提交 token 达到 20,000 SessionEnd 和 SubagentStop 总是提交;SessionStart 重放排队的写入 PreCompact 总是同步提交
Codex Stop 时待提交 token 达到 20,000 SessionEnd(Codex 0.145+)补齐漏掉的轮次,然后在分离的 worker 中提交。startup 或 clear 的 SessionStart 会提交已标记结束或空闲超过 30 分钟的会话 PreCompact 补齐后提交全部内容
TraeCode CLI 2.0 同 Codex 同 Codex;没有 SessionEnd 时只有启动时的扫描 同 Codex
Cursor 距上次提交捕获满 8 条消息时,在 stop 提交(commitTurnThreshold),本地计数 sessionEnd 已注册,但实际不会运行 preCompact 总是提交
TRAE、TRAE CN 每个捕获到内容的 Stop 无 没有压缩前事件
ZCode 每个 Stop;漏掉的 Stop 对应的轮次,在下一个 Stop 从 rollout 文件补齐 无 没有压缩前事件
Kimi Code 距上次提交捕获满 8 条消息时,在 Stop 提交 SessionEnd 和 Interrupt 提交所有尚未提交的消息,包括 Stop 已经发送的 PreCompact 提交所有尚未提交的消息
CodeBuddy Code 距上次提交捕获满 8 条消息时,在 Stop 提交 SessionEnd(仅交互式 TUI)提交所有尚未提交的消息,包括 Stop 已经发送的;SessionStart 重放排队的写入 PreCompact 提交所有尚未提交的消息
OpenCode v1 session.idle、v2 执行结束时:待提交 token 达到 20,000 删除会话、v1 session.error、v1 dispose 和 v2 cleanup 强制提交 v1 在压缩前后各一次;v2 在压缩结束后一次
DSH turn/end 时待提交 token 达到 20,000 Cordis teardown 提交每个会话 compaction/start 提交,跳过阈值检查
pi,takeover 开(默认) 本地估算达到 30,000 token,且用户轮多于 3 个 /viking commit session_before_compact
pi,takeover 关 每次同步后待提交 token 达到 20,000 session_shutdown 和 /viking commit session_before_compact
OpenClaw 每轮结束后达到 tokenBudget × commitTokenThresholdRatio(默认 128,000 × 0.5) /new、/reset 和 memory_store 提交并等待 compact() 提交,并最多等待 5 分钟完成抽取
Hermes(内置) 无 会话结束、会话切换(/new、/resume、/branch、fork 型压缩)、gateway 缓存驱逐,以及退出处理器;/undo 和原地压缩不提交 只在 fork 型压缩时
ov CLI 无 ov session commit;ov add-memory 会创建、写入并提交自己的会话 不适用

退出时会发生什么

“提交”指退出路径会发出提交请求,“视情况”取决于最后一列的说明。已经写入的消息留在服务端会话中,由同一会话的下一次提交归档。本表假设服务端自动提交关闭。

集成 正常退出 Ctrl+C SIGTERM 关闭终端或窗口 kill -9 或崩溃 剩余内容如何回收
Claude Code 提交 提交 提交 提交 否 SessionEnd 把提交交给自成进程组的分离 worker,SIGHUP 不会终止它。否则等下次阈值、/compact 或 SessionEnd
Codex 提交 视情况 否 否 否 连按两次 Ctrl+C 属于正常退出,会触发 SessionEnd;只按一次不会。漏掉的内容在下一次 startup 或 clear 的 SessionStart 提交:结束标记还在就立即提交,否则等空闲 30 分钟后提交
TraeCode CLI 2.0 否,除非版本带 SessionEnd 否 否 否 否 下一次 SessionStart 的 30 分钟空闲扫描
Cursor 否 否 否 否 否 关闭或切换对话不触发任何事件。sessionEnd 只在关闭窗口时触发,而此时宿主已停止执行 hook 命令。不足 8 条消息阈值的部分要等同一会话的后续消息
TRAE、TRAE CN 否 否 否 否 否 每个 Stop 已经提交,最多丢失正在进行的那一轮
ZCode 否 视情况 否 否 否 按 Ctrl+C 时如果该轮的 Stop 已触发,分离的 worker 会写完。每个 Stop 都提交,漏掉的轮次在下一个 Stop 补齐
Kimi Code 提交 视情况 未验证 未验证 否 SessionEnd 和 Interrupt 提交所有尚未提交的消息,包括 Stop 已经发送的。Interrupt 的捕获和提交共用 2 秒请求预算,捕获慢时提交留给同一会话的下一次提交
CodeBuddy Code 视情况 否 否 否 否 SessionEnd 只在交互式 TUI 触发,会提交所有尚未提交的消息,包括 Stop 已经发送的;headless 运行依赖阈值或 /compact。捕获由分离的 worker 完成,hook 自身的超时不会波及它
OpenCode 视情况 视情况 视情况 视情况 否 v1 1.15.11+ 的 dispose 和 v2 cleanup 会提交所有会话,但宿主留给清理的时间有限,慢请求或会话较多时可能被截断。v2 cleanup 还会在空闲 60 分钟和插件热重载时运行
DSH 提交 提交 提交 否 否 teardown 给每个会话一次 3 秒的提交,排在慢写入之后,整体处于 5 秒的进程宽限期内。第二次 Ctrl+C 会强制退出,跳过提交。Web 形态下关闭浏览器标签页不会触发 teardown
pi,takeover 开 否 否 否 否 否 session_shutdown 保存 takeover 状态但不提交。等下次运行达到阈值,或执行 /viking commit
pi,takeover 关 提交 提交 提交 提交 否 失败的提交进入离线队列
OpenClaw 否 否 否 否 否 session_end 处理器不提交。归档依赖 /new、/reset 和阈值
Hermes(内置) 视情况 视情况 视情况 视情况 否 退出处理器最多用 10 秒等待上传完成,然后提交;上传没有完成就跳过提交,不提交半个会话。SIGTERM 和 SIGHUP 默认有 1.5 秒宽限期,Hermes 的退出看门狗可能中断较慢的提交
LangChain、Open WebUI、Agent Plugins、MCP 客户端 否 否 否 否 否 没有会话 hook。MCP 代理退出时发送的 DELETE /mcp 只关闭协议会话。LangChain 依赖调用方的 close()

这张表的实际含义:

  • 正常退出时会提交:Claude Code、Codex 0.145+、OpenCode、DSH、takeover 关闭的 pi,以及 Hermes。其他集成依赖最后一列的回收方式。
  • kill -9 之后没有任何集成会提交。已写入的消息保持未提交,直到该会话的下一次提交。带空闲超时的服务端自动提交策略是唯一的服务端兜底,而插件不会配置它。
  • TRAE、TRAE CN 和 ZCode 的退出行为最简单,因为每轮都提交;代价是每个 Stop 都要做一次完整的归档和抽取。

离线重试

集成 写入失败时
Claude Code、CodeBuddy Code、TRAE、TRAE CN、ZCode、Kimi Code、OpenCode、DSH、pi 可重试的失败进入 ~/.openviking/pending 下的磁盘队列,在会话开始时重放:每次最多 50 条,每条最多 3 次,保留 7 天。网络错误、408、429 和 5xx 可重试;其他 4xx(含 401 和 403)不入队。某条消息重放失败时停止,以保证顺序
Cursor 新捕获不入离线队列。文本 transcript 与本地工具记录保留未上报内容,服务端确认后才推进进度;同一会话后续采集重试。消息未传完整时不提交。SessionStart 仍重放旧队列中的写入
Codex、TraeCode CLI 2.0 新捕获的内容不入队。transcript 游标只越过服务端已接受的消息,下次捕获或启动扫描会重发剩余部分。SessionStart 仍会重放已排队的条目
OpenClaw 没有队列,失败的轮次不会重发
Hermes(内置) 上传在进程内线程中运行,不从磁盘重放。$HERMES_HOME/openviking/pending_sessions/ 下的待提交标记让之后的启动能提交已退出进程留下的会话(仅 POSIX)
LangChain 提交失败时在下一次 record 时重试,只保存在内存中。部分写入会抛出 OpenVikingPartialWriteError,附带计数,调用方可据此重试剩余消息
日志导入 SQLite 游标库在发送前记录每批数据。崩溃后,下次运行根据服务端的消息数判断这批数据是否已送达

子代理

集成 子代理处理
Claude Code 每个子代理有自己的会话 cc-<id>__subagent-<agent_id>。SubagentStop 发送它的 transcript 并提交
Codex、TraeCode CLI 2.0 子代理输出并入主会话
OpenCode 子代理使用 oc-<parent>__subagent-<child> 会话。会话开场上下文对它们跳过,召回不跳过
DSH 每个子代理是单独的 dsh-<id> 会话,与父会话没有关联,各自获得会话开场上下文
Hermes 委派任务以 skip_memory=True 运行,子代理没有 OpenViking 会话、召回或工具,输出也不会被捕获
Cursor、TRAE、ZCode、Kimi Code、pi、OpenClaw 没有特殊处理。有独立会话 ID 的子代理有自己的会话,否则消息并入主会话。OpenClaw 可以用 bypassSessionPatterns 排除会话
日志导入 Claude Code 适配器跳过 sidechain 和 meta 记录,子代理对话不会导入

宿主压缩

宿主缩减上下文时,多数集成只确保被丢弃的消息已经提交,摘要由宿主生成。pi 和 OpenClaw 可以用 OpenViking 的归档替换宿主的摘要。

集成 方式 压缩前 压缩后
Claude Code 宿主摘要 PreCompact 同步提交;这是唯一不在后台运行的写入,因为宿主紧接着就会重写 transcript source="compact" 的 SessionStart 注入归档概览和最多 5 条摘要
Codex、TraeCode CLI 2.0 宿主摘要 PreCompact 补齐未捕获的轮次,提交全部内容,并开始一个新的 OpenViking 会话。补齐不完整时不提交,稍后重试 resume 时注入归档摘要
Cursor 宿主摘要 preCompact 提交 无
CodeBuddy Code 宿主摘要 PreCompact 提交 无
TRAE、TRAE CN、ZCode 宿主摘要 没有压缩前事件 无
Kimi Code 宿主摘要 PreCompact 提交 无
OpenCode 宿主摘要 v1 刷新并提交;v2 捕获 transcript v1 在 session.compacted 时再提交一次;v2 在 session.compaction.ended 后提交
DSH 宿主摘要 compaction/start 无论 token 阈值如何都会提交。注入的上下文是一条用户消息,随宿主压缩一起缩减;profile 不再发送 无
pi takeover,默认开启 提交并等待归档概览 用概览替换 pi 的摘要;失败时 pi 照常压缩
OpenClaw 插件接管压缩 compact() 提交并等待 下一次上下文组装从服务端重建历史
Hermes(内置) 宿主摘要 fork 型压缩提交旧会话;原地压缩不做任何处理 无

pi takeover

  • 改变了什么。pi 自己的历史不会被修改。扩展改写每次 context 事件中发送的消息:边界之前的内容合并成一条合成用户消息 [OpenViking Session Context],内容是截到 3,000 token 的归档概览。它的时间戳取第一条保留消息之前的时刻,让发给 provider 的请求保持稳定,prompt 缓存继续生效。
  • 何时运行。由 token 压力触发,而不是 pi 的压缩事件:约 30,000 token,保留最近 3 个用户轮。提交时把这 3 轮对应的确切消息数作为 keep_recent_count 发送。
  • 摘要来源。该次提交产生的归档概览,每 2 秒轮询一次,最多 15 次。边界作为 ov-takeover 条目存在 pi 的 branch 中,重启后仍然有效。
  • 何时回退。指纹不匹配、历史短于边界或缺少概览时,pi 使用完整历史。如果概览一直为空,边界不移动,待提交计数归零,重新累积后再试。
  • pi 自己的压缩。takeover 成功时,session_before_compact 把 OpenViking 摘要返回给 pi。没有 firstKeptEntryId 时,pi 执行默认压缩。

OpenClaw 上下文引擎

  • OpenClaw 把插件注册为上下文引擎,并设置 ownsCompaction: true,宿主不再自己生成摘要。
  • 上下文组装分两部分。transformContext 只添加召回,前面有五道 passthrough 检查。主组装调用 getSessionContext(tokenBudget),用服务端的返回替换宿主的实时历史,按四档预算切分,前面有三道 passthrough 检查和一个消息清洗步骤。
  • compact() 以 keep_recent_count 0 提交,每 500 ms 轮询一次,最多 5 分钟,然后把归档概览作为摘要返回。
  • ingest() 和 ingestBatch() 有意不做任何事;对话在每轮结束后捕获。
  • 存在归档时,system prompt 会加入一段简短指引,要求模型在回答“没有相关信息”之前先重读摘要,并用 ov_archive_search 至少尝试两组关键词。

pi 与 OpenClaw 接管对比

pi takeover OpenClaw 上下文引擎
宿主契约 在 context 事件中改写消息 上下文引擎,ownsCompaction: true
历史来源 pi 本地的 branch 服务端的会话上下文
触发 客户端 token 阈值(30,000,保留最近 3 个用户轮) 宿主每次调用 assemble 或 compact
结果 一条合成用户消息,最多 3,000 token 重建的消息列表,加上压缩摘要
失败时 完整历史 宿主的实时消息
召回 带会话 ID 的 context 检索 不带会话 ID 的 /find,没有扩写和去重

服务端不可用时

召回出错时,宿主可以在没有注入记忆的情况下继续。但请求仍可能让提问一直等到请求结束或到达截止时间;出错后能继续,不代表不用等待。

集成 服务端不可达 缓存的失败状态 等待与错误传递
Claude Code 每个 hook 捕获错误并让宿主继续;会话开始时跳过队列重放 context 检索标记 6 小时,本地 CLI 检测 7 天,健康状态 5 秒 召回等到请求结束或截止时间后再继续。URI guard 的拒绝是有意设计,与召回失败无关
Codex、TraeCode CLI 2.0 每个 hook 捕获错误,不做任何处理 context 检索标记;本地压缩器失败后停用到下次启动 召回等到请求结束或截止时间,然后提问继续
Cursor、TRAE、TRAE CN、ZCode 请求错误被吞掉,不注入任何内容。5 秒内拿不到锁的 hook 静默跳过 只有 context 检索标记,所以每轮都要等满 15 秒召回超时 每轮最多等到召回超时
OpenCode 召回、捕获和清理的错误被捕获并记录日志 context 检索标记;健康检查不缓存 召回会等待网络请求;清理也可能等到截止时间
CodeBuddy Code 每个 hook 捕获错误并让宿主继续 context 检索标记;每次 hook 各自做健康检查 召回等到自己的请求结束后继续
DSH 插件吞掉错误。会话初始化失败不缓存,所以每个 pre-step 会发两次 5 秒的健康检查 context 检索标记;用户空间查询结果在进程生命周期内缓存 pre-step 依次执行 profile 和召回,会话 flush 会阻塞
pi 启动时健康检查失败则不注册工具,之后的提问静默重试。只有 MCP 握手失败时,召回、同步和 takeover 不受影响;状态栏显示 tools ✗,/viking 打印错误 context 检索标记。MCP 握手每轮重试一次,召回开始前可能用掉 5 秒的握手预算 召回等到请求结束或截止时间。不开 takeover 时 session_shutdown 最多等 30 秒;turn_end 遇到网络错误时每条消息等 10 秒
OpenClaw 500 ms 健康检查失败时跳过召回 无;每轮一次健康检查 只有 memory_store 的错误会返回给模型;compact() 最多可能等 5 分钟
Hermes(内置) 失败的连接在 30 秒内不重试,除非连接设置改变 记住失败的设置 召回在 4 秒总预算内等待,然后不带上下文继续
ov CLI 多数命令以状态码 1 退出;表格模式的 ov status 和 ov health 即使不健康也退出 0 无 不适用

共享超时与锁

共享插件的 HTTP 超时为 15 秒(最小 1 秒)。MCP 代理请求 15 秒超时,退出时发送的 DELETE /mcp 为 2 秒。跨进程锁等待 5 秒,60 秒后视为过期;正在重放的队列条目 10 分钟后被回收。MCP 代理不处理 SIGHUP,关闭终端时不会发送 DELETE /mcp;服务端以无状态方式运行 MCP,不会留下残留状态。

安装、会话与配置

从会话 ID 前缀可以看出服务端上的会话由哪个集成写入。

集成 安装方式 会话 ID 配置来源
Claude Code 统一安装器(--harness claude)或插件市场 cc-<session id>;子代理 cc-<id>__subagent-<agent_id> 共享配置,plugin.claude_code
Codex 统一安装器(--harness codex)或 codex plugin marketplace add cx-<id>,由 Codex 会话推导 共享配置,plugin.codex
TraeCode CLI 2.0 统一安装器(--harness trae-cli),对 traecli 执行 Codex 的安装流程 同 Codex 同 Codex
Cursor 统一安装器;写入 ~/.cursor/hooks.json 和 mcp.json cu-<conversation id> 共享配置,plugin.cursor
TRAE、TRAE CN 统一安装器;写入 ~/.trae/ 或 ~/.trae-cn/ 下的 hook 与 MCP 文件 tr- 或 trcn- 共享配置,plugin.trae 或 plugin.trae_cn
ZCode 统一安装器;合并进 ~/.zcode/cli/config.json 并开启 hook zc-<id> 共享配置,plugin.zcode
Kimi Code 统一安装器;Kimi Code 托管插件 kc-<id> 共享配置,plugin.kimicode
CodeBuddy Code 统一安装器,由其注册本地 marketplace cb-<id> 共享配置,plugin.codebuddy
OpenCode 统一安装器、npm(@openviking/opencode-plugin)或源码 oc-<id>;子代理 oc-<parent>__subagent-<child> 共享配置,plugin.opencode
DSH 统一安装器、dsh plugin add @openviking/dsh-memory-plugin 或 Desktop 的插件页 dsh-<id> 共享配置,plugin.dsh,然后是 Cordis patch
pi 统一安装器,装入 pi 的扩展目录 pi-<id> 共享配置,plugin.pi
OpenClaw ClawHub、npm 安装器或离线包;之后运行 openclaw openviking setup 会话 UUID,或会话 key 的 SHA-256 openclaw.json 和少量环境变量
Hermes(内置) 随 Hermes 发布;运行 hermes memory setup openviking Hermes 自己的会话 ID .env、关联的 ovcli.conf 和 Hermes config.yaml
ov CLI npm、uv tool install、cargo 或 GitHub Releases 不管理 ovcli.conf profile

“共享配置”指配置与工作区文件中分层的插件配置。

统一安装器

examples/memory-plugin-shared/install.sh 安装 Claude Code、Codex、TraeCode CLI 2.0、Cursor、TRAE、TRAE CN、ZCode、Kimi Code、OpenCode、pi 和 DSH。OpenClaw 和 Hermes 有各自的安装渠道。需要知道的几点:

  • 不带 --harness 时显示多选菜单。各插件自带的 setup 脚本会替你传入 --harness。通过 curl 管道执行时,从 /dev/tty 读取输入。
  • 从文档站下载;在仓库 checkout 中运行时,使用本地 checkout。
  • hook 和 MCP 条目带有 OPENVIKING_INTEGRATION_ID 标记,重新运行只替换自己的条目,不动其他工具的条目。每个被修改的文件先备份为 .bak,再以 0600 权限原子替换。
  • 凭据步骤为本地服务端、OpenViking Service 或自定义 URL 写入 ~/.openviking/ovcli.conf。已有配置会先显示当前值(API key 打码),再让你选择保留或修改。
  • --uninstall 支持 Cursor、TRAE、TRAE CN、ZCode 和 Kimi Code。其他集成通过宿主自己的插件管理卸载。
  • 需要 Node.js 18 或更高版本。

凭据来源

一共有四套凭据体系,各自使用不同的变量名和请求头。连接失败时,先确认集成用的是哪一套。

使用方 服务端 URL API key 身份 认证头
共享插件代码:Claude Code、CodeBuddy Code、Codex、Cursor、TRAE、ZCode、Kimi Code、OpenCode、DSH、pi、Agent Plugins OPENVIKING_URL,其次 OPENVIKING_BASE_URL OPENVIKING_BEARER_TOKEN,其次 OPENVIKING_API_KEY OPENVIKING_ACCOUNT、OPENVIKING_USER、OPENVIKING_PEER_ID 只有 Authorization: Bearer
OpenClaw OPENVIKING_BASE_URL,其次 OPENVIKING_URL OPENVIKING_API_KEY 或 SecretRef OPENVIKING_ACCOUNT_ID、OPENVIKING_USER_ID X-API-Key
Hermes OPENVIKING_ENDPOINT OPENVIKING_API_KEY OPENVIKING_ACCOUNT、OPENVIKING_USER、OPENVIKING_AGENT 同时发送 X-API-Key 和 Bearer。有 key 时不发租户头,服务端要求时补发并重试一次
ov CLI ovcli.conf ovcli.conf --account、--user、--actor-peer-id X-API-Key;按 auth_mode 使用 Basic 或 Bearer。含两个及以上点号的 key 也会以 Bearer 发送

共享插件代码的规则:

  • OPENVIKING_CREDENTIAL_SOURCE(env、cli 或 auto,默认 auto)决定凭据来源。auto 下,环境中只要有任一凭据变量就以环境为准;只有一个都没设、且 ovcli.conf 中有凭据时,插件才改用该文件。env 不读任何文件,URL 默认为 http://127.0.0.1:1933。
  • hook 和 MCP 代理用同一个函数解析连接,且都不读取工作目录,所以从插件目录启动的代理与 hook 连到同一个服务端,使用同一身份。
  • X-OpenViking-Account 和 X-OpenViking-User 只在 trusted 模式下发送。使用 API key 时,服务端从 key 中读取身份。

完整的解析顺序见客户端配置字段和插件开发指南。

配置与工作区文件

基于共享插件代码的集成按以下优先级(从高到低)读取行为配置:OPENVIKING_* 环境变量、每机工作区注册表、仓库的 .openviking/config.local.json 和 .openviking/config.json、ovcli.conf 的 plugin.<harness>、ovcli.conf 的 plugin,以及 ov.conf 中旧的 harness 段。工作区文件不能设置 URL、key 或其他凭据。见插件配置和工作区配置。OpenClaw 读取 openclaw.json,Hermes 读取自己的 .env 和 config.yaml。

工作区 peer。这些集成默认用仓库规范化后的 origin URL 推导一个 peer 来标记记忆,所以同一仓库的所有 clone 共用一个 peer。不在仓库中时不发送 peer,记忆进入用户自己的空间。可以用 peer.source 和 .openviking/config.json 修改,见工作区 peer。OpenClaw 根据 peer_role 和 peer_prefix 推导 peer;peer_role=sender 时,如果宿主没有提供发送者,工具调用会失败。Hermes 默认不设助手 peer,除非由 OPENVIKING_AGENT、关联的 OpenViking peer 或 YAML 的 agent 键设置。Agent Plugins 不发送 peer。

只对部分集成生效的设置:

  • OPENVIKING_COMMIT_TURN_THRESHOLD:Cursor 和 Kimi Code。TRAE、TRAE CN 和 ZCode 每轮都提交。
  • OPENVIKING_WRITE_PATH_ASYNC:Claude Code、Codex 和 ZCode。
  • OPENVIKING_RECALL_COMPRESS=client:Claude Code 和 Codex。server 和 auto 适用于召回摘要中列出的所有集成。
  • 工作区文件、ovcli.conf 的 plugin 段、OPENVIKING_RECALL_DEDUP_TURNS、OPENVIKING_RECALL_QUERY_EXPANSION、OPENVIKING_PEER_SOURCE 和 skill 清单相关设置:所有基于共享插件代码的集成,不包括 OpenClaw 和 Hermes。

其他宿主功能

集成 状态栏 命令 附带的 skill 配置向导
Claude Code 有 /openviking-memory:ov 显示服务端状态、身份和注入内容的来源 openviking-memory、openviking-skills、ov-experience-memory、ov-memory-doctor 有
Codex、TraeCode CLI 2.0 无 无 与 Claude Code 相同的四个 有
Cursor 无 无 一条常驻 rule,加上 openviking-memory、openviking-skills、ov-experience-memory 安装器菜单
TRAE、TRAE CN、ZCode 无 无 无 安装器菜单
OpenCode 无 无 与 Cursor 相同的三个,仅在插件注册自己的 MCP 服务时提供 有
DSH 无 无 与 Cursor 相同的三个 无
CodeBuddy Code 无 无 与 Cursor 相同的三个 无
pi 有 /viking、/viking commit 与 Cursor 相同的三个,mcpEnabled 为 false 时不提供 有
OpenClaw 无 /add-resource、/add-skill、/ov-search、/ov-query-config、/ov-recall-trace 三个插件 skill 有;检查 key 的角色和版本兼容性
Hermes(内置) 无 无 无 有;hermes memory status 列出环境变量覆盖项
ov CLI 无 CLI 本身 无 ov config

Claude Code、Cursor、TRAE、ZCode、Kimi Code、DSH 和 pi 还会安装 URI guard:文件工具的路径是 viking:// URI 时,调用会被拒绝,并提示改用 OpenViking 工具;shell 命令中包含这种 URI 时照常执行,但附带一条提示。各宿主检查哪些工具不同,见各集成说明。

各集成说明

这里只写每个集成特有的内容,共享行为见上文各节。

Claude Code

Claude Code。插件市场插件,包含 9 个 hook、一个 MCP 代理、一个斜杠命令、状态栏和 4 个 skill。

  • 注册的 hook 比其他集成都多:SessionStart、UserPromptSubmit、PostToolUse:Read(skill 经验 hook,默认关闭)、作用于 Read、Glob、Grep、Edit、Write 和 Bash 的 PreToolUse(URI guard)、Stop、PreCompact、SessionEnd、SubagentStart 和 SubagentStop。
  • 召回摘要默认通过本地 claude -p 生成,服务端摘要作为回退。
  • 除 kill -9 外,所有退出方式都会发出提交。
  • 捕获游标保存在 /tmp 下。系统清理后,整个会话会重新发送。
  • 插件自身的开关关闭时,URI guard 仍然运行。

Codex 与 TraeCode CLI 2.0

Codex、TRAE。插件市场插件,包含 6 个 hook(SessionStart、UserPromptSubmit、Stop、SessionEnd、PreCompact、PostToolUse)、一个 MCP 代理,以及与 Claude Code 相同的 4 个 skill。

  • SessionEnd 只在干净退出且 Codex 0.145 及以上时触发。信号、崩溃、旧版本和 codex app-server 延后的情况都交给启动时的扫描,扫描使用 30 分钟空闲超时。
  • Stop 和 SessionEnd 在分离的 worker 中写入。每个会话一把锁,按顺序处理 Stop worker、PreCompact、SessionEnd worker 和扫描。
  • 不安装 URI guard。Codex 会把 PreToolUse 的提示写在工具调用和它的输出之间,火山方舟 Ark 这类按 chat 消息校验历史的 Responses 服务端会因此返回 HTTP 400。
  • Codex 为每个 hook 保存信任记录。升级新增 hook 后,需要在 /hooks 中批准新的 hook。
  • TraeCode CLI 2.0(可执行文件 traecli,配置 ~/.trae/traecli.toml)是 Codex 系 CLI,安装同一个插件。只支持 2.0;早期面向 1.0 的独立插件已移除,--harness trae-cli --uninstall 仍可删除旧安装留下的副本。不带 SessionEnd 的版本会忽略该 hook。

Cursor

Cursor。hook 与 MCP 配置,包含 7 个 hook(sessionStart、beforeSubmitPrompt、beforeReadFile、afterMCPExecution、stop、preCompact、sessionEnd)、一条常驻 rule 和 3 个 skill。

  • URI guard 只在 beforeReadFile 运行,不受插件开关影响。shell 命令不检查,升级会移除旧版本注册的 beforeShellExecution 条目。
  • afterMCPExecution 保留 OpenViking 工具完成记录,Stop 与对话一起上报。成功读取的 Experience 可关联到同次提交生成的轨迹;失败、未完成调用和自动注入不计为成功读取。
  • sessionEnd 只在关闭窗口时触发,此时 Cursor 已停止执行 hook 命令,因此实际不会提交。
  • 服务端不可达时,每轮都要等满 15 秒召回超时。

TRAE 与 TRAE CN

TRAE。hook 与 MCP 配置,包含 4 个 hook:SessionStart、UserPromptSubmit、PreToolUse 和 Stop。MCP 服务名为 openviking。

  • PreToolUse 拒绝对 viking:// 路径执行 Read、Glob 和 Grep;Bash 和 RunCommand 命令中包含这种路径时附加提示。
  • 每个有内容的 Stop 都会提交,退出时最多丢失正在进行的那一轮。
  • TRAE 和 TRAE CN 只有会话前缀和安装路径不同。同样的工作在两个客户端中会产生不同的会话,要等抽取完成后才共享记忆。
  • 不处理压缩,没有状态栏和 skill,也不单独处理子代理。

ZCode

社区插件:ZCode。hook 与 MCP 配置,包含 4 个 hook:SessionStart、UserPromptSubmit、作用于 Read、Glob 和 Grep 的 PreToolUse,以及 Stop。

  • 捕获的轮次来自 rollout 文件 ~/.zcode/cli/rollout/model-io-<sid>.jsonl;漏掉的 Stop 对应的轮次在下一个 Stop 补齐。
  • 第一次捕获读取整个 rollout,所以在长时间运行的会话中安装会产生一次大上传。
  • 捕获只去掉注入块,不做其他文本清理。
  • Stop 默认在分离的 worker 中写入。

Kimi Code

社区插件:Kimi Code。Kimi Code 托管插件,包含 7 个 hook(SessionStart、UserPromptSubmit、作用于 Read、Glob 和 Grep 的 PreToolUse、Stop、PreCompact、SessionEnd、Interrupt)和一个 MCP 代理。安装器在 $KIMI_CODE_HOME/plugins/managed/openviking-memory 下构建一份自包含的副本。

  • 捕获的轮次来自 wire.jsonl。一轮对话只有在发送成功或存入离线队列后才会推进游标。
  • 会话开场上下文在首次提问时注入,失败后在后续提问中重试,直到成功。
  • Stop、PreCompact 和 SessionEnd 可以在后台写入。Interrupt 保持同步,请求预算 2 秒。
  • UserPromptSubmit 返回纯文本上下文,不是 JSON。
  • 安装时保留其他插件记录,不修改旧的 config.toml 或 mcp.json。

CodeBuddy Code

CodeBuddy Code。带 6 个 hook、一个 MCP 代理和 3 个 skill 的插件,由统一安装器以本地 marketplace 的形式安装;与 ZCode、Kimi Code 一样是 agent-hook-plugin 的宿主适配器。

  • UserPromptSubmit 与 SessionEnd 只在交互式 TUI 触发。headless 运行(-p、--input-format stream-json)只在 Stop 捕获,永远不发收尾提交。
  • URI guard 会拒绝路径为 viking:// URI 的文件类工具。拒绝以「工具调用失败」的形式到达模型;allow 携带的文字到不了模型,因此本宿主没有劝告通道。Shell 命令不做检查,ov 调用与字面量 viking:// 参数照常可用。
  • SessionStart 不带 cwd,且同一会话内可能投递两次,因此该 hook 是幂等的,并以进程工作目录兜底。
  • Hook 超时被杀时不会连带杀掉它的子进程——这正是提交能在 hook 进程返回后在分离的 worker 中完成的原因。
  • v1 不支持子代理采集,与其他社区适配器一致:宿主会触发这些事件,但共享 dispatcher 目前没有子代理阶段。

OpenCode

OpenCode。npm 插件 @openviking/opencode-plugin 用同一个入口支持 OpenCode v1(1.15.7 及以上)和 v2(2.0.15 及以上)。

  • v2 每次提问只召回一次,把结果存进用户消息的 metadata;后续模型 step 直接复用,不发新请求,prompt 缓存因此保持稳定。每次执行结束时,v2 读取完整的用户、助手和工具消息用于捕获。
  • v2 在每次执行结束后检查提交阈值,包括失败和被中断的执行,这些执行会保留状态。v2 只处理本 location 的会话,游标存在插件 storage 中。v2 没有 toast API,改为写日志。
  • MCP 工具保留 openviking_ 前缀;v2 设置 codemode: false。3 个 skill 只在插件注册自己的 MCP 服务时加入,hook-only 模式或关闭 mcp.openviking 时不加入。
  • 提交超时 30 秒。

DSH

DeepSeek Harness。唯一的同进程 Cordis 插件。hook 直接调用 REST API;工具通过 @deepseek-ai/dsh-mcp-client 和共享的 stdio 代理接入。

  • 监听 agent/session-start、agent/pre-step、session/event、session/flush、tools/pre-execute 和 tools/post-execute。
  • ctx.provide("openvikingMemory") 让其他 Cordis 插件可以在它之上构建功能。
  • 安装器默认使用 web profile,可以用 --dsh-profile 指定其他 profile。在 macOS 上,它还会把 DeepSeek Harness Desktop 的 desktop profile 作为单独的 harness dsh-desktop,通过 Desktop 自带的 dsh 命令安装(见 DeepSeek Harness Desktop)。除 dev 外的所有模式都安装已发布的 npm 包。
  • 默认捕获工具结果(captureToolResults: true),所以 ov-experience-memory 能完整运行;关闭捕获后,只能检索和应用 Experience。
  • URI guard 先把工具名转成小写,在 tools/pre-execute 拒绝对 viking:// 路径的文件工具调用,在 tools/post-execute 为包含这种路径的 bash 命令(Windows 上是 pwsh 命令)附加提示。
  • Cordis patch 中写明的凭据优先于其他所有来源;对行为配置来说,patch 是优先级最低的一层。

pi

pi。原生扩展,包含 9 个事件处理器和 /viking 命令。召回、同步、会话开场上下文和 takeover 使用 REST;工具使用 pi 内置的 MCP 客户端。

  • 工具就是服务端 tools/list 返回的内容,重命名为 openviking_<tool>。服务端增删工具后,pi 在下一个会话生效,不需要扩展发版。
  • 从 0.3.x 升级时,所有工具都从 viking_* 改了名,没有别名过渡期。请更新 --tools 或 --exclude-tools 列表,否则工具会静默消失。
  • openviking_read 返回文件内容,支持 offset 和 limit。目录 URI 会返回错误。旧的 level="abstract" 和 "overview" 读取在 MCP 中没有对应工具,可改用 openviking_search(mode="context", detail="overview") 或 openviking_tree(include_abstract=true)。
  • 工具调用 15 秒超时(OPENVIKING_TIMEOUT_MS)。超时或按 ESC 只让本地调用失败,已发出的请求会继续执行,写入仍可能生效。
  • tool_call 拒绝对 viking:// 路径执行 read、grep、find、ls、write 和 edit;tool_result 为包含这种路径的 bash 输出附加提示。
  • takeover 关闭时,用 pi -c 恢复会话会重新发送整个 branch。
  • bypass 使用 bypassSessionPatterns;旧的 bypassPatterns 仍然有效。

OpenClaw

OpenClaw。接管压缩的 context-engine 插件,包含 15 个工具、5 个斜杠命令、生命周期 hook、Gateway HTTP 路由,以及受功能开关控制的 RPC 方法。

  • memory_recall 检索记忆,ov_search 检索资源和用户的 skill;通过显式参数,两个工具都能查另一类内容。
  • 召回通过 /find 进行,不带会话 ID,所以没有查询扩写和去重,长会话中同一条记忆可能被重复注入。默认每条召回的记忆多一次 read(recallPreferAbstract=false)。
  • 退出不提交。归档依赖 /new、/reset 和阈值。没有离线队列,失败的轮次不会重发。
  • compact() 最多可能阻塞 5 分钟。
  • 配置严格校验:有未知键或非法值时,插件进入 setup-only 模式。
  • 提交阈值是 tokenBudget(默认 128,000)乘以 commitTokenThresholdRatio(默认 0.5)。

Hermes

Hermes。Hermes 通过两种分发方式提供名为 openviking 的 memory provider:

  • 目录插件在本仓库的 examples/hermes-plugin 中维护。先运行 hermes plugins install openviking --enable,再运行 hermes memory setup openviking。
  • 内置 provider 存在于旧版 Hermes 的 plugins/memory/openviking 中, 无需安装。本页的 Hermes 行描述 Hermes 提交 989798c 时的内置 provider。

仍包含内置 provider 的版本会优先加载内置副本。当更新移除内置副本时,已配置 OpenViking 的 profile 会自动尝试安装目录插件。provider 名、配置和已存数据均保持不变。

两者是独立的代码库。行为差异如下:

内置 provider(Hermes 989798c) 外部插件(本仓库)
会话中的提交 无,只在会话边界 待提交 token 达到 20,000 时后台提交(commit_token_threshold)
召回摘要 不支持 可选的服务端摘要(recall_compress)
镜像 Hermes 内置记忆 只同步新增 同步新增、替换和删除,用 URI 注册表跟踪
viking_forget 带明确用户 ID 的用户记忆文件 还接受 viking://~/,拒绝不带用户 ID 的路径,删除前检查归属
cron、子代理和 flush 上下文 该提交中没有说明 召回可用;跳过自动写入和镜像

上述固定提交中内置 provider 的行为:

  • 每次模型调用前召回,走带会话的 search/search,以 /find 作为回退。默认值:6 条结果、分数阈值 0.15、4,000 字符、总计 4 秒、单请求 3 秒。
  • viking_remember 把事实原样通过独立会话发送并提交,返回 status: submitted。
  • 提交不保留消息(keep_recent_count 0)。上传不持久化,但在 POSIX 上,待提交标记让之后的启动能提交已退出进程留下的会话。
  • 记忆写入 viking://user/<uid>/memories/;设置了 peer 时写入 viking://user/<uid>/peers/<peer>/memories/。
  • 关联 OpenViking 的 ovcli.conf profile 会清除 Hermes .env 中的 5 个连接变量。hermes backup 会包含 $HOME 下默认或由环境变量指定的 ovcli.conf;通过 YAML 关联的文件需要单独备份。

ov CLI

安装与使用 CLI。ov 是 REST API 的 Rust 客户端,没有宿主事件、自动召回或压缩处理;每个动作都是由你或脚本执行的命令。运行 ov --help 查看命令列表,JSON 输出见 CLI 输出格式。

CLI 提供而插件没有的能力:多个 ovcli.conf profile、账户与用户管理(ov admin)、用 --sudo 执行 root 操作、隐私策略管理(ov privacy)、快照、备份与恢复、导出与导入、ov reindex、在本地生成 root key(ov system crypto init-key)、ov tui 文件浏览器,以及会话自动提交策略(ov session new --auto-commit-policy-json、ov session config set)。其中的服务端操作也可以通过 HTTP API 和 SDK 完成。

在脚本中需要注意:

  • ov rm 不确认就删除;-r 递归删除。
  • 服务端报告不健康时 ov health 仍退出 0,表格模式的 ov status 始终退出 0。
  • echo_command 开启时(默认开启),find、search、ls、tree、grep 和 glob 会先在标准输出打印一行 cmd: … 再输出结果,使用 -o json 时也是如此。
  • 大多数命令在 compact JSON 模式下输出 {"ok": true, "result": …} 或 {"ok": false, "error": …};ov config 系列命令输出 {"status": "ok", "result": …}。
  • 运行命令前必须配置显示语言;在非交互 shell 中未配置时,CLI 以状态码 2 退出。
  • ov doctor 只存在于用 uv tool install openviking 安装的 Python 包中,用于检查服务端的 ov.conf。npm 和 cargo 安装的二进制不包含它。

自建集成

如果你的 Agent 不在上面的列表中,按需要的行为选择工作量最小的方式:

方式 工作量 Agent 可用的工具 自动召回与捕获 提交
通过 MCP 连接 几分钟 服务端 MCP 工具 无;由模型自己调用工具 只有 remember,在它自己的会话中
Agent Plugins 插件包 几分钟 服务端 MCP 工具,外加一个教模型使用这些工具的 skill 无 只有 remember
HTTP API、SDK 或 LangChain 几小时 取决于你调用的接口 自己实现,或使用 LangChain 中间件 由你决定
复用共享插件代码 几天 通过代理使用服务端 MCP 工具 召回、捕获、提交和离线队列 取决于你接入的宿主事件

通过 MCP 连接

支持 Streamable HTTP 的客户端可以连接服务端的 /mcp。下面的示例使用常见的 mcpServers 格式;其他客户端的字段见 MCP 客户端。

{
  "mcpServers": {
    "openviking": {
      "url": "http://127.0.0.1:1933/mcp",
      "headers": {
        "Authorization": "Bearer <api_key>"
      }
    }
  }
}

使用用户或管理员 API key,服务端从 key 中读取账户和用户。X-OpenViking-Account 和 X-OpenViking-User 只在 trusted 身份模式下生效,不能覆盖普通 key 的身份。需要工作区 peer 上下文时,添加 X-OpenViking-Actor-Peer,见认证。只支持 stdio 的客户端可以使用 Agent Plugins 代理。直接通过 MCP 连接没有自动召回、捕获或提交。

调用 HTTP API 或 SDK

  • REST。召回用 POST /api/v1/search/search;查询扩写和去重需要 mode: "context"、session_id 和 dedup_turns(见召回请求如何到达服务端),rewrite 用于请求召回摘要。写入用 POST /api/v1/sessions/{id}/messages/batch(最多 100 条,会自动创建会话),提交用 POST /api/v1/sessions/{id}/commit,读取用 GET /api/v1/content/read。见会话和检索。服务端自动提交见服务端会话与提交机制。
  • LangChain 与 LangGraph(pip install langchain-openviking)。OpenVikingContextMiddleware 在模型调用前把召回内容注入 <openviking_context>,在 Agent 运行后按 CommitPolicy(默认 never)捕获并提交。只读调用重试一次,写入从不重试。部分写入会抛出 OpenVikingPartialWriteError,附带重试剩余部分所需的计数。见 LangChain / LangGraph。
  • Open WebUI。python -m openviking_openwebui 启动一个独立的 OpenAPI 工具服务器,提供 7 个工具,没有删除工具和 hook。见其他集成。

复用共享插件代码

需要自动召回、捕获、提交和离线重试时,复用现有代码,不必重写:

  • examples/memory-plugin-shared/lib/(Node.js)包含共享模块:带回退的召回、会话开场上下文、捕获清理、离线队列、批量发送、MCP 代理、会话 ID 和凭据。通过 hook 文件配置的宿主可以在 examples/agent-hook-plugin/hosts/ 下添加适配器,Cursor、TRAE、ZCode 和 Kimi Code 都是这样接入的。
  • Agent Plugins 插件包(agent-plugins/)由可移植的 plugin.json、skills/ 和 mcp.json 组成,带 stdio 到 HTTP 的代理,没有 hook。它的 plugin.test.mjs 检查是否符合 Agent Plugins 规范,可以作为你自己插件包的 lint 基线。

插件开发指南介绍模块职责、配置、生成副本、安装器和测试。无论构建什么,都遵守以下三条规则,让它的行为与现有集成一致:

  1. 使用带会话 ID 和 dedup_turns 的 context 模式召回,让服务端能扩写查询并跨轮去重。
  2. 不要让适配器自己的超时截断共享代码计算出的截止时间。
  3. 在关闭时提交。否则低于阈值的对话尾部会一直未提交,直到其他事件触发提交。如果宿主没有关闭事件,开启 memory.session_auto_commit.enabled 并为会话设置策略。完成后,在真实宿主中检查退出事件是否触发、写入是否完成。

其他集成

集成 是什么 工具 会话与提交 失败处理 何时生效
Open WebUI 独立的 OpenAPI 工具服务器 7 个:ov_search、ov_recall_memories、ov_add_memory、ov_list_memories、ov_read_resource、ov_add_resource、ov_session_status;没有删除工具 没有会话 不重试,不缓存失败。它的 /health 只回显配置,不连接 OpenViking 你启动进程后
LangChain 与 LangGraph Python SDK 适配层:retriever、tools、store、middleware、recorder create_openviking_tools() 提供 12 个工具;viking_forget 不在默认 agent profile 中 会话 ID 和 thread ID 由调用方提供;CommitPolicy 默认 never 读取重试一次,写入不重试;部分写入抛出结构化错误 你构造它之后
Agent Plugins 带 stdio 到 HTTP MCP 代理的可移植插件包 服务端 MCP 工具;没有 hook,由 skill 告诉模型何时调用 只有 remember 代理在 401 或 403 后用新凭据重试一次,在 400 或 404 后用新 MCP 会话重试一次 客户端加载后
MCP 客户端 直连 /mcp 服务端 MCP 工具 只有 remember 由客户端决定 服务端始终提供
日志导入 openviking-server ingest,在日志所在的机器上运行 无,只导入 会话 ID {prefix}__{harness}__{id};待提交 token 达到 6,000 或空闲 5 秒时提交,keep_recent_count 0 游标库、单实例锁,崩溃后核对服务端消息数 默认关闭;ingest.enabled 和各适配器的 enabled 都要开启。适配器:Claude Code、Codex、Hermes、OpenCode、OpenClaw、Cursor
OpenViking Helper 闭源桌面应用 本页不涉及 本页不涉及 本页不涉及 本页不涉及

源码依据

以上对比依据以下位置核对。需要确认某项限制在你的版本中是否成立时,可以查看这些位置。

  • 服务端 MCP 工具:openviking/server/mcp_endpoint.py,以其中的 @mcp.tool 注册为准。
  • 写入与删除检查:openviking/storage/content_write.py 和 openviking/storage/viking_fs/_access.py。
  • 服务端自动提交:openviking_cli/utils/config/memory_config.py 和 openviking/session/auto_commit_policy.py。
  • 插件配置与默认值:examples/memory-plugin-shared/lib/config-schema.mjs。
  • hook 宿主:examples/agent-hook-plugin/hosts/,对应 Cursor、TRAE、ZCode 和 Kimi Code。
  • pi takeover:examples/pi-coding-agent-extension/lib/takeover-core.mjs。
  • OpenClaw 工具和生命周期 hook:examples/openclaw-plugin/registries/openviking-tools.ts 和 examples/openclaw-plugin/plugin/openviking-lifecycle-hooks.ts。
  • Hermes:Hermes 中链接的旧版内置 provider 固定提交,以及目录插件的 README。

参见