Dreaming

Dreaming is idle-time memory consolidation. When the system is quiet and no sessions are active, agents with dreaming enabled review and optimize their memory stores — decaying stale entries, pruning noise, promoting important facts, deduplicating overlaps, and reflecting on patterns.

How It Works

Dreaming runs automatically during idle windows — periods when no user activity is detected and no chat turns are executing. The system guarantees at least one idle-window check every 24 hours.

Each dream cycle has two tiers:

Tier	Type	What It Does
Tier 1	Deterministic (server-side)	Decay, prune, promote, and deduplicate memories without LLM calls
Tier 2	Intelligent (agent-driven)	LLM reviews memories to consolidate overlapping entries and write reflections

Tier 1: Server-Side Operations

Tier 1 runs automatically and requires no LLM calls:

Decay: memories older than the configured decayAgeDays (default 30) with zero access and zero reinforcement are marked as decayed
Prune: working-tier memories older than pruneThresholdDays (default 90) with no activity are deleted
Promote: working-tier memories with 3+ accesses and 2+ reinforcements are promoted to durable tier
Dedup: duplicate memories (by content hash) are removed

Exempt categories that are never decayed or pruned: daily_digest, consolidated_insight, dream_reflection.

Tier 2: Agent-Driven Reflection

When enabled, Tier 2 sends the agent's top memories (up to tier2MaxMemories, default 50) to the agent's configured LLM. The model is asked to:

Consolidate overlapping memories into single entries (saved as consolidated_insight category)
Reflect on patterns across memories (saved as dream_reflection category)
Flag outdated or contradictory memories for operator review

Dream-produced memories are persisted at the durable tier with metadata.origin: 'dream' for traceability.

Configuration

Dreaming is opt-in per agent. Enable it in the agent settings under Advanced > Dreaming.

Setting	Default	Description
`dreamEnabled`	`false`	Master toggle for this agent
`cooldownMinutes`	`360` (6 hours)	Minimum time between dream cycles
`decayAgeDays`	`30`	Memories older than this with no activity get decayed
`pruneThresholdDays`	`90`	Stale working-tier memories older than this get deleted
`tier2Enabled`	`true`	Whether to run LLM-driven reflection
`tier2MaxMemories`	`50`	Maximum memories sent to the LLM per dream cycle

Dream Cycles

Each dream run produces a dream cycle record with:

Status: pending, running, completed, or failed
Trigger: idle (automatic) or manual (operator-triggered)
Result: counts for decayed, pruned, promoted, deduped, consolidated entries plus reflection titles and duration

Dream cycles are viewable in the memory UI and queryable via the API.

API

Method	Endpoint	Description
`GET`	`/api/memory/dream`	List dream cycles (filter by `agentId`, `limit`)
`POST`	`/api/memory/dream`	Trigger a manual dream cycle (`{ "agentId": "..." }`)
`GET`	`/api/memory/dream/:id`	Get a specific dream cycle
`GET`	`/api/agents/:id/dream`	Get agent's dream config and recent cycles
`PATCH`	`/api/agents/:id/dream`	Update agent's dream config

CLI

# List recent dream cycles
swarmclaw memory dream

# List dream cycles for a specific agent
swarmclaw memory dream --query agentId=<agent-id>

# Trigger a dream cycle
swarmclaw memory dream-trigger --data '{"agentId":"<agent-id>"}'

# Get a specific dream cycle
swarmclaw memory dream-get <cycle-id>

Relationship to Memory Consolidation

Dreaming extends the existing memory consolidation system:

Daily digests (existing) summarize the last 24 hours of memories per agent
Access-based compaction (existing) promotes and archives memories based on access patterns
Dreaming (new) adds configurable per-agent decay/prune thresholds and LLM-driven reflection

All three systems use the idle-window scheduler and run independently without interference.