Metadata-Version: 2.4
Name: hermes-dreaming
Version: 0.3.0
Summary: Background memory consolidation plugin for Hermes
License-Expression: MIT
Project-URL: Homepage, https://github.com/alejandroiglesias/hermes-dreaming
Project-URL: Repository, https://github.com/alejandroiglesias/hermes-dreaming
Project-URL: Documentation, https://alejandroiglesias.github.io/hermes-dreaming/
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: filelock>=3.13
Requires-Dist: PyYAML>=6.0
Dynamic: license-file

# hermes-dreaming

A background memory consolidation plugin for [Hermes](https://hermes-agent.nousresearch.com), 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

```bash
pip install hermes-dreaming
```

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

```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:

```bash
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

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

## Design

See [docs/implementation-brief.md](docs/implementation-brief.md) for the full design brief.
