DreamCycle#

Detect, analyze, and auto-repair failure patterns from AI agent session logs.

When to use#

Use DreamCycle when:

• An agent has been running for a while and you want to check for recurring failures
• Session logs are accumulating and you want trend analysis
• You suspect the same error keeps happening but no one is tracking it
• You want automated fix suggestions for known failure patterns
• After making changes to agent configuration, to verify nothing regressed

How it works#

DreamCycle is a retrospective debugger for AI agents. It scans your agent's session log files in three phases:

text

Session Logs → Scan → Analyze → Fix

1. Scan — Extracts failure, pattern, and lesson signals from JSON session files
2. Analyze — Detects recurring patterns (appearing 2+ times) and trends (up/down/stable compared to previous scans)
3. Fix — Maps known failure patterns to automated fix suggestions with confidence scores

Installation#

bash

pip install dreamcycle

Usage#

bash

# Basic diagnostic: scan last 2 days of sessions
dreamcycle diagnose ~/.openclaw/sessions/

# Scan last 7 days
dreamcycle diagnose ~/my-agent/logs/ --days 7

# JSON output for programmatic use
dreamcycle diagnose ./sessions/ --output json

# Version info
dreamcycle version

Example output#

text

━━━ DreamCycle Diagnose ━━━
Scanned:    42 sessions (last 2 days)
Signals:    156 total (failures: 78, patterns: 52, lessons: 26)
━━━━━━━━━━━━━━━━━━━━━━━━━━

🔄 Top Recurring Patterns
  [12x] "timeout" → ⚡ high
    Fix: add retry_with_backoff (confidence: 85%)
  [8x]  "ModuleNotFoundError" → ⚡ high
    Fix: pip install <module> (confidence: 95%)

📈 Trends
  ↑ timeout: 12x (up from 5x last scan)
  ↓ ModuleNotFoundError: 8x (down from 15x)

🔧 Auto-Fix Summary
  ✅ 2/4 patterns have automated fixes
  ❌ 2 patterns need manual review

Requirements#

Only python3 and pip. Zero external dependencies — DreamCycle uses only the Python standard library.

Notes#

• Session files must be JSON format with a messages array containing role/ content fields
• First run establishes a baseline; trends appear starting from the second run
• Trend data is stored at ~/.dreamcycle/scan_history.json