Dream

Dream - Memory Consolidation for Claude Code

> Your AI agent dreams like you do. Consolidates memory while you sleep.

---

How It Works

Dream runs in 4 sequential phases. Execute them in order. Do not skip phases.

ORIENT --> GATHER SIGNAL --> CONSOLIDATE --> PRUNE & INDEX

Auto-trigger flow (native Claude Code hooks)

Session ends
  --> Stop hook fires should-dream.sh (~10ms)
  --> Checks: 24hrs passed? 5+ sessions?
  --> If NO: exits silently, zero overhead
  --> If YES: creates ~/.claude/.dream-pending flag
Next session starts
  --> Claude reads CLAUDE.md, sees .dream-pending exists
  --> Spawns /dream as background subagent
  --> Dream runs all 4 phases
  --> Writes .last-dream timestamp, deletes .dream-pending
  --> Timer resets for next 24hrs

---

Phase 1: ORIENT

Goal: Understand the current state of memory before changing anything.

Step 0: Read config

cat ~/.claude/skills/dream/.dream-config 2>/dev/null || echo "DREAM_MEMORY_TYPE=native"

This tells you which memory system to target:

• native - scan ~/.claude/projects/*/memory/
• openclaw - scan the memory/ folder in the project root (daily logs + MEMORY.md)
• project-root - scan MEMORY.md and topic files in the project root

Steps

1. Find memory directories based on type:

# native (default)
ls -d ~/.claude/projects/*/memory/ 2>/dev/null

# openclaw
ls ./memory/ 2>/dev/null

# project-root
ls ./MEMORY.md ./memory/ 2>/dev/null

1. Read the memory directory for the detected type:

# native
ls ~/.claude/projects/*/memory/ 2>/dev/null

# openclaw - also list daily logs
ls ./memory/*.md 2>/dev/null

1. Read MEMORY.md (the index file) in each project's memory directory. Note:

• How many topic files exist
• Total line count of MEMORY.md
• Last modified dates
• Any entries that look stale (relative dates like "yesterday", "last week" with no anchor)

1. Read each topic file to understand what's already stored.

Output of this phase

You should now have a mental map of:

• Which projects have memory
• What topics are covered
• How large the memory files are
• What's potentially stale or contradictory

---

Phase 2: GATHER SIGNAL

Goal: Extract important information from recent sessions without reading everything.

Where to find transcripts

find ~/.claude/projects/*/sessions/ -name "*.jsonl" -mtime -7 2>/dev/null | sort -t/ -k6 -r

This finds JSONL session files modified in the last 7 days, sorted newest first. Adjust -mtime -7 for different windows.

What to scan for

Use targeted grep, not full reads. Each pattern targets a specific signal type:

User corrections (highest priority):

grep -il "actually\|no,\|wrong\|incorrect\|not right\|stop doing\|don't do\|I said\|I meant\|that's not\|correction" ~/.claude/projects/*/sessions/*.jsonl 2>/dev/null

Preferences and configuration:

grep -il "I prefer\|always use\|never use\|I like\|I don't like\|I want\|from now on\|going forward\|remember that\|keep in mind\|make sure to\|default to" ~/.claude/projects/*/sessions/*.jsonl 2>/dev/null

Important decisions:

grep -il "let's go with\|I decided\|we're using\|the plan is\|switch to\|move to\|chosen\|picked\|decision\|we agreed" ~/.claude/projects/*/sessions/*.jsonl 2>/dev/null

Recurring patterns:

grep -il "again\|every time\|keep forgetting\|as usual\|same as before\|like last time\|we always\|the usual" ~/.claude/projects/*/sessions/*.jsonl 2>/dev/null

How to read matches

For each file that matches, read ONLY the surrounding context of the match (not the full session). JSONL files have one JSON object per line. Focus on lines where type is "human" (user messages) and the immediately following "assistant" response.

grep -n "I prefer\|always use\|never use"  | head -20

What to extract

For each finding, note:

• The fact - What was said or decided
• The date - Derive from the session file's modification time
• Confidence - Was it an explicit instruction (high) or implied preference (medium)?
• Contradictions - Does this conflict with anything currently in memory?

---

Phase 3: CONSOLIDATE

Goal: Merge new findings into existing memory. This is the most delicate phase.

Rules

1. Never duplicate. Before adding anything, check if it already exists in memory. If it does, update the existing entry rather than creating a new one.

1. Convert relative dates to absolute. If a session from March 15 says "yesterday I changed the API key", write "2026-03-14: Changed API key" in memory. Never store "yesterday" or "last week".

1. Delete contradicted facts. If memory says "Prefers tabs" but a recent session has the user saying "Use spaces", remove the old entry and write the new one. Add a note: (Updated YYYY-MM-DD, previously: tabs).

1. Preserve source attribution. When adding a new memory entry, note where it came from: (from session YYYY-MM-DD).

1. Topic file organization. Group related memories into topic files:

• preferences.md - How the user likes things done
• decisions.md - Choices and their rationale
• corrections.md - Things the user corrected
• patterns.md - Recurring workflows, common tasks
• facts.md - Project-specific knowledge, architecture notes
• Create new topic files only when existing ones don't fit

1. Entry format. Each memory entry should be concise:

- [YYYY-MM-DD] The fact or preference. (source: session, confidence: high/medium)

How to write

Use the Edit tool to modify existing memory files, or Write to create new topic files. Always read a file before editing it.

---

Phase 4: PRUNE & INDEX

Goal: Keep MEMORY.md as a lean index. Remove stale content. Enforce size limits.

MEMORY.md rules

MEMORY.md is an index file, not a content store. It should contain:

• Links/references to topic files
• A brief (one-line) summary of what each topic file contains
• The last-updated date for each topic file

MEMORY.md should never contain:

• Full memory entries (those go in topic files)
• Verbose descriptions
• Duplicate content that exists in topic files

Size limit: 200 lines

If MEMORY.md exceeds 200 lines after consolidation:

1. Move any inline content to the appropriate topic file
2. Replace verbose entries with one-line summaries + links
3. Remove entries that point to deleted or empty topic files
4. If still over 200 lines, demote the oldest entries to an archive.md topic file

Prune stale entries

Remove or archive entries that are:

• More than 90 days old with no references in recent sessions
• Contradicted by newer entries (should have been caught in Phase 3)
• About projects/repos that no longer exist in ~/.claude/projects/

Final index format

# Memory Index

Last consolidated: YYYY-MM-DD

## Topic Files

| File | Summary | Updated |
|------|---------|---------|
| preferences.md | Editor, formatting, communication style preferences | YYYY-MM-DD |
| decisions.md | Architecture choices, tool selections, project direction | YYYY-MM-DD |
| corrections.md | Past mistakes to avoid repeating | YYYY-MM-DD |
| patterns.md | Common workflows and recurring tasks | YYYY-MM-DD |
| facts.md | Project knowledge, API details, system architecture | YYYY-MM-DD |

## Quick Reference

- Fact 1
- Fact 2

The Quick Reference section is for facts so important they should be seen every time memory is loaded. Keep it to 10 items maximum.

Record the dream timestamp

After completing all 4 phases, write timestamps so the auto-trigger knows when you last dreamed:

date +%s > ~/.claude/projects//memory/.last-dream
rm -f ~/.claude/.dream-pending

---

Safety

• Never delete memory without replacement. If removing an entry, either it was contradicted (replaced by a newer entry) or it was moved (to a topic file or archive). Never just delete.
• Back up before first run. On the very first run against a project, copy the memory directory:

cp -r ~/.claude/projects//memory/ ~/.claude/projects//memory-backup-$(date +%Y%m%d)/

• Dry run option. On first use, read through all 4 phases but only print what you WOULD change, without writing. Confirm with the user before applying.

---

Verification

After running, verify the consolidation:

1. wc -l on MEMORY.md - should be under 200 lines
2. Check that no topic file has duplicate entries
3. Confirm no relative dates remain ("yesterday", "last week", etc.)
4. Verify all topic files referenced in MEMORY.md actually exist
5. Print a summary: entries added, entries updated, entries archived, contradictions resolved

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: justnau1020
• Source: justnau1020/claude-os
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.