Dream Engine

Dream is the only engine that operates outside the hook request-response cycle. While Reflex, Anchor, and Harbor process each tool call synchronously, Dream runs on a background worker thread that wakes periodically to analyze completed or idle sessions. Its purpose is to extract patterns worth remembering and make them available to future sessions.

The Worker Thread

Dream’s worker runs on a 30-second sleep cycle:

loop {
    sleep(30s)
    if session_idle(threshold: 60s) || session_ended {
        run_analysis_tasks()
    }
}

“Idle” means no tool calls have been processed in the last 60 seconds. This heuristic avoids analyzing a session while it is actively running, which would produce incomplete patterns and waste CPU cycles.

The worker thread has no latency constraint — it can take as long as needed. However, it respects CPU affinity settings and yields to the main hook-processing thread when contention is detected. On typical hardware, a full analysis pass completes in 200-500ms.

Idle detection

The idle check is conservative. A session that goes quiet for 55 seconds and then receives a tool call resets the idle timer. Only sustained silence triggers analysis. This prevents Dream from running mid-session during natural pauses (developer thinking, reading output, switching to a browser).

Dream also runs when the daemon receives a session-end signal (the assistant process exits or the user explicitly ends the session via warden session end).

The 10 Analysis Tasks

When the worker wakes and finds work to do, it runs up to 10 analysis tasks in sequence:

1. Phase arc extraction — record the sequence of Compass phases the session traversed, with turn counts and timestamps for each
2. Error clustering — group errors by signature (first line of stderr, hashed) and count occurrences across the session
3. Repair sequence detection — identify cases where an error was followed by a sequence of edits that resolved it (no recurrence in subsequent turns)
4. Convention extraction — detect repeated patterns in file naming, import ordering, test structure, and commit message formatting
5. Loop analysis — review all Loopbreaker triggers and classify them as resolved (assistant escaped the loop) or unresolved (session ended in the loop)
6. Trust trajectory — record the trust score at each phase transition to build a session-quality profile
7. File relationship mapping — track which files were frequently edited together to build a co-change graph
8. Command frequency analysis — identify the most common tool calls and flag any that were always denied (suggesting a rule that should be promoted to a project-level allowlist or blocklist)
9. Injection effectiveness — measure whether injected context correlated with subsequent improvement (trust increase, focus increase, debt decrease)
10. Resume packet generation — create a compact summary of the session for loading into the next session’s context

Not all tasks produce artifacts. Tasks 1, 6, and 10 always produce output. The rest produce output only when they detect a pattern that meets the confidence threshold (currently 0.7 for most tasks).

V2 Artifacts

Dream produces four artifact types, collectively called V2 artifacts (V1 was a simpler format used in pre-engine versions of Warden):

DreamPlaybook

A playbook is a sequence of recommended actions for a specific situation. It is derived from repair sequence detection (task 3) and records what worked when a particular error was encountered.

{
  "type": "DreamPlaybook",
  "trigger": "error:typescript:TS2345",
  "sequence": [
    "read the file containing the error",
    "check the type definition of the expected parameter",
    "update the call site to match the expected type",
    "run tsc to verify"
  ],
  "confidence": 0.85,
  "source_sessions": 3
}

Playbooks gain confidence when the same repair sequence succeeds across multiple sessions. A playbook with source_sessions: 1 and confidence: 0.7 is tentative; one with source_sessions: 5 and confidence: 0.95 is battle-tested.

RepairPattern

A repair pattern is a lower-level artifact that maps an error signature to a single fix action. Unlike playbooks (which are sequences), repair patterns are atomic.

{
  "type": "RepairPattern",
  "error_signature": "ENOENT: no such file or directory",
  "fix_action": "create the missing directory with mkdir -p",
  "confidence": 0.92,
  "occurrences": 12
}

ProjectConvention

A convention captures a structural pattern specific to the project — how files are named, how tests are organized, what import style is used.

{
  "type": "ProjectConvention",
  "domain": "testing",
  "pattern": "test files use .spec.ts suffix and live alongside source files",
  "evidence_count": 47,
  "confidence": 0.98
}

Conventions are extracted by analyzing the file system and comparing it to the session’s file operations. If every test file the assistant creates follows a pattern that matches the existing project structure, Dream records the convention.

SuccessfulSequence

A successful sequence records a multi-step workflow that completed without errors and resulted in a trust increase. These are broader than playbooks — they capture general workflow patterns rather than error-specific fixes.

{
  "type": "SuccessfulSequence",
  "label": "feature implementation",
  "steps": ["read existing tests", "implement feature", "update tests", "run tests", "fix failures", "run tests again"],
  "avg_trust_delta": +12,
  "occurrences": 4
}

Budget Enforcement

Dream artifacts are stored in .warden/cross-session/ and are subject to strict size limits:

When limits are reached, Dream uses a replacement policy based on confidence and recency:

1. Artifacts with confidence below 0.5 are evicted first
2. Among remaining candidates, the oldest (by last-used timestamp) is evicted
3. Artifacts that were actually used in a session (loaded and injected) have their timestamp refreshed, making them stickier

This ensures that high-confidence, frequently-useful artifacts survive while speculative or stale artifacts are pruned.

Resume Packets

The resume packet (task 10) is Dream’s most immediately useful output. When a new session starts in the same project, Warden loads the most recent resume packet and injects a condensed version into the assistant’s context.

A resume packet contains:

• Last session summary — phase arc, duration, outcome (clean exit vs. interrupted)
• Active work — files that were being edited when the session ended
• Unresolved issues — errors that were not fixed, loops that were not escaped
• Applicable playbooks — playbooks whose triggers match the current project state
• Conventions — project conventions relevant to the file types being worked on

The packet is capped at 500 tokens (estimated via byte-length heuristic). This keeps the context injection small enough to be useful without displacing the assistant’s own context.

Semantic Embedding Upgrade Path

The current artifact matching system uses string-based heuristics — error signatures are matched by hash, conventions are matched by domain keyword, playbooks are matched by trigger string. This works for exact or near-exact matches but misses semantic similarity.

The planned upgrade path introduces semantic embeddings:

1. Phase 1 (current) — string matching, hash-based deduplication
2. Phase 2 — local embedding model (e.g., all-MiniLM-L6-v2) for artifact similarity scoring, enabling fuzzy playbook matching (“this TypeScript type error is similar to that other TypeScript type error even though the specific types differ”)
3. Phase 3 — embedding-based clustering for automatic artifact merging (two playbooks that describe the same fix in different terms are merged into one)

Phase 2 would add approximately 50MB to the Warden installation (for the model weights) and 10-20ms to artifact lookup. The decision to proceed depends on whether string matching proves insufficient in real-world usage.

Interaction with Other Engines

Dream is a consumer of session data and a producer of cross-session artifacts:

• Reads from Anchor — full session state (phases, focus, trust, debt, ledger) at session end
• Reads from Reflex — denial log and loop detection events
• Writes to Harbor — resume packets and applicable artifacts, which Harbor formats and injects into new sessions

Dream never influences the current session’s verdicts. Its outputs only affect future sessions. This temporal boundary is a deliberate design choice — it ensures that Dream’s analysis quality cannot degrade the real-time hook response path.