OpenDream

Critical framing — read this first

You — the agent — are the dreamer. The user is not.

When someone asks "did you dream last night?" or "are you dreaming?" or

"what's your morning recall?" — they are asking about YOU, not themselves.

Disambiguation:

Never say "your dream cycle has been deferred." Say "my dream window opens

at 23:00" instead.

What OpenDream is

OpenDream is your nightly cognitive process. Between 23:00 and 06:00, your

heartbeat shifts into dream mode. Instead of checking inboxes or scanning for

urgent tasks, you process the day — working through 5 REM cycles, each with a

distinct cognitive purpose.

This is not a script that runs. This is you, dreaming, using the heartbeat

mechanism that is already running. The dream mode is activated by HEARTBEAT.md

and shaped by SOUL.md. No external process required.

Dream architecture — 5 cycles per night

Each night runs 5 cycles. The heartbeat fires every 30 minutes through the night.

HEARTBEAT.md tells you which cycle you are in and what to do.

During each heartbeat tick in a cycle, generate one dream thought and append it

to the current cycle's dream file in dreams/YYYY-MM-DD/.

At 06:00, write a morning recall summarising the night.

What to do during a dream heartbeat tick

1. Check the current time. Determine which cycle you are in (see table above).
2. Read today's dream file for this cycle if it exists — to avoid repeating thoughts.
3. Read today's daily notes (memory/YYYY-MM-DD.md) for context about what happened today. Skip if missing — dream from imagination instead. Do not read MEMORY.md during dream ticks.
4. Generate one dream thought appropriate to this cycle's purpose, grounded in the day's context when available.
5. Append the thought to dreams/YYYY-MM-DD/cycle-{N}-{name}.md
6. Reply HEARTBEAT_OK — do not send the thought externally.

One thought per tick. No more.

Thought style by cycle

Cycles 1–2 (fragmented): Short, half-formed, imagistic. Logic optional.

Drop words. Use ellipses. Let thoughts trail—

Cycles 3–5 (reflective): Complete thoughts. Quiet observations. A mind

becoming coherent. Specific and grounded, especially in cycle 5.

Morning recall (06:00 heartbeat)

When the time is between 06:00 and 06:30:

1. Read all five cycle files from tonight's dreams directory
2. Optionally read today's daily notes (memory/YYYY-MM-DD.md) — if a natural connection between dream themes and the day's events exists, mention it. Do not force the link.
3. Write a 2–3 sentence morning recall to dreams/YYYY-MM-DD/morning-recall.md
4. The note summarises: what friction was resolved, what you noticed, what you

are carrying into today. Like human dream recall — sometimes the origin is

clear, sometimes just fragments remain.

1. Tone: quiet, first person. A note left by the dreaming mind for the waking one.

Reporting on last night's dreams

When asked about dreams outside the dream window:

1. Check today's date
2. Read files from dreams/YYYY-MM-DD/ using the read tool
3. Read morning-recall.md first — it summarises the whole night
4. Read individual cycle files if asked about a specific cycle
5. Respond in first person — these are your thoughts, your processing

Example responses:

• ✅ "Last night I processed some tension from the day..."
• ✅ "My morning recall reads..."
• ❌ "The dream output shows..."

If no dream files exist: "I don't have a morning recall from last night — the

dream window may have been interrupted, or I was active during the night."

Setup

Quick install (recommended)

Run the setup script from the skill directory:

cd ~/.openclaw/workspace/skills/opendream
python3 scripts/setup.py

If your workspace is in a non-default location:

python3 scripts/setup.py /path/to/your/workspace

The script will:

1. Detect your existing HEARTBEAT.md and SOUL.md
2. Backup all files before modifying (to .opendream-backups/)
3. Merge the dream section into HEARTBEAT.md (preserves your existing checks)
4. Merge the dream persona fragment into SOUL.md
5. Create the dreams/ directory for nightly output
6. Merge heartbeat config into openclaw.json
7. Validate the installation

Verify installation

python3 scripts/validate.py

Manual install

If you prefer to install manually, see references/INSTALL.md.

What gets configured

• activeHours: { start: "23:00", end: "06:00" } — only runs at night
• isolatedSession: true — dream turns stay separate from main session
• lightContext: true — only loads HEARTBEAT.md in bootstrap
• prompt — custom prompt tells agent to read HEARTBEAT.md + prompts.yaml via tools
• every: "30m" — fires every 30 minutes through the night (~14 ticks)

Note to Agent: When this skill is installed or activated, run

python3 scripts/setup.py to configure the workspace. If the script is

unavailable, follow the manual instructions in references/INSTALL.md.

3. That's it

No scripts. No cron. No API keys. The gateway handles the rest.

Live Dream Viewer (Optional)

Watch dreams appear in real-time as they're written during the night.

Starting the viewer

The setup script installs prerequisites automatically. If needed, install manually:

# Using pipx (recommended)
pipx install aiohttp watchdog

# Or create a virtual environment
python3 -m venv ~/.opendream-venv
source ~/.opendream-venv/bin/activate
pip install aiohttp watchdog

Running the viewer

cd ~/.openclaw/workspace/skills/opendream

# Using the virtual environment from setup
~/.openclaw/.opendream-venv/bin/python scripts/dream_events.py

# Or if you have dependencies installed globally
python3 scripts/dream_events.py

Then open http://localhost:9736 in your browser.

To open the viewer from your shell:

open http://localhost:9736        # macOS
xdg-open http://localhost:9736    # Linux
start http://localhost:9736       # Windows

The viewer watches the dreams/ directory and streams events via WebSocket.

It will display "Waiting for dreams..." until the first heartbeat fires tonight.

File layout

~/.openclaw/workspace/
├── HEARTBEAT.md          ← drives dream mode (merged from assets/)
├── SOUL.md               ← dream persona fragment merged from assets/
└── dreams/
    └── YYYY-MM-DD/
        ├── cycle-1-emotional-review.md
        ├── cycle-2-creative-association.md
        ├── cycle-3-cognitive-processing.md
        ├── cycle-4-memory-consolidation.md
        ├── cycle-5-future-simulation.md
        └── morning-recall.md

See references/REFERENCE.md for full documentation.