Context Persistence & Cross-Session Sync
Design and implement persistent context systems that survive session boundaries.
Core Problem
OpenClaw has multiple session types with different context access:
| Session | Memory Files | History | Cron Context |
|---|
| Main DM | ✅ All injected | ✅ Full | N/A |
| Group Chat |
❌ Not loaded | ✅ Partial | N/A |
| Cron (isolated) | ❌ None | ❌ None | ✅ Payload only |
| Heartbeat | ❌ None | ✅ Partial | N/A |
| Subagent | ❌ None | ❌ None | ✅ Task only |
Result: State created in one session is invisible to others unless persisted to files.
Architecture: Three-Layer Memory System
Layer 1: Long-Term Memory (MEMORY.md)
- - What: Curated facts, decisions, lessons, key state
- Who writes: Main session only
- Who reads: Main session only (injected via AGENTS.md)
- Update frequency: On significant events, periodic review during heartbeats
- Size limit: < 200 lines (context budget)
Layer 2: Daily Logs (memory/YYYY-MM-DD.md)
- - What: Raw chronological notes, conversations, decisions
- Who writes: Any session that has something to record
- Who reads: Main session (at startup), heartbeats (for review)
- Update frequency: Real-time as events happen
- Size limit: Unbounded (not injected into context)
Layer 3: Task Progress Files (memory/-progress.md)
- - What: Structured progress for long-running work
- Who writes: Any session doing the task
- Who reads: Any session continuing the task
- Update frequency: At task boundaries (session end, checkpoints)
- Size limit: < 300 lines
The Key Insight
Files are the only cross-session communication channel.
In-memory state dies with the session. Files survive.
Pattern 1: Progress Tracking
For tasks spanning multiple sessions (source code reading, data analysis, etc.)
See references/progress-tracking.md for full template.
Essential elements:
CODEBLOCK0
Pattern 2: Cron Job Context Injection
Isolated cron sessions have NO access to workspace memory. Solutions:
- 1. Embed context in payload message (for <1KB state)
- Read from progress files (task loads its own context)
- Shared state file (coordination between sessions)
See references/cross-session-sync.md for patterns.
Pattern 3: Main Session Initialization
The AGENTS.md startup sequence ensures context loading:
CODEBLOCK1
This is the ONLY automated context loading. Everything else must be explicit.
Quick Checklist
When designing context for a new task:
- - [ ] Can this span multiple sessions? → Create progress file
- [ ] Does cron/subagent need this? → Embed in payload or file
- [ ] Is this a fact to remember? → Update MEMORY.md
- [ ] Is this a raw event? → Append to daily log
- [ ] Should future sessions know this? → Write it DOWN, never rely on memory
上下文持久化与跨会话同步
设计并实现能够跨越会话边界的持久化上下文系统。
核心问题
OpenClaw 拥有多种会话类型，其上下文访问权限各不相同：
| 会话类型 | 记忆文件 | 历史记录 | 定时任务上下文 |
|---|
| 主DM | ✅ 全部注入 | ✅ 完整 | 不适用 |
| 群聊 |
❌ 未加载 | ✅ 部分 | 不适用 |
| 定时任务（隔离） | ❌ 无 | ❌ 无 | ✅ 仅负载 |
| 心跳 | ❌ 无 | ✅ 部分 | 不适用 |
| 子代理 | ❌ 无 | ❌ 无 | ✅ 仅任务 |
结果：在一个会话中创建的状态对其他会话不可见，除非持久化到文件中。
架构：三层记忆系统
第一层：长期记忆（MEMORY.md）
- - 内容：经过整理的事实、决策、经验教训、关键状态
- 写入者：仅主会话
- 读取者：仅主会话（通过 AGENTS.md 注入）
- 更新频率：重要事件发生时，心跳期间定期审查
- 大小限制：< 200 行（上下文预算）
第二层：每日日志（memory/YYYY-MM-DD.md）
- - 内容：原始的时间顺序笔记、对话、决策
- 写入者：任何有内容需要记录的会话
- 读取者：主会话（启动时）、心跳（用于审查）
- 更新频率：事件发生时实时更新
- 大小限制：无限制（不注入上下文）
第三层：任务进度文件（memory/<任务名>-progress.md）
- - 内容：长期工作的结构化进度
- 写入者：执行任务的任何会话
- 读取者：继续执行任务的任何会话
- 更新频率：任务边界处（会话结束、检查点）
- 大小限制：< 300 行
关键洞察
文件是唯一的跨会话通信渠道。
内存中的状态随会话消亡。文件则得以存续。
模式一：进度追踪
适用于跨越多个会话的任务（源代码阅读、数据分析等）
完整模板请参见 references/progress-tracking.md
核心要素：
markdown
<任务> 进度
已完成列表（去重）
当前位置 / 下一步
关键发现
模式二：定时任务上下文注入
隔离的定时任务会话无法访问工作区记忆。解决方案：
- 1. 在负载消息中嵌入上下文（适用于 <1KB 的状态）
- 从进度文件中读取（任务加载自身上下文）
- 共享状态文件（会话间协调）
相关模式请参见 references/cross-session-sync.md
模式三：主会话初始化
AGENTS.md 启动序列确保上下文加载：
- 1. 读取 SOUL.md（角色设定）
- 读取 USER.md（服务对象）
- 读取 memory/YYYY-MM-DD.md（今天和昨天）
- 如果是主会话：同时读取 MEMORY.md
这是唯一自动化的上下文加载方式。其他所有内容必须显式处理。
快速检查清单
为新任务设计上下文时：
- - [ ] 该任务是否可能跨越多个会话？→ 创建进度文件
- [ ] 定时任务/子代理是否需要此内容？→ 嵌入负载或文件中
- [ ] 这是需要记住的事实吗？→ 更新 MEMORY.md
- [ ] 这是原始事件吗？→ 追加到每日日志
- [ ] 未来的会话是否需要知道此信息？→ 将其写下来，切勿依赖记忆
