Skip to content

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

docs(design): consolidate openclaw plugin docs into single design doc (#2043)

AutoCoder185bce89349a
diff --git a/docs/design/openclaw-context-engine-refactor.md b/docs/design/openclaw-context-engine-refactor.md
deleted file mode 100644
index cbdec7ab0..000000000
--- a/docs/design/openclaw-context-engine-refactor.md
+++ /dev/null
@@ -1,670 +0,0 @@
-# OpenClaw Plugin 升级为真正上下文引擎的设计方案
-
-## 1. 背景与目标
-
-当前 `examples/openclaw-plugin` 已经具备 OpenViking 记忆写入、自动召回和工具式记忆操作能力,但整体仍然是“记忆插件 + 一个很薄的 context-engine 外壳”,而不是由 context-engine 生命周期统一负责上下文管理的真正上下文引擎。
-
-现状特征:
-
-- 自动召回主路径仍挂在 `before_prompt_build`
-- 自动写入主路径仍挂在 `afterTurn`
-- `assemble()` 目前基本没有承担上下文组装职责
-- `compact()` 仍然委托 legacy engine,OpenViking 只参与记忆提取
-
-这会带来 4 类问题:
-
-1. OpenViking 统一以 context engine 的方式注册,但继续保留并使用原有 hook 链路。这里的 hook 能力并不等同于“必须注册成独立 memory plugin 并占据 `kind=memory` slot 才能使用”的能力。当前问题不是要去掉 hook,而是要把 hook 与 context engine 生命周期之间的职责分工、调用优先级和数据流转规则明确收口。
-2. 自动召回结果目前以 `prependContext` 文本块直接注入,模型只能看到结果内容,看不到检索动作本身。这使自动召回与显式 `memory_recall` 工具在模型视角下不一致,模型也无法基于当前 recall 的 query 和结果边界判断是否需要继续检索。
-3. 当前 compact 仍由 legacy engine 主导,OpenViking 只是在 compact 过程中附带参与记忆提取,尚未成为这条链路的正式主控方。因此,原始上下文的无损落盘、compact summary 生成、长期记忆提取、后续历史回放与来源追溯还没有被收口为一条统一的数据链路。
-4. 后续如果要支持 skill memory、tool memory 和 session history expand,这些能力都需要跨越“原始 turn 写入、上下文组装、compact、历史回放、来源追溯”多个阶段流转。当前插件里还缺少统一的引擎状态和稳定的数据模型来记录这些对象及其引用关系,后续扩展容易分散在多个局部逻辑中,难以形成一致的数据链路。
-
-## 2. 设计原则
-
-后续实现统一遵循以下原则。
-
-### 2.1 职责分层
-
-OpenViking 统一注册为 context engine,但继续保留原有 hook 链路。后续需要明确的是二者的职责边界:hook 继续承接兼容路径和局部增强能力;完整的上下文组装、compact、历史回放和主生命周期协同由 context engine 统一编排。
-
-### 2.2 复用 OpenViking 原生能力
-
-优先复用 OpenViking 已有的 `Session -> Commit -> Archive -> Memory Extract` 体系,不在插件层额外创造第二套上下文生命周期,也不新增独立数据库。实现上尽量沿用以下能力完成闭环:
-
-- `session.add_message`
-- `session.commit`
-- session archive / summary
-- memory extract pipeline
-- VikingFS 中已有的 user/agent/session 存储分层
-
-### 2.3 无损优先
-
-每轮参与推理的原始上下文必须先保存,再考虑抽取和压缩。compact 压缩的是“模型接下来看到的工作上下文”,不是 OpenViking 中已经无损保存的原始 turn / session 数据;压缩结果也不能替代原始消息本体。
-
-### 2.4 可追溯、可展开
-
-原始数据是后续追溯、重新抽取和历史展开的事实基座。无论长期记忆、compact summary 还是后续 expand,都必须保留到原始 turn/session 的稳定引用。
-
-### 2.5 分阶段落地
-
-先把插件升级成真正的 context-engine 闭环,再引入 skill/tool memory 等增强能力。Phase 1 完成后,插件就应当已经具备“真正上下文引擎”的最小定义。
-
-
-本文档作为后续开发执行规范,聚焦 OpenClaw 插件升级为真正上下文引擎时的目标架构、数据模型和落地步骤,并优先按各个 hook 的实施职责组织说明。
-
-参考资料:
-- [OpenViking Session 管理文档](/Users/quemingjian/Source/OpenViking/docs/en/concepts/08-session.md)
-
----
-
-## 3. 按 Hook 的当前实现与实施清单
-
-当前相关实现主要分布于:
-
-- [examples/openclaw-plugin/index.ts](/Users/quemingjian/Source/OpenViking/examples/openclaw-plugin/index.ts)
-- [examples/openclaw-plugin/context-engine.ts](/Users/quemingjian/Source/OpenViking/examples/openclaw-plugin/context-engine.ts)
-- [examples/openclaw-plugin/client.ts](/Users/quemingjian/Source/OpenViking/examples/openclaw-plugin/client.ts)
-
-## 3.1 `before_prompt_build`: 兼容 fallback 与迁移约束
-
-### 当前实现
-
-当前 `before_prompt_build` 会执行搜索,并把 recall 结果拼接为 `<relevant-memories>` 文本块注入。
-
-### 职责
-
-在 Phase 1 期间保留 fallback recall,保证旧环境仍可工作;一旦 `assemble()` 成为主链路,这个 hook 只保留兼容职责,不再承担默认实现。
-
-### 实施清单
-
-1. 保留当前 recall fallback 作为兼容与降级路径,保证旧环境继续可用;后续新增的自动召回能力、上下文编排能力和注入形态演进统一落在 `assemble()`,不再继续扩展 `before_prompt_build` 主逻辑。
-2. 延续现有“宽检索、窄注入”的有界策略,不允许回退到无上限全文拼接。
-3. 保持并行检索 `viking://user/memories` 与 `viking://agent/memories` 的做法,并在本地完成去重、筛选、排序和预算裁剪。
-4. 保持 `level === 2` 作为最终可注入 detail memory 的判断标准,不把 L0/L1 直接当作最终注入正文。
-5. 保持 `recallScoreThreshold`、`recallMaxContentChars`、`recallPreferAbstract`、`recallTokenBudget` 这些配置约束继续生效。
-6. 后续迁移到 `assemble()` 时,迁移的是并行检索、去重、`level === 2` 过滤、score threshold、query-aware ranking、摘要优先、单条截断、总 token budget 这些规则本身;迁移完成后,`before_prompt_build` 只保留一个最小 fallback,而不再作为默认主入口。
-
-### 不在此 hook 做的事情
-
-- 不负责主路径上下文组装
-- 不承接 compact 结果回放
-- 不新增新的状态写入逻辑
-
-## 3.2 `afterTurn`: 无损写入主链路
-
-### 当前实现
-
-当前 `afterTurn` 会提取本轮增量 user/assistant 文本,创建临时 OpenViking session,并调用 `/extract`。
-
-### 职责
-afterTurn 在新架构中承担两件事:
-1. **无损写入**:将本轮消息写入 OpenViking session。
-2. **Compact 评估与触发**:判断是否需要调用 `session.commit()` 归档消息和提取记忆。
-两个职责顺序执行:先写入,再评估。评估结果可能导致同步或异步的 compact 调用,但不影响写入的完成。
-
-重构逻辑:
-管理一个OV的Session状态数组,每个Session对应一个OV的Session状态和信息:(下面涉及到的session都是指OV内部定义的session)
-0. Compact状态检查,检查Session数组的状态:
- - 如果数组中没有本次会话期望的sessionId 则新建OV session;
- - 如果数组中有本次会话期望的session, 检查session状态:
- - 如果在Compact状态,则新建会话;
- - 如果在非Compact状态,则复用这个session;
-1. 入口检查:autoCapture 未启用 → 直接返回(复用原逻辑)
-2. 解析身份:调用 resolveAgentId(sessionId) 获取当前 agentId,生成复合 bufferKey = sessionId:agentId
-3. 切片新消息:用 prePromptMessageCount 从完整 messages 中切出本轮新增部分(复用原逻辑)
-4. 提取文本:extractNewTurnTexts 提取 user/assistant 角色的纯文本,无新文本 → 返回(复用原逻辑)
-5. 捕获判断:getCaptureDecision 判断文本是否值得捕获(长度、模式匹配等),不值得 → 返回(复用原逻辑)
-6. 累积到 buffer:按 bufferKey 查找或创建 SessionBuffer,更新 totalChars 和 messageCount
-
-Compact 评估与触发:
-7. 按优先级从高到低逐条判断(命中第一个即触发,不继续往下):
- - 预算阈值:estimatedTokens >= budget × 0.75? → 异步后台 compact
- - 新增 token 积累:tokensAdded >= 30,000? → 异步后台 compact
- - 轮次积累:turns >= 20? → 异步后台 compact
- - 最长间隔:interval >= 30min 且 turns >= 1? → 异步后台 compact
- - 无条件满足 → 不触发
-8. 触发后执行 compact 提交:
- - 调用 `session.commit(wait=false)` 提交 OpenViking session
- - 异步:commit 在后台执行,afterTurn 立即返回,更新 session中 CompactState, 下一轮 Compact状态检查 中确认完成
-
-兜底 flush:进程退出时(service.stop() / SIGTERM / SIGINT),遍历所有 buffer 执行 commitAndReset,确保未提交的累积内容不丢失
-
-#### Compact触发条件与保护机制
-**触发条件**
-
-| 条件 | 场景 | 阈值 | 执行方式 |
-|---|---|---|---|
-| 预算阈值 | 上下文达到预警线 | `estimatedTokens >= budget × 0.75` | 异步后台 |
-| 新增 token 积累 | 大量新内容(大文件、长工具输出等) | `tokensAdded >= 30,000` | 异步后台 |
-| 轮次积累 | 短对话多轮,token 阈值不触发 | `turns >= 20` | 异步后台 |
-| 最长间隔 | 长时间未 compact | `interval >= 30min` 且 turns >= 1 | 异步后台 |
-
-典型场景:
-- **预算阈值**:上下文达到 96k(128k × 0.75),还有余量但该开始压缩了。后台异步执行 commit,不阻塞当前轮返回。这是最常见的触发路径。
-- **新增 token 积累**:总上下文才 60k,远没到阈值,但本轮用户粘贴了一个大文件(35k tokens)。虽然总量不紧张,但大量原始内容堆积不压缩会持续占用空间。对应 lossless-claw 的"叶子触发",但阈值更高(30k vs 20k),因为 `session.commit()` 是全量归档的重操作。
-- **轮次积累**:用户在做代码审查,每轮只问一个短问题(300-500 tokens),20 轮下来才 8k tokens,token 阈值不会触发。但 20 轮的对话已经有足够的信息量值得做一次摘要和记忆提取。
-- **最长间隔**:用户上午聊了 5 轮后去开会,下午回来继续。距离上次 compact 已超过 30 分钟,触发一次整理。要求至少有 1 轮新内容,避免空 commit。
-
-**保护机制**
-| 机制 | 场景 | 说明 |
-|---|---|---|
-| 并发互斥 | 上一轮的异步 compact 还在跑,本轮又触发了条件 | 同一 session 同时只允许一个 compact,避免重复提交 |
-| 异常退出 | 进程退出时(service.stop() / SIGTERM / SIGINT),遍历所有 session 执行 commit,确保未提交的累积内容不丢失 |
-
-## 3.3 `assemble`: 自动召回与上下文组装主链路
-
-### 当前实现
-
-当前 `assemble()` 基本直接回传原始 messages,不承担上下文编排职责。
-
-### 职责
-
-`assemble()` 是真正的上下文组装入口,负责把 profile、长期记忆、recent raw turns、compact summary 统一编排成最终返回给 OpenClaw 的 messages。
-
-### 输入
-
-- 当前 OpenClaw sessionId
-- 当前 messages
-- token budget
-
-### 输出
-
-- 注入后的 `messages`
-- `estimatedTokens`
-- 必要时的 `systemPromptAddition`
-
-### 实施清单
-
-1. 读取 stable profile,包括 `profile.md` 和稳定偏好类高质量记忆。
-2. 从最近 `assembleRecallWindow` 条 user turns 构造 recall query,并做轻量 skip 判断,跳过问候、无内容、纯短句。
-3. 并行检索 `viking://user/memories` 与 `viking://agent/memories`。
-4. 复用当前 fallback recall 的本地约束:去重、`level === 2` 过滤、score threshold、query-aware ranking、摘要优先、单条截断、总 token budget。
-5. 读取 session context,包括最近 raw turns 和最近 compact summary / archive overview。
-6. 把 recalled memories、raw turns、compact summary 混合编排为最终注入消息。
-7. 统一计算 token,并在超预算时优先裁剪 recalled memories 和旧 summary,而不是裁剪最新 raw turns。
-
-### 自动召回的注入形态
-
-自动召回结果不再用:
-
-```text
-<relevant-memories> ... </relevant-memories>
-```
-
-而改为注入为合成消息,形态类似:
-
-```text
-assistant: [tool_call] memory_recall_auto({"query":"..."})
-tool: [tool_result] {"memories":[...], "source":"openviking-auto-recall"}
-```
-
-### 补充职责
-
-- 读取 compact summary,而不是只靠长期记忆支撑历史连续性
-- 将最近未 compact 的 raw turns 与历史 summary 混合组装
-- 为后续 `memory_expand` 提供 summary 到 raw session 的桥梁
-
-## 3.4 `compact`: 正式 commit 边界
-
-### 当前实现
-
-当前 `compact()` 仍调用 legacy context engine 的 compact,OpenViking 只是在其过程中附带参与记忆提取。
-
-### 职责
-
-`compact()` 负责触发 OpenViking `session.commit()`,把 session 写入、归档、summary 生成和长期记忆提取统一收口到一个正式同步点。
-
-### 实施清单
-
-1. 调用 OpenViking `session.commit()`。
-2. 触发当前 session 消息归档。
-3. 读取并记录最新 session summary / archive summary。
-4. 触发长期记忆提取,并记录本次抽取出的 memory URI。
-5. 落 `CompactCheckpoint`,保存本次 compact 的时间、来源 turn 范围和 summary 引用。
-6. 返回新的工作上下文,至少包含最近 `recentRawTurnCount` 条 raw turns、最新 compact summary、必要的 pending tasks / active instructions。
-7. 保证 compact 失败时可回退,不破坏原始 session 数据。
-
-### 与当前实现的差异
-
-- 不再依赖 legacy compact
-- 自动记忆提取从 `afterTurn` 主路径迁移到 `compact` 主路径
-- `compact()` 成为 OpenViking 与 OpenClaw session 边界的正式同步点
-
----
-
-## 4. 终态架构
-
-### 4.1 总体数据流
-
-```text
-OpenClaw turn
- │
- ├─ afterTurn
- │ └─ 将本轮真实上下文写入 OpenViking session(无损保存)
- │
- ├─ assemble
- │ ├─ 读取 profile / stable memories
- │ ├─ 按 query 检索 user/agent memories
- │ ├─ 读取最近 raw turns + compact summaries
- │ └─ 组装成新的 messages 返回给 OpenClaw
- │
- └─ compact
- ├─ 调用 OpenViking session.commit()
- ├─ 归档旧消息并生成 session summary
- ├─ 提取长期记忆
- └─ 返回压缩后的工作上下文
-```
-
-### 4.2 存储分层
-
-本方案不引入新的顶层存储系统,直接复用 OpenViking:
-
-- `viking://session/{user_space}/{session_id}`:保存完整对话 turn、工具调用、上下文使用记录、compact history
-- `viking://user/.../memories`:用户画像、偏好、实体、事件等长期记忆
-- `viking://agent/.../memories`:cases、patterns 等 agent 记忆
-- `viking://agent/.../skills`:后续 skill memory Phase 3 的锚点
-
-### 4.3 关键设计决策
-
-1. 不引入插件侧独立 SQLite / DAG。
-2. 不再把自动召回主结果作为纯文本 prompt prepend。
-3. 自动 recall 的默认注入形态改为“模拟工具调用结果消息”。
-4. compact 的正式语义改为 OpenViking `session.commit()`,而不是 legacy compact + 附带提取。
-5. `memory_store` 仍保留,但只是“显式强制写入”的辅助手段,不再承担主数据链路。
-
----
-
-## 5. 核心数据结构
-
-为了让实现可执行,插件内部需要统一最小数据结构。
-
-### 5.1 TurnEnvelope
-
-每个进入 OpenViking session 的 turn 都按统一结构落盘。
-
-```ts
-type TurnEnvelope = {
- turn_id: string;
- session_id: string;
- sequence: number;
- timestamp: string;
- role: "user" | "assistant" | "system" | "tool";
- parts: Array<
- | { type: "text"; text: string }
- | { type: "tool_call"; tool_name: string; arguments: unknown }
- | { type: "tool_result"; tool_name: string; result: unknown }
- | { type: "context_ref"; uri: string; abstract?: string }
- | { type: "meta"; key: string; value: unknown }
- >;
- used_context_uris: string[];
- used_skills: Array<{
- uri: string;
- input?: string;
- output?: string;
- success?: boolean;
- }>;
- tool_calls: Array<{
- tool_name: string;
- arguments: unknown;
- status?: "success" | "error";
- }>;
- tool_results: Array<{
- tool_name: string;
- result: unknown;
- status?: "success" | "error";
- }>;
- compaction_marker?: {
- source: "raw" | "post_compact";
- compact_checkpoint_id?: string;
- };
-};
-```
-
-约束:
-
-- `parts` 必须能完整表示本轮输入给模型和模型产出的关键上下文
-- `used_context_uris` 记录本轮真正注入的外部上下文 URI
-- `used_skills` 和 `tool_calls/tool_results` 用于后续 patterns/cases 抽取与可追溯分析
-- 当前无法拿到的字段可以先留空,但字段定义必须稳定
-
-### 5.2 AssembledContextPacket
-
-`assemble()` 内部统一生成如下结构,再转换成 OpenClaw `messages`:
-
-```ts
-type AssembledContextPacket = {
- profile_blocks: string[];
- recalled_memories: Array<{
- query: string;
- uri: string;
- abstract?: string;
- score?: number;
- }>;
- compact_summaries: Array<{
- session_uri: string;
- abstract?: string;
- overview?: string;
- }>;
- recent_raw_turns: TurnEnvelope[];
- injected_messages: Array<Record<string, unknown>>;
- estimated_tokens: number;
-};
-```
-
-### 5.3 CompactCheckpoint
-
-每次 compact 后记录一个 checkpoint,用于之后的可展开与调试:
-
-```ts
-type CompactCheckpoint = {
- checkpoint_id: string;
- session_id: string;
- committed_at: string;
- archive_index: number;
- source_turn_range: {
- start_sequence: number;
- end_sequence: number;
- };
- summary_uri?: string;
- extracted_memory_uris: string[];
-};
-```
-
----
-
-## 6. 工具设计
-
-## 6.1 保留工具
-
-保留以下工具,并继续由插件注册:
-
-- `memory_recall`
-- `memory_store`
-- `memory_forget`
-
-其中:
-
-- `memory_recall`:显式检索长期记忆
-- `memory_store`:用户明确要求“记住这件事”时强制写入
-- `memory_forget`:删除或撤销错误记忆
-
-## 6.2 新增工具 `memory_expand`
-
-Phase 2 新增:
-
-```ts
-memory_expand({
- summaryOrMemoryUri: string,
- query?: string,
- limit?: number
-})
-```
-
-返回:
-
-- 关联的 session/archive URI
-- 命中的原始 turn 摘要
-- 可进一步 read 的原始上下文 URI 列表
-
-作用:
-
-- 从 compact summary 回到原始对话片段
-- 从 memory 抽象回到创建它的原始 turn
-- 补足 summary 到原始上下文之间的回钻能力
-
-## 6.3 自动与显式工具的关系
-
-- 自动 recall 由 `assemble()` 触发
-- 显式 recall 由模型主动调用 `memory_recall`
-- 自动 recall 的注入形态与显式 recall 保持一致,降低模型学习成本
-
----
-
-## 7. 配置与兼容策略
-
-### 7.1 保持兼容的配置项
-
-以下现有配置保持保留:
-
-- `mode`
-- `configPath`
-- `port`
-- `baseUrl`
-- `apiKey`
-- `agentId`
-- `timeoutMs`
-- `autoRecall`
-- `autoCapture`
-- `recallLimit`
-- `recallScoreThreshold`
-- `recallMaxContentChars`
-- `recallPreferAbstract`
-- `recallTokenBudget`
-
-### 7.2 新增配置项
-
-新增最小集合:
-
-```ts
-type ContextEngineRefactorConfig = {
- recentRawTurnCount?: number;
- assembleRecallWindow?: number;
- compactCommitThreshold?: number;
- memoryExpandMaxResults?: number;
-};
-```
-
-建议默认值:
-
-- `recentRawTurnCount = 8`
-- `assembleRecallWindow = 5`
-- `compactCommitThreshold = 0.75`
-- `memoryExpandMaxResults = 6`
-
-### 7.3 协同与兼容策略
-
-Phase 1 期间采用双轨兼容:
-
-1. 如果 OpenClaw 支持完整 context-engine 生命周期:
- - 由 `assemble()` / `compact()` 承担完整上下文生命周期
- - 原有 hook 继续保留,用于兼容与局部协同
-2. 如果环境缺少完整能力:
- - 退化到现有 `before_prompt_build` recall 方案
-
-默认目标不是移除 hook,而是让 hook 与 context engine 的职责边界和调用优先级稳定下来,避免重复实现和相互覆盖。
-
-### 7.4 弃用项
-
-以下实现被标记为 deprecated:
-
-- `afterTurn` 中临时 session + `/extract` 的主逻辑
-- `tryLegacyCompact()` 依赖 legacy context engine
-
-说明:
-
-- `before_prompt_build` hook 本身不废弃;被弃用的是把完整自动 recall 主链路长期放在该 hook 中的做法。
-- 原有 hook 体系继续保留,但其职责应收敛到兼容路径和局部增强,而不是继续承接完整上下文生命周期。
-
----
-
-## 8. 分阶段实施方案
-
-## Phase 1: 让插件成为真正 context-engine
-
-### 目标
-
-完成“写入、组装、compact”三条主链路收口。
-
-### 必做项
-
-1. `afterTurn` 改为持久化 `TurnEnvelope`
-2. `assemble()` 接管自动 recall 和上下文组装
-3. 自动 recall 注入形态改为合成工具消息
-4. `compact()` 改为调用 OpenViking `session.commit()`
-5. 保留原有 hook 链路,并明确它与 context engine 生命周期之间的边界、优先级和协同方式
-
-### Phase 1 验收标准
-
-- 在具备完整 context-engine 生命周期的环境中,不依赖 `before_prompt_build` 也能完成自动 recall
-- 不依赖临时 extract 也能正常积累上下文
-- 不依赖 legacy compact 也能完成 compact 与后续连续对话
-
-## Phase 2: 可追溯与可展开
-
-### 目标
-
-让压缩历史真正可回钻。
-
-### 必做项
-
-1. 为 compact 结果落 `CompactCheckpoint`
-2. 读取 session summary / archive overview 参与 `assemble`
-3. 新增 `memory_expand`
-4. 建立 memory -> source turn / session 的追溯关系
-
-### Phase 2 验收标准
-
-- 新 session 中可以回答依赖 compact 前历史的问题
-- 模型在需要时可以通过 `memory_expand` 找回原始细节
-
-## Phase 3: 高级增强能力
-
-这一阶段不阻塞 context-engine 升级成功。
-
-范围包括:
-
-- skill memory 注入
-- tool memory 注入
-- `ov ls viking://` 目录预注入
-- 更细粒度的 recall intent analyzer
-- summary 质量治理与更复杂的层级压缩策略
-
----
-
-## 9. 需要修改的接口与模块
-
-### 9.1 插件侧
-
-- [examples/openclaw-plugin/context-engine.ts](/Users/quemingjian/Source/OpenViking/examples/openclaw-plugin/context-engine.ts)
- - 重写 `assemble()`
- - 重写 `afterTurn()`
- - 重写 `compact()`
-- [examples/openclaw-plugin/index.ts](/Users/quemingjian/Source/OpenViking/examples/openclaw-plugin/index.ts)
- - 将 `before_prompt_build` recall 降级为 fallback
- - 新增 `memory_expand`
- - 迁移自动 recall 辅助逻辑到 context-engine 内部
-- [examples/openclaw-plugin/client.ts](/Users/quemingjian/Source/OpenViking/examples/openclaw-plugin/client.ts)
- - 补充 session commit / summary / archive 相关读写接口
-
-### 9.2 OpenViking 服务端
-
-插件实现默认复用现有 session API,但以下能力若现有返回不够用,需要补充:
-
-1. 读取 session latest summary / archive overview 的便捷接口
-2. 从 memory 反查 source session / source turn 的元数据
-3. compact checkpoint 的持久化查询接口
-
-原则:
-
-- 能复用已有 `session` / `content` / `fs` API 就不新增新协议
-- 若新增 API,必须围绕 “summary read / source trace / expand support” 三类能力展开
-
----
-
-## 10. 测试方案
-
-## 10.1 单元测试
-
-新增或补齐以下测试:
-
-- `TurnEnvelope` 构造与字段完整性
-- recall query window 拼接与 skip 策略
-- 自动 recall 注入消息格式
-- token budget 裁剪
-- 新增配置项解析
-- `memory_expand` 参数校验与结果格式
-
-## 10.2 集成测试
-
-覆盖以下场景:
-
-1. 多轮对话后 `afterTurn` 成功无损写入 session
-2. 触发 compact 后 session 完成 commit、archive、memory extract
-3. 新会话中 `assemble()` 能召回 compact 前历史
-4. `memory_store` 显式提交与自动管线不冲突
-5. 本地模式和远程模式均可工作
-6. 多 agent 场景下 `agentId` 隔离不破坏
-
-## 10.3 回归测试
-
-必须验证:
-
-- 自动注入内容不会再次被 capture
-- OpenViking 服务不可用时,context-engine 优雅降级
-- recall 注入不会导致明显上下文膨胀回归
-- 旧配置文件仍能启动插件
-
----
-
-## 11. 验收场景
-
-以下场景全部成立,才算升级成功。
-
-### 场景 1:长期对话连续性
-
-一个长对话触发 compact 后,后续会话仍能回答:
-
-- “我们上周关于项目 X 做过什么决定?”
-- “之前你给我的数据库优化建议里,哪条是针对慢查询的?”
-
-### 场景 2:显式记忆与自动记忆共存
-
-用户说“记住我偏好深色主题”,插件通过 `memory_store` 立即写入;之后普通对话中的重要决策,在 compact 时通过自动管线进入长期记忆。
-
-### 场景 3:压缩历史可回钻
-
-模型先依据 compact summary 回答,再在需要时通过 `memory_expand` 找回原始 turn 细节,而不是只能依赖抽象 memory。
-
-### 场景 4:引擎而非 hook 主导
-
-禁用 `before_prompt_build` 主 recall 路径后,context-engine 仍能正常工作。
-
----
-
-## 12. 明确不做的事情
-
-本设计不包含以下内容:
-
-- 在插件内自建新的独立持久化数据库
-- 在 Phase 1 中同时上线 skill memory / tool memory 全能力
-- 修改 OpenClaw 内核的 session reset 语义
-
----
-
-## 13. 开发执行建议
-
-建议按以下顺序开发:
-
-1. 先实现 `afterTurn` 的 `TurnEnvelope` 持久化
-2. 再实现 `assemble()` 的 recall 注入与 session summary 读取
-3. 然后切换 `compact()` 到 OpenViking `session.commit()`
-4. 最后补 `memory_expand` 与追溯元数据
-
-原因:
-
-- 先有稳定写入,后续 recall 和 expand 才有可靠数据源
-- 先让 `assemble()` 成为主链路,再移除 hook 才安全
-- `compact()` 最后切换,便于逐步回归验证
-
----
-
-## 14. 默认决策
-
-为避免后续开发再次出现未收敛讨论,本文固定以下默认决策:
-
-1. 文本自动 recall 的默认注入方式为“模拟工具调用结果”,不是 prompt prepend。
-2. 自动长期记忆提取的正式触发边界为 `compact()`,不是每轮 `afterTurn`。
-3. `afterTurn` 的第一职责是无损保存,不是立即抽取。
-4. OpenViking Session 是主存储基座,不新增插件侧独立数据库。
-5. skill memory / tool memory 不进入 Phase 1 验收范围。
-
-以上决策除非后续出现明确阻塞,否则实现阶段不再重新讨论。
diff --git a/docs/design/openclaw-integration.md b/docs/design/openclaw-integration.md
deleted file mode 100644
index a77892633..000000000
--- a/docs/design/openclaw-integration.md
+++ /dev/null
@@ -1,395 +0,0 @@
-# OpenClaw Context Engine Integration Design / OpenClaw 上下文引擎集成方案设计
-
-## Context / 背景
-
-本方案讨论在 OpenViking 中集成 OpenClaw Context Engine 的扩展机制,以及围绕新引擎的记忆管理、查询、注入等完整设计。
-
-This proposal discusses the extension mechanism for integrating OpenClaw Context Engine into OpenViking, along with the complete design for memory management, retrieval, and injection around the new engine.
-
----
-
-## Component 1: Memory Write Mechanism / 组件 1:记忆写入机制
-
-### Compact-Triggered Automatic Write / compact 触发的自动写入
-
-1. 当 compact 时一次性把对话上传到 ov。
-
- Upload conversation to OpenViking in one batch when compact is triggered.
-
-2. 可选项:compact 时,可以把一些工作记忆(比如 TODO,摘要),留在压缩后的上下文里面(如果有的话),避免断档。
-
- Optional: During compact, keep some working memories (e.g., TODOs, summaries) in the compressed context (if available) to avoid discontinuity.
-
-3. 由于涉及 agent 记忆的提取,建议把 system prompt 和工具调用也一起上传。
-
- Since agent memory extraction is involved, it is recommended to also upload the system prompt and tool calls together.
-
-4. 相比于之前模式(每条消息都写入),一次性的写入可以减少记忆提取阶段的 token 消耗,带来的缺点是跨 session 的记忆同步会变慢(不敏感)。
-
- Compared to the previous mode (writing every message), one-time writing reduces token consumption during memory extraction. The downside is that cross-session memory synchronization will be slower (not sensitive).
-
-5. compact 一般在 /new 或消息达到一定长度时触发,消息未达长度的部分不会触发记忆提取。这部分未来可以加入 timeout 触发提取的机制(当前可以不要)。
-
- Compact is typically triggered by /new or when messages reach a certain length. Messages that don't reach the length threshold won't trigger memory extraction. A timeout-based extraction mechanism can be added in the future (not needed currently).
-
-### Two-Threshold Compact Upload Mechanism / 双阈值 Compact 上报机制
-
-为了平衡记忆同步的实时性和用户体验,采用双阈值的非阻塞上报机制:
-
-**Threshold 1: Early Upload (e.g., 50% of context window) / 阈值 1:提前上报(如上下文窗口的 50%)**
-- **Trigger Condition / 触发条件**: When session reaches ~50% of context window limit / 当会话达到上下文窗口限制的约 50% 时
-- **Action / 行为**:
- - Trigger memory upload to OpenViking in background / 后台触发记忆上报到 OpenViking
- - **DO NOT block the main flow / 不阻塞主流程**
- - **DO NOT clear session messages / 不清空会话消息**
- - Record the range of messages being uploaded (start_index, end_index) / 记录正在上报的消息范围(start_index, end_index)
- - Store upload state (upload_id, status, message_range) in session metadata / 在会话元数据中存储上报状态(upload_id, status, message_range)
-
-**Threshold 2: Force Cleanup (e.g., 70% of context window) / 阈值 2:强制清理(如上下文窗口的 70%)**
-- **Trigger Condition / 触发条件**: When session reaches ~70% of context window limit / 当会话达到上下文窗口限制的约 70% 时
-- **Action / 行为**:
- - **Always clear the messages marked for upload** / 总是清理标记为待上报的消息
- - The upload will continue in background, messages are already in memory buffer / 上报将在后台继续,消息已在内存缓冲区中
- - Keep the newer messages that arrived after upload started / 保留上报开始后到达的新消息
-
-**Cleanup After Upload Completion (Before Threshold 2) / 上报完成后的清理(阈值 2 前)**
-- **Trigger Condition / 触发条件**: Upload to OpenViking has completed and session hasn't reached Threshold 2 / 上报到 OpenViking 已完成且会话未达到阈值 2
-- **Action / 行为**:
- - Clear only the messages that were uploaded (from message_range) / 只清理已上报的消息(从 message_range)
- - Keep the newer messages that arrived after upload started / 保留上报开始后到达的新消息
-
-**Compact Hook Integration / Compact Hook 集成**
-- In each compact hook (before message processing) / 在每次 compact hook 中(消息处理前):
- 1. Check session size against thresholds / 检查会话大小是否达到阈值
- 2. If Threshold 1 reached and no ongoing upload: trigger background upload / 如果达到阈值 1 且无正在进行的上报:触发后台上报
- 3. If Threshold 2 reached: force cleanup marked messages / 如果达到阈值 2:强制清理标记的消息
- 4. If any upload has completed and below Threshold 2: cleanup those messages / 如果有上报完成且在阈值 2 以下:清理那些消息
-
-
-**Benefits / 优势**:
-- Non-blocking: User never waits for memory extraction / 非阻塞:用户永远不需要等待记忆提取
-- Progressive: Memory is uploaded early, reduces final compact work / 渐进式:记忆提前上报,减少最终 compact 的工作量
-- Safe: Messages only cleared after upload confirmation when possible / 安全:尽可能在上报确认后清理消息
-- Guaranteed: At Threshold 2, messages are cleared even if upload not complete / 保证:在阈值 2 时,即使上报未完成也清理消息
-- Backward compatible: Works with existing compact flow / 向后兼容:与现有 compact 流程兼容
-
----
-
-### Active Memory (Tool-based) / 主动记忆(基于工具)(可选)
-
-这允许 agent 通过 `commit_memory` 工具(或ov cli)主动记录记忆,支持用户请求如:
-
-This allows the agent to actively record memories via a `commit_memory` tool (or ov cli), supporting user requests like:
-
-- "Remember that I like dark mode" / "记住我喜欢深色模式"
-- "Don't ask me for confirmation again" / "下次不要再让我确认了"
-- "Note that project X is on hold" / "记下项目 X 暂停了"
-
-**commit_memory Tool / 工具**:
-- **Purpose / 用途**: Actively commit a memory to long-term storage / 主动将记忆提交到长期存储
-- **When to use / 何时使用**: User asks to remember, strong preference, important decision, etc. / 用户要求记住、强烈偏好、重要决定等
-- **Parameters / 参数**: `memory_content`, `memory_type`, `priority`, `category`
-- **Behavior / 行为**: Immediate extraction and write (no compact delay) / 立即提取和写入(无 compact 延迟)
-
----
-
-## Component 2: Memory Retrieval / 组件 2:记忆查询/召回
-
-记忆查询分为三部分:
-
-Memory retrieval has three parts:
-
-1. **用户画像注入** - 在会话开始时注入到 system prompt / User Profile Injection - Injected into system prompt at session start
-2. **每轮记忆召回** - 为每条用户消息召回相关记忆 / Per-turn Memory Retrieval - Retrieve relevant memories for each user message
-3. **Agent主动通过工具调用召回记忆**(TODO) / Agent-initiated memory retrieval via tool calls (TODO)
-
----
-
-### Part 1: User Profile Injection / 第一部分:用户画像注入
-
-在会话开始时一次性注入到 system prompt。
-
-Injected once at session start into the system prompt.
-
-**Profile Sources / 画像来源**:
-- `profile.md` - User's main profile file (always included) / 用户主画像文件(总是包含)
-- High-quality memory abstracts (only if quality score >= threshold) / 高质量记忆摘要(TODO:是否加入取决于摘要机制的质量是否ok / TODO: inclusion depends on whether the quality of the abstraction mechanism is acceptable)
-
----
-
-### Part 2: Per-turn Memory Retrieval / 第二部分:每轮记忆召回
-
-为每条用户消息召回,仅用于该次 LLM 调用。
-
-Retrieved for each user message, only used for that single LLM call.
-
-**Query Construction / 查询构建**: Use last N user messages (default: 5) concatenated as the search query / 使用最近 N 条用户消息(默认:5条)拼接作为搜索查询
-
-**Lightweight Intent Detection / 轻量级意图检测(TODO 可选模块,可基于轻量模型实现 / TODO optional module, can be implemented with lightweight models)**:
-- Skip retrieval for greetings ("你好", "在吗", "hi", "hello") / 跳过问候语的召回
-- Skip very short messages (<= 3 chars) / 跳过很短的消息(<= 3 字符)
-
----
-
-**将自动召回的记忆作为模拟的 function call 结果注入,而不是直接注入到 prompt 中**
-
-Inject auto-retrieved memories as simulated function call results instead of directly injecting into the prompt. This is a continuation of Part 2.
-
-**Benefits / 好处**:
-1. **Agent Awareness / Agent 感知**: The agent sees that a search was performed, so it knows this pattern exists and can use it itself later / Agent 看到执行了搜索,因此知道这种模式存在,以后可以自己使用
-2. **Query Transparency / 查询透明**: The agent sees exactly what query was used, so it can choose different keywords if it searches again / Agent 看到具体使用了什么查询,因此如果再次搜索可以选择不同的关键词
-
-**Example Flow / 示例流程**:
-```
-User: How do I optimize the database?
-
-Assistant: [Function Call] search_memories({"query": "database optimization...", "max_results": 5})
-
-System: [Function Result] {"success": true, "memories": [...]}
-
-Assistant: Based on...
-```
-
-**Retrieval Flow / 召回流程**:
-1. Get current user message / 获取当前用户消息
-2. Check if should skip retrieval / 检查是否应该跳过召回
-3. Build search query from last N user messages / 从最近 N 条用户消息构建搜索查询
-4. Search in OpenViking / 在 OpenViking 中搜索
-5. Apply relevance threshold filter / 应用相关性阈值过滤
-6. Format memories (L0/L1/L2 based on config) / 格式化记忆(根据配置使用 L0/L1/L2)
-7. Inject into THIS LLM call only (not persisted) / 仅注入到本次 LLM 调用(不持久化)
-
----
-
-## Component 3: Agentic Memory Query / 组件 3:Agent 通过工具主动记忆查询
-
-除了每轮自动注入之外,还提供 Agent 发起的查询机制,以满足更复杂的检索需求。这是一种"测试时计算"的方法,用于解决单轮回召可能遗漏的多跳和多背景检索问题。
-
-In addition to per-turn auto-injection, provide an agent-initiated query mechanism to meet more complex retrieval needs. This is a "test-time compute" approach to solve multi-hop and multi-context retrieval problems that single-round retrieval may miss.
-
-### Pre-inject Directory Structure / 预先注入目录结构
-
-为了让主动记忆的路径尽可能短,可以默认把 `ov ls viking://` 的结果预先注入到 system prompt 里面,让 agent 预先知道 ov 里有哪些数据可以用。如果能模拟成是 agent 主动调用的,效果可能更好。
-
-To make the path to active memory as short as possible, pre-inject the results of `ov ls viking://` into the system prompt by default, so the agent knows in advance what data is available in OpenViking. Effect may be better if simulated as an agent-initiated call.
-
-**Design / 设计**:
-- At session start / 在会话开始时
-- Run `ov ls viking://` (or equivalent) / 运行 `ov ls viking://`(或等效操作)
-- Format results as directory tree / 将结果格式化为目录树
-- Inject into system prompt, optionally simulate as function call / 注入到 system prompt,可选模拟为 function call
-
-**Example / 示例**:
-```
-Assistant: [Function Call] ov_ls({"path": "viking://"})
-
-System: [Function Result] {
- "directories": [
- "viking://docs/",
- "viking://user/memories/",
- "viking://agent/skills/",
- "viking://assets/"
- ]
-}
-```
-
-### When to Use / 何时使用
-
-| Scenario / 场景 | Example / 示例 |
-|----------------|---------------|
-| **Multi-hop reasoning / 多跳推理** | "What did I say about project X last week, and how does that relate to the Y file we discussed?" |
-| **Need for comprehensive context / 需要全面上下文** | "Tell me everything I've said about database optimization" |
-| **Temporal queries / 时间查询** | "What decisions did we make in the last month about authentication?" |
-| **Cross-session retrieval / 跨会话检索** | "Find my previous conversation about API design patterns" |
-| **Directory semantic exploration / 目录语义探索** | "What's in the /docs folder that's relevant to my current task?" |
-
----
-
-## Component 4: Skill Memory Injection / 组件 4:Skill 记忆注入
-
-Skill 记忆是Agent记忆的一种,区别点在于他锚定一个确定性的Skill
-
-因此可以通过拦截工具调用中的 `read skills/xxx/SKILL.md` 文件调用,在返回结果中添加 skill 记忆的方式注入。
-
-Skill memories are a type of agent memory, with the key distinction that they are anchored to a specific skill.
-
-Therefore, they can be injected by intercepting `read skills/xxx/SKILL.md` file calls in tool calls, and adding skill memories to the returned results.
-
-**Design / 设计**:
-
-1. **Intercept skill file reads / 拦截 skill 文件读取**
- - When agent reads `skills/<skill_name>/SKILL.md` / 当 agent 读取 `skills/<skill_name>/SKILL.md` 时
- - Intercept the read operation / 拦截读取操作
- - Look up skill memories from memory store / 从记忆存储中查找 skill 记忆
-
-2. **Augment skill content / 增强 skill 内容**
- - Prepend/append skill memories to the SKILL.md content / 在 SKILL.md 内容前后添加 skill 记忆
- - Include usage patterns, success tips, common pitfalls, etc. / 包含使用模式、成功技巧、常见陷阱等
- - Keep the original SKILL.md intact / 保持原始 SKILL.md 不变
-
-3. **Skill memory structure / Skill 记忆结构**
- - Usage statistics (how often used, success rate) / 使用统计(使用频率、成功率)
- - Past examples (successful invocations) / 过去的示例(成功调用)
- - Tips and tricks (learned from experience) / 技巧和窍门(从经验中学习)
- - Known issues and workarounds / 已知问题和解决方法
-
-**Example / 示例**:
-```
-Original SKILL.md:
-## Create Presentation
-Create a PowerPoint presentation...
-
-Augmented with skill memory:
-## Create Presentation (Used 15 times, 93% success)
-
-Create a PowerPoint presentation...
-
----
-## Past Examples
-- Successfully created Q3 financial report (2024-03-01)
-- Created project kickoff deck (2024-02-15)
-
-## Tips
-- User prefers dark theme templates
-- Always include executive summary slide
-- Use company logo from /assets/logo.png
-
-## Known Issues
-- Large images (>10MB) sometimes fail - compress first
-```
-
----
-
-## Component 5: Tool Memory Injection / 组件 5:工具记忆注入
-
-工具记忆可以通过 system prompt 方式注入。
-
-Tool memories can be injected via system prompt.
-
-**Design / 设计**:
-
-1. **Inject into system prompt / 注入到 system prompt**
- - At the start of each session or turn / 在每个会话或轮次开始时
- - Include tool usage memories / 包含工具使用记忆
- - Keep it concise to avoid token bloat / 保持简洁以避免 token 膨胀
-
-2. **Tool memory content / 工具记忆内容**
- - Tool usage statistics (call count, success rate, average time) / 工具使用统计(调用次数、成功率、平均时间)
- - Common parameter patterns / 常见参数模式
- - Error patterns and how to avoid them / 错误模式和如何避免
- - Best practices learned / 学到的最佳实践
-
-3. **Format / 格式**
- - Structured, easy to parse / 结构化,易于解析
- - Priority-based (most important first) / 基于优先级(最重要的在前)
- - Include only high-value insights / 仅包含高价值洞察
-
-**Example / 示例**:
-```
-## Tool Usage Memories
-
-### run_shell
-- Called 42 times, 88% success rate
-- Average time: 2.3s
-- Common issues:
- - Forgetting to use `cd` before relative paths
- - Long-running commands need `--async` flag
-- Best practice: Always use `&&` for chained commands
-
-### edit_file
-- Called 156 times, 95% success rate
-- Best practice: Use `search_replace` instead of full rewrite when possible
-```
-
----
-
-## Appendix: OpenViking Tool Injection / 附录:OpenViking 工具注入
-
-本节讨论如何将 OpenViking 能力注入到 Agent 中。提出了两种方案,都避免了基于 skill 的注入模式。
-
-This section discusses how to inject OpenViking capabilities into the agent. Two options are proposed, both avoiding the skill-based injection pattern.
-
-### Problem with Skill-based Injection / 基于 Skill 注入的问题
-
-- **Unstable triggering / 触发不稳定**
-- **Competition with other skills / 需要和其他 skill 竞争**
-- **Hard to predict when it will be used / 难以预测何时会被使用**
-
----
-
-### Option 1: System Prompt + Bash CLI (Recommended if CLI is LLM-friendly) / 方案 1:System Prompt + Bash CLI(如果 CLI 对 LLM 友好,推荐此方案)
-
-直接将 OpenViking CLI 用法说明注入到 system prompt 中。Agent 使用内置的 bash 工具调用 `ov` 命令。
-
-Inject OpenViking CLI usage instructions directly into the system prompt. The agent uses the built-in bash tool to call `ov` commands.
-
-**Advantages / 优势**:
-- No tool definition needed / 不需要定义 tool
-- Uses agent's existing bash capabilities / 使用 Agent 已有的 bash 能力
-- More flexible (agent can compose commands) / 更灵活(Agent 可以组合命令)
-- Works well if CLI is simple and intuitive / 如果 CLI 简单直观,效果很好
-
-**Requirements / 要求**:
-- CLI must be LLM-friendly (simple commands, good help text) / CLI 必须对 LLM 友好(命令简单、帮助文本完善)
-- Predictable output format (JSON by default) / 可预测的输出格式(默认 JSON)
-- Clear, self-documenting commands / 清晰、自解释的命令
-
-**Example Commands / 示例命令**:
-```bash
-ov search --query "your query" [--category <category>] [--limit N]
-ov ls memories [--category <category>]
-ov search-docs --query "your query" [--path <directory>]
-ov history [--limit N]
-ov remember --content "what to remember" [--type <type>] [--priority N]
-```
-
----
-
-### Option 2: Tool Definition Injection / 方案 2:工具定义注入
-
-将 OpenViking 能力定义为显式的工具定义(function calling)。
-
-Define OpenViking capabilities as explicit tool definitions (function calling).
-
-**Advantages / 优势**:
-- More predictable triggering / 触发更可预测
-- Structured input validation / 结构化输入验证
-- Clear separation from bash usage / 与 bash 用法清晰分离
-- Works even if agent doesn't have bash access / 即使 Agent 没有 bash 访问权限也能工作
-
-**Disadvantages / 劣势**:
-- Need to maintain tool definitions / 需要维护工具定义
-- Less flexible than free-form bash / 不如自由形式的 bash 灵活
-- More verbose for complex operations / 复杂操作更冗长
-
----
-
-### Comparison / 对比
-
-| Aspect / 方面 | Option 1: System Prompt + Bash / 方案 1:System Prompt + Bash | Option 2: Tool Definition / 方案 2:工具定义 |
-|--------------|----------------------------------------------------------------|----------------------------------------------|
-| **Trigger Stability / 触发稳定性** | Depends on bash tool reliability / 取决于 bash 工具可靠性 | More predictable / 更可预测 |
-| **Flexibility / 灵活性** | High - can compose commands / 高 - 可以组合命令 | Lower - fixed schema / 较低 - 固定 schema |
-| **Maintenance / 维护成本** | Maintain CLI help text / 维护 CLI 帮助文本 | Maintain tool definitions / 维护工具定义 |
-| **LLM Friendliness / LLM 友好度** | Requires good CLI design / 需要好的 CLI 设计 | Explicit schema helps / 显式 schema 有帮助 |
-| **Bash Required / 需要 Bash** | Yes / 是 | No / 否 |
-
----
-
-### Recommendation / 建议
-
-**Primary Recommendation: Option 1 (CLI + Bash) if CLI can be made LLM-friendly**
-
-**主要建议:如果 CLI 能做到对 LLM 友好,选择方案 1(CLI + Bash)**
-
-Why / 为什么:
-1. More flexible for power users / 对高级用户更灵活
-2. Single source of truth (CLI works for humans and agents) / 单一事实来源(CLI 对人类和 Agent 都有效)
-3. Less code to maintain (no duplicate tool definitions) / 维护代码更少(没有重复的工具定义)
-4. Agents can discover and experiment with commands / Agent 可以发现和实验命令
-
-**Fallback: Option 2 (Tool Definition) if CLI can't be simplified enough**
-
-**备选方案:如果 CLI 无法足够简化,选择方案 2(工具定义)**
-
----
diff --git a/docs/design/openclaw-plugin-design.md b/docs/design/openclaw-plugin-design.md
new file mode 100644
index 000000000..864e3b110
--- /dev/null
+++ b/docs/design/openclaw-plugin-design.md
@@ -0,0 +1,258 @@
+# OpenClaw Plugin 架构与流程
+
+## 概述
+
+OpenClaw Plugin 将 OpenViking 注册为 OpenClaw 的 Context Engine,全面接管对话上下文的**组装、写入、压缩**三条主链路,同时提供若干显式工具供 Agent 主动调用。
+
+---
+
+## 整体架构
+
+```
+┌──────────────────────────────────────────────────────────┐
+│ OpenClaw │
+│ │
+│ User Message │
+│ │ │
+│ ├──► assemble() ──────────────────────────────┐ │
+│ │ │ │
+│ │ LLM Call │ │
+│ │ │ │ │
+│ └──► afterTurn() ──────────────────────────────┤ │
+│ │ │
+│ /compact ──► compact() ───────────────────────────┤ │
+│ │ │
+└──────────────────────────────────────────────────────┼───┘
+ │
+ ▼
+ ┌────────────────────────────────────────────────────┐
+ │ OpenViking │
+ │ │
+ │ ┌──────────────────────────────────────────────┐ │
+ │ │ OV Session │ │
+ │ │ addMessage / commit │ │
+ │ └──────────────────┬───────────────────────────┘ │
+ │ │ │
+ │ ┌────────┴────────┐ │
+ │ ▼ ▼ │
+ │ Archive Memories │
+ │ (归档原文) (长期记忆提取) │
+ │ │
+ │ viking://session/{id} │
+ │ viking://user/memories │
+ │ viking://agent/memories │
+ │ viking://resources │
+ └────────────────────────────────────────────────────┘
+```
+
+---
+
+## 三条主链路
+
+### 链路 1:afterTurn — 无损写入
+
+每轮 LLM 返回后执行,将本轮上下文持久化到 OV session,并在积累量达阈值时触发后台记忆提取。
+
+```
+afterTurn(messages, prePromptMessageCount)
+ │
+ ├── autoCapture 未启用 → 返回
+ ├── isHeartbeat → 返回
+ ├── session 匹配 bypassSessionPatterns → 返回
+ │
+ ├── extractNewTurnMessages(messages, prePromptMessageCount)
+ │ 从 prePromptMessageCount 位置切出本轮新增消息
+ │ 无新消息 → 返回
+ │
+ ├── 清理 recall 注入块(防止 <relevant-memories> 被二次捕获)
+ │
+ ├── client.addSessionMessage(ovSessionId, role, parts, agentId)
+ │ 逐条写入 OV session(user / assistant)
+ │
+ ├── client.getSession(ovSessionId) → pending_tokens
+ │
+ ├── pending_tokens < commitTokenThreshold(20k) → 返回
+ │
+ └── client.commitSession(wait=false) ──► 后台异步执行
+ Phase 2: archive + memory extract
+ └── pollPhase2ExtractionOutcome
+```
+
+---
+
+### 链路 2:assemble — 上下文组装
+
+每次 LLM 调用前执行,根据调用场景走两条不同路径。
+
+```
+assemble(sessionId, messages, tokenBudget, runtimeContext)
+ │
+ ├── session 被 bypass → passthrough(原样返回)
+ │
+ ├── 判断调用类型
+ │ ├── isTransformContextAssemble(无 prompt/availableTools 等字段)
+ │ │ → 走「自动召回路径」
+ │ └── isMainAssemble(含 prompt/availableTools 等字段)
+ │ → 走「完整上下文路径」
+ │
+ ├──【自动召回路径】
+ │ ├── latest message 非 user → passthrough
+ │ ├── autoRecall 未启用 → passthrough
+ │ ├── 已含 AUTO_RECALL_SOURCE_MARKER → 跳过(防重复注入)
+ │ ├── prepareRecallQuery(userMessage) → query(最大 4000 chars)
+ │ ├── buildAutoRecallContext
+ │ │ ├── 并行检索 viking://user/memories
+ │ │ ├── 并行检索 viking://agent/memories
+ │ │ └── 过滤:level=2、score≥threshold、总chars≤recallMaxInjectedChars
+ │ └── prependRecallToLatestUserMessage → 前插 <relevant-memories> 块
+ │
+ └──【完整上下文路径】
+ ├── client.getSessionContext(ovSessionId, tokenBudget, agentId)
+ │ → latest_archive_overview
+ │ → pre_archive_abstracts
+ │ → messages(活跃消息)
+ │
+ ├── OV 无数据 OR OV 消息量 < 输入消息量 → passthrough
+ │
+ ├── allocateContextBudget(tokenBudget)
+ │ Archive: 剩余 × 15%,上限 8000 tokens ← 历史摘要(较旧)
+ │ Session: 剩余全部 ← 活跃消息(较新)
+ │ 保留区: max(15%, 20k tokens) ← 模型输出空间
+ │
+ ├── buildArchiveMemory → [Session History Summary] 消息
+ ├── buildSessionContext → OV messages → AgentMessages(超预算时从头裁剪)
+ │
+ ├── 消息后处理管道
+ │ normalizeAssistantContent
+ │ → canonicalizeAgentMessages
+ │ → sanitizeToolUseResultPairing
+ │ → mergeConsecutiveUsers
+ │ → ensureAlternation
+ │
+ └── 存在 archive 时注入 systemPromptAddition(Session Context Guide)
+```
+
+**Token 预算分层**
+
+```
+ ↑ 旧(输入)
+┌─────────────────────────────────────────────┐ tokenBudget
+│ Archive Memory(历史摘要) │ 15%,max 8k
+├─────────────────────────────────────────────┤
+│ Session Context(活跃消息) │ 剩余全部
+├─────────────────────────────────────────────┤
+│ Reserved(保留区) │ 15%,min 20k
+└─────────────────────────────────────────────┘
+ ↓ 新(模型输出)
+```
+
+---
+
+### 链路 3:compact — 归档提交
+
+由 OpenClaw 触发(用户 /compact 或上下文超限),同步执行完整归档流程。
+
+```
+compact(sessionId, tokenBudget, currentTokenCount)
+ │
+ ├── session 被 bypass → { ok:true, compacted:false }
+ │
+ ├── 获取 tokensBefore
+ │ ├── 有 currentTokenCount → 直接使用
+ │ └── 无 → getSessionContext 估算
+ │
+ ├── client.commitSession(wait=true) ← 同步等待 Phase 2
+ │ ├── status=failed → { ok:false, compacted:false }
+ │ ├── status=timeout → { ok:false, compacted:false }
+ │ └── archived=false → { ok:true, compacted:false, reason:"commit_no_archive" }
+ │
+ ├── client.getSessionContext → latest_archive_overview(summary)
+ │
+ └── 返回 CompactResult
+ ok: true
+ compacted: true
+ result:
+ summary: latest_archive_overview
+ firstKeptEntryId: archive_uri 末段
+ tokensBefore / tokensAfter
+```
+
+---
+
+## Session 身份映射
+
+OpenClaw session 标识 → OV storage id 的转换规则:
+
+```
+输入: sessionId, sessionKey
+ │
+ ├── sessionId 是 UUID 格式
+ │ → 小写直接使用
+ │
+ ├── sessionKey 非空
+ │ → sha256(sessionKey)
+ │
+ ├── sessionId 含 Windows 非法字符(: < > " \ 等)
+ │ → sha256("openclaw-session:" + sessionId)
+ │
+ └── 其他 sessionId
+ → 直接使用
+```
+
+**Agent ID 解析优先级**
+
+```
+sessionKey 格式 "agent:<id>:<rest>" 提取 agentId
+ └──► agent_prefix + "_" + agentId (sanitize 为 [a-zA-Z0-9_-])
+
+runtimeContext.agentId
+ └──► agent_prefix + "_" + agentId
+
+无任何来源
+ └──► "main"(或 "<agent_prefix>_main")
+```
+
+---
+
+## 工具注册
+
+| 工具 | 触发场景 |
+|------|---------|
+| `memory_recall` | 主动检索 user/agent memories(可选 resources) |
+| `memory_store` | 用户明确要求记住某内容,立即写入并同步 commit |
+| `memory_forget` | 按 URI 删除,或 query 搜索后高置信度自动删除 |
+| `add_resource` | 导入文档 / URL / Git 仓库到 viking://resources |
+| `add_skill` | 导入 SKILL.md 到 viking://agent/skills |
+| `memory_search` | 搜索 resources + agent/skills |
+| `ov_archive_search` | 关键词 grep 当前 session 所有归档原始消息 |
+| `ov_archive_expand` | 按 archive_id 展开归档原始消息列表 |
+
+`memory_recall` 的搜索范围:
+
+```
+并行检索
+ ├── viking://user/memories
+ ├── viking://agent/memories
+ └── viking://resources(需 recallResources=true)
+
+后处理:去重 → 只保留 level=2 叶子节点 → score 过滤 → 按 query 重排
+```
+
+---
+
+## 关键配置
+
+| 配置项 | 默认值 | 说明 |
+|--------|--------|------|
+| `baseUrl` | `http://127.0.0.1:1933` | OV server 地址 |
+| `agent_prefix` | `""` | Agent ID 前缀 |
+| `autoCapture` | `true` | afterTurn 自动写入开关 |
+| `autoRecall` | `true` | assemble 自动召回开关 |
+| `commitTokenThreshold` | `20000` | 触发后台 commit 的 pending_tokens 阈值 |
+| `commitKeepRecentCount` | `10` | afterTurn commit 后服务端保留的活跃消息数 |
+| `recallLimit` | `6` | 自动召回最大记忆条数 |
+| `recallScoreThreshold` | `0.15` | 召回分数过滤阈值 |
+| `recallMaxInjectedChars` | `4000` | 自动召回注入的最大总字符数 |
+| `recallPreferAbstract` | `false` | 优先使用摘要而非读取全文 |
+| `bypassSessionPatterns` | `[]` | 完全跳过 OV 的 session key 模式 |
+