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.
When a dream rewrites a context file, the order of frontmatter fields (title, summary, tags, keywords, related, createdAt, updatedAt) is preserved. brv vc diff only surfaces real content changes — not field reorderings.
| Operation | What It Does |
|---|
| Consolidate | Merges related files, updates content with temporal context, and adds cross-references between connected knowledge. |
| Synthesize | Detects cross-domain patterns and generates new knowledge files documenting insights that span multiple domains. |
| Prune | Archives 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:
| Action | When | Review Required |
|---|
| MERGE | Two or more files cover the same topic | Always |
| TEMPORAL_UPDATE | A file needs narrative updates reflecting recent changes | When confidence < 0.7 |
| CROSS_REFERENCE | Files are related but distinct — adds related links to frontmatter | Only for core maturity files |
| SKIP | Files are unrelated | — |
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"
---
Prune
Prune identifies files that have become stale or low-value using two signals:
| Signal | Threshold |
|---|
| Importance decay | Decayed importance below 35 (same threshold as the archive system) |
| Mtime staleness | draft: 60 days, validated: 120 days, core: never pruned by staleness |
| Decision | Effect |
|---|
| ARCHIVE | Moved to .brv/archives/ with a searchable stub. Always requires review. |
| KEEP | Bumps mtime to reset the staleness clock. |
| MERGE_INTO | Defers 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:
| Gate | Check | Default | Skipped by --force |
|---|
| Time | Hours since last dream | 12 hours minimum | Yes |
| Activity | Curations since last dream | 3 minimum | Yes |
| Queue | Agent task queue is empty | — | Yes |
| Lock | No other dream is running (PID-based lock file) | — | No |
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:
| Field | Description |
|---|
curationsSinceDream | Counter incremented by each curate, reset to 0 after a dream completes |
lastDreamAt | ISO 8601 timestamp of the last completed dream |
totalDreams | Lifetime dream count |
pendingMerges | Cross-cycle merge suggestions from prune (see below) |
Dream Logs
Each dream is logged to .brv/dream-log/drm-{timestamp}.json with a status, the full list of operations, and a summary:
| Status | Meaning |
|---|
completed | All three operations finished successfully |
partial | One or more operations completed before a timeout or error |
error | The dream failed before any operations completed |
undone | A completed dream was reverted via --undo |
Dream completed (drm-1713364200000)
3 consolidated | 1 synthesized | 2 pruned
4 operations flagged for review
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:
- Consolidate reads
pendingMerges as non-binding hints
- Adds suggested source files to its changed-file set (if they still exist on disk)
- Passes the hints to the LLM alongside its own analysis
- 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:
| Operation | Undo Effect |
|---|
| MERGE | Restores source files, reverts target to pre-merge content |
| TEMPORAL_UPDATE | Restores original file content |
| CROSS_REFERENCE | Reverts frontmatter to pre-change state |
| Synthesis (CREATE) | Deletes the generated synthesis file |
| ARCHIVE | Restores from .brv/archives/ stub |
| MERGE_INTO suggestion | Removes the entry from pendingMerges |
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
