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
Update docs (#782)
zhoujiahui06dad3a9536f
diff --git a/examples/openclaw-plugin/INSTALL-ZH.md b/examples/openclaw-plugin/INSTALL-ZH.mdindex 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.mdindex 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.mdindex 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 |