Hermes Dreaming

What It Does

Hermes Dreaming is a staged self-improvement engine for Hermes Agent. When the agent is idle (or on a cron schedule), it scans source files for DREAM: markers, proposes changes to memory, user preferences, skills, and facts, stages those proposals as reviewable artifacts, and only writes to live state after an explicit apply step with human approval. The system operates locally with no required cloud API, though an optional OpenAI-compatible provider is available for LLM-driven analysis. It ships as both a standalone Python CLI and a Hermes plugin with a bundled SKILL.md.

The Good

The artifact pipeline is thoughtfully designed. Every proposed change goes through a four-stage gate: create (scan sources), validate (check safety rules), diff (human review), and apply (explicit approval). Artifacts are stored as simple directory structures (manifest.json, REPORT.md, sources.jsonl, proposals.jsonl) that are easy to inspect in a terminal or diff in git. The separation between live root, artifact root, and backup root prevents accidental corruption of production state.

Safety mechanisms go beyond what you would expect at v0.1. The validation layer detects secrets in proposals (regex patterns for API keys, tokens, hex strings), blocks path traversal attacks (rejects .. and absolute paths in target paths), enforces character limits on memory files, and requires provenance tracking for every proposal. The scoring module defines explicit thresholds per operation type: add requires score 0.88, replace requires 0.80 with supersession confidence 0.75, remove requires confidence 0.85. Run-level limits cap changes at 3 per run, 1 add per run, and 250 new characters per run. These are sensible defaults that prevent runaway self-modification.

The codebase is clean and well-structured for a two-day-old project. 3,985 lines across 14 source modules and 14 test files. The module boundaries are clear: cli.py handles parsing, providers.py handles source analysis, memory_io.py handles file reads/writes, scoring.py defines thresholds, validation.py enforces rules, apply.py handles mutations. Atomic writes via tempfile + os.replace prevent partial writes. The 63-line SKILL.md is concise and actionable without padding.

Documentation is unusually thorough for a young project. README.md covers install, CLI usage, dream markers, and artifact layout. CONTRIBUTING.md defines repo rules and a pre-merge checklist. CHANGELOG.md tracks releases. SECURITY.md covers vulnerability reporting. CODE_OF_CONDUCT.md is present. The specs/ directory contains the implementation plan. The reviews/ directory contains QA pass notes. This is a level of process documentation rarely seen at 30 stars.

The Hermes plugin integration is first-class. The plugin.yaml manifest, hermes plugins install support, the bundled SKILL.md, and the dreaming update command for safe self-updates show the author understands the Hermes ecosystem. The install-cron command for scheduling nightly reviews is a practical touch.

The Bad

The offline provider is limited to static DREAM: marker parsing. Without configuring an external LLM provider, the system can only extract explicit DREAM: memory: ... lines from source files. It cannot analyze agent session history, conversation logs, or behavioral patterns to propose improvements autonomously. The session_reader module exists but is not wired into the default provider flow. The "dreaming" metaphor (agents proposing improvements while idle) is compelling, but the current implementation requires a human to write the DREAM: markers by hand, which is closer to a structured editing workflow than autonomous self-improvement.

One test fails on macOS due to case-sensitivity assumptions. test_read_prefers_uppercase_live_file fails because macOS filesystems are case-insensitive by default: creating both memory.md and MEMORY.md resolves to the same file. The test expects the uppercase file to be found first, but the filesystem returns the lowercase path. This is a platform portability bug that will affect every macOS user running the test suite (53/54 pass).

Python 3.11+ requirement adds friction. The pyproject.toml declares requires-python = ">=3.11". macOS ships Python 3.9. Users need to install a newer Python before they can use the tool. The README does not mention this requirement prominently; it only surfaces if you read pyproject.toml or get an install error.

The project is two days old with a single commit. The entire git history is one commit (b28b2d5). There is no evidence of iterative development, issue tracking history, or community contributions. The 30-star count reflects interest in the concept rather than proven production use.

No published package on PyPI. Installation requires either the Hermes plugin path or a local pip install -e . from a cloned repo. There is no pip install hermes-dreaming option, which adds setup friction for non-Hermes users.

Smoke Test Results

Testing on macOS (aarch64) with Python 3.11 venv. Full CLI cycle verified with real DREAM: markers.

Run A: CLI smoke test

$ python3.11 -m venv /tmp/hermes-dreaming-venv
$ /tmp/hermes-dreaming-venv/bin/pip install -e ".[dev]" -q
✅ install succeeded

$ /tmp/hermes-dreaming-venv/bin/dreaming --help
usage: dreaming [-h] {create,review,diff,validate,apply,discard,compact,install-cron,status,update} ...
✅ CLI entry point works

$ /tmp/hermes-dreaming-venv/bin/dreaming review --live-root /tmp/test/live --artifact-root /tmp/test/artifacts --source /tmp/test/sources/notes.md
artifact: /tmp/test/artifacts/20260527T090303Z-6a0734d0
status: staged
proposals: 3
mode: dry-run
validation: valid
✅ review created 3 proposals from DREAM: markers

$ /tmp/hermes-dreaming-venv/bin/dreaming diff /tmp/test/artifacts/20260527T090303Z-6a0734d0
(proposals for fact, memory, skill targets)
✅ diff shows human-readable report

$ /tmp/hermes-dreaming-venv/bin/dreaming validate /tmp/test/artifacts/20260527T090303Z-6a0734d0 --live-root /tmp/test/live
artifact is valid
✅ validation passes

$ /tmp/hermes-dreaming-venv/bin/dreaming apply /tmp/test/artifacts/20260527T090303Z-6a0734d0 --live-root /tmp/test/live --backup-root /tmp/test/backups --approve all
applied artifact: 20260527T090303Z-6a0734d0
status: applied
✅ apply wrote changes to live files

$ cat /tmp/test/live/memory.md
- Existing memory entry one.
- Existing memory entry two.

- Keep updates short and concrete.
✅ memory.md updated with new entry

$ cat /tmp/test/live/facts.jsonl
{"key": "tone", "type": "preference", "value": "casual"}
✅ facts.jsonl created with parsed JSON

$ cat /tmp/test/backups/memory.md
- Existing memory entry one.
- Existing memory entry two.
✅ backup preserved original content

Pass rate: 8 of 8. Full artifact lifecycle works end to end.

Run B: Test suite

$ /tmp/hermes-dreaming-venv/bin/python -m pytest tests/ -q
........F.....................................
1 failed, 53 passed in 1.06s

Pass rate: 53 of 54. The single failure is test_read_prefers_uppercase_live_file, a macOS case-sensitivity issue in the memory_io module.

Run C: Functional verification

The apply step was verified by checking actual file contents after the operation:

• memory.md gained a new bullet entry matching the DREAM: marker
• facts.jsonl was created with valid JSON from the fact marker
• skills/review.md was created with the skill marker content
• backups/memory.md contains the original content before mutation
• The artifact status changed from "staged" to "applied"

Functional pass rate: 4 of 4. All claim verifications passed.

What the runs tell you

The CLI is functional and the artifact pipeline works as documented. The test suite is solid with one platform-specific failure. The main gap is not in the code quality but in the default provider scope: without an LLM provider, the system parses static markers rather than autonomously proposing improvements. The safety infrastructure (score gating, run limits, secret detection, atomic writes, backups) is production-ready even if the autonomous analysis layer is not yet.

Setup Walkthrough

1. Install Python 3.11+ if needed: brew install python@3.11
2. Clone and install: git clone https://github.com/asimons81/hermes-dreaming.git && cd hermes-dreaming && python3.11 -m venv .venv && .venv/bin/pip install -e ".[dev]"
3. Verify: .venv/bin/dreaming --help
4. For Hermes plugin users: hermes plugins install asimons81/hermes-dreaming --enable
5. Create source files with DREAM: markers (see README for format)
6. Run: dreaming review --live-root ./live --artifact-root ./artifacts --source ./sources
7. Inspect: dreaming diff ./artifacts/
8. Apply: dreaming apply ./artifacts/ --live-root ./live --backup-root ./backups --approve all

Post-install gotcha: the default offline provider only reads DREAM: markers from files you point it at. For autonomous "dreaming" (analyzing session history without explicit markers), you need the optional LLM provider: pip install -e ".[llm]" and pass --provider openai-compatible --api-key .

Alternatives

1. mori (compounding agent memory) -- focuses on memory persistence and compounding over sessions, not staged self-improvement with review gates. Complementary rather than competing.
2. juice (negative-constraint memory) -- stores what agents should avoid, not what they should change. Different problem (avoidance vs. improvement) with no overlap in approach.
3. tracebase (memory runtime) -- provides in-narrative time tracking and first-class deletion for agent memory. A runtime, not a staging/review pipeline.