Skip to content

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

Update docs (#782)

zhoujiahui06dad3a9536f
diff --git a/examples/openclaw-plugin/INSTALL-ZH.md b/examples/openclaw-plugin/INSTALL-ZH.md
index 3548337e9..478503a2f 100644
--- a/examples/openclaw-plugin/INSTALL-ZH.md
+++ b/examples/openclaw-plugin/INSTALL-ZH.md
@@ -2,23 +2,18 @@
通过 [OpenViking](https://github.com/volcengine/OpenViking) 为 [OpenClaw](https://github.com/openclaw/openclaw) 提供长效记忆能力。安装完成后,OpenClaw 将自动**记住**对话中的重要信息,并在回复前**回忆**相关内容。OpenViking 最新版本发布了 [WebConsole](https://github.com/volcengine/OpenViking/tree/main/openviking/console),方便调试和运维。文档方式三也提供了如何在 WebConsole 界面验证记忆写入的说明,欢迎试用和反馈。
-> **⚠️ OpenClaw >= 2026.3.12 兼容性问题**
+> **ℹ️ 历史兼容性说明**
>
-> OpenClaw `2026.3.12` 及更高版本存在已知兼容性问题,会导致加载插件后对话卡死无响应。
-> 这不是本插件的 bug——根因是 OpenClaw 3.12 的 slug generator(会话自动命名)有硬编码 15s 超时,
-> 当 LLM provider 响应较慢时会逐个 profile 超时重试,阻塞整个会话初始化管线。
-> 此外 3.12 新增的插件信任机制也可能影响本地插件的加载时序。
-> 另一个已知问题:`before_agent_start` 中的 auto-recall 缺少超时保护,可能导致 agent 静默挂起([#673](https://github.com/volcengine/OpenViking/issues/673))。
->
-> **临时方案:** 回退到 `2026.3.11`:`npm install -g [email protected]`
->
-> 上游修复 PR:openclaw/openclaw#34673、openclaw/openclaw#33547。
-> 详见 [#591](https://github.com/volcengine/OpenViking/issues/591)。
+> 旧版 OpenViking/OpenClaw 集成方案在 OpenClaw `2026.3.12` 附近曾出现过已知兼容性问题,表现为加载插件后对话卡死无响应。
+> 该问题主要影响旧版本插件链路;当前文档介绍的 context-engine 插件 2.0 已不再受此问题影响,新的安装流程无需因此回退 OpenClaw。
+> 同时,插件 2.0 与旧版 `memory-openviking` 插件及其配置不兼容,升级时需要按本文迁移步骤完成替换,不能混装。
+> 插件 2.0 也依赖 OpenClaw 的 context-engine 能力,不支持旧版 OpenClaw;请升级到当前安装助手支持的较新 OpenClaw 版本后再安装。
+> 如需排查旧版本部署,可参考 [#591](https://github.com/volcengine/OpenViking/issues/591) 以及上游修复 PR:openclaw/openclaw#34673、openclaw/openclaw#33547。
-> **🚀 插件 2.0 设计中**
+> **🚀 插件 2.0(context-engine 架构)**
>
-> 我们正在设计基于 context-engine 架构重构的插件 2.0 版本,将作为 OpenViking 接入 AI 编程助手的最佳实践。
-> 欢迎参与讨论:https://github.com/volcengine/OpenViking/discussions/525
+> 当前文档介绍的是基于 context-engine 架构的 OpenViking 插件 2.0 方案,也是 OpenViking 接入 AI 编程助手的推荐实践。
+> 更多背景和演进讨论可见:https://github.com/volcengine/OpenViking/discussions/525
---
@@ -28,7 +23,7 @@
### 从旧版 `memory-openviking` 升级到新版 `openviking` 前置操作步骤
-如果当前环境里已经安装过旧版插件 `memory-openviking`,建议先完成以下前置操作,再执行新版安装,避免旧版和新版插件同时存在。
+如果当前环境里已经安装过旧版插件 `memory-openviking`,建议先完成以下前置操作,再执行新版安装。插件 2.0 与旧版插件/旧版配置不兼容,避免旧版和新版插件同时存在。
1. 停止 OpenClaw gateway:
diff --git a/examples/openclaw-plugin/INSTALL.md b/examples/openclaw-plugin/INSTALL.md
index 5e1ae7506..eab355d17 100644
--- a/examples/openclaw-plugin/INSTALL.md
+++ b/examples/openclaw-plugin/INSTALL.md
@@ -2,24 +2,18 @@
Provide long-term memory capabilities for [OpenClaw](https://github.com/openclaw/openclaw) via [OpenViking](https://github.com/volcengine/OpenViking). After installing, OpenClaw will automatically **remember** important information from conversations and **recall** relevant content before replying. The latest version of OpenViking includes a [WebConsole](https://github.com/volcengine/OpenViking/tree/main/openviking/console) for debugging and operations. Method 3 in this document also provides instructions on how to verify that memories are written via the WebConsole interface. We welcome you to try it out and provide feedback.
-> **⚠️ OpenClaw >= 2026.3.12 Compatibility Issue**
+> **ℹ️ Historical Compatibility Note**
>
-> OpenClaw `2026.3.12` and later have a known issue that causes conversations to hang after loading the plugin.
-> This is not a bug in our plugin — the root cause is OpenClaw 3.12's slug generator (automatic conversation naming),
-> which has a hardcoded 15s timeout that cascades when the LLM provider responds slowly, blocking the entire
-> session initialization pipeline. Additionally, 3.12's new plugin trust mechanism may affect loading order for
-> locally installed plugins. A separate issue: the `before_agent_start` auto-recall hook lacks timeout protection,
-> which can cause the agent to hang silently ([#673](https://github.com/volcengine/OpenViking/issues/673)).
->
-> **Workaround:** Downgrade to `2026.3.11`: `npm install -g [email protected]`
->
-> Upstream fix PRs: openclaw/openclaw#34673, openclaw/openclaw#33547.
-> See [#591](https://github.com/volcengine/OpenViking/issues/591) for details.
+> Legacy OpenViking/OpenClaw integrations had a known issue around OpenClaw `2026.3.12` where conversations could hang after the plugin loaded.
+> That issue affected the legacy plugin path; the current context-engine Plugin 2.0 described in this document is not affected, so new installations do not need to downgrade OpenClaw for this reason.
+> Plugin 2.0 is also not backward-compatible with the legacy `memory-openviking` plugin and its configuration, so upgrades must replace the old setup instead of mixing the two versions.
+> Plugin 2.0 also depends on OpenClaw's context-engine capability and does not support older OpenClaw releases; upgrade OpenClaw first before following this guide.
+> If you are troubleshooting a legacy deployment, see [#591](https://github.com/volcengine/OpenViking/issues/591) and upstream fix PRs: openclaw/openclaw#34673, openclaw/openclaw#33547.
-> **🚀 Plugin 2.0 In Design**
+> **🚀 Plugin 2.0 (Context-Engine Architecture)**
>
-> We are designing Plugin 2.0, rebuilt on the context-engine architecture — the best practice for integrating
-> OpenViking with AI coding assistants. Join the discussion:
+> This document covers the current OpenViking Plugin 2.0 built on the context-engine architecture, which is the recommended integration path for AI coding assistants.
+> For design background and earlier discussion, see:
> https://github.com/volcengine/OpenViking/discussions/525
---
@@ -30,7 +24,7 @@ Provide long-term memory capabilities for [OpenClaw](https://github.com/openclaw
### Prerequisite Steps for Upgrading from Legacy `memory-openviking` to New `openviking`
-If the current environment already has the legacy `memory-openviking` plugin installed, complete the following prerequisite steps before installing the new version to avoid having both plugins active at the same time.
+If the current environment already has the legacy `memory-openviking` plugin installed, complete the following prerequisite steps before installing the new version. Plugin 2.0 is not backward-compatible with the legacy plugin/configuration, so do not keep both versions active at the same time.
1. Stop the OpenClaw gateway:
diff --git a/examples/openclaw-plugin/README.md b/examples/openclaw-plugin/README.md
index 6feee23ce..104ffbe4b 100644
--- a/examples/openclaw-plugin/README.md
+++ b/examples/openclaw-plugin/README.md
@@ -2,24 +2,18 @@
Use [OpenViking](https://github.com/volcengine/OpenViking) as the long-term memory backend for [OpenClaw](https://github.com/openclaw/openclaw). In OpenClaw, this plugin is registered as the `openviking` context engine. Once installed, OpenClaw will automatically **remember** important information from conversations and **recall** relevant context before responding.
-> **⚠️ OpenClaw >= 2026.3.12 Compatibility Issue**
+> **ℹ️ Historical Compatibility Note**
>
-> OpenClaw `2026.3.12` and later have a known issue that causes conversations to hang after loading the plugin.
-> This is not a bug in our plugin — the root cause is OpenClaw 3.12's slug generator (automatic conversation naming),
-> which has a hardcoded 15s timeout that cascades when the LLM provider responds slowly, blocking the entire
-> session initialization pipeline. Additionally, 3.12's new plugin trust mechanism may affect loading order for
-> locally installed plugins. A separate issue: the `before_agent_start` auto-recall hook lacks timeout protection,
-> which can cause the agent to hang silently ([#673](https://github.com/volcengine/OpenViking/issues/673)).
->
-> **Workaround:** Downgrade to `2026.3.11`: `npm install -g [email protected]`
->
-> Upstream fix PRs: openclaw/openclaw#34673, openclaw/openclaw#33547.
-> See [#591](https://github.com/volcengine/OpenViking/issues/591) for details.
+> Legacy OpenViking/OpenClaw integrations had a known issue around OpenClaw `2026.3.12` where conversations could hang after the plugin loaded.
+> That issue affected the legacy plugin path; the current context-engine Plugin 2.0 described in this document is not affected, so new installations do not need to downgrade OpenClaw for this reason.
+> Plugin 2.0 is also not backward-compatible with the legacy `memory-openviking` plugin and its configuration, so upgrades must replace the old setup instead of mixing the two versions.
+> Plugin 2.0 also depends on OpenClaw's context-engine capability and does not support older OpenClaw releases; upgrade OpenClaw first before using this plugin.
+> If you are troubleshooting a legacy deployment, see [#591](https://github.com/volcengine/OpenViking/issues/591) and upstream fix PRs: openclaw/openclaw#34673, openclaw/openclaw#33547.
-> **🚀 Plugin 2.0 In Design**
+> **🚀 Plugin 2.0 (Context-Engine Architecture)**
>
-> We are designing Plugin 2.0, rebuilt on the context-engine architecture — the best practice for integrating
-> OpenViking with AI coding assistants. Join the discussion:
+> This document covers the current OpenViking Plugin 2.0 built on the context-engine architecture, which is the recommended integration path for AI coding assistants.
+> For design background and earlier discussion, see:
> https://github.com/volcengine/OpenViking/discussions/525
---
@@ -104,7 +98,7 @@ openclaw --version # installed
- Python: https://www.python.org/downloads/
- Node.js: https://nodejs.org/
-- OpenClaw: `npm install -g [email protected] && openclaw onboard`
+- OpenClaw: `npm install -g openclaw && openclaw onboard`
---
@@ -418,7 +412,8 @@ Open http://127.0.0.1:8020 in your browser.
| Symptom | Cause | Fix |
|---------|-------|-----|
-| Conversation hangs, no response | OpenClaw >= 2026.3.12 compatibility issue | Downgrade to `2026.3.11`: `npm install -g [email protected]`. See [#591](https://github.com/volcengine/OpenViking/issues/591) |
+| Conversation hangs, no response | Usually a legacy pre-2.0 integration affected by the historical OpenClaw `2026.3.12` issue | If you are on the legacy path, see [#591](https://github.com/volcengine/OpenViking/issues/591) and temporarily downgrade to `2026.3.11`; for current installs, migrate to Plugin 2.0 |
+| `registerContextEngine is unavailable` in logs | OpenClaw version is too old and does not expose the context-engine API required by Plugin 2.0 | Upgrade OpenClaw to a current release, then restart the gateway and verify `openclaw status` shows `openviking` as the ContextEngine |
| Agent hangs silently, no output | auto-recall missing timeout protection | Disable auto-recall temporarily: `openclaw config set plugins.entries.openviking.config.autoRecall false --json`, or apply the patch in [#673](https://github.com/volcengine/OpenViking/issues/673) |
| ContextEngine is not `openviking` | Plugin slot not configured | `openclaw config set plugins.slots.contextEngine openviking` |
| `memory_store failed: fetch failed` | OpenViking not running | Check `ov.conf` and Python path; verify service is up |