AutoDream memory consolidation

How Claurst’s background memory consolidation engine synthesizes session learnings into durable, organized memories.

AutoDream is Claurst’s background memory consolidation engine. It runs as a forked subagent — separate from your active session — and synthesizes recent learnings into durable, well-organized memory files so that future sessions can orient quickly.

The name is intentional. The process mirrors how biological memory consolidation happens during sleep: raw experience is transformed into structured, long-term knowledge.

“You are performing a dream — a reflective pass over your memory files. Synthesize what you’ve learned recently into durable, well-organized memories so that future sessions can orient quickly.”

Memory directory

All memories live in ~/.claude/memory/. The directory structure is:

~/.claude/memory/
├── MEMORY.md              # entrypoint index, always loaded (max 200 lines / ~25KB)
├── <topic-file>.md        # individual topic memory files with YAML frontmatter
└── logs/                  # KAIROS mode: append-only daily logs
    └── YYYY/MM/YYYY-MM-DD.md

Each topic file carries YAML frontmatter with name, description, and type fields. The description is used to decide relevance — a future session’s memory selector reads these descriptions to choose which files to inject.

The three-gate trigger

AutoDream does not run on every session exit. It requires all three gates to pass simultaneously:

The dream only runs when all three gates pass. This prevents both over-consolidation (wasteful API calls) and under-consolidation (stale memories building up).

Gate	Condition
Time gate	At least 24 hours have passed since the last dream
Session gate	At least 5 sessions have occurred since the last dream
Lock gate	A consolidation lock can be acquired (prevents concurrent dreams)

The lock gate ensures that multiple Claurst instances running simultaneously don’t trigger competing dream passes that overwrite each other’s work.

The four dream phases

1. Orient

   The dream subagent runs ls on the memory directory, reads MEMORY.md, and skims the headers of existing topic files. This gives it a map of what is already known before looking at new information.

2. Gather recent signal

   The subagent searches for new information worth persisting. It checks sources in priority order:

   1. Daily logs — KAIROS mode append-only log files in logs/YYYY/MM/
   2. Drifted memories — existing memory files that may contain outdated claims
   3. Transcript search — recent session transcripts for learnings not yet captured
3. Consolidate

   The subagent writes or updates memory files based on gathered signal:

   • New facts get new topic files with proper frontmatter
   • Existing files get updated with new findings merged in
   • Relative dates (e.g., “yesterday”, “last week”) are converted to absolute dates
   • Facts that contradict more recent information are deleted
4. Prune and index

   The subagent enforces the index limits and cleans up stale pointers:

   • MEMORY.md is kept under 200 lines AND ~25KB
   • Topic files with stale pointers to deleted content are cleaned up
   • Contradictions between files are resolved, keeping the more recent claim

Read-only bash access

The dream subagent has read-only bash access. It can observe your project — list files, read source code, search for patterns — but it cannot modify any project files. The dream pass is purely a memory consolidation operation; it has no ability to make changes to your codebase.

This restriction is intentional: a background process running without your supervision should never be able to alter your work.

Managing memories with /memory

Use the /memory slash command to inspect and manage your memories interactively:

/memory                   # Show current MEMORY.md contents
/memory list              # List all memory files with descriptions
/memory edit <file>       # Open a specific memory file for editing

You can also manually trigger a memory write using the /remember skill:

/remember The project uses a custom retry interceptor in src/api/retry.rs

Memory freshness

Memory files include an mtime timestamp. When a memory file is older than 1 day, Claurst injects a staleness warning alongside the content:

This memory is N days old. Memories are point-in-time observations, not live state —
claims about code behavior or file:line citations may be outdated.
Verify against current code before asserting as fact.

This prevents stale architectural notes from being presented as ground truth in sessions far removed from when they were written.

Do not store code patterns, file structure, or git history in memory files. These are derivable by reading the code directly and will become stale quickly. Memory is best used for non-derivable information: team conventions, architectural decisions, ongoing work context, and external system references.