Hermes Dreaming

Background memory consolidation for Hermes. Curates scarce durable memory through a three-phase Light → Deep → REM cycle — promoting very little, replacing what is superseded, and keeping MEMORY.md compact, current, and high-signal.

Get Started GitHub ↗

Phase 1

Light

Scans recent sessions. Extracts candidate facts and preferences. No durable writes.

Phase 2

Deep

Reflects on patterns. Detects contradictions and superseded entries.

Phase 3

REM

Scores candidates. Applies at most a few high-confidence memory operations.

💡

Core principle: Hermes durable memory is prompt-visible and scarce. A successful Dreaming run may produce zero durable writes. The goal is highest future usefulness per character — not more memories.

Installation

Install Hermes Dreaming into the same Python environment that runs Hermes, then enable the plugin in your Hermes config.

Install

Use the Hermes plugin manager — it handles cloning, environment setup, and enabling automatically:

bash

hermes plugins install alejandroiglesias/hermes-dreaming

To update later:

bash

hermes plugins update hermes-dreaming

Enable the plugin

Add Hermes Dreaming to ~/.hermes/config.yaml:

yaml

plugins:
  enabled:
    - hermes-dreaming

Verify

From the terminal:

bash

hermes dreaming status

Or from within a Hermes session:

hermes

/dreaming status

Commands

Hermes Dreaming exposes commands as Hermes slash commands (for use within sessions) and as CLI subcommands.

Slash Commands

/dreaming run

Full dreaming cycle (Light → Deep → REM). Applies memory changes. Mirrors scheduled behaviour.

/dreaming review

Dry-run mode. Stages candidates, scores them, and proposes operations — but does not mutate MEMORY.md or USER.md.

/dreaming status

Shows last run, staged candidate count, last memory changes, current memory usage, and any errors.

/dreaming compact

Cleanup pass: detects duplicates, contradictions, and superseded entries — without a full Light → Deep scan.

CLI Commands

bash

hermes dreaming run           # full cycle
hermes dreaming review        # dry-run
hermes dreaming status        # show state
hermes dreaming compact       # cleanup pass
hermes dreaming install-cron  # register nightly 03:00 cron job

install-cron options

bash

hermes dreaming install-cron --schedule "0 3 * * *"

Configuration

Add a dreaming block to ~/.hermes/config.yaml. All fields are optional — defaults are conservative.

yaml

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

enabled default: true

Whether the plugin is active. Set to false to disable without uninstalling.

schedule default: "0 3 * * *"

Cron expression for the nightly scheduled run. Defaults to 03:00 every day. No idle napping — runs are predictable and auditable.

max_changes_per_run default: 3

Hard limit on durable memory mutations per run (additions + replacements + removals). When candidates exceed this limit, priority is: replace contradictions → merge duplicates → add one exceptional memory.

recent_sessions_limit default: 14

How many recent Hermes sessions the Light phase scans for candidates.

How It Works

Each dreaming run executes three cooperative phases. Only the REM phase can mutate durable memory.

sessions

→

Light

→

Deep

→

REM

→

MEMORY.md

Phase 1 — Light Sleep

Cheap and conservative. Scans recent sessions and extracts compact candidate signals. Never writes durable memory.

Reads the most recent sessions from the Hermes session DB (up to recent_sessions_limit)
Extracts candidates: preferences, corrections, project facts, recurring workflows, supersession signals
Deduplicates obvious repeats and records source session IDs
Writes staged candidates to candidates.jsonl

Candidate types:

Type	Description
`user_preference`	A stable preference about tools, workflows, or approaches
`communication_preference`	How the user prefers to receive information
`project_fact`	A stable fact about a project or environment
`decision`	A decision the user has made
`correction`	User corrected the assistant — strong signal
`recurring_workflow`	A workflow appearing repeatedly across sessions
`supersession_signal`	Evidence that an existing memory may be outdated
`stale_signal`	Evidence that an existing memory is no longer relevant
`skill_candidate`	Something better represented as a skill than memory

Phase 2 — Deep Sleep

Reflects on staged candidates against existing durable memory. Does not write memory.

Identifies recurring themes and detects contradictions
Identifies superseded memories (older entries overridden by newer statements)
Distinguishes durable preferences from session-specific details
Flags candidates better suited to skills than durable memory
Suggests canonical phrasings for potential merged entries

Phase 3 — REM Sleep

The only phase allowed to mutate durable memory. Applies at most max_changes_per_run high-confidence operations, in preference order:

no-op

Memory unchanged when no candidate clears score thresholds.

replace

Replaces a superseded entry with a more current or compact version. Score ≥ 0.80, supersession confidence ≥ 0.75.

remove

Removes an entry that is clearly obsolete, false, or superseded. Confidence ≥ 0.85.

add

Adds a new entry only when the candidate would improve almost every future session. Score ≥ 0.88.

⚠️

Before any mutation, timestamped backups of MEMORY.md and USER.md are created at ~/.hermes/dreaming/backups/. All operations are logged to DREAMS.md.

Scoring Model

The REM phase scores each candidate using a weighted model. The agent computes scores via LLM judgment; this module defines the threshold values enforced as hard gates.

formula

score =
  future_usefulness    # will this improve future answers often?
+ query_diversity      # how many different types of future tasks benefit?
+ stability            # is it likely to remain true?
+ recurrence           # has it appeared across multiple sessions?
+ recency              # how recently did this signal appear?
+ explicitness         # did the user state it directly?
+ correction_signal    # did the user correct the assistant?
+ actionability        # will this change what the assistant says or does?
+ compression_value    # does this compactly summarize many observations?
− character_cost       # how much prompt budget will it consume?
− duplication          # is it already covered?
− volatility           # is it likely to change soon?
− sensitivity          # does it involve sensitive attributes?

Dimensions

future_usefulness

Will this improve future answers often? The primary metric.

query_diversity

How many different types of future tasks benefit? Breadth, not just frequency.

stability

Is it likely to remain true for months?

recurrence

Has it appeared across multiple sessions?

recency

How recently did this signal appear? Recent patterns outweigh old unreinforced ones.

explicitness

1.0 = user stated it directly; 0.0 = inferred.

correction_signal

User corrected the assistant — strong signal.

actionability

Will knowing this change what the assistant says or does? Pure context that alters no response is low-value.

compression_value

Compactly summarizes many observations.

character_cost

Characters consumed from the scarce prompt budget.

duplication

Already covered by an existing memory entry.

volatility

Likely to change or become outdated quickly.

sensitivity

Involves sensitive personal attributes.

Thresholds

Operation	Threshold	Additional requirement
`add`	score ≥ 0.88	—
`replace`	score ≥ 0.80	supersession confidence ≥ 0.75
`remove`	confidence ≥ 0.85	—
`merge`	overlap ≥ 0.80	merged entry is shorter or clearer

Run-level limits

Limit	Default	Description
`max_changes_per_run`	3	Total durable mutations per run
`max_adds_per_run`	1	Add operations are rate-limited extra strictly
`max_new_chars_per_run`	250	Net characters added to memory per run

State Files

All runtime state lives under ~/.hermes/dreaming/. The JSONL files are machine-readable sidecars and are not injected into the prompt.

~/.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 (incl. rejections) ├── promotions.jsonl # applied memory operations ├── runs/ # per-run JSON records │ └── YYYY-MM-DDTHH-mm-ss.json └── backups/ # timestamped MEMORY.md / USER.md snapshots └── 2026-05-01T03-00-00/ ├── MEMORY.md └── USER.md

DREAMS.md

The human-readable audit diary. Records every run — what was scanned, proposed, applied, and rejected. Not used as a promotion source.

markdown

## 2026-05-01 03:00 — Nightly Dream

### Light Sleep
- Scanned 14 recent sessions.
- Staged 12 candidates. Deduped 4 repeats.

### REM Sleep
Memory operations:
1. REPLACE user memory
   Old: Ale prefers long explanatory answers by default.
   New: Ale prefers concise answers first, with detail added when useful.
   Reason: newer explicit preference supersedes older style guidance.

Summary: 2 durable memory changes applied. 10 candidates rejected.

Design Philosophy

Hermes Dreaming treats durable memory as scarce prompt budget: each run consolidates recent session traces into a few compact, high-signal memories, or deliberately writes nothing.

📌

Hermes durable memory is premium memory.
Every character has a permanent prompt cost.
Dreaming must maximise future usefulness per character.

What it is

A general Hermes plugin — not a memory provider
A scheduled and manual memory consolidation process
A curatorial layer over Hermes' existing built-in memory
A tool for keeping MEMORY.md / USER.md compact, current, and high-signal

What it is not

Not a replacement for Hermes' memory provider system
Not a vector database or temporal knowledge graph
Not a replacement for Honcho, Hindsight, Supermemory, etc.
Not a nightly memory-append process
Not dependent on any external infrastructure

Good vs bad durable memory

❌ Reject	✓ Promote
Ale discussed whether Dreaming should have review or auto mode.	Ale prefers simple, packaged, low-maintenance tools over custom infrastructure.
Ale asked about idle naps and decided not to implement them.	Ale is cost-sensitive about background tasks; prefers scheduled over idle LLM activity.

Compatibility with memory providers

Hermes Dreaming coexists with any external memory provider. The intended layering:

Provider (Honcho, Hindsight, etc.) — broader long-term memory
MEMORY.md / USER.md — always-prompt-visible premium memory
Dreaming — curator of premium memory

📖

See the full implementation brief for the complete design specification.

Contributing

Hermes Dreaming is open source under the MIT license. Contributions, bug reports, and feature requests are welcome.

Bug reports & feature requests

Please open an issue on GitHub:

Report a bug ↗ Request a feature ↗

Contributing code

Fork the repository on GitHub
Create a branch for your change
Run the test suite: pytest tests/
Open a pull request against main

Security vulnerabilities

Do not open a public issue. See the Security Policy for responsible disclosure instructions.