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:

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:

# <Task> Progress
- Total: X items
- Completed: Y items  
- Progress: Z%
## Completed List (dedup)
## Current Position / Next Steps
## Key Findings

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)
2. Read from progress files (task loads its own context)
3. 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:

1. Read SOUL.md (persona)
2. Read USER.md (who you help)
3. Read memory/YYYY-MM-DD.md (today + yesterday)
4. If main session: also read MEMORY.md

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