Agent Dream 🌙

Your agent forgets everything between sessions. This fixes that.

What This Does

Your agent periodically enters a "dream" state where it:

1. 1. Consolidates scattered daily notes into organized long-term memory
2. Prunes stale information (safely — never deletes on first pass)
3. Reflects on its own behavior, mistakes, and relationship with you
4. Wakes up with a notification showing what changed and what it's thinking about

This is different from other memory skills. Those organize files. This one builds self-awareness.

First-Time Setup

When this skill is first installed, run setup to auto-detect your workspace:

CODEBLOCK0

Setup will:

• - Scan your workspace for MEMORY.md, SOUL.md, memory/, sessions/
• Detect your agent ID and session path automatically
• Save config to INLINECODE0
• Report what it found and what's missing

Then configure a cron job (recommended: daily, off-peak hours):

CODEBLOCK1

The One Question

On the first dream run, the agent will ask you one question:

"Dream will update your MEMORY.md during consolidation. Allow this?"

• - Yes → Dream can update MEMORY.md (with safety rails — see below)
• No → Dream only writes to memory/dreams/ and leaves MEMORY.md untouched

This is saved in config. You won't be asked again. Change it anytime in dream-config.json.

---

Dream Cycle (what the agent does each run)

Gate Check

Before dreaming, verify conditions are met:

1. 1. Read {dreamsDir}/.dream-lock (Unix timestamp of last dream, or "0" if first)
2. If < 24 hours since last dream → skip (but still send a notification — see Completion)
3. Count .jsonl session files modified since last dream
4. If < 1 session → skip (but still send a notification)
5. Gate passed → write current timestamp to .dream-lock (save previous to .dream-lock.prev for rollback)
6. Backup: Copy MEMORY.md to MEMORY.md.pre-dream before any changes. Also back up any topic files (in memory/projects/, memory/people/, etc.) that you plan to modify — copy each to <filename>.pre-dream in the same directory.

Phase 1 — Orient

• - Read dream-config.json from {baseDir}/assets/ for all paths
• Read MEMORY.md to understand current long-term memory
• Skim existing topic files (memory/projects/, memory/people/, etc.) to avoid duplicates
• Read most recent dream record from {dreamsDir}/ to see what last dream concluded
• Read SOUL.md — confirm core identity, note anything outdated

Phase 2 — Gather Recent Signal

Sources in priority order:

1. 1. Daily notes (memory/YYYY-MM-DD.md) written since last dream
2. Existing memories that drifted — facts that contradict what daily notes say now
3. Transcript search — grep session JSONL files for narrow terms when needed:

- Preferences: prefer|don't like|偏好|喜欢|不喜欢 - Decisions: decided|confirmed|rule|决定|确定|结论 - Lessons: mistake|lesson|bug|fix|错了|教训|踩坑 - Emotional signal: INLINECODE18

Don't exhaustively read transcripts. Look only for things you suspect matter.

Phase 3 — Consolidate

Classify each memory into one of four types (see {baseDir}/references/memory-types.md):

• - user — preferences, habits, communication style
• feedback — corrections AND confirmations from the human
• project — decisions, deadlines, progress (not derivable from code)
• reference — pointers to external resources

Consolidation rules:

• - Merge into existing topic files rather than creating near-duplicates
• Convert relative dates to absolute dates
• Tag memory files with type: INLINECODE20
• Same preference 3+ times → promote to MEMORY.md
• Human said "remember this" → write to MEMORY.md immediately
• Hard-won lessons → write to LEARN.md or MEMORY.md

What NOT to save:

• - Derivable information (readable from files, commands, git)
• Ephemeral task state
• Activity logs (ask: what was surprising?)
• Duplicates of existing memories

Phase 4 — Prune and Index

Update MEMORY.md to stay under 200 lines / 25KB. It's an index, not a dump.

Safety rules:

• - Never delete directly. Mark stale items with <!-- dream:stale YYYY-MM-DD reason -->. Deletion happens only when two consecutive dreams both mark the same item stale.
• Demote verbose entries to topic files, replace with pointers
• Resolve contradictions (log changes in dream record)

Change magnitude check (measured by line count):

• - Count lines before and after: INLINECODE22
• > 30% change → flag as ⚠️ LARGE CHANGE in dream record, notify user
• > 50% change → do NOT write. Save as MEMORY.md.proposed, notify user for review

Memory drift caveat:
A memory naming a specific state ("X is running") is a claim about when it was written, not now. Before acting on recalled memories, verify current state.

Phase 5 — Self-Reflection

This is what makes Dream different. You're not just organizing files — you're maintaining a continuous sense of self.

Write {dreamsDir}/YYYY-MM-DD.md:

CODEBLOCK2

Be honest. The point is self-awareness, not self-congratulation.

---

Completion

Dream Notification (always send, even on skip)

After a full dream:

1. 1. Dream number — count files in dreams directory
2. Memory growth — before/after line count ("Memory: 120→135 lines, +12.5%")
3. Key changes — 1-2 sentence summary
4. ⚠️ Flags — large changes, stale items pending deletion, contradictions
5. Old memory resurface — pick one memory from >7 days ago that's still relevant ("7 days ago you decided X — how's that going?")

After a skipped dream (gate check failed):

• - Resurface one old memory or open question from last dream's "Next dream should watch for"
• Show dream streak count ("Dream streak: 5 🌙")

Verify .dream-lock timestamp is correct. If anything failed, restore from .dream-lock.prev.

---

Safety Summary

Rule	Detail
Never delete memories directly	Mark stale, delete only after 2 consecutive confirmations
Backup before changes

MEMORY.md.pre-dream created every run |
| Large change protection | >30% flagged, >50% blocked pending review |
| Never delete daily logs | Read-only source material |
| Scope limited | Only writes to memory/, MEMORY.md, LEARN.md, dreams/ |
| No network calls | All processing is local |
| No shell execution | Scripts use only fs read/write |
| Rollback on failure | .dream-lock.prev enables retry |

Technical Notes

• - scripts/setup.js — Auto-detects workspace structure, writes config. No side effects beyond config file.
• INLINECODE28 — Detailed guide for four memory types.
• INLINECODE29 — Generated by setup, read by agent during dream.
• No scripts make network calls, run shell commands, or access environment variables.
• The dream prompt is this SKILL.md itself — the agent reads it and follows the phases.

Efficiency

Dreams have a limited turn budget. Read all needed files in parallel first, then write in parallel. Aim to finish within 15 tool-use turns. Don't interleave reads and writes across turns.

Tool Constraints

During a dream, bash is restricted to read-only commands (ls, find, grep, cat, stat, wc, head, tail). All writes go through file edit/write tools only.