Dream Consolidation

Dream consolidation is AGH's memory cleanup loop. It starts a one-shot dream session that reviews recent session history and existing memory files, then tightens the persistent memory store.

The goal is not to archive everything. The goal is to keep future sessions useful:

merge duplicate memories
prune stale or low-signal notes
update MEMORY.md indexes
preserve durable decisions, preferences, feedback, and references

What Triggers A Dream

Dream consolidation is enabled by default when memory is enabled.

AGH evaluates dream gates from two paths:

Trigger path	What happens
Background ticker	The daemon checks on `memory.dream.check_interval`, which defaults to 30 minutes.
Session stop hook	When a non-dream session stops and has a workspace ID, AGH queues a dream check for that workspace.
Manual command	`agh memory consolidate` asks the daemon to run a gated consolidation pass for the current working directory.
HTTP or UDS API	`POST /api/memory/consolidate` optionally targets a supplied workspace.

Manual consolidation still respects the gates. If the gates are not satisfied, the response is successful but says consolidation was not triggered.

Gate Conditions

AGH checks gates in this order:

Gate	Default	Behavior
Time gate	24 hours	Passes when no consolidation lock exists, or when the lock mtime is at least `memory.dream.min_hours` old.
Session gate	3 completed sessions	Passes when at least `memory.dream.min_sessions` completed sessions exist since the last consolidation timestamp.
Lock gate	one active runner	Passes only when AGH can acquire `.consolidate-lock`.

The lock file lives in the global memory directory:

~/.agh/memory/.consolidate-lock

While a dream is running, the lock contains the daemon process ID. After a successful run, AGH clears the lock body and leaves the lock mtime as the last successful consolidation timestamp. If the run fails before completion, AGH rolls the timestamp back.

A lock can be reclaimed when its process is gone or the lock is older than one hour.

Dream Session Lifecycle

Rendering diagram...

Dream consolidation uses a normal AGH session type, so its work is observable and stops through the same lifecycle as other sessions.

Dream sessions are ordinary persisted AGH sessions with type dream. They are special in two ways:

AGH always starts them with approve-all permissions.
The session prompt is the embedded four-phase consolidation guide.

The dream agent is configured by memory.dream.agent, which defaults to general.

The Four Phases

The embedded consolidation prompt tells the dream agent to work in four phases.

Phase	What the dream agent does
Orient	Read global and workspace `MEMORY.md` indexes first. Read relevant memory files before changing them. Keep the four-type taxonomy intact.
Gather	Review recent completed session artifacts, especially event databases for sessions completed since the last consolidation. Extract durable signal and ignore transient tool noise.
Consolidate	Merge new signal into focused memory files. Prefer updating existing files over creating near-duplicates. Convert relative dates to absolute dates.
Prune	Remove duplicate, obsolete, or low-signal content. Rebuild or tighten indexes so they remain concise and discoverable.

The prompt also tells the dream agent not to store secrets, speculative ideas without evidence, or temporary execution steps.

Workspace Selection

When a dream run receives an explicit workspace, AGH resolves that workspace and runs one dream session for it.

When a background ticker run has no explicit workspace, AGH chooses workspaces from recent non-dream sessions since the last consolidation. It sorts them by most recently updated session and runs a dream session per eligible workspace.

If no recent workspace can be found, the background run logs the problem and does not mutate memory.

Configuration

Default dream configuration:

[memory.dream]
enabled = true
agent = "general"
min_hours = 24
min_sessions = 3
check_interval = "30m"

Rules:

Field	Meaning	Validation when enabled
`enabled`	Turns dream consolidation on or off.	none
`agent`	Agent name used for dream sessions.	Required and non-empty.
`min_hours`	Minimum hours between successful runs.	Must be positive.
`min_sessions`	Minimum completed sessions since last run.	Must be positive.
`check_interval`	Background ticker interval.	Must be positive.

Disable only dream consolidation:

[memory]
enabled = true

[memory.dream]
enabled = false

This keeps memory files and prompt injection active, but stops background and manual dream runs from starting.

Manual Consolidation

Run a gated consolidation check for the current workspace:

agh memory consolidate

Call the API directly:

curl -X POST http://localhost:2123/api/memory/consolidate \
  -H "Content-Type: application/json" \
  -d '{"workspace":"/absolute/path/to/repo"}'

Possible outcomes:

Outcome	Meaning
`triggered: true`	A dream session was started and completed without reported prompt errors.
`triggered: false`, gates not satisfied	The time or session threshold has not been reached.
`triggered: false`, disabled	Memory dream consolidation is disabled or not wired.
`triggered: false`, already running	Another consolidation run holds the lock.
error response	Workspace resolution, session creation, dream prompt, or lock handling failed.

What Dream Does Not Do

Dream consolidation is not a per-turn extractor. AGH does not silently summarize every prompt into memory while a session runs. Agents write explicit memory files through agh memory write, and the dream pass later compresses and organizes that material with recent session history.

Dream also does not bypass the file format. Memory remains Markdown with YAML frontmatter, and MEMORY.md remains the discoverability layer injected into the next startup prompt.

Memory System explains memory files and indexes.
Global vs Workspace Memory explains storage and resolution rules.
Session Lifecycle documents the dream session type.
Memory Consolidate CLI shows generated command reference.

On this page