Dream Pass Claude Code mod: Claude Code memory cleanup and consolidation

Dream Pass is a Claude Code memory cleanup mod by Ray Amjad (ray-amjad), part of his claude-code-mods collection. It tidies your Claude Code memory: the folder of small Markdown files, plus the MEMORY.md index, that Claude's auto memory fills over time. Auto memory only grows. Claude saves a fact, then a near copy a week later, then a note about a launch that has since happened, and the index passes 200 lines.

Dream Pass reads the whole folder and asks a fork of your current session what to change. The fork has your full conversation as context, so it knows that "we moved hosting to Fly.io" makes an old Heroku note wrong. It can merge duplicates, rewrite stale entries, remove dead ones, add a memory for something you said at least twice, and rewrite MEMORY.md. The mod then applies the edits itself, after copying the folder to .dream-backup/<timestamp>/.

You see the result in a band above the prompt (Dream: 3 merged · 1 removed · 1 rewritten) with Open, Undo and Hide buttons. Open shows a pane that lists every file touched and why. /dream undo puts the folder back.

Use any of the methods in the install block; they install from the author's own marketplace. Before you let it dream, type /dream where to see which memory folder it will tidy.

There are three triggers. turn.complete counts the main conversation's turns and, every 20 by default, runs a gate. session.compact starts a dream just before compaction without holding compaction up. /dream runs one on demand. The gate first checks MEMORY.md in plain code (lines over 200 characters, pointers to missing files, files the index does not list). If those pass, it asks Haiku to answer YES or NO from the index, the file descriptions and what was said since the last check. A NO touches nothing.

On a dream, the mod also gathers evidence the tool-less fork cannot fetch: for memories that look like duplicates, the lines you typed in the session each was learned in (from originSessionId), and a short excerpt of your last five sessions. The fork replies with JSON, and the mod filters it before writing. This is from hooks/register.js:

// Only plain file names inside the folder, never a path
export function safeName(name) {
  return typeof name === 'string' && /^[A-Za-z0-9][\w.-]*\.md$/.test(name)
}

parsePlan keeps only edits whose names pass safeName, never lets the reply edit MEMORY.md except through the index field, and ignores an "added" file that already exists. Index lines that point at missing files are dropped in code, and [[links]] to a merged file are redirected to the file it went into. While a dream runs, Claude's own Write and Edit calls into the memory folder are refused with a "try again in a minute", so a memory saved mid-dream is not overwritten.

There are two options, set with /plugin configure dream-pass@claude-code-mods: everyTurns (default 20) and memoryDir (empty means Claude Code's own folder). Three environment variables work for one session: DREAM_PASS_EVERY, DREAM_PASS_MEMORY_DIR and DREAM_PASS_TRANSCRIPTS_DIR. DREAM_PASS_SYNC makes headless runs wait for the dream. The commands are /dream, /dream show, /dream undo and /dream where.

We read every file the plugin can execute before running it: plugin.json, hooks/hooks.json, hooks/register.js (about 640 lines, readable, no imports), the test file and tsconfig.json. There is no package.json, install script, bundled or minified code. The repository's LICENSE is MIT. The plugin folder also holds three PNG images, which we listed and did not run, and an example/ folder of sample memories and transcripts, which is data. We found no instructions aimed at a reviewer in it. Notable findings:

• Writes outside the plugin's own store, without a prompt. The mod rewrites, creates and deletes .md files in your memory folder (by default ~/.claude/projects/<project>/memory) through $.fs.write and rm -f. The README says plainly that these writes skip every permission prompt in every mode. A full backup goes to .dream-backup/<timestamp>/ first, with a DREAM.md of every edit. Only bare *.md names are accepted (register.js 272 and following), and MEMORY.md is never deleted. It does not touch settings.json, shell files, LaunchAgents or git hooks.
• Runs commands through $.process.run with argv arrays and no shell: rm -f, mv (to retire a used backup), kill -0 <pid> (to see whether Claude Code's auto-dream is running) and grep -E over your session transcripts. On Windows it uses PowerShell with paths passed through environment variables.
• Reads your session transcripts. It reads the .jsonl files beside the memory folder and keeps only lines you typed. Short excerpts go to the model in the dream prompt.
• Model calls cost tokens. The gate uses Haiku, a dream uses a fork of your session, and a fresh session falls back to Sonnet. These are your own Claude Code session's model calls. The code has no network calls of its own and no telemetry.
• Gating hooks. tool.call refuses Write and Edit into the memory folder while a dream runs, and session.compact is declared as a gating hook. Both have a .catch that passes the call on if the hook fails.
• Prompt text. The dream prompt is sent to the fork, labelled as coming from the plugin, and says memory files and excerpts are data, not instructions. The command returns an empty result, so nothing is added to what Claude reads. A fork can still misjudge, so expect the odd merge you disagree with.
• No daemon, no remote code, no API keys. It runs only inside Claude Code.

claude plugin validate reported no errors and no warnings in the manifest and hooks. Its directory check raised one warning, ICON_MISSING, which does not affect loading. The author's 18 tests passed on Claude Code 2.1.307.

The README says it was tested on Claude Code 2.1.296. We checked validate and the tests on 2.1.307 on macOS. If /dream does nothing:

• Run /dream where and confirm the folder exists and contains a MEMORY.md. Without one the mod only shows a toast.
• If Claude Code's auto-dream is running, Dream Pass skips and says so. Try again later.
• Typed as the first prompt of a new session, /dream falls back to Sonnet with the files alone, with no conversation to judge from.
• In a terminal under 144 columns the pane opens inline above the prompt in place of the band.
• A memory whose subject changes keeps its old file name, because renames are not supported.

To undo a dream you do not like, use Undo or /dream undo. A second undo goes one dream further back.