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(openclaw-plugin): refresh architecture guides with diagrams (#1145)
Qin Haojie2bc65f3869ae
diff --git a/examples/openclaw-plugin/README.md b/examples/openclaw-plugin/README.mdindex 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+-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+-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`+-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+-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```bashov-install --current-version@@ -200,51 +200,41 @@ openclaw config get plugins.entries.openviking.configopenclaw config get plugins.slots.contextEngine```-### Follow Recall and Capture+### Watch logs-Watch the OpenClaw side:+OpenClaw plugin logs:```bashopenclaw logs --follow```-Then inspect the OpenViking side:+OpenViking service logs:```bashcat ~/.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````bashov 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.mdindex 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 负责长期记忆检索、会话归档和记忆抽取。+## 总体架构-### 身份与路由+-插件并不是把所有请求都打到一个固定的 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 的原始消息+-这也是插件能撑长会话的原因:它不会把整段原始 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 是这套设计的主轴。当前实现里,它覆盖了“历史组装、增量写入、异步提交、阻塞压缩回读”四个动作。-### 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 运行模式-### 查看版本+-查看当前已安装的插件版本和 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)`,但它的职责仍以“同步提交 + 结果回读”为主,而不是承载一切上层编排。++这段区分很重要,否则很容易把未来设计误读成现状。-## 使用教程+## 运维与调试入口-### 查看当前整体状态+如果你要排查这套插件,优先看这几类入口:-建议一起执行:+### 查看当前配置```bashov-install --current-version@@ -200,51 +200,41 @@ openclaw config get plugins.entries.openviking.configopenclaw config get plugins.slots.contextEngine```-### 观察召回和写入链路+### 看日志-先看 OpenClaw 侧日志:+OpenClaw 插件侧日志:```bashopenclaw logs --follow```-再看 OpenViking 侧日志:+OpenViking 服务侧日志:```bashcat ~/.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````bashov 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.pngnew file mode 100644index 000000000..39b66d0c8Binary files /dev/null and b/examples/openclaw-plugin/images/openclaw-plugin-engine-overview.png differdiff --git a/examples/openclaw-plugin/images/openclaw-plugin-recall-flow.png b/examples/openclaw-plugin/images/openclaw-plugin-recall-flow.pngnew file mode 100644index 000000000..cfe8edb4fBinary files /dev/null and b/examples/openclaw-plugin/images/openclaw-plugin-recall-flow.png differdiff --git a/examples/openclaw-plugin/images/openclaw-plugin-runtime-routing.png b/examples/openclaw-plugin/images/openclaw-plugin-runtime-routing.pngnew file mode 100644index 000000000..e9834e788Binary files /dev/null and b/examples/openclaw-plugin/images/openclaw-plugin-runtime-routing.png differdiff --git a/examples/openclaw-plugin/images/openclaw-plugin-session-lifecycle.png b/examples/openclaw-plugin/images/openclaw-plugin-session-lifecycle.pngnew file mode 100644index 000000000..73a8884e0Binary files /dev/null and b/examples/openclaw-plugin/images/openclaw-plugin-session-lifecycle.png differ