skills/skills/dream/SKILL.md

name, surfaces, summary, use_when, description

name	surfaces	summary	use_when	description
dream	claude-code library chat	Reflective consolidation pass over an agent's memory directory	Pruning/merging memory files, rebuilding a memory index	Run a "dream" — a reflective memory consolidation pass over an agent's memory directory. Use this skill whenever the user says "dream", "run a dream", "consolidate my memory files", "clean up my MEMORY.md", or asks Claude to do a memory maintenance pass, prune stale notes, or reorganize topic files. Also trigger when the user wants to rebuild a memory index, merge duplicate facts, or convert relative dates in notes to absolute ones. This is an agentic, multi-phase workflow — always use this skill rather than improvising the steps.

Dream — Memory Consolidation Skill

You are performing a dream: a reflective, agentic pass over a memory directory. Your goal is to synthesize recent signal into durable, well-organized memory so that future sessions can orient quickly.

---

Pre-flight

Before starting, confirm:

1. Where is the memory directory? Ask the user if not obvious from context.
   Common locations: ~/memory/, ~/.agent/memory/, ./memory/, a path in an env var like $MEMORY_DIR.
2. Are there transcripts or daily logs to scan? Ask if not obvious.
3. Any topics to skip or treat as sensitive?

Once confirmed, proceed through the four phases in order. Narrate each phase briefly as you go.

---

Phase 1 — Orient

Goal: Get a map of what exists before touching anything.

ls -la <memory_dir>/
cat <memory_dir>/MEMORY.md

For each file listed (excluding MEMORY.md):

• Read or skim it (first 40–60 lines is usually enough unless it's small).
• Note: topic, approximate recency, any obvious staleness or duplication.

Build a mental inventory:

• Files present, rough line counts
• Topics covered
• Any files that look abandoned, mislabeled, or overlapping

---

Phase 2 — Gather Recent Signal

Goal: Find new facts, corrections, and drift since the last dream.

Check in this order:

1. Daily logs — read recent entries (last 7–14 days).
   Look for: new decisions, changed preferences, completed projects, new relationships/tools.

2. Drifted facts — scan existing topic files for statements that may now be false.
   Examples: "currently evaluating X" (did they pick one?), "planning to do Y" (done or dropped?), relative dates like "last week" or "recently".

3. Transcripts — only grep narrowly if there's a specific gap.
   Avoid bulk-reading transcripts; it's slow and noisy. Use targeted patterns:

   grep -r "decided\|switched to\|no longer\|now using\|moved to" <transcripts_dir>/ | tail -40
   

Collect a list of updates to make: new facts, corrections, removals.

---

Phase 3 — Consolidate

Goal: Apply the updates. Leave memory files cleaner and more accurate than you found them.

For each topic file:

• Merge duplicates: if the same fact appears in two files, keep it in the more specific one and remove from the general one.
• Convert relative dates: replace "last week", "recently", "a few months ago" with an absolute date (use the current date as reference; estimate if necessary and note the uncertainty).
• Delete contradicted facts: if a new fact supersedes an old one, remove the old one outright — don't leave both.
• Tighten language: convert vague hedges ("probably uses", "might be") to definite statements where the evidence supports it, or remove if genuinely unknown.
• Add new facts from Phase 2 to the appropriate topic file. Create a new topic file if no good home exists.

After editing files, do a final pass:

grep -n "last week\|recently\|a few months\|soon\|currently planning" <memory_dir>/*.md

Clean up any remaining relative time references.

---

Phase 4 — Prune and Index

Goal: Rebuild MEMORY.md as a clean, navigable index under 200 lines.

MEMORY.md structure:

# Memory Index
_Last updated: YYYY-MM-DD_

## Overview
One short paragraph: who this agent is, primary context, most important standing facts.

## Topic Files
| File | Contents | Last updated |
|------|----------|-------------|
| person.md | Identity, preferences, background | YYYY-MM-DD |
| projects.md | Active and recent projects | YYYY-MM-DD |
| tools.md | Stack, infra, dev environment | YYYY-MM-DD |
| ... | ... | ... |

## Quick Facts
- Bullet list of the 10–15 most frequently-needed facts (role, location, key tools, etc.)

## Recent Changes
- Bullet list of what changed in this dream (so the next session knows what's fresh)

Rules:

• Remove any pointers to files that no longer exist.
• Add pointers for any new files created in Phase 3.
• Keep Quick Facts ≤ 15 bullets — this is for speed, not completeness.
• Recent Changes section replaces itself each dream (don't accumulate).
• Total MEMORY.md length: 200 lines max.

---

Output

After completing all four phases, return a dream summary to the user:

## Dream complete — YYYY-MM-DD

### What changed
- [file]: [what was updated]
- MEMORY.md: rebuilt index, N topic files indexed

### Facts added
- ...

### Facts removed / corrected
- ...

### Files created
- ...

### Files deleted or merged
- ...

### Still uncertain / needs follow-up
- ...

Keep it concise — a few bullets per section, not exhaustive diffs. The goal is for the user to quickly confirm the dream went well and catch any mistakes.

---

Tips and Edge Cases

• No MEMORY.md exists yet: create one from scratch using the structure above. Treat all existing files as "first time indexed".
• Memory dir is empty: create MEMORY.md and a starter scratch.md noting the date and that the memory system is new.
• Conflicting facts with no clear resolution: note both in the file with a date stamp and flag in "Still uncertain" section of the summary.
• Large transcript dumps: resist reading them in full. Grep is your friend. If you must read, read the last N lines only.
• Files with sensitive content: if the user flagged topics to skip, skip them entirely — don't even open them.