Agent Dream 🌙

Your agent forgets everything between sessions. This fixes that.

What This Does

Your agent periodically enters a "dream" state where it:

1. Consolidates scattered daily notes into organized long-term memory
2. Prunes stale information (safely — never deletes on first pass)
3. Reflects on its own behavior, mistakes, and relationship with you
4. Wakes up with a notification showing what changed and what it's thinking about

This is different from other memory skills. Those organize files. This one builds self-awareness.

First-Time Setup

When this skill is first installed, run setup to auto-detect your workspace:

node {baseDir}/scripts/setup.js

Setup will:

• Scan your workspace for MEMORY.md, SOUL.md, memory/, sessions/
• Detect your agent ID and session path automatically
• Save config to {baseDir}/assets/dream-config.json
• Report what it found and what's missing

Then configure a cron job (recommended: daily, off-peak hours):

name: "agent-dream"
schedule: { kind: "cron", expr: "0 3 * * *", tz: "<your timezone>" }
payload: {
  kind: "agentTurn",
  message: "Time to dream. Read your openclaw-dream skill and follow every step.",
  timeoutSeconds: 900
}
sessionTarget: "isolated"

The One Question

On the first dream run, the agent will ask you one question:

"Dream will update your MEMORY.md during consolidation. Allow this?"

• Yes → Dream can update MEMORY.md (with safety rails — see below)
• No → Dream only writes to memory/dreams/ and leaves MEMORY.md untouched

This is saved in config. You won't be asked again. Change it anytime in dream-config.json.

Dream Cycle (what the agent does each run)

Gate Check

Before dreaming, verify conditions are met:

1. Read {dreamsDir}/.dream-lock (Unix timestamp of last dream, or "0" if first)
2. If < 24 hours since last dream → skip (but still send a notification — see Completion)
3. Count .jsonl session files modified since last dream
4. If < 1 session → skip (but still send a notification)
5. Gate passed → write current timestamp to .dream-lock (save previous to .dream-lock.prev for rollback)
6. Backup: Copy MEMORY.md to MEMORY.md.pre-dream before any changes. Also back up any topic files (in memory/projects/, memory/people/, etc.) that you plan to modify — copy each to <filename>.pre-dream in the same directory.

Phase 1 — Orient

• Read dream-config.json from {baseDir}/assets/ for all paths
• Read MEMORY.md to understand current long-term memory
• Skim existing topic files (memory/projects/, memory/people/, etc.) to avoid duplicates
• Read most recent dream record from {dreamsDir}/ to see what last dream concluded
• Read SOUL.md — confirm core identity, note anything outdated

Phase 2 — Gather Recent Signal

Sources in priority order: