Dreams: how Remnic consolidates memory in its sleep
Remnic's background consolidation runs in three named phases: light sleep, REM, and deep sleep. Here is what each one actually does.
Memory that only accumulates becomes noise. A store that grows by hundreds of files a week needs a process that merges duplicates, promotes what matters, and retires what does not. Remnic calls that process Dreams, and it runs in three phases named after the thing your brain does every night.
Light sleep
Light sleep is the housekeeping pass: scoring and clustering. It mirrors the default lifecycle policy, so it runs without any extra configuration. Memories get importance scores, near-duplicates get clustered, and low-value entries get flagged before they can crowd the recall budget.
REM
REM is synthesis. Clusters of related memories get consolidated into fewer, denser entries. Ten scattered observations about how you like your commit messages become one preference with provenance links back to every source. This phase is opt-in, because synthesis rewrites content and some users want their store append-only.
Deep sleep
Deep sleep handles promotion and tiering: moving validated memories up trust tiers, migrating cold entries to cheaper storage states, and snapshotting page versions so every overwrite stays diffable and revertable. Also opt-in.
Why phases instead of one big job
Splitting consolidation into phases keeps each step inspectable and reversible. Every consolidated fact carries provenance fields that point at its sources. If REM merges something it should not have, you can see exactly which files fed the merge and revert through page versions.
That is the design bet across Remnic: background automation is fine, invisible automation is not. Consolidation should leave receipts.
The full pipeline is documented in docs/dreams.md. The design principles behind what gets to occupy your recall budget are on the memory quality page.