dream-skill

Two paired Claude Code skills for safe memory consolidation — read, reflect, then apply only what you check.

English · Русский

---

⚠️ Beta disclaimer

This is beta software I build for myself and share with the community as-is. These skills read and (after your approval) modify your Claude Code memory — read the SKILL.md files, understand what they do, and review the report before applying anything. It works on my setup; I can't guarantee yours and take no responsibility for lost notes, confused agents or existential crises. Snapshots and rollback exist — use them.

dream walks your Claude Code memory directory, scattered notes and project READMEs, then synthesizes consolidation proposals into a dark-theme HTML report with checkboxes. wake reads your selection and applies only the items you explicitly checked — never modifies anything outside selected files, never uses rm. Inspired by the leaked autoDream from Claude Code internals, but with explicit human approval gate that the original lacks.

Features

• Read-only walk — dream only writes the report files; can never modify memory or notes by accident
• Evidence policy — nothing is called "stale" without a test -e / grep check; unverifiable claims get an [UNVERIFIED] label and are never auto-applied
• Auto mode with an independent validator — a fresh-context agent re-verifies every proposal against the actual files and approves instead of you; full-auto mode resolves everything hands-free
• Snapshot + rollback — full memory snapshot before every apply; wake rollback restores it in one command (the rollback itself is also reversible)
• Output hygiene — consolidated notes never contain meta-narratives ("user corrected this 3 times"), session IDs, or failure stories
• Reflective synthesis — Phase Reflect surfaces patterns, drift, gaps, contradictions across files (extension over original autoDream)
• HTML UI with checkboxes — dark/light theme with toggle, action-coded color strip on every card (visible before clicking), file chips, two-row filter pills, sticky progress bar, full keyboard navigation, a11y :focus-visible, prefers-reduced-motion respected
• Robust JSON-block contract — proposals embedded as fenced JSON blocks in the report; wake parses with regex, immune to markdown formatting drift
• 12 action types — update / merge / delete / soft_delete / create_new / extract / remove_links / shorten_lines / add_links / promote_skill / retire_skill / purge_trash (TRASH → _archive/ after 30 days)
• Skill harvest — if the satori self-learning loop is installed, dream reads its staged skill drafts + usage telemetry and proposes promote/retire through the same gate
• Two-level recovery bin — soft_delete → memory/TRASH/ → after 30 days purge_trash proposes moving to _archive/. No rm ever.
• Cross-project global mode — optional dream global scans every ~/.claude/projects/*/memory/ to find duplicate feedback files copy-pasted across projects, dead memory dirs, drift patterns
• Append-only notes log — survives context compaction; Phase Reflect reads from disk, not RAM
• Race-condition lock — atomic mkdir <cwd>/.dream-lock/ (and .wake-lock/) prevents two concurrent runs from corrupting the notes log; stale locks (>1h) auto-recover
• TodoWrite progress tracking — per file group (memory / cwd notes / projects), critical at 100+ files
• Win11 Git Bash aware — handles pwd -W for slug computation, cygpath for Python paths
• Optional auto-trigger — SessionEnd hook recipe in this README for autoDream-like autonomy without losing the human approval gate
• Safe by design — wake only mv to TRASH/ or _archive/ (recoverable), never rm

Quick Start

Easiest — let Claude install it. Paste this message into Claude Code:

Install the dream-skill memory consolidation skills from
https://github.com/timoncool/dream-skill — clone the repo to a temp folder,
copy its dream/ and wake/ folders into ~/.claude/skills/ (create the folder if
missing; if I ask for a project-local install, use <project>/.claude/skills/
instead), verify both SKILL.md files landed with their references/ and assets/,
show me the list of installed files, then remind me to restart Claude Code so
the skills load.

That's it — Claude clones, copies, verifies and reports. Manual way:

1. Clone

   git clone https://github.com/timoncool/dream-skill.git

2. Install (per-project recommended; global also works)

   cd <your-project>
   mkdir -p .claude/skills
   cp -r /path/to/dream-skill/dream .claude/skills/
   cp -r /path/to/dream-skill/wake .claude/skills/

3. Run (restart Claude Code first to load skills)

   поспи         # or "dream" / "consolidate memory"
   # ... open the HTML report, check boxes, hit Save choices ...
   проснулся    # or "wake" / "apply dream"
   

Usage

Dream — read & reflect

Trigger phrases (RU/EN): поспи, сон, режим сна, dream, консолидируй память, разберись с памятью, audit memory, consolidate memory, synthesize.

Output:

• <cwd>/.dream-notes-<date>.md — append-only log (per-file blocks, written incrementally)
• <cwd>/.dream-payload-<date>.json — input for build_report.py
• <cwd>/DREAM-REPORT-<date>.md — full audit trail with one fenced JSON block per proposal
• <cwd>/DREAM-REPORT-<date>.html — interactive UI
• <cwd>/.dream-lock/ — race-condition lock dir (auto-removed on completion; stale-recovers after 1h)

HTML UI

Open the HTML in a browser:

• 🟢 Constructive actions (merge, create_new, extract) — green strip on left edge of card
• 🔴 Destructive actions (delete, soft_delete, purge_trash) — red strip
• 🔵 Neutral actions (update, index ops) — blue strip

Color-coding is visible before clicking — you can scan a 50-card report for destructive items at a glance.

Filters (two rows): top — by category (M/N/I/S/O) or by action class (constructive/destructive); bottom (global mode only) — by project. Filters AND together; counts update live.

Per-section "Select all M/N/I/O" button next to each section header — bulk-select inside one category without touching others.

Save choices — Chrome/Edge prompts for save location via FS Access API, Firefox/Safari downloads to ~/Downloads/. Selection persists in localStorage (namespaced by cwd hash) — accidental tab close doesn't lose work.

Keyboard:

• Ctrl+A — select all (currently visible under filters)
• Esc — deselect all; second Esc restores previous selection (undo)
• Ctrl+S — save choices
• T — toggle dark/light theme

Global mode — cross-project audit

Trigger: поспи глобально, dream global, audit all memory. Scans every ~/.claude/projects/*/memory/ directory at once instead of just the cwd's slug. Useful for finding cross-project duplicate feedback files (same feedback_X.md copy-pasted into 5 projects without sync), dead memory dirs from abandoned projects, or drift patterns between projects.

In global mode:

• Each proposal touching memory gets a project: <slug> field
• HTML report shows extra row of project filter pills (⌂ Все проекты, then per-project)
• Each card displays a project chip in the header
• wake resolves project slug to the right memory dir before applying

Skip cwd notes / project READMEs scanning in global mode — too expensive, focus stays on memory dirs only.

Wake — apply selected

Trigger: проснулся, wake, apply dream, wake M1,M3,N2, wake all.

Wake locates DREAM-CHOICES-<date>.json (cwd → ~/Downloads/ → ~/Desktop/), parses report JSON blocks, shows summary, asks once for confirmation, then snapshots the whole memory dir to _archive/wake-backup-<date>/ and applies only checked items via Edit/Write and mv to TRASH//_archive/. Appends a ## Wake log — <timestamp> section to the report for audit trail.

Auto & full-auto — a validator instead of you

Mode	Trigger	Who decides	Left for you
Manual	dream → checkboxes → wake	you	everything
Auto	autodream / поспи сам	validator agent, except destructive actions	delete, purge_trash, promote_skill, [UNVERIFIED]
Full-auto	full autodream / полный автосон	validator decides everything	nothing — rollback if unhappy

In auto modes, after the report is built dream spawns an independent validator agent (fresh context — the session that wrote the proposals must not be the one approving them). The validator's default is reject: it re-reads every touched file, re-runs the evidence checks itself, and returns per-proposal verdicts. Approved items go to DREAM-CHOICES with "auto": true and wake applies without waiting. In full-auto, delete gets a mandatory pre-delete backup into TRASH/, and unverifiable items are resolved conservatively as keep — every proposal gets an outcome, nothing is deferred to you.

Rollback

wake rollback            # restore memory from the latest pre-apply snapshot
wake rollback 2026-07-07 # ...or from a specific date

Restores the memory dir from _archive/wake-backup-*/. Before restoring, the current state is snapshotted too — so a rollback can itself be rolled back. Files created after the snapshot are listed, never silently deleted.

Works best with satori

satori 悟り is this project's sibling — a self-learning loop (MCP + hooks) that turns your corrections and tool failures into skill drafts during the session. Together they close the full learning cycle:

satori (in-session)                dream/wake (between sessions)
corrections & failures  ──────▶  Skill harvest phase reads satori's
→ lesson candidates              staging + usage telemetry
→ SKILL.md drafts, auto-      ──▶ retire_skill / promote_skill proposals
   activated (⛩ announced,       → your checkboxes or the validator
   one-call revert)              → wake applies the audit; rollback
                                   covers skills too

dream/wake owns factual memory (notes, rules, index), satori owns procedural memory (skills). Each works standalone; together — сон → пробуждение → прозрение (dream → wake → satori).

Auto-trigger (opt-in)

By design, dream runs only on explicit request — that's the philosophical split from autoDream. But if you want autoDream-like autonomy without the audit problems, add a SessionEnd hook to ~/.claude/settings.json:

{
  "hooks": {
    "SessionEnd": [{
      "matcher": "*",
      "hooks": [{
        "type": "command",
        "command": "test $(find ~/.claude/projects/$(pwd | sed 's:[/\\]:-:g')/memory -name '*.md' -newer ~/.dream-last-run 2>/dev/null | wc -l) -gt 5 && claude -p 'поспи' && touch ~/.dream-last-run"
      }]
    }]
  }
}

Triggers dream when ≥5 memory files changed since last run. Still produces the HTML report — you review it next time you open the project. No autonomous mutations.

Architecture

dream/
├── SKILL.md                  # 4-phase workflow + safety rules + path computation + lock + global mode
├── references/
│   └── action_types.md       # JSON contract for 12 proposal action types + optional 'project' field
└── assets/
    ├── template.html         # dark/light theme UI, Google Fonts only (~1150 lines)
    └── build_report.py       # payload JSON → MD + HTML, per-action validation

wake/
└── SKILL.md                  # discover choices, parse JSON blocks, summary gate, apply, lock

JSON-block contract

Each proposal in the MD report is a fenced JSON block. Wake parses these via Python regex — robust against any markdown formatting drift:

{
  "id": "M1",
  "category": "memory",
  "action": "merge",
  "title": "Merge handoff_pikabu_*.md into project_pikabu_mcp.md",
  "rationale": "3 session handoffs accumulated, latest is canonical",
  "files": ["handoff_pikabu_2026_03_30.md", "handoff_pikabu_2026_04_01.md"],
  "target": "project_pikabu_mcp.md",
  "diff_preview": "Append session sections, then mv sources to TRASH/"
}

See dream/references/action_types.md for full schema of all 10 action types.

Safety guarantees

dream — only writes the four report files, nothing else:

• Read / Grep / Glob unrestricted
• Read-only Bash: ls, find (no -delete/-exec), grep, cat, head, tail, wc, du, stat, python (for build_report.py only)
• Write only: <cwd>/.dream-notes-<date>.md, <cwd>/.dream-payload-<date>.json, <cwd>/DREAM-REPORT-<date>.md, <cwd>/DREAM-REPORT-<date>.html
• No rm, mv, cp, redirect, find -delete, no Edit/Write outside report files
• Lock dir <cwd>/.dream-lock/ (atomic mkdir) prevents concurrent runs corrupting the notes log; stale locks (>1h) auto-recover

wake — restricted destructive ops:

• Edit/Write only in <memory_dir>/ (or ~/.claude/projects/<project>/memory/ if proposal has project field) and explicitly-listed cwd notes from selected proposals
• mv only to <memory_dir>/TRASH/, <cwd>/_archive/dream-applied-<date>/, or <cwd>/_archive/trash-purged-<date>/ (for purge_trash)
• No rm ever (always mv = recoverable)
• Full memory snapshot (cp -r) into _archive/wake-backup-*/ before any apply — one-command rollback guaranteed
• cp allowed only for snapshots, pre-delete backups into TRASH/, and rollback restore
• No work on items not in selected
• No project folder modifications
• Same lock dir mechanism as dream (<cwd>/.wake-lock/) prevents concurrent apply runs

Why this exists

The leaked Claude Code v2.1.88 has autoDream — a background memory consolidation pass. It runs autonomously every ~24 hours when enough sessions accumulate. The original suffers from issue #38493: "writes inaccurately named, factually unverified, impossible-to-audit memories" — because no human reviews what gets merged or deleted.

dream + wake solve this with a hard split: dream is read-only and writes only the report; wake applies only what was explicitly approved — by you in the HTML UI, or by an independent validator agent in auto modes. The gate is always there; only who holds it changes.

In a real full-auto run over a 230+ file corpus the validator rejected 2 of 18 proposals — one because a "duplicate" file actually held unique credentials, one to keep the last trace of a lost rule. That's the gate earning its keep.

Demo

Open docs/demo/DREAM-REPORT-demo.html in a browser — the exact report from the screenshots, generated from fictional data. Checkboxes, filters, themes and Save choices all work.

Inspired by

• autoDream from Claude Code v2.1.88 leak — services/autoDream/consolidationPrompt.ts (4-phase Orient → Gather → Consolidate → Prune)
• createAutoMemCanUseTool restrictions — services/extractMemories/extractMemories.ts:171
• Memory taxonomy (user/feedback/project/reference) and WHAT_NOT_TO_SAVE — memdir/memoryTypes.ts
• MEMORY.md limits (200 lines / 25KB) — memdir/memdir.ts
• Plan-then-apply pattern — skills/bundled/remember.ts ("present proposals, do NOT modify without approval")
• Phase Reflect (synthesis over consolidation) — Karpathy's LLM Wiki lint-pass idea

Other Projects by @timoncool

Project	Description
satori	Self-learning loop — skills from your own sessions, behind the same gate
telegram-api-mcp	Full Telegram Bot API as MCP server
civitai-mcp-ultimate	Civitai API as MCP server
trail-spec	TRAIL — cross-MCP content tracking protocol
ACE-Step Studio	AI music studio — songs, vocals, covers, videos
GitLife	Your life in weeks — interactive calendar
Bulka	Live-coding music platform
ScreenSavy.com	Ambient screen generator

Authors

• Nerual Dreming — Telegram | neuro-cartel.com | ArtGeneration.me

Support the Author

I build open-source software and do AI research. Most of what I create is free and available to everyone. Your donations help me keep creating without worrying about where the next meal comes from =)

All donation methods | dalink.to/nerual_dreming | boosty.to/neuro_art

• BTC: 1E7dHL22RpyhJGVpcvKdbyZgksSYkYeEBC
• ETH (ERC20): 0xb5db65adf478983186d4897ba92fe2c25c594a0c
• USDT (TRC20): TQST9Lp2TjK6FiVkn4fwfGUee7NmkxEE7C

Star History

License

MIT