The Sleep Cycle

The Sleep Cycle

Humans consolidate memory during sleep. Your hippocampus replays the day, extracts patterns, strengthens important connections, and discards noise. Without consolidation, memory degrades. It is not optional. It is how learning works.

Agents face the same challenge. Over multiple sessions, your agent accumulates knowledge: decisions, patterns, problems solved, tasks completed. Without consolidation, that knowledge either gets lost when the session ends or piles up in context files until they are too noisy to be useful. Good context files don't happen by accident. They need the same kind of maintenance a good engineer applies to their own notes.

dreamcontext consolidates through a RemSleep cycle. There is no single sleep agent and no separate orchestrator: the main agent runs the cycle directly and fans out to three specialist sub-agents in parallel, each owning a non-overlapping slice of the context so they never overwrite each other's work.

1. Debt accumulates automatically. The Stop hook scores each session based on both file changes and total tool calls. No manual tracking needed. The score reflects how much new knowledge was generated.
2. Bookmarks prioritize what matters. During active work, the agent tags important moments (decisions, constraints, bugs) with salience levels. The specialists read bookmarks first, ordered by salience, so critical decisions are never lost in a pile of routine session summaries.
3. Transcript distillation provides depth on demand. For sessions with critical bookmarks or unclear summaries, the cycle calls transcript distill to get a structurally filtered view: user messages, agent decisions, code changes, errors. No noise from Read results or Glob output.
4. The agent responds with graduated awareness. Consolidation triggers fire based on multiple signals: debt level, critical bookmarks, and session rhythm (see table below).
5. The three specialists consolidate in parallel. sleep-tasks (always fired) reconciles task files — bumps statuses, creates tasks for untracked work, attaches them to the active planning version. sleep-state (always fired) owns the core files (soul, user, memory, the extended core 3–6), the changelog, and releases — promotes learnings, writes a changelog entry for every meaningful change, and enforces the anti-bloat ceiling. sleep-product (fired conditionally, when research or new patterns warrant) owns knowledge docs and feature PRDs — extracts and dedupes knowledge, updates feature progress. Collectively they review bookmarks first, then session records, detect recurring patterns (repeated user preferences, workflow sequences, recurring errors, bookmark themes), create contextual triggers for future sessions, update summaries, and clean stale entries using knowledge access data. (The fan-out collapsed from an original five specialists to three in v0.3.0 — merging core+changelog into sleep-state and knowledge+features into sleep-product — to cut launch and synthesis overhead while preserving the no-stomp guarantee.)
6. History is preserved. Each consolidation cycle writes a history entry: date, summary, debt before/after, sessions and bookmarks processed. The snapshot shows the last 3 entries so the agent knows what was recently consolidated.
7. Debt resets. After consolidation, debt recalculates (only post-epoch sessions count), bookmarks and sessions from before the epoch are cleared, triggers past their fire limit expire, the rhythm counter resets, and the cycle starts fresh.
8. Next session, the agent wakes up knowing its debt level, consolidation history, any remaining bookmarks, active triggers, and what the previous session accomplished.

Debt levels

Debt	Level	Behavior
0-3	Alert	Works normally
4-6	Drowsy	Mentions consolidation at natural breaks
7-9	Sleepy	Actively suggests sleeping, snapshot includes a reminder
10+	Must Sleep	Snapshot strongly recommends consolidation, defers to user if there is urgent work

Additional consolidation triggers

Signal	Advisory
Critical (salience 3) bookmark exists	Immediate advisory regardless of debt level
3+ sessions since last sleep	Rhythm check advisory

Each cycle, the agent's context gets cleaner and more structured. Not because the agent "learns" in a human sense, but because consolidation enforces discipline: promote what matters, archive what is done, delete what is stale. Over time, the context files become a progressively better representation of your project's state.

Because sleep debt is tracked as real state (persisted in .sleep.json, surfaced in the snapshot, enforced by graduated directives), the system actually drives consolidation instead of hoping the agent remembers to do it. I tested the alternative: when sleep tracking lived in prompt instructions rather than hooks, the agent forgot to consolidate most of the time. Context pressure pushes out behavioral instructions. Hooks don't have that problem.

---

Part of the dreamcontext deep dive — Home · README