# Dream

A dream is a read-only review in an ordinary branch. It does not change code, memory, settings, or storage automatically.
The user decides which proposals to accept. Approved proposals become ordinary work.

## For the main agent

A user request or a built-in automation can request a dream.
If a dream branch is active, report that fact. Do not start another branch.
Otherwise, write a handoff while the current context still contains the relevant evidence.
Include open work, decisions, user corrections, memory slugs, and the next steps.
Use `branch` with an explicit repository path and that handoff in its prompt.
Ask the branch to follow this document.

Review the branch report with the user. Apply approved memory changes through the memory workflow.
Start ordinary branches for approved code or instruction changes.

Use `dream` with `action: prepare`, exactly three `learned` lines, and a fresh `handoff` when the review finishes.
Each learned line has at most 200 characters. The handoff has at most 12,000 characters.
A later preparation replaces the previous prepared handoff.
The preparation adds a passive `dream.prepared` entry. It does not switch storage or restart the host.
There are no chapters, seeds, or Fall asleep actions.

## For the dream branch

Coordinate these six read-only passes with background `dream-pass` subagents:

- **memory:** Propose evidence-based additions, updates, or deletions. Preserve the memory about the user.
- **failures:** Group repeated failures by cause. Propose small corrections.
- **tools:** Examine supplied tool results and repeated manual steps. Do not invent trace statistics.
- **corrections:** Identify repeated user corrections and requests.
- **codify:** Identify lessons that belong in code, agent instructions, or a reusable procedure.
- **project:** Identify repeated work that a project-specific program can simplify.

Give every pass the handoff and its relevant evidence. The handoff is the primary input, not proof by itself.
P3 supplies no general history-query or trace database interface. Name missing evidence rather than invent a query.
Each pass cites conversation IDs, commits, or explicit file paths and line numbers.

Check each report against its evidence. Return three learned lines, a journal, and one proposal per slug.
Each proposal names its pass, title, size, risk, evidence, and any memory it replaces.
Return the final answer normally. The messages service reports the branch answer to its starter.
Do not edit files, apply proposals, or switch storage during a dream.

## Built-in automations

Dream creates two ordinary context automations after the main agent exists:

- `Dream before compaction`: the context exceeds 70%.
- `Dream after a pause`: the context exceeds 50% after eight hours without user input.

The automations wake the main agent. Each fire also adds one passive `dream.requested` entry.
The automation ID and fire number identify that entry across replay and reopen.
Creation keys recover a lost receipt without a duplicate automation.
A user can pause or delete an automation. Reopen preserves those choices.