dream-pass

What it does

Auto memory only grows. Claude saves a fact, then a near copy of it a week later, then a note about a launch that has since happened, and the index passes 200 lines. Nobody cleans it, so stale memories keep steering new sessions.

dream-pass does that cleanup the way sleep consolidates memories. Every so often it merges duplicate memories, rewrites the ones the conversation proved stale, removes dead ones and cleans up MEMORY.md. Because it runs with the whole conversation as context, it knows that "we moved to Fly.io" makes the Heroku note wrong.

It also checks sources. Claude Code stamps each memory with the session it came from (originSessionId), so when two memories disagree, the mod pulls what you actually typed in those sessions and settles it from evidence. And it saves a new memory only for something you said at least twice, across your last five sessions.

Using it

• /dream dreams now. The band shows the counts.
• Open in the band, or /dream show, opens a pane with one row per file and the reason for each change.
• Undo, or /dream undo, restores the folder from the last backup. A second undo goes one dream further back.
• Hide clears the band until the next dream.
• /dream where shows which memory folder it will tidy.

It also runs every 20 turns and just before the conversation is compacted, so nothing said is lost.

Settings

• everyTurns (default 20): turns between periodic checks.
• memoryDir (default empty): the folder to tidy. Empty means Claude Code's own auto memory folder.
• DREAM_PASS_EVERY, DREAM_PASS_MEMORY_DIR: one-session overrides.

How it works

On the periodic trigger, a cheap gate runs first. Plain code checks the index for lines over 200 characters, pointers to missing files and files the index doesn't list. If those pass, Haiku reads the index, each file's description and what was said since the last check, and answers YES or NO. Most checks stop here.

On YES, a fork of the session (full conversation, no tools) reads every memory file and replies with JSON: what to merge, rewrite, remove and add, plus the new MEMORY.md. The mod applies it itself, only for bare *.md names inside the folder, and never deletes MEMORY.md. When two files merge, every [[link]] to the old one is pointed at the new one, in code. Before any of that, it copies the folder to .dream-backup/<timestamp>/ with a DREAM.md listing every edit and why.

While a dream runs, Claude's own Write and Edit calls into the memory folder are refused, so a memory saved mid-dream can't be overwritten. If Claude Code's own auto-dream holds its .consolidate-lock, dream-pass skips, so the two can run side by side.

Limits

• The writes skip every permission prompt, in every mode. The file-name check and the backup are the only guards, so read hooks/register.js before you install it.
• A dream takes 15 to 30 seconds and costs one fork of the session.
• A file whose subject changes keeps its old name. Renames aren't supported.
• The fork is judging, so expect the odd merge you disagree with. That's what the backup and /dream undo are for.
• Source checking only works for memories with an originSessionId whose transcript still exists.
• Typed as the very first prompt, /dream has nothing to fork, so it falls back to Sonnet without the conversation.