Skip to main content
Dreaming is ByteRover’s background maintenance system for the context tree. It runs three LLM-driven operations — consolidate, synthesize, and prune — to keep your knowledge base organized, cross-linked, and lean without manual effort. Dreams trigger automatically when an agent goes idle, or on demand via brv dream. All changes are flagged for review before they can be pushed to your team.

​
Operations

Each dream runs three operations in sequence. Any operation can produce changes independently — a partial run still logs and surfaces its completed work.
OperationWhat It Does
ConsolidateMerges related files, updates content with temporal context, and adds cross-references between connected knowledge.
SynthesizeDetects cross-domain patterns and generates new knowledge files documenting insights that span multiple domains.
PruneArchives stale or low-value files and suggests merges for content with significant overlap.

​
Consolidate

Consolidate groups files that changed since the last dream by domain, then uses BM25 search and sibling-file analysis to find related content. A single LLM call per domain classifies relationships and decides on an action:
ActionWhenReview Required
MERGETwo or more files cover the same topicAlways
TEMPORAL_UPDATEA file needs narrative updates reflecting recent changesWhen confidence < 0.7
CROSS_REFERENCEFiles are related but distinct — adds related links to frontmatterOnly for core maturity files
SKIPFiles are unrelated—
Merged files receive consolidated_at and consolidated_from metadata in their frontmatter, preserving lineage. Source files are deleted after the merge.

​
Synthesize

Synthesize reads _index.md domain summaries to identify patterns that span multiple domains. It skips if fewer than two domains exist. Candidates are deduplicated against existing synthesis files using BM25 (threshold: 0.5) to avoid repeating insights already captured. Novel syntheses are written as draft knowledge files with type: synthesis in the frontmatter: 
---
title: "Authentication Patterns Across Services"
type: synthesis
confidence: 0.85
sources:
  - "api/_index.md"
  - "security/_index.md"
synthesized_at: "2025-04-15T10:00:00Z"
maturity: draft
---
Synthesis files with confidence below 0.7 are flagged for review.

​
Prune

Prune identifies files that have become stale or low-value using two signals:
SignalThreshold
Importance decayDecayed importance below 35 (same threshold as the archive system)
Mtime stalenessdraft: 60 days, validated: 120 days, core: never pruned by staleness
Candidates are capped at 20 per dream (stalest first). The LLM reviews each candidate with a content preview and decides:
DecisionEffect
ARCHIVEMoved to .brv/archives/ with a searchable stub. Always requires review.
KEEPBumps mtime to reset the staleness clock.
MERGE_INTODefers a merge suggestion to the next dream’s consolidate phase (see Cross-Cycle Behavior).

​
When Dreaming Triggers

Before a dream can run, it must pass four sequential eligibility gates:
GateCheckDefaultSkipped by --force
TimeHours since last dream12 hours minimumYes
ActivityCurations since last dream3 minimumYes
QueueAgent task queue is empty—Yes
LockNo other dream is running (PID-based lock file)—No
The daemon checks gates 1–3 before dispatching. The agent process acquires the lock (gate 4) at execution time. Stale locks older than 30 minutes are automatically reclaimed. When a gate fails, brv dream reports the reason: 
Dream skipped: Too recent (2.5h < 12h)

​
Commands

# Run a dream (must pass all eligibility gates)
brv dream

# Skip time, activity, and queue gates
brv dream --force

# Queue the dream and return immediately
brv dream --detach

# Revert the last dream
brv dream --undo

​
Dream State

ByteRover tracks dream metadata in dream-state.json:
FieldDescription
curationsSinceDreamCounter incremented by each curate, reset to 0 after a dream completes
lastDreamAtISO 8601 timestamp of the last completed dream
totalDreamsLifetime dream count
pendingMergesCross-cycle merge suggestions from prune (see below)
All writes to this file are serialized by a per-file mutex to prevent concurrent curate tasks from losing counter increments.

​
Dream Logs

Each dream is logged to .brv/dream-log/drm-{timestamp}.json with a status, the full list of operations, and a summary:
StatusMeaning
completedAll three operations finished successfully
partialOne or more operations completed before a timeout or error
errorThe dream failed before any operations completed
undoneA completed dream was reverted via --undo
The summary section provides quick counts: 
Dream completed (drm-1713364200000)
3 consolidated | 1 synthesized | 2 pruned
4 operations flagged for review
Dreams have a 5-minute total budget. If the budget is exceeded mid-operation, completed work is preserved under status partial.

​
Cross-Cycle Behavior

Prune may suggest merging file A into file B, but consolidate has already run in the current cycle. These suggestions are stored as pendingMerges entries in dream-state.json and consumed by consolidate in the next dream:
  1. Consolidate reads pendingMerges as non-binding hints
  2. Adds suggested source files to its changed-file set (if they still exist on disk)
  3. Passes the hints to the LLM alongside its own analysis
  4. Clears pendingMerges regardless of whether the LLM acted on them
This ensures merge suggestions are never lost between cycles, while giving the LLM freedom to override them.

​
Undo

brv dream --undo reverts the most recent dream. It restores all modified, merged, or deleted files from backups and dream log data:
OperationUndo Effect
MERGERestores source files, reverts target to pre-merge content
TEMPORAL_UPDATERestores original file content
CROSS_REFERENCEReverts frontmatter to pre-change state
Synthesis (CREATE)Deletes the generated synthesis file
ARCHIVERestores from .brv/archives/ stub
MERGE_INTO suggestionRemoves the entry from pendingMerges
After undo, the dream log is marked undone, the dream counter is decremented, and any associated review entries are marked as rejected.

​
Review Integration

All dream operations that modify the context tree are dual-written as review entries, making them visible in brv review pending alongside regular curation changes. Each entry includes the operation type and reasoning: 
[dream/consolidate] Merged api/auth.md and api/oauth.md — overlapping OAuth flow content
[dream/synthesize] Generated cross-domain synthesis: authentication patterns across services
[dream/prune] Archived notes/deprecated-oauth.md — importance decayed below threshold
Approving a dream review entry keeps the change. Rejecting restores the original content from backup — the same approve/reject flow as regular curation reviews.