1. Initialize Files

mkdir -p memory/episodes

Ensure the following files exist (create from references/memory-template.md templates if missing):

• memory/index.json
• memory/procedures.md
• memory/dream-log.md
• memory/archive.md

2. Create Cron Job

name: "auto-memory-dream"
schedule: { kind: "cron", expr: "0 4 * * *", tz: "<user timezone>" }
payload: {
  kind: "agentTurn",
  message: "Run auto memory consolidation.\n\nRead skills/skills/openclaw-auto-dream/references/dream-prompt-lite.md and follow every step strictly.",
  timeoutSeconds: 600
}
sessionTarget: "isolated"
delivery: { mode: "announce" }

3. Verify

• [ ] Cron job created and enabled
• [ ] MEMORY.md exists with section headers
• [ ] memory/index.json exists
• [ ] memory/procedures.md exists
• [ ] memory/dream-log.md exists

Dream Cycle Flow

Each dream runs in an isolated session (see references/dream-prompt-lite.md):

Step 0: Smart Skip + Recall

Check if any unconsolidated daily logs exist in the last 7 days. All processed → still send a useful message: surface an old memory ("N days ago, you decided...") and show streak count. Never send a blank "nothing to do" message.

Step 1: Collect

Read unconsolidated daily logs. Extract decisions, facts, progress, lessons, and todos.

Step 2: Consolidate

Compare with MEMORY.md → append new content, update existing, skip duplicates. Write workflow preferences to procedures.md. Mark processed daily logs with <!-- consolidated -->.

Step 2.8: Stale Thread Detection

Scan Open Threads for items stale >14 days. Include top 3 in notification with context.

Step 3: Generate Report + Auto-Refresh Dashboard

Append to dream-log.md with change list + insights + suggestions. If dashboard.html exists, regenerate with latest data.

Step 4: Notify with Growth Metrics

Send a consolidation report showing:

• Before → after comparison (entries, decisions, lessons)
• Cumulative growth ("142 → 145 entries, +2.1%")
• Dream streak count ("Dream #14")
• Milestones when hit (first dream, 7-day streak, 100 entries, etc.)
• Top 3 stale reminders (if any)
• Weekly summary on Sundays (week-over-week growth, biggest memories)

Notification Principles

1. Every notification must deliver value — never send empty "nothing happened" messages
2. Show growth, not just changes — cumulative stats make the user feel the system is evolving
3. Surface forgotten context — stale thread reminders and old memory recalls create surprise and utility
4. Celebrate milestones — streak counts and entry milestones build habit and attachment

Manual Triggers

| Command | Action | |---------|--------| | "Consolidate memory" / "Dream now" | Run full dream cycle in current session | | "Memory dashboard" | Generate memory/dashboard.html | | "Export memory" | User-initiated export of memory files to JSON (see migration guide) |

Language Rules

All output uses the user's preferred language (from workspace settings).

Safety Rules

1. Never delete daily logs — only mark with <!-- consolidated -->
2. Never remove ⚠️ PERMANENT items — user-protected markers
3. Safe changes — if MEMORY.md changes >30%, save .bak copy first
4. Index safety — save index.json.bak before each dream
5. Privacy — only consolidate information the user has already written in their own workspace files
6. Scope — only read and write files within the memory/ directory and MEMORY.md

Reference Files

• references/first-dream-prompt.md — First Dream: post-install full scan with before/after report
• references/dream-prompt-lite.md — Compact prompt for daily cron use (default)
• references/dream-prompt.md — Full prompt (for manual deep consolidation)
• references/scoring.md — Importance scoring, forgetting curve, health score algorithms
• references/memory-template.md — File templates (MEMORY.md, procedures, index.json, etc.)
• references/dashboard-template.html — HTML dashboard template
• references/migration-cross-instance.md — Cross-instance migration protocol
• references/migration-v1-to-v2.md — v1→v2 upgrade guide
• references/migration-v2-to-v3.md — v2→v3 upgrade guide

The Problem

Every AI agent forgets. Session ends, context gone. Files pile up. What was that decision from two weeks ago? Which workflow worked last time? Your agent has amnesia — functional, but forgetting everything the moment it sleeps.

Auto-Dream fixes this. Like the human brain consolidating memories during sleep, Auto-Dream runs periodic "dream cycles" that scan, extract, organize, score, link, and prune your agent's knowledge — automatically, safely, and intelligently.

Why This Matters for MyClaw Users

Your MyClaw agent runs 24/7. It handles your projects, tracks your decisions, remembers your preferences, manages your workflows. Over weeks and months, it accumulates thousands of daily log entries. Without Auto-Dream, that knowledge sits in raw files — unsorted, unscored, disconnected. Your agent has the data but can't think about it.

Auto-Dream transforms your agent from a tool that executes commands into a partner that understands context, learns from history, and connects the dots you didn't see.

Why This Is Different

| Feature | Claude Code CLAUDE.md | Typical Memory Plugins | Auto-Dream | |---------|----------------------|----------------------|----------------| | Memory layers | 1 flat file | 1 file or key-value | 5 cognitive layers | | Scoring | ❌ | ❌ | Importance × Recency × References | | Forgetting | Manual cleanup | Delete or nothing | Gradual decay + archival | | Knowledge graph | ❌ | ❌ | Linked entries + reachability | | Health monitoring | ❌ | ❌ | 5-metric score + trend tracking | | Cross-instance | ❌ | ❌ | Export/import/merge bundles | | Dashboard | ❌ | ❌ | Interactive HTML with charts |

Architecture

┌──────────────────────────────────────────────────────────────────┐
│                                                                  │
│   ┌─────────────┐   ┌──────────────┐   ┌───────────────────┐   │
│   │   COLLECT    │──▶│ CONSOLIDATE  │──▶│     EVALUATE      │   │
│   │             │   │              │   │                   │   │
│   │ Scan 7 days │   │ Route layers │   │ Score importance  │   │
│   │ Flag markers│   │ Semantic dedup│   │ Forgetting curve  │   │
│   │ Extract     │   │ Assign IDs   │   │ Health metrics    │   │
│   │  insights   │   │ Link relations│  │ Generate insights │   │
│   └─────────────┘   └──────────────┘   └───────────────────┘   │
│                                                                  │
│                      ☽ Dream Cycle ☾                             │
└──────────────────────────────────────────────────────────────────┘
                              │
              ┌───────────────┼───────────────┐
              ▼               ▼               ▼
     ┌──────────────┐ ┌─────────────┐ ┌──────────────┐
     │  📊 Dashboard │ │ 🔔 Notify   │ │ 📝 Dream Log │
     │  HTML + Charts│ │ Push to chat│ │ Append report│
     └──────────────┘ └─────────────┘ └──────────────┘

Five Memory Layers

| Layer | Storage | What Goes Here | |-------|---------|---------------| | Working | LCM plugin (optional, detected at setup) | Real-time context compression & semantic recall | | Episodic | memory/episodes/*.md | Project narratives, event timelines, story arcs | | Long-term | MEMORY.md | Facts, decisions, people, milestones, strategy | | Procedural | memory/procedures.md | Workflows, preferences, tool patterns, shortcuts | | Index | memory/index.json | Metadata, importance scores, relations, health stats |

Features

🧠 Cognitive Dream Cycle

Runs automatically via cron (default: 4 AM daily). Three phases:

1. Collect — Scans unconsolidated daily logs (last 7 days), detects priority markers (⚠️ PERMANENT, 🔥 HIGH, 📌 PIN, <!-- important -->), extracts decisions / people / facts / projects / lessons / procedures / open threads

2. Consolidate — Routes each insight to the correct memory layer, performs semantic deduplication, assigns unique IDs (mem_NNN), creates relation links between connected entries

3. Evaluate — Scores importance using base_weight × recency × reference_boost / 8.0, applies forgetting curves (>90 days + low importance → archived, never deleted), calculates 5-metric health score, generates 1–3 non-obvious insights, writes dream report, sends notification

📊 Importance Scoring

Every entry gets a score on every dream cycle:

importance = (base_weight × recency_factor × reference_boost) / 8.0

• Recency: max(0.1, 1.0 - days/180) — gradual decay over 6 months
• References: log₂(count + 1) — logarithmic boost for frequently-referenced entries
• Markers: 🔥 HIGH doubles base weight; ⚠️ PERMANENT always scores 1.0

📉 Intelligent Forgetting

Memories aren't deleted — they're gracefully archived:

• Entry must be >90 days unreferenced AND importance < 0.3
• Compressed to a one-line summary in memory/archive.md
• Original ID preserved for relation tracking
• ⚠️ PERMANENT and 📌 PIN entries are immune

🕸️ Knowledge Graph

Entries are linked by semantic relations. The reachability metric measures graph connectivity:

• Union-find algorithm across all entry relations
• Detects isolated knowledge clusters
• Suggests cross-references to improve coherence

🩺 Health Score (5 Metrics)

health = (freshness×0.25 + coverage×0.25 + coherence×0.2 + efficiency×0.15 + reachability×0.15) × 100

| Metric | What It Measures | |--------|-----------------| | Freshness | % of entries referenced in last 30 days | | Coverage | % of knowledge categories updated in last 14 days | | Coherence | % of entries with at least one relation link | | Efficiency | How concise MEMORY.md stays (inversely proportional to line count) | | Reachability | How well-connected the memory graph is |

🔔 Push Notifications

Dream results delivered to your chat automatically:

| Level | What You Get | |-------|-------------| | silent | Nothing — logged to dream-log.md only | | summary | 🌀 Health: 82/100 \| +5 new, ~3 updated, -1 archived \| 💡 Top insight | | full | Complete dream report with all sections |

📊 Interactive Dashboard

A zero-dependency HTML dashboard with:

• Animated health gauge (0–100)
• 5 metric cards with color-coded status
• Memory distribution donut chart
• Importance histogram
• Health trend line chart (last 30 cycles)
• Force-directed knowledge graph visualization
• Recent changes, insights, suggestions, stale entries

Generate it: "Show memory dashboard"

🔄 Cross-Instance Migration

Move memories between MyClaw instances:

"Export memory bundle"    →  memory/export-20