feat(memory): add Auto Dream — REM-style consolidation cycle

[izo]

Summary

Quatrième mode de la boucle mémoire ulk : lovecraft memory dream — cycle de consolidation inspiré du sommeil REM, analogue à la feature Auto Dream d'Anthropic (Claude Code v2.1.83+, server feature flag) et inspiré du papier Sleep-time Compute (UC Berkeley).

Capture écrit, dream nettoie. Le mode merge les doublons (similarité ≥ 0.85), normalise les horodatages relatifs en dates absolues, archive les obsolètes (>90j + non référencées), promeut les patterns récurrents en règles et reconstruit docs/_memory/00-MOC.md. Strictement transformatif — aucune création d'entrée (rôle de capture).

Pourquoi c'est important pour les 85 agents ulk

Le vault docs/_memory/ est partagé par les agents et projeté dans CLAUDE.md à chaque session via distribute. Sans nettoyage périodique, le bruit / contradictions / horodatages périmés s'amplifient en cascade : chaque entrée pourrie devient un faux signal pour Claude à chaque session, et 85 agents lisent du contenu désuet. Dream coupe la chaîne d'erreur à la source, sans intervention humaine.

Garde-fous

• Sandbox d'écriture stricte (permissions: scoped-write + post-flight diff 🚨 SCOPE VIOLATION) — écriture autorisée UNIQUEMENT dans docs/_memory/**, .claude/memory-archive/**, .claude/state/auto-dream.json, .ulk-reports/auto-dream-*.json, bloc <!-- vault:begin --> de CLAUDE.md. Jamais code source / tests / config / specs.
• Lock file (flock -n ou mkdir atomique en fallback) pour gérer les instances Claude Code concurrentes sur le même projet, TTL 30 min pour dead-lock cleanup.
• Background non-bloquant via & disown — la session courante n'est jamais ralentie ; 0 token côté hook (le check est pur shell).
• Indépendance vis-à-vis du feature flag Anthropic — l'implémentation est côté projet sur le vault projet, ne dépend d'aucun toggle serveur.

Déclenchement

Mode	Conditions
Auto (hook SessionStart)	24h écoulées ET ≥ 5 sessions depuis le dernier dream
Manuel	lovecraft memory dream
Force	lovecraft memory dream --force (ignore conditions)
Dry-run	lovecraft memory dream --dry-run
Naturel	« consolidate my memory files »

Seuils configurables via AUTO_DREAM_MIN_HOURS / AUTO_DREAM_MIN_SESSIONS.

Fichiers

Ajoutés

• framework/agents/_shared/auto-dream-protocol.md — spec canonique (D1-D8 pipeline, sandbox, lock, intégration agents)
• framework/tools/hooks/auto-dream.sh — trigger script (state, lock, gating, sous-commandes tick|status|force|reset)
• .claude/hooks-examples/auto-dream.json — recette hook SessionStart

Modifiés

• framework/agents/orchestrators/47-lovecraft.md — nouveau mode dream + frontmatter permissions: scoped-write
• framework/agents/_shared/memory-protocol.md — référence dream + alerte gandalf si state stale
• framework/cli/internal/installer/catalog.go — flag --with-auto-dream
• CLAUDE.md — section dédiée Auto Dream + 6 raisons « pourquoi c'est bien pour les agents »
• .claude/rules/install-reference.md — ligne d'option
• framework/agents/registry.json — régénéré

Activation

./install.sh --with-auto-dream
# puis merge manuel du bloc `hooks` dans ~/.claude/settings.json
# (settings jamais modifiés automatiquement, par design)
~/.claude/hooks/auto-dream.sh status   # voir l'état courant

Test plan

• Spec markdown lisible et complète (auto-dream-protocol.md)
• Script shell : bash -n OK, chmod +x, smoke test tick / status / sandbox state file
• Hook JSON valide (python3 -c "json.load(...)")
• Go CLI compile (go build ./...)
• Go installer tests passent (go test ./internal/installer/...)
• Registry régénéré, dream apparaît dans la description lovecraft
• 610/610 golden tests passent (node --test framework/tests/agents-golden.test.mjs)
• À tester en condition réelle après merge : ./install.sh --with-auto-dream sur projet vide → vérifier copie auto-dream.sh dans ~/.claude/hooks/ et auto-dream.json dans ~/.claude/hooks-examples/
• À tester : invocation manuelle lovecraft memory dream --dry-run sur un vault peuplé

https://claude.ai/code/session_01KWPifuDpUp8wxhaqh7ZT93

---

Generated by Claude Code

Summary by CodeRabbit

• New Features

  • Added Auto Dream: an automated memory consolidation system that deduplicates entries, normalizes timestamps, archives obsolete items, and reconstructs memory indexes. Activates automatically based on time and session thresholds or via manual command.

• Documentation

  • Added documentation for memory consolidation protocols and workflows.

• Chores

  • Auto Dream now available as an optional installation feature.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 09c49b35-20f8-4b9a-a6c4-37619819eeee

📥 Commits

Reviewing files that changed from the base of the PR and between f5812a4 and 8dcfb68.

📒 Files selected for processing (9)

• .claude/hooks-examples/auto-dream.json
• .claude/rules/install-reference.md
• CLAUDE.md
• framework/agents/_shared/auto-dream-protocol.md
• framework/agents/_shared/memory-protocol.md
• framework/agents/orchestrators/47-lovecraft.md
• framework/agents/registry.json
• framework/cli/internal/installer/catalog.go
• framework/tools/hooks/auto-dream.sh

---

📝 Walkthrough

Walkthrough

This PR introduces Auto Dream, a background memory consolidation feature for the lovecraft agent. It comprises a bash hook script managing state and concurrency, hook configuration, installer integration, and comprehensive protocol/orchestration documentation. Triggered automatically by session/time thresholds via SessionStart hook or manually via CLI flags.

Changes

Auto Dream Memory Consolidation

Layer / File(s)	Summary
Configuration & Installation .claude/hooks-examples/auto-dream.json, framework/agents/registry.json, framework/cli/internal/installer/catalog.go	Hook configuration defines SessionStart trigger for auto-dream.sh tick with 24h/5-session thresholds. Installer catalog registers auto-dream hook module with --with-auto-dream flag. Agent registry updated to list dream in memory loop sequence.
Hook Script Implementation framework/tools/hooks/auto-dream.sh	New 274-line bash script managing auto-dream state and triggering. Supports tick (increment sessions, spawn if conditions met), force (immediate spawn), status (report state/conditions), and reset (record cycle) commands. Handles concurrency via flock/mkdir-based locking with stale-lock cleanup. Maintains JSON state tracking session count, last run time, and cycle counters.
Auto Dream Protocol Specification framework/agents/_shared/auto-dream-protocol.md	New 251-line protocol documentation detailing REM-inspired consolidation pipeline: duplicate merging, timestamp normalization, obsolete archival, MOC reconstruction, and JSON report generation. Specifies trigger conditions, scoped write sandbox enforcement, lock file behavior, non-blocking background execution, and explicit prohibition on creating new entries.
Orchestration & Integration framework/agents/orchestrators/47-lovecraft.md, framework/agents/_shared/memory-protocol.md	Lovecraft orchestrator defines memory.dream mode with auto-trigger gating (24h + 5-session cooldown unless --force), vault scanning, inconsistency detection matrix, and JSON report schema. Updates permissions_scope and extends list. Memory protocol documents dream step in REM-style consolidation cycle and adds gandalf health check for stale auto-dream runs.
User Documentation CLAUDE.md, .claude/rules/install-reference.md	Expands lovecraft memory subcommands from three to four, adding dream. Defines Auto Dream spec with trigger conditions, manual CLI flags (--force, --dry-run), sandbox constraints, and non-blocking execution. Install reference documents --with-auto-dream flag and links to auto-dream-protocol.

Sequence Diagram(s)

sequenceDiagram
  participant SessionStart as SessionStart Hook
  participant TickScript as auto-dream.sh tick
  participant StateFile as .claude/state/auto-dream.json
  participant Lock as Lock File
  participant Dream as lovecraft memory dream
  
  SessionStart->>TickScript: invoke (background)
  TickScript->>StateFile: read current state
  TickScript->>TickScript: increment sessions_since_last_dream
  TickScript->>Lock: attempt acquire (flock or mkdir)
  alt conditions_met (time & session thresholds)
    TickScript->>Dream: spawn background process (nohup)
    Dream->>Dream: scan & consolidate memory
    Dream->>StateFile: write JSON report
    TickScript->>Lock: release
  else conditions_not_met
    TickScript->>Lock: release
  end

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• izo/Ulk#66: Memory-vault loop feature implementation with overlapping hook configuration, protocol documentation, and CLI integration.

Poem

🐰 A dreaming rabbit tends the vault with care,
Merging duplicates floating in the air.
Sessions tick like heartbeats, rhythms rise,
Auto-consolidation—a memory paradise!
Background whispers normalize the past,
While REM-sleep loops make memories last. ✨

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/auto-dream-memory-TMgkl

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 golangci-lint (2.12.1)

level=error msg="[linters_context] typechecking error: pattern ./...: directory prefix . does not contain main module or its selected dependencies"

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}