skills/dream/SKILL.md

---
name: dream
description: >
  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.

```bash
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:
   ```bash
   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:
```bash
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**:
```markdown
# 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.