hermes-dreaming

A background memory consolidation plugin for Hermes, built around Hermes' small, always-prompt-visible memory model.

What it does

Hermes durable memory (MEMORY.md ≈2,200 chars, USER.md ≈1,375 chars) is scarce and injected into every session prompt. hermes-dreaming runs a periodic three-phase consolidation cycle:

• Light — scans recent sessions for candidate facts/preferences
• Deep — identifies patterns, contradictions, supersessions
• REM — scores candidates and applies at most a few high-confidence memory operations (add, replace, remove)

A successful run may produce zero durable writes. The goal is highest future usefulness per character, not more memories.

Note: memory mutations take effect on the next session start (Hermes loads memory as a frozen snapshot at session init).

Install

pip install hermes-dreaming

Then enable in ~/.hermes/config.yaml:

plugins:
  enabled:
    - hermes-dreaming

Commands

/dreaming run       — full cycle (schedules + manual)
/dreaming review    — dry-run; proposes ops without mutating memory
/dreaming status    — last run, candidate counts, memory usage
/dreaming compact   — merge duplicates + remove obsolete; no new adds

CLI equivalents:

hermes dreaming run
hermes dreaming review
hermes dreaming status
hermes dreaming compact
hermes dreaming install-cron   # register nightly 03:00 cron job

State files

All runtime state lives in ~/.hermes/dreaming/:

~/.hermes/dreaming/
├── DREAMS.md           # human-readable audit diary
├── state.json          # last run metadata
├── candidates.jsonl    # staged Light-phase candidates
├── decisions.jsonl     # all Deep/REM decisions (including rejections)
├── promotions.jsonl    # applied memory operations (includes sidecar metadata)
├── runs/               # per-run JSON records
└── backups/            # timestamped MEMORY.md / USER.md snapshots

Configuration

dreaming:
  enabled: true
  schedule: "0 3 * * *"
  max_changes_per_run: 3

Design

See docs/implementation-brief.md for the full design brief.