Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
docs(agent-integrations): put install first on the pi and OpenCode pages (#5995)
t0saki2f077bbec00c
diff --git a/docs/en/agent-integrations/10-opencode.md b/docs/en/agent-integrations/10-opencode.mdindex b343c634c..52788cf62 100644--- a/docs/en/agent-integrations/10-opencode.md+++ b/docs/en/agent-integrations/10-opencode.md@@ -4,29 +4,10 @@ Give [OpenCode](https://opencode.ai/) cross-project and cross-session long-termSource: [examples/opencode-plugin](https://github.com/volcengine/OpenViking/tree/main/examples/opencode-plugin)-Tool calls and results are captured as dedicated `tool` parts, and `tool_output` is reported verbatim. Truncation is the server's job: output larger than `tool_output_externalization.threshold_chars` (default `20000`) is written to the session's tool-result store, and the part keeps a synopsis stub plus `tool_output_ref`, so the original stays readable through [`/api/v1/sessions/{id}/tool-results`](../api/05-sessions.md#read-tool-result).--## Prerequisites--- [OpenCode](https://opencode.ai/) 1.15.7+ or 2.0.15+-- Node.js 18+-- An OpenViking HTTP server-- An OpenViking API key when your server requires authentication--Start your OpenViking server first:--```bash-openviking-server --config ~/.openviking/ov.conf-```--In another terminal, check the service:--```bash-curl http://localhost:1933/health-```-## Install+Requirements: [OpenCode](https://opencode.ai/) 1.15.7+ or 2.0.15+, Node.js 18+, and an OpenViking HTTP server — verify with `curl http://localhost:1933/health`. You also need an OpenViking API key when the server requires authentication.+### One-line installer (recommended)OpenCode shares the unified installer with Claude Code and Codex. It asks which harnesses to install and for your OpenViking credentials; every step is idempotent—re-running it is entirely safe.@@ -153,6 +134,8 @@ Restart OpenCode after installation. In an OpenCode session, the plugin should eOpenCode 2 captures the current turn's user message, assistant response, and tool results when each execution ends, and captures the transcript before compaction discards it. It commits at the token threshold, and forces a commit on compaction, session deletion, and plugin cleanup. OpenCode 2 runs cleanup after 60 minutes of inactivity, when the service stops, and when a local plugin is hot-reloaded.+Tool calls and results are captured as dedicated `tool` parts, and `tool_output` is reported verbatim. Truncation is the server's job: output larger than `tool_output_externalization.threshold_chars` (default `20000`) is written to the session's tool-result store, and the part keeps a synopsis stub plus `tool_output_ref`, so the original stays readable through [`/api/v1/sessions/{id}/tool-results`](../api/05-sessions.md#read-tool-result).+OpenCode 1.15.7 does not call plugin disposal hooks. A short-lived v1 CLI run can also exit before asynchronous capture finishes; this behavior predates v2 support. Keep the v1 service running to let idle capture finish. OpenCode 1.18.32 calls the disposal hook when its instance is disposed.Ask OpenCode to search or browse OpenViking memory. Runtime state and errors are written to:diff --git a/docs/en/agent-integrations/11-pi.md b/docs/en/agent-integrations/11-pi.mdindex ef9ed4080..26803a633 100644--- a/docs/en/agent-integrations/11-pi.md+++ b/docs/en/agent-integrations/11-pi.md@@ -4,30 +4,10 @@ Give [pi](https://github.com/earendil-works/pi) cross-session long-term memory aSource: [examples/pi-coding-agent-extension](https://github.com/volcengine/OpenViking/tree/main/examples/pi-coding-agent-extension)-## How it works--- **Session start** builds your OpenViking profile block and restores takeover state, including the branch watermark used by `pi -c`. The block holds your profile, memory indexes, and an `<available-skills>` catalog of your own and account-shared OpenViking skills, and it is added to pi's system prompt on every turn; the model reads a skill's `SKILL.md` with `openviking_read` before following it.-- **Every prompt** runs semantic recall against the OpenViking server and injects matching memories as hidden context.-- **Every turn** captures user and assistant messages (including structured tool calls) into an OpenViking session; takeover mode commits once synced-token pressure crosses the threshold and then keeps only the recent live tail in model context.-- **Context takeover** is enabled by default. The `context` hook injects `[OpenViking Session Context]` from the latest archive overview before recall is added to the latest user turn.-- **Model-callable tools** are whatever the server's MCP `tools/list` returns, each registered under an `openviking_` prefix, including `openviking_find`, `openviking_search`, `openviking_read`, `openviking_list`, `openviking_tree`, `openviking_grep`, `openviking_glob`, `openviking_remember`, `openviking_write`, `openviking_edit`, `openviking_add_resource`, `openviking_add_skill`, `openviking_list_watches`, `openviking_cancel_watch`, `openviking_forget`, `openviking_health`. The extension keeps no tool catalogue of its own, so a server that adds or drops a tool changes pi's tool surface at the next session, with no extension release. The shared `mcpEnabled: false` turns the tool surface off and leaves recall, capture, and takeover running.-- **Skills**: the extension ships `openviking-memory`, `openviking-skills`, and `ov-experience-memory` from its `skills/` directory and adds them through pi's `resources_discover` event, so the model knows when to use which OpenViking tool. They are left out when `mcpEnabled` is `false`.-- The tool handshake never fails startup. If only the MCP handshake fails, REST recall, capture, and takeover can still work. If the server is unavailable or authentication fails, those features also fail or fall back; the bridge retries on a later turn, so a server started after pi is picked up without a restart.-- A footer status segment (`OV ✓ …`) shows connection and capture state, plus `tools ✗` when the handshake failed; the `/viking` command prints status, including the registered tool count or the last handshake error, and `/viking commit` forces a commit.-- Accidental `read`/`grep`/`find`/`ls`/`write`/`edit` calls whose path is a `viking://` URI are blocked with a hint pointing to the matching `openviking_*` tool. A `bash` command that carries a `viking://` URI still runs, and its result ends with a notice suggesting `openviking_read` / `openviking_search`.--Extension 0.4.0 replaced the seven hand-written `viking_*` REST tools with this mirrored surface, with no alias period: a `--tools` / `--exclude-tools` allowlist that pins the old names must be updated by hand, or those tools silently disappear. Some semantics moved with the names — `openviking_remember` writes through its own session that the server commits immediately, `openviking_read` reads file content, with line pagination (the old `level="abstract"` / `"overview"` tiers are gone; use `openviking_search(mode="context", detail="overview")` or `openviking_tree(include_abstract=true)` for the condensed views), and `openviking_forget` deletes the URI you give it instead of the strongest match of a query. Context takeover still injects the archive overview itself over REST, so that path is unchanged.--Tool calls and results are captured as dedicated `tool` parts, and `tool_output` is reported verbatim. Truncation is the server's job: output larger than `tool_output_externalization.threshold_chars` (default `20000`) is written to the session's tool-result store, and the part keeps a synopsis stub plus `tool_output_ref`, so the original stays readable through [`/api/v1/sessions/{id}/tool-results`](../api/05-sessions.md#read-tool-result).--## Prerequisites--- Node.js 22.19.0+ and npm-- pi coding agent (`npm i -g @earendil-works/pi-coding-agent`)-- An OpenViking HTTP server — verify with `curl http://localhost:1933/health`-## Install+Requirements: Node.js 22.19.0+ and npm, pi coding agent (`npm i -g @earendil-works/pi-coding-agent`), and an OpenViking HTTP server — verify with `curl http://localhost:1933/health`.+pi shares the unified installer with the other memory plugins. It asks which harnesses to install and for your OpenViking credentials; every step is idempotent.```bash@@ -50,6 +30,22 @@ npm ci --prefix ~/.pi/agent/extensions/openviking --omit=dev --ignore-scriptsThe extension imports its shared modules from a `shared/` directory that is not in git; `sync.mjs` generates it, so run it before copying. After a `git pull`, run `sync.mjs` again before copying the update.+## How it works++- **Session start** builds your OpenViking profile block and restores takeover state, including the branch watermark used by `pi -c`. The block holds your profile, memory indexes, and an `<available-skills>` catalog of your own and account-shared OpenViking skills, and it is added to pi's system prompt on every turn; the model reads a skill's `SKILL.md` with `openviking_read` before following it.+- **Every prompt** runs semantic recall against the OpenViking server and injects matching memories as hidden context.+- **Every turn** captures user and assistant messages (including structured tool calls) into an OpenViking session; takeover mode commits once synced-token pressure crosses the threshold and then keeps only the recent live tail in model context.+- **Context takeover** is enabled by default. The `context` hook injects `[OpenViking Session Context]` from the latest archive overview before recall is added to the latest user turn.+- **Model-callable tools** are whatever the server's MCP `tools/list` returns, each registered under an `openviking_` prefix, including `openviking_find`, `openviking_search`, `openviking_read`, `openviking_list`, `openviking_tree`, `openviking_grep`, `openviking_glob`, `openviking_remember`, `openviking_write`, `openviking_edit`, `openviking_add_resource`, `openviking_add_skill`, `openviking_list_watches`, `openviking_cancel_watch`, `openviking_forget`, `openviking_health`. The extension keeps no tool catalogue of its own, so a server that adds or drops a tool changes pi's tool surface at the next session, with no extension release. The shared `mcpEnabled: false` turns the tool surface off and leaves recall, capture, and takeover running.+- **Skills**: the extension ships `openviking-memory`, `openviking-skills`, and `ov-experience-memory` from its `skills/` directory and adds them through pi's `resources_discover` event, so the model knows when to use which OpenViking tool. They are left out when `mcpEnabled` is `false`.+- The tool handshake never fails startup. If only the MCP handshake fails, REST recall, capture, and takeover can still work. If the server is unavailable or authentication fails, those features also fail or fall back; the bridge retries on a later turn, so a server started after pi is picked up without a restart.+- A footer status segment (`OV ✓ …`) shows connection and capture state, plus `tools ✗` when the handshake failed; the `/viking` command prints status, including the registered tool count or the last handshake error, and `/viking commit` forces a commit.+- Accidental `read`/`grep`/`find`/`ls`/`write`/`edit` calls whose path is a `viking://` URI are blocked with a hint pointing to the matching `openviking_*` tool. A `bash` command that carries a `viking://` URI still runs, and its result ends with a notice suggesting `openviking_read` / `openviking_search`.++Extension 0.4.0 replaced the seven hand-written `viking_*` REST tools with this mirrored surface, with no alias period: a `--tools` / `--exclude-tools` allowlist that pins the old names must be updated by hand, or those tools silently disappear. Some semantics moved with the names — `openviking_remember` writes through its own session that the server commits immediately, `openviking_read` reads file content, with line pagination (the old `level="abstract"` / `"overview"` tiers are gone; use `openviking_search(mode="context", detail="overview")` or `openviking_tree(include_abstract=true)` for the condensed views), and `openviking_forget` deletes the URI you give it instead of the strongest match of a query. Context takeover still injects the archive overview itself over REST, so that path is unchanged.++Tool calls and results are captured as dedicated `tool` parts, and `tool_output` is reported verbatim. Truncation is the server's job: output larger than `tool_output_externalization.threshold_chars` (default `20000`) is written to the session's tool-result store, and the part keeps a synopsis stub plus `tool_output_ref`, so the original stays readable through [`/api/v1/sessions/{id}/tool-results`](../api/05-sessions.md#read-tool-result).+## ConfigureCredentials resolve from `OPENVIKING_*` environment variables, then `~/.openviking/ovcli.conf`, then `~/.openviking/ov.conf` — shared with the Claude Code, Codex, and OpenCode plugins. Run the wizard once if you have not configured them yet:diff --git a/docs/zh/agent-integrations/10-opencode.md b/docs/zh/agent-integrations/10-opencode.mdindex 5038c2592..310ae4cbf 100644--- a/docs/zh/agent-integrations/10-opencode.md+++ b/docs/zh/agent-integrations/10-opencode.md@@ -4,29 +4,10 @@源码:[examples/opencode-plugin](https://github.com/volcengine/OpenViking/tree/main/examples/opencode-plugin)-工具调用和结果会作为独立的 `tool` part 捕获,`tool_output` 原样上报。截断由服务端负责:超过 `tool_output_externalization.threshold_chars`(默认 `20000`)的输出会写入 session 的 tool-result 存储,part 中只保留 synopsis stub 和 `tool_output_ref`,原文仍可通过 [`/api/v1/sessions/{id}/tool-results`](../api/05-sessions.md#read-tool-result) 读回。--## 前置条件--- [OpenCode](https://opencode.ai/) 1.15.7+ 或 2.0.15+-- Node.js 18+-- OpenViking HTTP server-- 如果服务端启用了鉴权,需要一个可用的 OpenViking API key--先启动 OpenViking server:--```bash-openviking-server --config ~/.openviking/ov.conf-```--在另一个终端检查服务:--```bash-curl http://localhost:1933/health-```-## 安装+前置条件:[OpenCode](https://opencode.ai/) 1.15.7+ 或 2.0.15+、Node.js 18+,以及一个可访问的 OpenViking HTTP server(用 `curl http://localhost:1933/health` 确认);服务端启用了鉴权时,还需要一个可用的 OpenViking API key。+### 一键安装(推荐)OpenCode 与 Claude Code、Codex 共用同一个安装器。它会询问要安装的 harness 和 OpenViking 凭据;每一步都是幂等的,重复运行完全安全。@@ -153,6 +134,8 @@ API key 会由 hooks 和 MCP proxy 作为 `Authorization: Bearer ...` 发送;`OpenCode 2 在每次 execution 结束时抓取本轮用户消息、助手回复和工具结果,并在压缩前补齐即将移出上下文的对话;达到 token 阈值时提交,compaction、session 删除和插件 cleanup 会强制提交。OpenCode 2 会在无活动 60 分钟、服务停止或本地插件热重载时执行 cleanup。+工具调用和结果会作为独立的 `tool` part 捕获,`tool_output` 原样上报。截断由服务端负责:超过 `tool_output_externalization.threshold_chars`(默认 `20000`)的输出会写入 session 的 tool-result 存储,part 中只保留 synopsis stub 和 `tool_output_ref`,原文仍可通过 [`/api/v1/sessions/{id}/tool-results`](../api/05-sessions.md#read-tool-result) 读回。+OpenCode 1.15.7 不会调用插件 dispose。v1 的短时 CLI 运行也可能在异步捕获完成前退出,这一行为在 v2 适配前已存在。使用常驻 v1 服务可以让 idle 捕获完成;OpenCode 1.18.32 会在 instance dispose 时调用插件的 dispose。可以让 OpenCode 搜索或浏览 OpenViking memory。运行时状态和错误日志会写入:diff --git a/docs/zh/agent-integrations/11-pi.md b/docs/zh/agent-integrations/11-pi.mdindex 31f22f97c..6b4b95283 100644--- a/docs/zh/agent-integrations/11-pi.md+++ b/docs/zh/agent-integrations/11-pi.md@@ -4,30 +4,10 @@源码:[examples/pi-coding-agent-extension](https://github.com/volcengine/OpenViking/tree/main/examples/pi-coding-agent-extension)-## 工作方式--- **Session 开始**时构建 OpenViking profile 块,并恢复 takeover 状态,包括 `pi -c` 续跑所需的 branch 水位。profile 块包含你的 profile、记忆索引和 `<available-skills>` 清单(你自己的和账号共享的 OpenViking skill),每个 turn 都会附加到 pi 的系统提示词里;模型照某个 skill 做事之前,先用 `openviking_read` 读它的 `SKILL.md`。-- **每个 prompt** 向 OpenViking server 做语义召回,把命中的记忆作为隐藏上下文注入。-- **每个 turn** 把用户与助手消息(含结构化工具调用)捕获进 OpenViking session;takeover 模式会在 synced token 压力超过阈值后 commit,并在模型上下文中只保留近期 live tail。-- **Context takeover** 默认开启。`context` hook 会先注入来自最新 archive overview 的 `[OpenViking Session Context]`,再把 recall 结果插入最新用户消息。-- **模型可调用工具**就是服务端 MCP `tools/list` 返回的工具,注册时统一加 `openviking_` 前缀,包括:`openviking_find`、`openviking_search`、`openviking_read`、`openviking_list`、`openviking_tree`、`openviking_grep`、`openviking_glob`、`openviking_remember`、`openviking_write`、`openviking_edit`、`openviking_add_resource`、`openviking_add_skill`、`openviking_list_watches`、`openviking_cancel_watch`、`openviking_forget`、`openviking_health`。扩展自己不再维护工具清单,服务端增删工具后,下一次 pi 会话即生效,无需发布新版扩展。共享键 `mcpEnabled: false` 可关掉整个工具面,召回、捕获和 takeover 不受影响。-- **Skill**:扩展从自己的 `skills/` 目录提供 `openviking-memory`、`openviking-skills` 和 `ov-experience-memory`,通过 pi 的 `resources_discover` 事件加入,让模型知道什么时候该用哪个 OpenViking 工具。`mcpEnabled` 为 `false` 时不会加入。-- 工具握手失败不会影响启动。仅 MCP 握手失败时,REST 召回、捕获和 takeover 仍可使用;整个服务不可达或认证失败时,这些功能也会失败或降级。桥接会在后续 turn 重试,所以 pi 启动之后才拉起的服务端不必重启 pi 也能接上。-- 底部状态栏显示 `OV ✓ …` 连接与捕获状态,握手失败时还会追加 `tools ✗`;`/viking` 命令查看状态,包括已注册的工具数量或最近一次握手错误,`/viking commit` 强制 commit。-- 模型用本地 `read`/`grep`/`find`/`ls`/`write`/`edit` 访问 `viking://` URI 路径时,调用会被拦截,并提示改用对应的 `openviking_*` 工具;`bash` 命令带 `viking://` URI 时照常执行,结果末尾附一条提示,建议改用 `openviking_read` / `openviking_search`。--扩展 0.4.0 用这套镜像工具面替换了原先手写的 7 个 `viking_*` REST 工具,且不保留别名:`--tools` / `--exclude-tools` 白名单里写死旧名字的,必须手动改过来,否则这些工具会静默消失。部分语义也随之改变——`openviking_remember` 写入独立 session 并由服务端立即 commit,`openviking_read` 读取文件正文,支持按行分页(旧的 `level="abstract"` / `"overview"` 两档已移除,需要精简视图改用 `openviking_search(mode="context", detail="overview")` 或 `openviking_tree(include_abstract=true)`),`openviking_forget` 直接删除给定 URI,而不是删除某个 query 的最强匹配。Context takeover 的归档 overview 仍由扩展经 REST 注入,这条路径不变。--工具调用和结果会作为独立的 `tool` part 捕获,`tool_output` 原样上报。截断由服务端负责:超过 `tool_output_externalization.threshold_chars`(默认 `20000`)的输出会写入 session 的 tool-result 存储,part 中只保留 synopsis stub 和 `tool_output_ref`,原文仍可通过 [`/api/v1/sessions/{id}/tool-results`](../api/05-sessions.md#read-tool-result) 读回。--## 前置条件--- Node.js 22.19.0+ 和 npm-- pi coding agent(`npm i -g @earendil-works/pi-coding-agent`)-- OpenViking HTTP server——用 `curl http://localhost:1933/health` 确认可达-## 安装+前置条件:Node.js 22.19.0+ 和 npm、pi coding agent(`npm i -g @earendil-works/pi-coding-agent`),以及一个可访问的 OpenViking HTTP server(用 `curl http://localhost:1933/health` 确认)。+pi 与其他记忆插件共用同一个安装器。它会询问要安装的 harness 和 OpenViking 凭据;每一步都是幂等的。```bash@@ -50,6 +30,22 @@ npm ci --prefix ~/.pi/agent/extensions/openviking --omit=dev --ignore-scripts扩展从 `shared/` 目录 import 共享模块,这个目录不在 git 里,由 `sync.mjs` 生成,所以复制前必须先运行它。之后 `git pull` 更新时,也要先重新运行 `sync.mjs` 再复制。+## 工作方式++- **Session 开始**时构建 OpenViking profile 块,并恢复 takeover 状态,包括 `pi -c` 续跑所需的 branch 水位。profile 块包含你的 profile、记忆索引和 `<available-skills>` 清单(你自己的和账号共享的 OpenViking skill),每个 turn 都会附加到 pi 的系统提示词里;模型照某个 skill 做事之前,先用 `openviking_read` 读它的 `SKILL.md`。+- **每个 prompt** 向 OpenViking server 做语义召回,把命中的记忆作为隐藏上下文注入。+- **每个 turn** 把用户与助手消息(含结构化工具调用)捕获进 OpenViking session;takeover 模式会在 synced token 压力超过阈值后 commit,并在模型上下文中只保留近期 live tail。+- **Context takeover** 默认开启。`context` hook 会先注入来自最新 archive overview 的 `[OpenViking Session Context]`,再把 recall 结果插入最新用户消息。+- **模型可调用工具**就是服务端 MCP `tools/list` 返回的工具,注册时统一加 `openviking_` 前缀,包括:`openviking_find`、`openviking_search`、`openviking_read`、`openviking_list`、`openviking_tree`、`openviking_grep`、`openviking_glob`、`openviking_remember`、`openviking_write`、`openviking_edit`、`openviking_add_resource`、`openviking_add_skill`、`openviking_list_watches`、`openviking_cancel_watch`、`openviking_forget`、`openviking_health`。扩展自己不再维护工具清单,服务端增删工具后,下一次 pi 会话即生效,无需发布新版扩展。共享键 `mcpEnabled: false` 可关掉整个工具面,召回、捕获和 takeover 不受影响。+- **Skill**:扩展从自己的 `skills/` 目录提供 `openviking-memory`、`openviking-skills` 和 `ov-experience-memory`,通过 pi 的 `resources_discover` 事件加入,让模型知道什么时候该用哪个 OpenViking 工具。`mcpEnabled` 为 `false` 时不会加入。+- 工具握手失败不会影响启动。仅 MCP 握手失败时,REST 召回、捕获和 takeover 仍可使用;整个服务不可达或认证失败时,这些功能也会失败或降级。桥接会在后续 turn 重试,所以 pi 启动之后才拉起的服务端不必重启 pi 也能接上。+- 底部状态栏显示 `OV ✓ …` 连接与捕获状态,握手失败时还会追加 `tools ✗`;`/viking` 命令查看状态,包括已注册的工具数量或最近一次握手错误,`/viking commit` 强制 commit。+- 模型用本地 `read`/`grep`/`find`/`ls`/`write`/`edit` 访问 `viking://` URI 路径时,调用会被拦截,并提示改用对应的 `openviking_*` 工具;`bash` 命令带 `viking://` URI 时照常执行,结果末尾附一条提示,建议改用 `openviking_read` / `openviking_search`。++扩展 0.4.0 用这套镜像工具面替换了原先手写的 7 个 `viking_*` REST 工具,且不保留别名:`--tools` / `--exclude-tools` 白名单里写死旧名字的,必须手动改过来,否则这些工具会静默消失。部分语义也随之改变——`openviking_remember` 写入独立 session 并由服务端立即 commit,`openviking_read` 读取文件正文,支持按行分页(旧的 `level="abstract"` / `"overview"` 两档已移除,需要精简视图改用 `openviking_search(mode="context", detail="overview")` 或 `openviking_tree(include_abstract=true)`),`openviking_forget` 直接删除给定 URI,而不是删除某个 query 的最强匹配。Context takeover 的归档 overview 仍由扩展经 REST 注入,这条路径不变。++工具调用和结果会作为独立的 `tool` part 捕获,`tool_output` 原样上报。截断由服务端负责:超过 `tool_output_externalization.threshold_chars`(默认 `20000`)的输出会写入 session 的 tool-result 存储,part 中只保留 synopsis stub 和 `tool_output_ref`,原文仍可通过 [`/api/v1/sessions/{id}/tool-results`](../api/05-sessions.md#read-tool-result) 读回。+## 配置凭据解析顺序是 `OPENVIKING_*` 环境变量、`~/.openviking/ovcli.conf`、`~/.openviking/ov.conf`——与 Claude Code、Codex、OpenCode 插件共用。尚未配置时可运行一次向导: