【RFC】OpenViking工作记忆设计v1

[Mijamind719]

OpenViking 工作记忆设计 v1

文档目标

这份文档只讨论 OpenViking 的工作记忆设计，不讨论长期记忆。

本文重点回答 4 个问题：

1. OpenViking 当前和工作记忆直接相关的实现现状是什么
2. OpenViking 里的工作记忆和原始历史边界怎么划分
3. 当前实现距离“可直接用于长会话续接的工作记忆”还缺什么
4. 应该如何把 archive 提升成工作记忆对象

本文是第一版设计文档，目标是帮助后续理解和迭代，不追求一次性定稿。

工作记忆设计原则

OpenViking 里的工作记忆不应被设计成 archive 旁边的一份外挂摘要，而应由 commit/archive 这条主链路直接生成。

它的核心作用不是“记住所有历史”，而是：

• 把当前 session 中已经完成的大部分上下文压缩成一份结构化工作摘要
• 在上下文接近上限时，用这份摘要替代旧消息
• 同时保留最近还需要继续工作的原始消息尾部
• 在后续续接时，基于 archive 边界恢复出可继续工作的上下文

一句话概括：

working memory = messages.jsonl 之上的、由 archive 生成并服务于 assemble/compact 的结构化工作摘要层

从设计上看，它依赖几个关键原则：

• messages.jsonl 永远是真相源，working summary 只是派生出的工作摘要
• 工作记忆必须是固定结构、可持续修订的对象，而不是自由摘要
• 工作记忆必须和覆盖边界、preserved tail 绑定，才能安全参与 compact
• 摘要不能单独工作，必须配合 recent raw messages 一起维持继续执行能力
• afterTurn() 负责判断触发时机，真正的工作记忆生成由 commit/archive 承担

工作记忆与原始历史必须分开理解

OpenViking 里最容易混淆的是两层东西。

1. 原始历史

原始历史是真相源。

• 当前 session 的原始消息在 messages.jsonl
• 归档后的旧消息进入 history/archive_x/messages.jsonl
• 这一层负责保存可追溯的原始事实

对应文档和代码位置：

• OpenViking/docs/zh/api/05-sessions.md:776
• OpenViking/docs/zh/api/05-sessions.md:784
• OpenViking/openviking/session/session.py:192
• OpenViking/openviking/session/session.py:444

2. 工作记忆

工作记忆是 archive 产出的结构化工作对象。

• 它服务于 assemble()、compact() 和后续续接
• 它不是原始事实层
• 它的职责是承载“当前该怎么继续工作”

工作记忆的真实定位

从设计上看，OpenViking 的工作记忆不应该被当成新的主历史，而应该被当成：

• 对原始历史的阶段性工作摘要
• assemble() 的主输入之一
• compact() 的主要返回结果
• 后续续接时的工作上下文

所以它不是：

• 原始消息的替代存储
• 一份和 archive 平行维护的 sidecar 文件
• 一个通用知识库存储

它更像一份由 archive 正式生成、持续服务于会话续接的工作对象。

OpenViking 当前已经做到什么

这部分调研基于 OpenViking 仓库当前 main 分支下的 examples/openclaw-plugin 实现。

从当前 README 和代码看，这个插件已经不是一个单纯的 memory lookup 插件，而是一个围绕 OpenClaw 生命周期工作的集成层。源码和文档位置：

• OpenViking/examples/openclaw-plugin/README_CN.md:19-24
• OpenViking/examples/openclaw-plugin/index.ts:1411-1561
• OpenViking/examples/openclaw-plugin/context-engine.ts:763-1125

它当前已经具备 3 个非常重要的基础能力。

1. assemble() 已经在消费 archive 产物

当前 assemble() 会调用 getSessionContext()，然后把 OpenViking 返回的 session context 重新组装成 OpenClaw 可消费的消息：

• latest_archive_overview -> [Session History Summary]
• pre_archive_abstracts -> [Archive Index]
• 当前活跃消息 -> active messages
• tool part 会被还原成 toolUse / toolResult

对应实现：

• OpenViking/examples/openclaw-plugin/context-engine.ts:705-740
• OpenViking/examples/openclaw-plugin/context-engine.ts:763-852

它还会附带一段 systemPromptAddition，显式告诉模型：

• [Session History Summary] 是有损的
• 如果要精确旧细节，先看 [Archive Index]
• 再调用 ov_archive_expand

对应实现：

• OpenViking/examples/openclaw-plugin/context-engine.ts:438-476

这说明 OpenViking 当前已经在用 archive 产物参与工作上下文组装。只是今天这个 archive 产物还比较薄，更多是“summary + index”，还没有进化成更强的 working memory object。

2. afterTurn() 已经在做原始消息的无损落盘和异步 commit

当前 afterTurn() 会：

• 用 prePromptMessageCount 切出本轮新增消息
• 提取结构化的 text / tool parts
• 清理掉 prompt 注入噪音
• 追加写入 OpenViking session
• 当 pending_tokens >= commitTokenThreshold 时，触发 commit(wait=false)

对应实现：

• OpenViking/examples/openclaw-plugin/context-engine.ts:867-1037

这说明 OpenViking 当前已经有了工作记忆系统所需的事实底座和后台异步 commit 触发点。

3. compact() 已经在做同步 commit 和 summary 回读

当前 compact() 会：

• 调用 commit(wait=true)
• 等待 archive 完成
• 再回读 getSessionContext()
• 取出 latest_archive_overview 作为 compact summary
• 返回 tokensBefore / tokensAfter / latest archive id / summary

对应实现：

• OpenViking/examples/openclaw-plugin/context-engine.ts:1039-1125
• OpenViking/examples/openclaw-plugin/context-engine.ts:1185-1293

所以，如果只从“有没有 compact 同步边界”和“有没有历史压缩后再回读”这两个角度看，OpenViking 当前已经有了工作记忆的基本骨架。

当前真正缺的是什么

OpenViking 现在差的不是“能不能压缩历史”，而是“archive 产物能不能直接充当工作记忆”。按这个标准看，当前实现还缺 4 个关键能力。

缺口 1：archive 产物还不够“工作态”

当前 latest_archive_overview 更像归档概述，不像工作交接文档。它至少还缺：

• Current State
• Next Actions
• Errors & Corrections
• Important Files / Functions
• 用户临时约束和当前任务状态

缺口 2：archive 缺少明确的覆盖边界

工作记忆对象必须明确表达两件事：

• 这份 archive-produced summary 已经覆盖到哪条 turn
• 从哪条 turn 之后必须保留原文

没有这个边界，archive 就只能提供“可读摘要”，不能安全接管 working context。

缺口 3：archive 缺少 recent tail 的保留语义

当前 assemble() 拿到的是：

• archive overview
• archive index
• active messages

但 archive 本体没有显式描述“为什么这些 recent raw messages 还要保留”，例如：

• headTurnId
• tailTurnId
• tailTokenEstimate
• why kept

这会让 assemble() 更像是在拼“摘要 + 活跃消息”，而不是消费一份已经定义好边界的 working memory。

缺口 4：assemble 消费的是 archive 摘要结果，不是 archive-working-memory object

当前主输入仍然是：

• OpenViking session context
• archive overview
• archive index

而不是：

• archive-produced working summary
• recent raw messages
• archive expansion hints

所以 OpenViking 现在已经是一个 archive-aware context engine，但还没有把 archive 提升成“工作记忆的正式输出物”。

技术方案：Archive 本体就是 Working Memory Object

把 archive 升级成 working memory object：

• 当前 session 的 messages.jsonl 仍然是真相源
• archive 则成为“当前 session 的工作记忆生成器和承载对象”

本章以下内容按选定方案描述。

1. 存储模型

archive 结果对象扩展为：

type SessionArchiveWorkingMemory = {
  archiveId: string
  sessionId: string
  createdAt: string
  sourceTurnRange: {
    startTurnId: string
    endTurnId: string
    endSeq: number
  }
  workingSummary: {
    markdown: string
    sections: {
      currentState: string
      nextActions: string
      errorsAndCorrections: string
      importantContext: string
    }
  }
  preservedTail: {
    headTurnId: string
    tailTurnId: string
    turnCount: number
    tokenEstimate: number
  }
  expansion: {
    archiveIndex: Array<{ archiveId: string; abstract: string }>
    latestArchiveOverview?: string
    expandTool: 'ov_archive_expand'
  }
}

兼容现有返回形态时，第一阶段不改 archive 主表结构，而是让 commit() / getSessionContext() 额外返回一个 working_memory 字段；但语义上它仍然是 archive 产物，而不是平行 sidecar。

2. 摘要模板

workingSummary.markdown 使用固定 section，至少包含：

• Session Title
• Current State
• User Goal & Constraints
• Important Files / Modules / Resources
• Decisions & Why
• Errors / Failed Paths / User Corrections
• Workflow / Commands / Tools
• Next Actions
• Key Results
• Worklog

其中最关键的是：

• Current State
• Errors / Failed Paths / User Corrections
• Next Actions

compact 后还能不能连续工作，基本就看这三块。

3. 生成提示词

archive-working-memory 生成 prompt 定义为：

IMPORTANT: This instruction is not part of the user conversation.

Generate the archive working-memory object for the current OpenClaw session commit boundary.

You are given:
- the raw messages covered by this commit
- the previous archive working summary when available
- the current active tail that should remain uncompressed

Your task is to produce:
- a structured working summary for future continuation
- the covered turn boundary
- the preserved recent tail boundary

Rules:
- Preserve the fixed section structure exactly.
- Always refresh "Current State" and "Next Actions" first.
- Record concrete files, tools, commands, constraints, errors, and user corrections.
- Treat this archive as the next working-memory object for the session.
- Do not invent details that are not present in raw messages or archives.
- If the summary grows too large, condense Worklog and older details first; keep Current State and Errors detailed.

这个 prompt 的目标只有两个：一是让 archive 产物具备工作记忆语义，二是同时产出 coverage 和 preserved tail 元数据。

4. 生命周期映射

afterTurn()

afterTurn() 保留当前的原始消息落盘逻辑，并在达到阈值时直接通过 commit(wait=false) 异步触发 archive working memory 生成：

1. 继续把本轮 raw messages 无损写入 OpenViking session
2. 判断是否需要触发 archive
3. 如果达到阈值，调用 commit(wait=false) 异步触发下一次 archive 生成

触发信号为：

• session context 初次超过某个阈值
• 距离上次 archive working memory 生成又新增了明显 token
• 最近几轮出现自然停顿点
• 或已经到达明确的 compact 预警线

这里不要阻塞主链路。afterTurn() 负责判断时机，真正的 working memory 生成由 commit/archive 承担。

assemble()

assemble() 直接消费 archive working memory，组装顺序为：

1. 最新 archive 的 workingSummary
2. recent raw messages
3. 必要时的 archive index
4. 必要时的 archive overview

也就是把当前的：

archive overview + archive index + active messages

收敛成：

workingSummary + preserved recent raw messages + archive hints

compact()

compact() 的职责是同步生成并返回最新的 archive working memory。

1. 调用 commit(wait=true)
2. 由 archive 流程同步生成新的 working memory object
3. 返回最新 archive 的 workingSummary + preservedTail + expansion hints
4. 必要时再返回 archiveId / tokensBefore / tokensAfter

compact 的结果不应该再只是 latest_archive_overview，而应该优先返回真正可继续工作的 workingSummary + preservedTail + expansion hints。

5. 续接与回溯

续接

OpenViking 不需要在客户端重接消息链，因为它的 session context 是服务端现组装的。它真正需要的是 archive object 上的边界字段：

• sourceTurnRange.endTurnId
• preservedTail.headTurnId
• preservedTail.tailTurnId

然后由 getSessionContext() 或增强版 working-context API 在服务端直接物化出：

• workingSummary
• recent raw messages
• archive hints

所以 OpenViking 的续接本质上是服务端重建 working context。

回溯旧历史

OpenViking 已经有现成入口 ov_archive_expand。回溯链路定义为：

1. 默认先靠最新 archive object 里的 workingSummary + preservedTail
2. 如果缺精确旧细节，优先根据 archive index 或 archiveId 调用 ov_archive_expand
3. 未来如果要更细粒度，再加 turn-level / range-level expand

对应的运行时提示写成：

• “If you need exact older details not present in the latest archive-produced working summary or recent tail, inspect the archive index and call ov_archive_expand.”

6. 这一章的边界

本文只讨论当前 session 内的 working memory，因此这里明确两层就够了：

• archive as working memory object
  只管当前 session 的连续工作状态
• messages.jsonl
  只管原始消息事实层；当前消息在 session 根目录下，归档后旧消息进入 history/archive_x/messages.jsonl

这里最重要的边界是：

• archive 是“当前 session 的工作记忆产物”
• messages.jsonl 是“最终事实源”

MVP 与完整版

落地分两步。

MVP：把 archive 结果扩成 working memory object

第一版只做 5 件事：

1. commit() / getSessionContext() 能返回 workingSummary + sourceTurnRange + preservedTail
2. afterTurn() 继续无损落盘，并按阈值异步触发 archive
3. assemble() 优先拼“最新 archive working memory object + recent raw messages”
4. compact() 同步等待 archive 完成，并返回 archive-working-memory-first 的结果
5. 缺精确旧细节时，继续用 ov_archive_expand

做到这一步，就已经能把当前任务状态从 archive overview 提升到真正的 working memory。

完整版：服务端原生 archive-working-memory API

第二版再把这层完全收进 OpenViking 服务端：

1. session.commit() 直接产出标准 working memory object
2. getSessionContext() 或新 API 直接返回 archive-working-memory 视图
3. 由服务端维护 sourceTurnRange 和 preservedTail
4. assemble() 只消费 archive-working-memory 视图，不自己拼装
5. 后续再接更细粒度的 expand 和其他上下文增强能力

做到这一步，OpenViking-openclaw plugin 才算真正拥有了一个以 archive 为核心的 working memory 子系统。

最终建议

如果只保留一句最重要的话，这份设计的结论是：

OpenViking 当前 openclaw-plugin 已经有了 session 真相源、archive summary 和 archive expand。下一步不该是在 archive 旁边再造一份 working memory sidecar，而应该直接把 archive 提升成 working memory object，让 commit/archive 成为正式的工作记忆生成边界，让 assemble() 和 compact() 统一消费 archive 产出的 workingSummary + preservedTail + expansion hints。

[qin-ctx]

可以，挺清晰的。现在有一些数据集能对比overview优化前后的效果吗