hermes-dreaming

A standalone, open-source staged self-improvement engine for Hermes-style memory, user, skill, and fact updates.
It scans explicit source inputs, stages proposed changes in a reviewable artifact directory, and only writes to live state after an explicit apply step.

Hermes plugin

This repo now ships as a proper Hermes plugin too.

Install from GitHub with:

hermes plugins install asimons81/hermes-dreaming --enable

For a local checkout during development:

hermes plugins install file:///path/to/hermes-dreaming --enable

Once installed, use:

hermes dreaming --help

The plugin also bundles a Hermes skill for the staged review workflow as hermes-dreaming:dreaming.

Current status

• Artifact-first MVP is implemented
• Apply and discard are explicit
• Tests pass locally
• Hermes plugin wrapper is included

Install

For local development:

python -m pip install -e .[dev]

If you want the optional OpenAI-compatible provider:

python -m pip install -e .[llm]

CLI

dreaming create --live-root ./live --artifact-root ./artifacts --source ./sources
dreaming diff ./artifacts/<artifact-id>
dreaming validate ./artifacts/<artifact-id> --live-root ./live
dreaming apply ./artifacts/<artifact-id> --live-root ./live --backup-root ./backups --approve all
dreaming discard ./artifacts/<artifact-id> --archive-root ./archive
dreaming status --artifact-root ./artifacts

Dream markers

The offline provider looks for explicit DREAM: lines in the source bundle.

DREAM: memory: Keep updates short and concrete.
DREAM: user: Prefer concise status updates.
DREAM: fact: {"type": "preference", "key": "tone", "value": "casual"}
DREAM: skill: path=skills/review.md | Preserve review gates and backups.

Artifact layout

Each run writes a staged artifact directory containing:

• manifest.json
• REPORT.md
• sources.jsonl
• proposals.jsonl

The artifact is intentionally simple, deterministic, and easy to review on disk or in git.

Repo docs

• CONTRIBUTING.md is the contributor guide and local workflow contract
• SECURITY.md covers private vulnerability reporting
• CODE_OF_CONDUCT.md sets the collaboration rules
• brief.md has the project brief and non-goals
• specs/mvp-implementation-plan.md describes the current implementation contract and package layout
• docs/release-checklist.md is the pre-release checklist
• reviews/final-sanity.md records the most recent QA pass

Contributing

If you want to contribute, start with CONTRIBUTING.md.

• Use the issue templates so the scope and intent are clear.
• Run pytest -q, python -m build --wheel, and git diff --check before requesting review.
• If your change touches live roots, artifact roots, or writeback behavior, state that explicitly.
• If you change release-facing text or safety rules, make sure the docs still match shipped behavior.

Development

pytest -q
python -m pip install build
python -m build --wheel

The repo is intentionally self-contained and safe for public release review.