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(plugins): run sync.mjs before copying a plugin out of a checkout (#5063)
t0sakia372c2dcfe7b
diff --git a/docs/en/agent-integrations/10-opencode.md b/docs/en/agent-integrations/10-opencode.mdindex a1316e3b6..91aee2d9f 100644--- a/docs/en/agent-integrations/10-opencode.md+++ b/docs/en/agent-integrations/10-opencode.md@@ -67,6 +67,7 @@ If package installation is not available in your environment:```bashgit clone https://github.com/volcengine/OpenViking.gitcd OpenViking+node examples/memory-plugin-shared/sync.mjsmkdir -p ~/.config/opencode/plugins/openvikingcp examples/opencode-plugin/wrappers/openviking.js ~/.config/opencode/plugins/openviking.jscp examples/opencode-plugin/index.mjs examples/opencode-plugin/package.json ~/.config/opencode/plugins/openviking/@@ -74,6 +75,8 @@ cp -r examples/opencode-plugin/lib ~/.config/opencode/plugins/openviking/cp -r examples/opencode-plugin/servers ~/.config/opencode/plugins/openviking/```+`sync.mjs` generates `lib/shared/`, the shared modules the plugin and its MCP proxy import. That directory is not in git, so run it before copying, and again after every `git pull`.+This source install creates the layout OpenCode can discover:```text@@ -91,9 +94,10 @@ Use the `.js` wrapper for source installs; OpenCode's local plugin scanner disco## Configure-Credentials are shared with the Claude Code and Codex memory plugins. Run the setup wizard once, or set `OPENVIKING_*` environment variables:+Credentials are shared with the Claude Code and Codex memory plugins. Run the setup wizard once from the repository root, or set `OPENVIKING_*` environment variables. The wizard imports `lib/shared/` too, so generate it first:```bash+node examples/memory-plugin-shared/sync.mjsnode examples/opencode-plugin/scripts/setup.mjs```@@ -155,6 +159,7 @@ Ask OpenCode to search or browse OpenViking memory. Runtime state and errors are| Issue | What to check ||-------|---------------|| Plugin does not load | Confirm `~/.config/opencode/opencode.json` references `@openviking/opencode-plugin`, or that `~/.config/opencode/plugins/openviking.js` exists for source installs |+| Load fails with a missing `lib/shared/*.mjs` module | The source copy was made without running `sync.mjs` first. Run `node examples/memory-plugin-shared/sync.mjs` from the repository root and copy `lib/` again || MCP tools call the wrong server | Check `~/.openviking/ovcli.conf`, or set `OPENVIKING_*` env vars; `OPENVIKING_CLI_CONFIG_FILE` points the plugin at a different ovcli.conf || 401 / 403 from OpenViking | Verify `OPENVIKING_API_KEY`; for trusted-mode deployments, also verify `OPENVIKING_ACCOUNT` and `OPENVIKING_USER` || Recall is empty | Confirm the OpenViking server has indexed memories/resources and that `autoRecall` is not set to `false` |diff --git a/docs/en/agent-integrations/11-pi.md b/docs/en/agent-integrations/11-pi.mdindex 040897db3..c12f9b458 100644--- a/docs/en/agent-integrations/11-pi.md+++ b/docs/en/agent-integrations/11-pi.md@@ -42,10 +42,13 @@ Manual copy from a repo checkout also works:```bashgit clone https://github.com/volcengine/OpenViking.gitcd OpenViking+node examples/memory-plugin-shared/sync.mjsmkdir -p ~/.pi/agent/extensionscp -r examples/pi-coding-agent-extension ~/.pi/agent/extensions/openviking```+The 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.+## 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:@@ -101,6 +104,7 @@ Start `pi`. Once connected, the footer shows an `OV ✓` status segment, and `/v| `OV ✗` in the footer or "server not reachable" | `curl http://localhost:1933/health`; check the endpoint in `~/.openviking/ovcli.conf` || Extension does not load | Confirm `~/.pi/agent/extensions/openviking/index.ts` exists (the directory is auto-discovered); re-run the installer. Do not register it with `pi install` — that loads it twice || `/viking` command appears twice (`viking:1` / `viking:2`) | An older installer registered the path with `pi install`, leaving a redundant `packages` entry so it loads once via auto-discovery and once via `packages`; run `pi remove ~/.pi/agent/extensions/openviking` to drop that entry (edits settings only, leaves the files) |+| Load fails with a missing `shared/*.mjs` module (for example `shared/capture-utils.mjs`) | The copy was made without running `sync.mjs` first. Run `node examples/memory-plugin-shared/sync.mjs` from the repository root and copy again, or re-run the installer || Import errors mentioning `@mariozechner/*` | Stale copy from before pi's move to `@earendil-works/*` — re-run the installer || 401 / 403 from OpenViking | Verify `OPENVIKING_API_KEY`; for trusted-mode deployments, also verify `OPENVIKING_ACCOUNT` and `OPENVIKING_USER` || Recall is empty | Confirm the server has indexed memories and the prompt is longer than `minQueryLength` |diff --git a/docs/zh/agent-integrations/10-opencode.md b/docs/zh/agent-integrations/10-opencode.mdindex 93518bf6a..50684388f 100644--- a/docs/zh/agent-integrations/10-opencode.md+++ b/docs/zh/agent-integrations/10-opencode.md@@ -67,6 +67,7 @@ opencode```bashgit clone https://github.com/volcengine/OpenViking.gitcd OpenViking+node examples/memory-plugin-shared/sync.mjsmkdir -p ~/.config/opencode/plugins/openvikingcp examples/opencode-plugin/wrappers/openviking.js ~/.config/opencode/plugins/openviking.jscp examples/opencode-plugin/index.mjs examples/opencode-plugin/package.json ~/.config/opencode/plugins/openviking/@@ -74,6 +75,8 @@ cp -r examples/opencode-plugin/lib ~/.config/opencode/plugins/openviking/cp -r examples/opencode-plugin/servers ~/.config/opencode/plugins/openviking/```+`sync.mjs` 会生成 `lib/shared/`,插件和 MCP 代理都从这里 import 共享模块。这个目录不在 git 里,所以复制前要先运行;之后每次 `git pull` 也要重新运行再复制。+源码安装后,OpenCode 能发现的目录结构应类似:```text@@ -91,9 +94,10 @@ cp -r examples/opencode-plugin/servers ~/.config/opencode/plugins/openviking/## 配置-凭据与 Claude Code / Codex 记忆插件共用。可以先运行 setup 向导,或使用 `OPENVIKING_*` 环境变量:+凭据与 Claude Code / Codex 记忆插件共用。可以在仓库根目录运行一次 setup 向导,或使用 `OPENVIKING_*` 环境变量。向导同样 import `lib/shared/`,所以要先生成:```bash+node examples/memory-plugin-shared/sync.mjsnode examples/opencode-plugin/scripts/setup.mjs```@@ -155,6 +159,7 @@ API key 会由 hooks 和 MCP proxy 作为 `Authorization: Bearer ...` 发送;`| 问题 | 排查方向 ||------|----------|| 插件没有加载 | 确认 `~/.config/opencode/opencode.json` 引用了 `@openviking/opencode-plugin`;源码安装时确认 `~/.config/opencode/plugins/openviking.js` 存在 |+| 加载时报找不到 `lib/shared/*.mjs` | 源码复制前没有运行 `sync.mjs`。在仓库根目录运行 `node examples/memory-plugin-shared/sync.mjs` 后重新复制 `lib/` || MCP tools 连到了错误的 server | 检查 `~/.openviking/ovcli.conf`,或用 `OPENVIKING_*` 环境变量;`OPENVIKING_CLI_CONFIG_FILE` 可让插件改读另一份 ovcli.conf || OpenViking 返回 401 / 403 | 检查 `OPENVIKING_API_KEY`;trusted-mode 部署还要检查 `OPENVIKING_ACCOUNT` 和 `OPENVIKING_USER` || recall 为空 | 确认 OpenViking server 中已有 memories/resources,且 `autoRecall` 没有被设成 `false` |diff --git a/docs/zh/agent-integrations/11-pi.md b/docs/zh/agent-integrations/11-pi.mdindex a2aedb2bd..ac936230b 100644--- a/docs/zh/agent-integrations/11-pi.md+++ b/docs/zh/agent-integrations/11-pi.md@@ -42,10 +42,13 @@ bash <(curl -fsSL https://ovrelease.tos-cn-beijing.volces.com/memory-plugin-shar```bashgit clone https://github.com/volcengine/OpenViking.gitcd OpenViking+node examples/memory-plugin-shared/sync.mjsmkdir -p ~/.pi/agent/extensionscp -r examples/pi-coding-agent-extension ~/.pi/agent/extensions/openviking```+扩展从 `shared/` 目录 import 共享模块,这个目录不在 git 里,由 `sync.mjs` 生成,所以复制前必须先运行它。之后 `git pull` 更新时,也要先重新运行 `sync.mjs` 再复制。+## 配置凭据解析顺序是 `OPENVIKING_*` 环境变量、`~/.openviking/ovcli.conf`、`~/.openviking/ov.conf`——与 Claude Code、Codex、OpenCode 插件共用。尚未配置时可运行一次向导:@@ -101,6 +104,7 @@ Takeover 是 fail-open:如果 pending 写入无法 flush、commit 失败、arc| 状态栏显示 `OV ✗` 或提示 "server not reachable" | `curl http://localhost:1933/health`;检查 `~/.openviking/ovcli.conf` 中的 endpoint || 扩展没有加载 | 确认 `~/.pi/agent/extensions/openviking/index.ts` 存在(该目录会被自动发现);重跑安装器即可。不要用 `pi install` 注册它——那样会重复加载 || `/viking` 命令出现两次(`viking:1` / `viking:2`) | 老版本安装器用 `pi install` 留下了冗余的 `packages` 条目,导致自动发现和 `packages` 各加载一次;执行 `pi remove ~/.pi/agent/extensions/openviking` 清掉该条目(只改 settings,不删文件) |+| 加载时报找不到 `shared/*.mjs`(例如 `shared/capture-utils.mjs`) | 手动复制前没有运行 `sync.mjs`。在仓库根目录运行 `node examples/memory-plugin-shared/sync.mjs` 后重新复制,或者重跑安装器 || 报错提到 `@mariozechner/*` | pi 迁移到 `@earendil-works/*` 之前的旧副本——重跑安装器 || OpenViking 返回 401 / 403 | 检查 `OPENVIKING_API_KEY`;trusted-mode 部署还要检查 `OPENVIKING_ACCOUNT` 和 `OPENVIKING_USER` || recall 为空 | 确认 server 中已有记忆,且 prompt 长度超过 `minQueryLength` |diff --git a/examples/dsh-memory-plugin/README.md b/examples/dsh-memory-plugin/README.mdindex 485e4a0ec..1f4502f7a 100644--- a/examples/dsh-memory-plugin/README.md+++ b/examples/dsh-memory-plugin/README.md@@ -29,6 +29,8 @@ be a real package. Linking a source checkout (`dsh plugin --profile web add./examples/dsh-memory-plugin`) only works when that checkout has its own`node_modules`, because Node resolves the bundle's dsh peers from the sourcetree's realpath rather than from the profile.+It also needs `node examples/memory-plugin-shared/sync.mjs` run first: the+`shared/` modules the bundle imports are generated, not committed.## Requirementsdiff --git a/examples/opencode-plugin/INSTALL-ZH.md b/examples/opencode-plugin/INSTALL-ZH.mdindex d02d56b20..b24139820 100644--- a/examples/opencode-plugin/INSTALL-ZH.md+++ b/examples/opencode-plugin/INSTALL-ZH.md@@ -49,6 +49,7 @@ curl http://localhost:1933/health在仓库根目录执行:```bash+node examples/memory-plugin-shared/sync.mjsmkdir -p ~/.config/opencode/plugins/openvikingcp examples/opencode-plugin/wrappers/openviking.js ~/.config/opencode/plugins/openviking.jscp examples/opencode-plugin/index.mjs examples/opencode-plugin/package.json ~/.config/opencode/plugins/openviking/@@ -56,6 +57,8 @@ cp -r examples/opencode-plugin/lib ~/.config/opencode/plugins/openviking/cp -r examples/opencode-plugin/servers ~/.config/opencode/plugins/openviking/```+`sync.mjs` 会生成 `lib/shared/`,插件和 MCP 代理都从这里 import 共享模块。这个目录不在 git 里,所以复制前要先运行;之后每次 `git pull` 也要重新运行再复制。+安装后结构应类似:```text@@ -247,6 +250,7 @@ openviking_add_resource(path="file:///home/alice/project/notes.md", description=| 问题 | 排查方向 ||------|----------|| 插件没有加载 | package 安装检查 `~/.config/opencode/opencode.json` 是否包含 `@openviking/opencode-plugin`;源码安装检查 `~/.config/opencode/plugins/openviking.js` 是否存在 |+| 加载时报找不到 `lib/shared/*.mjs` | 源码复制前没有运行 `sync.mjs`。在仓库根目录运行 `node examples/memory-plugin-shared/sync.mjs` 后重新复制 `lib/` || MCP tools 连到了错误的 server | 检查 `~/.openviking/ovcli.conf`,或用 `OPENVIKING_*` 环境变量 / `OPENVIKING_CLI_CONFIG_FILE` 指向正确配置 || OpenViking 返回 401 / 403 | 检查 `OPENVIKING_API_KEY`;trusted-mode 部署还要检查 `OPENVIKING_ACCOUNT` 和 `OPENVIKING_USER` || recall 为空 | 确认 OpenViking 中已有 memories/resources,并且 `autoRecall` 为 `true` |diff --git a/examples/opencode-plugin/INSTALL.md b/examples/opencode-plugin/INSTALL.mdindex cc4b24469..844ab2123 100644--- a/examples/opencode-plugin/INSTALL.md+++ b/examples/opencode-plugin/INSTALL.md@@ -49,6 +49,7 @@ Use this method for development, debugging, or PR testing. OpenCode's recommendeRun the following commands from the repository root:```bash+node examples/memory-plugin-shared/sync.mjsmkdir -p ~/.config/opencode/plugins/openvikingcp examples/opencode-plugin/wrappers/openviking.js ~/.config/opencode/plugins/openviking.jscp examples/opencode-plugin/index.mjs examples/opencode-plugin/package.json ~/.config/opencode/plugins/openviking/@@ -56,6 +57,8 @@ cp -r examples/opencode-plugin/lib ~/.config/opencode/plugins/openviking/cp -r examples/opencode-plugin/servers ~/.config/opencode/plugins/openviking/```+`sync.mjs` generates `lib/shared/`, the shared modules the plugin and its MCP proxy import. That directory is not in git, so run it before copying, and again after every `git pull`.+After installation, the layout should look like this:```text@@ -244,6 +247,7 @@ These are local runtime files and should not be committed to the repository.| Issue | What to check ||-------|---------------|| Plugin does not load | For package installs, confirm `~/.config/opencode/opencode.json` contains `@openviking/opencode-plugin`; for source installs, confirm `~/.config/opencode/plugins/openviking.js` exists |+| Load fails with a missing `lib/shared/*.mjs` module | The source copy was made without running `sync.mjs` first. Run `node examples/memory-plugin-shared/sync.mjs` from the repository root and copy `lib/` again || MCP tools call the wrong server | Check `~/.openviking/ovcli.conf`, or set `OPENVIKING_*` env vars / `OPENVIKING_CLI_CONFIG_FILE` to the intended config path || 401 / 403 from OpenViking | Verify `OPENVIKING_API_KEY`; for trusted-mode deployments, also verify `OPENVIKING_ACCOUNT` and `OPENVIKING_USER` || Recall is empty | Confirm OpenViking has indexed memories/resources and `autoRecall` is `true` |diff --git a/examples/opencode-plugin/README.md b/examples/opencode-plugin/README.mdindex e9f3662a1..d20c88f14 100644--- a/examples/opencode-plugin/README.md+++ b/examples/opencode-plugin/README.md@@ -83,6 +83,7 @@ npm view @openviking/opencode-plugin versionFor development or PR testing, copy the package into OpenCode's plugin directory with a top-level wrapper:```bash+node examples/memory-plugin-shared/sync.mjsmkdir -p ~/.config/opencode/plugins/openvikingcp examples/opencode-plugin/wrappers/openviking.js ~/.config/opencode/plugins/openviking.jscp examples/opencode-plugin/index.mjs examples/opencode-plugin/package.json ~/.config/opencode/plugins/openviking/@@ -90,6 +91,8 @@ cp -r examples/opencode-plugin/lib ~/.config/opencode/plugins/openviking/cp -r examples/opencode-plugin/servers ~/.config/opencode/plugins/openviking/```+`sync.mjs` generates `lib/shared/`, the shared modules the plugin and its MCP proxy import. That directory is not in git, so run it before copying, and again after every `git pull`.+This creates a stable OpenCode plugin layout:```text