Skip to content

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

docs(openclaw-plugin): refresh architecture guides with diagrams (#1145)

Qin Haojie2bc65f3869ae
diff --git a/examples/openclaw-plugin/README.md b/examples/openclaw-plugin/README.md
index fe9de4e2c..46007e0cb 100644
--- a/examples/openclaw-plugin/README.md
+++ b/examples/openclaw-plugin/README.md
@@ -2,197 +2,197 @@
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.
+This document is not an installation guide. It is an implementation-focused design note for integrators and engineers. It describes how the plugin works today based on the code under `examples/openclaw-plugin`, not a future refactor target.
+
## Documentation
- Install and upgrade: [INSTALL.md](./INSTALL.md)
-- Chinese install guide: [INSTALL-ZH.md](./INSTALL-ZH.md)
+- Chinese design and install guide: [INSTALL-ZH.md](./INSTALL-ZH.md)
- Agent-oriented operator guide: [INSTALL-AGENT.md](./INSTALL-AGENT.md)
-## Technical Architecture
+## Design Positioning
-### Plugin Responsibilities
+- OpenClaw still owns the agent runtime, prompt orchestration, and tool execution.
+- OpenViking owns long-term memory retrieval, session archiving, archive summaries, and memory extraction.
+- `examples/openclaw-plugin` is not a narrow “memory lookup” plugin. It is an integration layer that spans the OpenClaw lifecycle.
-This plugin is not only a memory retriever. In code it plays four roles at once:
+In the current implementation, the plugin plays four roles at once:
-- a `context-engine` plugin that implements `assemble`, `afterTurn`, and `compact`
-- a hook layer that runs `before_prompt_build`, `session_start`, `session_end`, `agent_end`, and `before_reset`
-- a tool provider that registers `memory_recall`, `memory_store`, `memory_forget`, and `ov_archive_expand`
-- a runtime manager that can start and monitor a local OpenViking subprocess in `local` mode
+- `context-engine`: implements `assemble`, `afterTurn`, and `compact`
+- hook layer: handles `before_prompt_build`, `session_start`, `session_end`, `agent_end`, and `before_reset`
+- tool provider: registers `memory_recall`, `memory_store`, `memory_forget`, and `ov_archive_expand`
+- runtime manager: starts and monitors an OpenViking subprocess in `local` mode
-OpenClaw still owns the agent runtime and prompt orchestration. OpenViking owns long-term memory retrieval, session archiving, and memory extraction.
+## Overall Architecture
-### Identity and Routing
+![Overall OpenClaw and OpenViking plugin architecture](./images/openclaw-plugin-engine-overview.png)
-The plugin does not send a single global agent ID to OpenViking. It keeps OpenClaw session identity and OpenViking routing aligned:
+The diagram above reflects the current implementation boundary:
-- `sessionId` or `sessionKey` is converted into an OpenViking-safe session ID
-- UUID session IDs are reused directly; other IDs fall back to a stable SHA-256 form when needed
-- `X-OpenViking-Agent` is resolved per session, not per process
-- if `plugins.entries.openviking.config.agentId` is not `default`, it becomes a prefix like `<configAgentId>_<sessionAgent>`
-- routing and tenant headers are emitted by the client layer, and can be logged with `logFindRequests`
+- OpenClaw remains the primary runtime on the left. The plugin does not take over agent execution.
+- The middle layer combines hooks, the context engine, tools, and runtime management in one plugin registration.
+- All HTTP traffic goes through `OpenVikingClient`, which centralizes `X-OpenViking-*` headers and routing logs.
+- The OpenViking service owns sessions, memories, archives, and Phase 2 extraction, with storage under `viking://user/*`, `viking://agent/*`, and `viking://session/*`.
-This matters because the plugin supports multi-agent and multi-session OpenClaw flows without mixing memory across sessions.
+That split lets OpenClaw stay focused on reasoning and orchestration while OpenViking becomes the source of truth for long-lived context.
-### Session Lifecycle
+## Identity and Routing
-Session handling is the core design, and it spans both hooks and the context engine.
+The plugin does not send one fixed agent ID to OpenViking. It tries to keep OpenClaw session identity and OpenViking routing aligned.
-1. OpenClaw session identity is mapped to an OpenViking session ID.
-2. `assemble()` asks OpenViking for session context with a token budget.
-3. Returned archive summaries are rewritten into `[Session History Summary]` and `[Archive Index]`.
-4. Active OpenViking messages are converted back into OpenClaw messages.
-5. Tool calls and tool results are repaired so transcript structure stays provider-safe.
-6. `afterTurn()` extracts only the new turn, sanitizes it, and appends it to the OpenViking session.
-7. Once pending session tokens cross `commitTokenThreshold`, the plugin commits the OpenViking session and lets Phase 2 memory extraction continue asynchronously.
-8. `compact()` performs a blocking commit, waits for archive generation, then re-reads compacted session context.
+The main rules are:
-The result is a session model where OpenClaw sees a reduced working context, while OpenViking keeps the long-form archive and extracted memories.
+- reuse `sessionId` directly when it is already a UUID
+- prefer `sessionKey` when deriving a stable `ovSessionId`
+- normalize unsafe path characters, or fall back to a stable SHA-256 when needed
+- resolve `X-OpenViking-Agent` per session, not per process
+- when `plugins.entries.openviking.config.agentId` is not `default`, prefix the session agent as `<configAgentId>_<sessionAgent>`
+- add `X-OpenViking-Account`, `X-OpenViking-User`, and `X-OpenViking-Agent` in the client layer
-### What `assemble()` Actually Builds
+This matters because the plugin is built to support multi-agent and multi-session OpenClaw usage without mixing memories across sessions.
-The assembled context is more than “old chat history”.
+## Prompt-Front Recall Flow
-- archive overviews become a compact session summary block
-- earlier archives are exposed as an ordered archive index
-- active session messages stay uncompressed
-- when precise details are missing, the model can call `ov_archive_expand` to reopen a specific archive
+![Automatic recall flow before prompt build](./images/openclaw-plugin-recall-flow.png)
-This is why the plugin can survive long sessions: it does not keep replaying the entire raw transcript into OpenClaw.
+Today the main recall path still lives in `before_prompt_build`:
-### Recall and Capture Pipeline
+1. Extract the latest user text from `messages` or `prompt`.
+2. Resolve the agent routing for the current `sessionId/sessionKey`.
+3. Run a quick availability precheck so prompt building does not stall when OpenViking is unavailable.
+4. Query both `viking://user/memories` and `viking://agent/memories` in parallel.
+5. Deduplicate, threshold-filter, rerank, and trim the results under a token budget.
+6. Prepend the selected memories as a `<relevant-memories>` block.
-There are two memory loops around each turn.
+The reranking logic is not pure vector-score sorting. The current implementation also considers:
-Before generation:
+- whether a result is a leaf memory with `level == 2`
+- whether it looks like a preference memory
+- whether it looks like an event memory
+- lexical overlap with the current query
-- `before_prompt_build` extracts the latest user text
-- it searches both `viking://user/memories` and `viking://agent/memories`
-- results are deduplicated, reranked, and trimmed to a token budget
-- the selected memories are injected as a `<relevant-memories>` block
+### Transcript ingest assist
-After generation:
+This path also includes a special transcript-oriented branch.
-- `afterTurn` formats the new turn into capture text
-- assistant text, `toolUse`, and `toolResult` content are preserved
-- metadata noise and injected memory blocks are stripped before capture
-- OpenViking session commit triggers archive + extraction
+When the latest user input looks like pasted multi-speaker transcript content:
-The reranking logic is query-aware. It boosts preferences, events, leaf memories, and lexical overlap instead of trusting vector score alone.
+- metadata blocks, command text, and pure question text are filtered out
+- the cleaned text is checked against speaker-turn and length thresholds
+- if it matches, the plugin prepends a lightweight `<ingest-reply-assist>` instruction
-### Transcript Ingest Assist
+The goal is not to change memory logic. It is to reduce the chance that the model responds with `NO_REPLY` when the user pastes chat history, meeting notes, or conversation transcripts for ingestion.
-The plugin also has a special path for transcript-like user input.
+## Session Lifecycle
-- multi-speaker text is detected with speaker-turn and length thresholds
-- command text, metadata blocks, and pure question prompts are filtered out
-- when a transcript-like ingest is detected, the plugin prepends a lightweight instruction so the model returns a short usable reply instead of `NO_REPLY`
+![Session lifecycle and compaction boundary](./images/openclaw-plugin-session-lifecycle.png)
-This is aimed at memory ingestion workflows where the user pastes chat transcripts or conversation dumps.
+Session handling is the main axis of this design. In the current implementation it covers history assembly, incremental append, asynchronous commit, and blocking compaction readback.
-### Local and Remote Runtime
+### What `assemble()` does
-#### Local Mode
+`assemble()` is not just replaying old chat history. It reads session context back from OpenViking under a token budget, then rebuilds OpenClaw-facing messages:
-In `local` mode, the plugin starts OpenViking itself.
+- `latest_archive_overview` becomes `[Session History Summary]`
+- `pre_archive_abstracts` becomes `[Archive Index]`
+- active session messages stay in message-block form
+- assistant tool parts become `toolUse`
+- tool output becomes separate `toolResult`
+- the final message list goes through a tool-use/result pairing repair pass
-- resolves Python from `OPENVIKING_PYTHON`, env files, or system defaults
-- prepares the port before boot
-- kills stale OpenViking processes on the same port
-- auto-picks the next free port if the configured port is occupied by another process
-- waits for `/health` before treating the service as ready
-- caches the local client so multiple OpenClaw plugin contexts do not spawn duplicate runtimes
+That means OpenClaw sees “compressed history summary + archive index + active messages”, not an ever-growing raw transcript.
-#### Remote Mode
+### What `afterTurn()` does
-In `remote` mode, the plugin only uses the HTTP API.
+`afterTurn()` has a narrower job: append only the new turn into the OpenViking session.
-- no subprocess is started
-- `baseUrl` and optional `apiKey` come from OpenClaw plugin config
-- the same session, recall, archive, and tool flow still applies
+- it slices only the newly added messages
+- it keeps only `user` / `assistant` capture text
+- it preserves `toolUse` / `toolResult` content in the serialized turn text
+- it strips injected `<relevant-memories>` blocks and metadata noise before capture
+- it appends the sanitized turn text into the OpenViking session
-### Tools and Operator Surfaces
+After that, the plugin checks `pending_tokens`. Once the session crosses `commitTokenThreshold`, it triggers `commit(wait=false)`:
-The plugin exposes more than automatic memory behavior.
+- archive generation and Phase 2 memory extraction continue asynchronously on the server
+- the current turn is not blocked waiting for extraction
+- if `logFindRequests` is enabled, the logs include the task id and follow-up extraction detail
-- `memory_recall`: search long-term memory explicitly
-- `memory_store`: write text into an OpenViking session and force extraction
-- `memory_forget`: delete a known memory URI or search and delete a strong single match
-- `ov_archive_expand`: reopen a compressed session archive when the summary is not enough
+### What `compact()` does
-For operators, the main surfaces are:
+`compact()` is the stricter synchronous boundary:
-- Web Console: inspect OpenViking files and memory state
-- `ov tui`: browse local OpenViking data in terminal
-- `ov-install --current-version`: show installed plugin version and OpenViking version
-- `openclaw config get plugins.entries.openviking.config`: inspect current plugin config
+- it calls `commit(wait=true)` and blocks for completion
+- when an archive exists, it re-reads `latest_archive_overview`
+- it returns updated token estimates, the latest archive id, and summary content
+- if the summary is too coarse, the model can call `ov_archive_expand` to reopen a specific archive
-## Tools
+So `afterTurn()` is closer to “incremental append plus threshold-triggered async commit”, while `compact()` is the explicit “wait for archive and compaction to finish” boundary.
-### Web Console
+## Tools and Expandability
-OpenViking includes a Web Console for inspecting stored files, debugging ingestion, and checking memory state.
+Beyond automatic behavior, the plugin exposes four tools directly:
-Example startup:
+- `memory_recall`: explicit long-term memory search
+- `memory_store`: write text into an OpenViking session and trigger commit
+- `memory_forget`: delete by URI, or search first and remove a single strong match
+- `ov_archive_expand`: expand a concrete archive back into raw messages
-```bash
-python -m openviking.console.bootstrap --host 0.0.0.0 --port 8020 --openviking-url http://127.0.0.1:1933
-```
+They serve different roles:
-### `ov tui`
+- automatic recall covers the default case where the model does not know what to search yet
+- `memory_recall` gives the model an explicit follow-up search path
+- `memory_store` is for immediately persisting clearly important information
+- `ov_archive_expand` is the “go back to archive detail” escape hatch when summaries are not enough
-Use the terminal UI to browse OpenViking files locally:
+`ov_archive_expand` is especially important because `assemble()` normally returns archive summaries and indexes, not the full raw transcript.
-```bash
-ov tui
-```
+## Local / Remote Runtime Modes
-### Version Inspection
+![Runtime modes and routing behavior](./images/openclaw-plugin-runtime-routing.png)
-Show the installed plugin version and OpenViking version:
+The current implementation supports two runtime modes. The upper-layer session, memory, and archive model stays the same in both.
-```bash
-ov-install --current-version
-```
+### Local mode
-### Plugin Config Inspection
+In `local` mode, the plugin manages the OpenViking subprocess itself:
-Print the full current OpenClaw plugin config:
+- resolve Python from `OPENVIKING_PYTHON`, env files, or system defaults
+- prepare the port before startup
+- kill stale OpenViking processes on the target port
+- move to the next free port if another process owns the configured one
+- wait for `/health` before marking the service ready
+- cache the local client so multiple plugin registrations do not spawn duplicates
-```bash
-openclaw config get plugins.entries.openviking.config
-```
+That is why this plugin is not only “memory logic”. It is also a local runtime manager.
-### Logs
+### Remote mode
-OpenClaw plugin log stream:
+In `remote` mode, the plugin behaves as a pure HTTP client:
-```bash
-openclaw logs --follow
-```
+- no local subprocess is started
+- `baseUrl` and optional `apiKey` come from plugin config
+- session context, memory find/read, commit, and archive expansion behavior stays the same
-OpenViking service log, default local path:
+The main difference between `local` and `remote` is who is responsible for bringing up the OpenViking service, not the higher-level context model.
-```bash
-cat ~/.openviking/data/log/openviking.log
-```
+## Relationship to the Older Design Draft
-## Troubleshooting
+The repo also contains a more future-looking design draft at `docs/design/openclaw-context-engine-refactor.md`. It is important not to conflate the two:
-| Symptom | Likely Cause | What to Check |
-| --- | --- | --- |
-| `plugins.slots.contextEngine` is not `openviking` | Plugin slot was not set or was replaced | `openclaw config get plugins.slots.contextEngine` |
-| Local mode does not start correctly | Python path, env file, or `ov.conf` is wrong | `source ~/.openclaw/openviking.env && openclaw gateway restart` |
-| `port occupied` | Local OpenViking port is already used | Change `plugins.entries.openviking.config.port` or free the port |
-| Recall works inconsistently across sessions | Agent/session routing is not what you expected | Enable `logFindRequests` and check `openclaw logs --follow` |
-| Memory is not being captured after long chats | Pending tokens stay below `commitTokenThreshold` or extraction failed server-side | Check plugin config, OpenClaw logs, and `~/.openviking/data/log/openviking.log` |
-| Session summaries are too lossy | You need archive expansion instead of summary-only context | Use `ov_archive_expand` with an ID from `[Archive Index]` |
-| Installed versions are not what you expected | Plugin and OpenViking runtime versions diverged | Run `ov-install --current-version` |
+- this README describes current implemented behavior
+- the older draft discusses a stronger future move into context-engine-owned lifecycle control
+- in the current version, the main automatic recall path still lives in `before_prompt_build`, not fully in `assemble()`
+- in the current version, `afterTurn()` already appends to the OpenViking session, but commit remains threshold-triggered and asynchronous on that path
+- in the current version, `compact()` already uses `commit(wait=true)`, but it is still focused on synchronous commit plus readback rather than owning every orchestration concern
+
+That distinction matters, otherwise the future design draft is easy to misread as already shipped behavior.
-## Usage Tutorials
+## Operator and Debugging Surfaces
-### Inspect the Current Setup
+If you need to debug this plugin, start with these entry points.
-Use these commands together:
+### Inspect the current setup
```bash
ov-install --current-version
@@ -200,51 +200,41 @@ openclaw config get plugins.entries.openviking.config
openclaw config get plugins.slots.contextEngine
```
-### Follow Recall and Capture
+### Watch logs
-Watch the OpenClaw side:
+OpenClaw plugin logs:
```bash
openclaw logs --follow
```
-Then inspect the OpenViking side:
+OpenViking service logs:
```bash
cat ~/.openviking/data/log/openviking.log
```
-This is the fastest way to see session commit, archive generation, memory recall, and memory extraction.
-
-### Switch to Remote Mode
-
-If you already have a remote OpenViking service:
+### Web Console
```bash
-openclaw config set plugins.entries.openviking.config.mode remote
-openclaw config set plugins.entries.openviking.config.baseUrl http://your-server:1933
-openclaw config set plugins.entries.openviking.config.apiKey your-api-key
-openclaw config set plugins.entries.openviking.config.agentId your-agent-id
-openclaw gateway restart
-```
-
-### Inspect Archived Session Details
-
-When the model only has a session summary, reopen a concrete archive:
-
-```text
-Use ov_archive_expand with an archive ID from [Archive Index]
+python -m openviking.console.bootstrap --host 0.0.0.0 --port 8020 --openviking-url http://127.0.0.1:1933
```
-### Browse Stored Memory
-
-Use the local terminal UI:
+### `ov tui`
```bash
ov tui
```
-Or use Web Console if you want a browser-based view of the stored memory data.
+### Common things to check
+
+| Symptom | More likely cause | First check |
+| --- | --- | --- |
+| `plugins.slots.contextEngine` is not `openviking` | The plugin slot was never set, or another plugin replaced it | `openclaw config get plugins.slots.contextEngine` |
+| `local` mode fails to start | Python path, env file, or `ov.conf` is wrong | `source ~/.openclaw/openviking.env && openclaw gateway restart` |
+| recall behaves inconsistently across sessions | Routing identity is not what you expected | Enable `logFindRequests`, then inspect `openclaw logs --follow` |
+| long chats stop extracting memory | `pending_tokens` never crosses the threshold, or Phase 2 fails server-side | Check plugin config and `~/.openviking/data/log/openviking.log` |
+| summaries are too coarse for detailed questions | You need archive-level detail, not just summary | Use an ID from `[Archive Index]` with `ov_archive_expand` |
---
diff --git a/examples/openclaw-plugin/README_CN.md b/examples/openclaw-plugin/README_CN.md
index 9c0079c89..ced61b4a7 100644
--- a/examples/openclaw-plugin/README_CN.md
+++ b/examples/openclaw-plugin/README_CN.md
@@ -2,197 +2,197 @@
使用 [OpenViking](https://github.com/volcengine/OpenViking) 作为 [OpenClaw](https://github.com/openclaw/openclaw) 的长期记忆后端。在 OpenClaw 中,此插件注册为 `openviking` 上下文引擎。
+本文档不是安装教程,而是面向集成方和工程师的“当前实现设计说明”。它基于 `examples/openclaw-plugin` 里的现有代码,重点解释这套插件今天实际上如何工作,而不是未来可能的重构方向。
+
## 文档入口
- 安装与升级:[INSTALL-ZH.md](./INSTALL-ZH.md)
- English install guide: [INSTALL.md](./INSTALL.md)
- Agent 专用操作文档:[INSTALL-AGENT.md](./INSTALL-AGENT.md)
-## 技术架构
+## 设计定位
-### 插件承担了什么职责
+- OpenClaw 仍然负责 agent runtime、prompt 编排和工具执行。
+- OpenViking 负责长期记忆检索、session 归档、archive summary 和记忆抽取。
+- `examples/openclaw-plugin` 不是一个单一职责的“记忆查询插件”,而是一组围绕 OpenClaw 生命周期工作的集成层。
-这个插件不只是“查记忆”的一层封装。按代码职责看,它同时扮演四个角色:
+按当前代码职责看,插件同时扮演四个角色:
-- `context-engine` 插件:实现 `assemble`、`afterTurn`、`compact`
+- `context-engine`:实现 `assemble`、`afterTurn`、`compact`
- Hook 层:接管 `before_prompt_build`、`session_start`、`session_end`、`agent_end`、`before_reset`
- Tool 提供者:注册 `memory_recall`、`memory_store`、`memory_forget`、`ov_archive_expand`
-- 运行时管理器:在 `local` 模式下负责拉起并监控 OpenViking 子进程
+- 运行时管理器:在 `local` 模式下拉起并监控 OpenViking 子进程
-OpenClaw 仍然负责 agent 运行时和 prompt 编排,OpenViking 负责长期记忆检索、会话归档和记忆抽取。
+## 总体架构
-### 身份与路由
+![OpenClaw 与 OpenViking 插件总体架构](./images/openclaw-plugin-engine-overview.png)
-插件并不是把所有请求都打到一个固定的 agent ID 上,而是尽量保持 OpenClaw 会话身份和 OpenViking 路由一致:
+上图对应的是当前实现里的整体边界:
-- `sessionId` 或 `sessionKey` 会被映射成 OpenViking 可接受的 session ID
-- UUID 会直接复用;不安全的 ID 会退化成稳定的 SHA-256
-- `X-OpenViking-Agent` 是按会话解析的,不是按进程写死的
-- 如果 `plugins.entries.openviking.config.agentId` 不是 `default`,它会作为前缀,形成 `<configAgentId>_<sessionAgent>`
-- 实际 HTTP 请求由 client 层补全 `X-OpenViking-*` 头,打开 `logFindRequests` 后可以看到详细路由日志
+- OpenClaw 在左侧,仍然是主运行时;插件并不接管 agent 执行本身。
+- 插件中间层把 Hook、Context Engine、Tools、Runtime Manager 四部分合并在一个注册单元里。
+- 所有 HTTP 调用最终都走 `OpenVikingClient`,由 client 层统一补 `X-OpenViking-*` 头和路由日志。
+- OpenViking 服务端承接 session、memory、archive 和 Phase 2 抽取,底层存储落在 `viking://user/*`、`viking://agent/*`、`viking://session/*`。
-这样做的目的,是支持多 agent、多 session 场景下的记忆隔离,避免不同会话串到一起。
+这套拆分的意义,是让 OpenClaw 继续专注推理与编排,让 OpenViking 成为长期上下文的事实源。
-### Session 生命周期
+## 身份与路由
-Session 是这套设计的核心,不只是“保留一段历史”这么简单。
+这套插件不是把所有请求都打到一个固定 agent ID 上,而是尽量保持 OpenClaw 会话身份和 OpenViking 路由一致。
-1. OpenClaw 会话标识先被映射成 OpenViking session ID。
-2. `assemble()` 按 token budget 向 OpenViking 拉取会话上下文。
-3. 归档摘要会被改写成 `[Session History Summary]` 和 `[Archive Index]`。
-4. 当前活跃消息会重新转换回 OpenClaw 可消费的消息格式。
-5. tool call / tool result 会做一次修复,保证 transcript 对各模型提供方更稳。
-6. `afterTurn()` 只提取当前这一轮新增内容,清洗后追加进 OpenViking session。
-7. 当 `pending_tokens` 超过 `commitTokenThreshold`,插件会提交 session,后端异步跑 Phase 2 记忆抽取。
-8. `compact()` 会阻塞等待归档完成,再回读压缩后的上下文。
+核心规则如下:
-因此,OpenClaw 侧拿到的是适合推理的精简上下文,OpenViking 侧保存的是长会话归档和抽取后的长期记忆。
+- `sessionId` 是 UUID 时直接复用。
+- `sessionKey` 存在时优先用它生成稳定的 `ovSessionId`。
+- 非安全路径字符会被规整或退化成稳定的 SHA-256。
+- `X-OpenViking-Agent` 按 session 解析,不按进程写死。
+- 若 `plugins.entries.openviking.config.agentId` 不是 `default`,会形成 `<configAgentId>_<sessionAgent>` 的前缀形式。
+- client 层统一补全 `X-OpenViking-Account`、`X-OpenViking-User`、`X-OpenViking-Agent` 这些 header。
-### `assemble()` 实际组装了什么
+这样做是为了支持多 agent、多 session 并发时的记忆隔离,避免不同 OpenClaw 会话串用同一套长期上下文。
-这里并不是简单地“把旧聊天记录塞回来”。
+## Prompt 前召回链路
-- archive overview 会变成压缩后的 session summary
-- 历史 archive 会变成有顺序的 archive index
-- 当前活跃消息保持未压缩状态
-- 如果摘要不够精确,模型可以调用 `ov_archive_expand` 打开某个 archive 的原始消息
+![Prompt 前的自动召回流程](./images/openclaw-plugin-recall-flow.png)
-这也是插件能撑长会话的原因:它不会把整段原始 transcript 永远重复喂回 OpenClaw。
+当前主召回路径仍然挂在 `before_prompt_build`,流程是:
-### 记忆召回与写入链路
+1. 从 `messages` 或 `prompt` 中提取最后一条用户文本。
+2. 基于当前 `sessionId/sessionKey` 解析本轮的 agent 路由。
+3. 先做一次快速可用性检查,避免在 OpenViking 不可用时把 prompt 前链路拖死。
+4. 并行检索 `viking://user/memories` 和 `viking://agent/memories`。
+5. 在插件侧做去重、阈值筛选、重排和 token budget 裁剪。
+6. 把最终记忆块以 `<relevant-memories>` 形式 prepend 到 prompt。
-每一轮对话前后,其实有两条记忆链路。
+这里的重排不是单纯依赖向量分数。当前实现还会额外考虑:
-生成前:
+- 是否是 `level == 2` 的叶子记忆
+- 是否属于偏好类记忆
+- 是否属于事件类记忆
+- 与当前 query 的词面重合度
-- `before_prompt_build` 提取最后一条用户文本
-- 同时检索 `viking://user/memories` 和 `viking://agent/memories`
-- 结果会先去重,再重排,再按 token budget 截断
-- 最终以 `<relevant-memories>` 的形式注入上下文
+### Transcript ingest assist
-生成后:
+除了普通 recall,这条链路还包含一个“转录文本辅助分支”。
-- `afterTurn` 把本轮新增内容格式化成可写入文本
-- assistant 文本、`toolUse`、`toolResult` 都会保留
-- 注入过的记忆块和元数据噪音会先被剥掉
-- OpenViking session commit 会触发 archive + memory extraction
+如果最后一条用户输入看起来像多说话人的转录文本:
-这里的重排不是纯看向量分数。代码里还会额外提升 preference、event、leaf memory 以及 query 词面重合度。
+- 会先清理 metadata block、命令文本、纯提问文本等噪音
+- 再按说话人数和文本长度做 transcript-like 判断
+- 命中后 prepend 一个很轻量的 `<ingest-reply-assist>` 指令
-### Transcript Ingest Assist
+它的目标不是改写记忆逻辑,而是降低模型在“用户粘贴聊天记录/会议纪要/对话转录”这类场景里直接返回 `NO_REPLY` 的概率。
-插件对“用户贴了一段多说话人转录文本”这种场景也单独做了处理。
+## Session 生命周期
-- 通过说话人数阈值和文本长度判断是否像 transcript
-- 命令文本、元数据块、纯提问型文本会被排除
-- 一旦判断为 transcript-like ingest,会额外注入一段轻量提示,减少模型直接返回 `NO_REPLY`
+![Session 生命周期与压缩边界](./images/openclaw-plugin-session-lifecycle.png)
-这主要服务于“把聊天记录、会议记录、对话转录灌进记忆系统”这类使用方式。
+Session 是这套设计的主轴。当前实现里,它覆盖了“历史组装、增量写入、异步提交、阻塞压缩回读”四个动作。
-### Local 和 Remote 运行模式
+### `assemble()` 负责什么
-#### Local 模式
+`assemble()` 并不是简单地把旧聊天记录塞回来,而是按 token budget 从 OpenViking 回读当前 session context,然后重新组装成 OpenClaw 可消费的消息:
-`local` 模式下,插件自己拉起 OpenViking。
+- `latest_archive_overview` 被改写成 `[Session History Summary]`
+- `pre_archive_abstracts` 被改写成 `[Archive Index]`
+- 当前活跃消息保持 message block 形式回放
+- assistant 的 tool part 会被还原成 `toolUse`
+- tool output 会被拆成独立的 `toolResult`
+- 之后再做一轮 `toolUse/toolResult` 配对修复,降低 transcript 结构不稳定的风险
-- 会从 `OPENVIKING_PYTHON`、env 文件或系统默认值解析 Python
-- 启动前先处理端口
-- 如果端口上残留旧 OpenViking,会主动清理
-- 如果端口被别的进程占用,会自动找下一个空闲端口
-- 只有 `/health` 检查通过后,才认为服务可用
-- 会缓存 local client,避免多个 OpenClaw 插件上下文重复拉起运行时
+因此,OpenClaw 拿到的是“压缩后的历史摘要 + archive 索引 + 当前活跃消息”,而不是无限增长的原始 transcript。
-#### Remote 模式
+### `afterTurn()` 负责什么
-`remote` 模式下,插件只走 HTTP API。
+`afterTurn()` 的职责更窄,专门处理本轮增量写入:
-- 不会启动本地子进程
-- `baseUrl` 和可选的 `apiKey` 来自 OpenClaw 插件配置
-- session、召回、archive、tool 的整体逻辑保持不变
+- 只切出本轮新增消息,不重写整段对话
+- 只保留 `user` / `assistant` 相关文本内容
+- 会把 `toolUse` / `toolResult` 格式化进 capture 文本
+- 会先剥掉注入过的 `<relevant-memories>` 和元数据噪音
+- 最终把清洗后的增量内容追加到 OpenViking session
-### 工具与运维入口
+之后插件会读取 session 的 `pending_tokens`。当它超过 `commitTokenThreshold` 时,会触发一次 `commit(wait=false)`:
-除了自动记忆行为,插件还直接暴露了几类工具:
+- archive 和 Phase 2 记忆抽取在服务端异步继续跑
+- 当前 turn 不会因为等待抽取而阻塞
+- 如果打开 `logFindRequests`,日志里能看到 task id 和后续抽取结果
-- `memory_recall`:显式检索长期记忆
-- `memory_store`:写入文本到 OpenViking session 并立即触发抽取
-- `memory_forget`:按 URI 删除,或先搜索再删除唯一高置信候选
-- `ov_archive_expand`:当摘要不够时,展开某个压缩 archive 的原始消息
+### `compact()` 负责什么
-对运维和调试来说,常用入口有:
+`compact()` 走的是另一条更严格的同步边界:
-- Web Console:看 OpenViking 文件和记忆状态
-- `ov tui`:在终端里浏览本地数据
-- `ov-install --current-version`:查看插件版本和 OpenViking 版本
-- `openclaw config get plugins.entries.openviking.config`:查看当前插件配置
+- 它调用 `commit(wait=true)`,阻塞等待 commit 完成
+- 如果有 archive 生成,会再回读 `latest_archive_overview`
+- 返回新的 token 估算、latest archive id 和 summary
+- 如果摘要不够精确,模型可以再调用 `ov_archive_expand` 读取某个 archive 的原始消息
-## 工具
+所以 `afterTurn()` 更像“增量写入 + 条件触发异步提交”,而 `compact()` 才是“明确等待压缩与归档完成”的正式边界。
-### Web Console
+## 工具层与可展开能力
-OpenViking 自带 Web Console,可用于查看存储文件、调试写入和观察记忆状态。
+这套插件除了自动行为,还直接暴露了 4 个工具:
-示例启动命令:
+- `memory_recall`:显式检索长期记忆
+- `memory_store`:把文本写入 OpenViking session 并立即触发 commit
+- `memory_forget`:按 URI 删除,或先搜索再删除唯一高置信候选
+- `ov_archive_expand`:展开某个 archive 的原始消息
-```bash
-python -m openviking.console.bootstrap --host 0.0.0.0 --port 8020 --openviking-url http://127.0.0.1:1933
-```
+它们各自的作用不同:
-### `ov tui`
+- 自动 recall 解决“模型不知道该先查什么”的默认场景。
+- `memory_recall` 给模型一个显式补查入口。
+- `memory_store` 适合把一段明确的重要信息立刻落入记忆管线。
+- `ov_archive_expand` 负责在 summary 不够细时回到 archive 级原文。
-可以用终端界面浏览本地 OpenViking 文件:
+其中 `ov_archive_expand` 是 `assemble()` 的重要补充,因为 `assemble()` 默认给的是压缩后的索引和摘要,而不是完整历史正文。
-```bash
-ov tui
-```
+## Local / Remote 运行模式
-### 查看版本
+![运行模式与路由解析](./images/openclaw-plugin-runtime-routing.png)
-查看当前已安装的插件版本和 OpenViking 版本:
+当前实现支持两种运行方式,但 session、memory、archive 的上层逻辑是一致的。
-```bash
-ov-install --current-version
-```
+### Local 模式
-### 查看插件配置
+`local` 模式下,插件自己管理 OpenViking 子进程:
-查看当前 OpenClaw 插件整体配置:
+- 解析 `OPENVIKING_PYTHON`、env 文件或系统默认 Python
+- 启动前先做端口准备
+- 若目标端口上残留旧 OpenViking,会尝试清理
+- 若端口被其他进程占用,会自动寻找下一个空闲端口
+- 只有 `/health` 成功后,才把服务视为可用
+- 会缓存 local client,避免同一环境里重复拉起多个运行时
-```bash
-openclaw config get plugins.entries.openviking.config
-```
+这也是为什么插件不仅是“查记忆的逻辑层”,还是一个本地运行时管理器。
-### 日志
+### Remote 模式
-OpenClaw 插件侧日志:
+`remote` 模式下,插件只作为 HTTP 客户端工作:
-```bash
-openclaw logs --follow
-```
+- 不会启动本地子进程
+- `baseUrl` 和可选 `apiKey` 由插件配置提供
+- session context、memory find/read、commit、archive expand 这些行为保持不变
-OpenViking 服务侧日志,默认本地路径:
+换句话说,`local` 和 `remote` 的差异主要在“谁负责把 OpenViking 服务启动起来”,不在上层的上下文模型本身。
-```bash
-cat ~/.openviking/data/log/openviking.log
-```
+## 与旧设计稿的关系
-## 故障排查
+仓库里还有一份更偏“未来演进方向”的设计稿:`docs/design/openclaw-context-engine-refactor.md`。阅读时需要区分两者的口径:
-| 现象 | 常见原因 | 排查方式 |
-| --- | --- | --- |
-| `plugins.slots.contextEngine` 不是 `openviking` | 插件槽位未设置,或被其它插件占用 | `openclaw config get plugins.slots.contextEngine` |
-| `local` 模式启动异常 | Python 路径、env 文件或 `ov.conf` 有问题 | `source ~/.openclaw/openviking.env && openclaw gateway restart` |
-| `port occupied` | 本地 OpenViking 端口已被占用 | 修改 `plugins.entries.openviking.config.port` 或释放端口 |
-| 不同 session 的 recall 表现不稳定 | agent/session 路由和预期不一致 | 打开 `logFindRequests`,再看 `openclaw logs --follow` |
-| 长对话后没有继续写入记忆 | `pending_tokens` 没达到阈值,或服务端抽取失败 | 检查插件配置、OpenClaw 日志和 `~/.openviking/data/log/openviking.log` |
-| session summary 过于模糊 | 你需要 archive 级别细节,不是只看摘要 | 用 `[Archive Index]` 里的 ID 调用 `ov_archive_expand` |
-| 当前版本和预期不一致 | 插件版本和 OpenViking 运行时版本未对齐 | 运行 `ov-install --current-version` |
+- 本文描述的是当前实现已经落地的行为。
+- 旧设计稿讨论的是“进一步把更多主链路迁入 context-engine 生命周期”的目标态。
+- 当前版本里,自动 recall 的主入口仍然在 `before_prompt_build`,并没有完全迁到 `assemble()`。
+- 当前版本里,`afterTurn()` 已经负责增量写入 OpenViking session,但它仍然依赖阈值触发异步 commit。
+- 当前版本里,`compact()` 已经走 `commit(wait=true)`,但它的职责仍以“同步提交 + 结果回读”为主,而不是承载一切上层编排。
+
+这段区分很重要,否则很容易把未来设计误读成现状。
-## 使用教程
+## 运维与调试入口
-### 查看当前整体状态
+如果你要排查这套插件,优先看这几类入口:
-建议一起执行:
+### 查看当前配置
```bash
ov-install --current-version
@@ -200,51 +200,41 @@ openclaw config get plugins.entries.openviking.config
openclaw config get plugins.slots.contextEngine
```
-### 观察召回和写入链路
+### 看日志
-先看 OpenClaw 侧日志:
+OpenClaw 插件侧日志:
```bash
openclaw logs --follow
```
-再看 OpenViking 侧日志:
+OpenViking 服务侧日志:
```bash
cat ~/.openviking/data/log/openviking.log
```
-这是判断 session commit、archive 生成、记忆召回和记忆抽取是否正常的最快方式。
-
-### 切换到 Remote 模式
-
-如果已经有远端 OpenViking 服务:
+### Web Console
```bash
-openclaw config set plugins.entries.openviking.config.mode remote
-openclaw config set plugins.entries.openviking.config.baseUrl http://your-server:1933
-openclaw config set plugins.entries.openviking.config.apiKey your-api-key
-openclaw config set plugins.entries.openviking.config.agentId your-agent-id
-openclaw gateway restart
-```
-
-### 查看压缩会话的原始细节
-
-当模型只拿到了摘要,但你需要更精确的命令、路径或代码内容时:
-
-```text
-使用 [Archive Index] 里的 archive ID 调用 ov_archive_expand
+python -m openviking.console.bootstrap --host 0.0.0.0 --port 8020 --openviking-url http://127.0.0.1:1933
```
-### 浏览记忆内容
-
-可以使用本地终端界面:
+### `ov tui`
```bash
ov tui
```
-如果希望用浏览器查看,也可以使用 Web Console。
+### 常见排查点
+
+| 现象 | 更可能的原因 | 优先检查 |
+| --- | --- | --- |
+| `plugins.slots.contextEngine` 不是 `openviking` | 插件槽位未设置或被其他插件覆盖 | `openclaw config get plugins.slots.contextEngine` |
+| `local` 模式启动失败 | Python 路径、env 文件或 `ov.conf` 不对 | `source ~/.openclaw/openviking.env && openclaw gateway restart` |
+| recall 在不同 session 间不稳定 | 路由身份和预期不一致 | 打开 `logFindRequests`,再看 `openclaw logs --follow` |
+| 长对话后没有持续抽取记忆 | `pending_tokens` 未过阈值,或服务端 Phase 2 失败 | 检查插件配置和 `~/.openviking/data/log/openviking.log` |
+| summary 太粗,不够回答细节问题 | 你要的是 archive 级明细,不是摘要 | 用 `[Archive Index]` 里的 ID 调用 `ov_archive_expand` |
---
diff --git a/examples/openclaw-plugin/images/openclaw-plugin-engine-overview.png b/examples/openclaw-plugin/images/openclaw-plugin-engine-overview.png
new file mode 100644
index 000000000..39b66d0c8
Binary files /dev/null and b/examples/openclaw-plugin/images/openclaw-plugin-engine-overview.png differ
diff --git a/examples/openclaw-plugin/images/openclaw-plugin-recall-flow.png b/examples/openclaw-plugin/images/openclaw-plugin-recall-flow.png
new file mode 100644
index 000000000..cfe8edb4f
Binary files /dev/null and b/examples/openclaw-plugin/images/openclaw-plugin-recall-flow.png differ
diff --git a/examples/openclaw-plugin/images/openclaw-plugin-runtime-routing.png b/examples/openclaw-plugin/images/openclaw-plugin-runtime-routing.png
new file mode 100644
index 000000000..e9834e788
Binary files /dev/null and b/examples/openclaw-plugin/images/openclaw-plugin-runtime-routing.png differ
diff --git a/examples/openclaw-plugin/images/openclaw-plugin-session-lifecycle.png b/examples/openclaw-plugin/images/openclaw-plugin-session-lifecycle.png
new file mode 100644
index 000000000..73a8884e0
Binary files /dev/null and b/examples/openclaw-plugin/images/openclaw-plugin-session-lifecycle.png differ