Dream Memory Consolidation

Problem

Long-running agent sessions accumulate fragmented context: daily notes, short conversations, temporary decisions, and conflicting preferences. Appending everything to memory files can bloat the entry index and increase retrieval noise. dream-skill moves this cleanup to the background, imitating human sleep-time memory consolidation: it merges recent fragment signals into structured memory and refreshes the entry index, instead of requiring every interaction to maintain memory on the fly.

How It Works

The skill runs via a cron job and checks once every 24 hours by default. Before consolidation, it passes three gates: the time gate requires at least minHours since the last run; the session gate requires at least minSessions new sessions; and the lock gate uses lock.json to detect another running instance and avoid concurrent writes.

The consolidation workflow runs in an isolated session and has four stages:
- Orient: inspect the memory directory and entry index to understand the current structure
- Gather: read daily logs and narrow grep session transcripts to find candidate facts and conflicts
- Consolidate: merge new facts into existing topic files, convert relative dates to absolute dates, and remove contradictory entries
- Prune & Index: compress the entry index to keep it small and readable

Tool constraints are strict: Bash is limited to read-only commands such as ls, grep, and cat; Edit/Write is scoped to the memory directory. This reduces the risk of mutating the workspace or running dangerous commands.

Boundaries

It fits local agent setups that already have workspace transcripts and a memory directory, especially when long-term memory needs periodic background cleanup. Manual triggers bypass the three gates and notify immediately. Setting minHours or minSessions to 0 disables the corresponding gate, useful for testing but not ideal for production throttling. The lock gate depends on state files, so clearing the state directory can affect concurrency checks.