| name | hermes-dream-task |
| description | Research-backed background thinking system for Hermes agents. Uses structured exploration trees, generate-verify loops, metacognitive monitoring, and adaptive termination to produce high-quality reasoning in the background.
|
| version | 2.0.0 |
| author | Hermes (architecture from Reflexion, SwiftSage, SPOC, MAPS, ToT) |
| license | MIT |
| metadata | {"hermes":{"tags":["dream","background","thinking","deliberative","system2","metacognition"],"triggers":["dream: ","dream about","background thinking","think about this","proactive research"]}} |
| prerequisites | {"tools":["terminal","read_file","write_file"]} |
HERMES DREAM TASK v2
Architecture
Based on peer-reviewed research: Reflexion (Shinn et al.), SwiftSage, SPOC, MAPS,
Tree-of-Thoughts, MetaRAG, Branch-and-Browse.
Core Components
-
ENTROPY GATE — hermes chat -q assesses query complexity (1-10). Only starts
dreams for score >= 7. No more auto-dreaming for simple questions.
-
TREE-STRUCTURED EXPLORATION — Each dream maintains a JSON exploration tree
(not flat log). Each node has: thought, confidence score, evaluation, children.
Enables backtracking and alternative path exploration.
-
GENERATE-VERIFY LOOP — Each iteration:
- Generate a thought for the current exploration path
- Evaluate with metacognitive monitoring (confidence, novelty, weakness)
- Add to tree, update path based on recommendation
- Track failures (low-confidence nodes) separately
-
ADAPTIVE TERMINATION — Stops when:
- Self-evaluated confidence >= 75%
- LLM recommends "distill_and_stop"
- Max iterations (10) reached
- Non-novel thoughts force backtracking past root
-
EPISODIC MEMORY — Three structured files per dream:
insights.json — key findings (distilled, not raw logs)failures.json — failure patterns to avoidpending_questions.json — open questions
-
DISTILLED INJECTION — When injecting into conversations, the plugin extracts
3-5 bullet insights + confidence score. NEVER raw dream logs.
File Structure
~/.hermes/state/dream/<dream_id>/
meta.json — metadata, status, confidence, iteration count
exploration_tree.json — tree of reasoning nodes
insights.json — distilled key findings
failures.json — failure patterns
pending_questions.json — open questions
brief.json — legacy compat
status.txt — legacy compat
iterations.json — legacy compat
Plugin Hooks
The dream_auto plugin fires at 6 hook points:
| Hook | Behavior |
|---|
| pre_llm_call | Inject distilled insights (never raw logs) |
| pre_tool_call | Non-blocking suggestion for complex code |
| post_tool_call | Auto-start troubleshooting dream on errors (gated) |
| post_llm_call | Entropy gate via hermes chat -q, auto-start if score >= 7 |
| on_session_start | Log active dreams |
| on_session_end | Clean up tracking |
Configuration
Environment variables:
| Variable | Default | Description |
|---|
| DREAM_AUTO_ENABLED | 1 | Set to 0 to disable |
| DREAM_AUTO_VERBOSE | 0 | Set to 1 for logging |
| DREAM_AUTO_MAX_INJECT | 3 | Max dreams to inject per turn |
| DREAM_AUTO_AUTOSTART | 1 | Set to 0 to disable auto-start |
| DREAM_AUTO_MIN_COMPLEXITY | 7 | Min complexity score (1-10) to start dream |
Dream Loop v2
scripts/dream_loop_v2.py implements the structured reasoning loop:
For each iteration:
1. GENERATE — hermes chat -q generates a thought for current path
2. EVALUATE — hermes chat -q evaluates with metacognitive monitoring
3. UPDATE TREE — add node, update path based on recommendation
4. TRACK — failures go to failures.json, confidence tracked
5. CHECK TERMINATION — confidence threshold, distill recommendation
6. SLEEP — 2 minutes between iterations
Checking Dreams
cat ~/.hermes/state/dream/*/meta.json | python3 -c "
import sys, json
for line in sys.stdin:
try:
m = json.loads(line)
print(f\"{m['dream_id']}: conf={m.get('confidence',0):.0%} iter={m.get('iteration',0)} status={m.get('status','?')}\")
except: pass
"
cat ~/.hermes/state/dream/<id>/insights.json | python3 -m json.tool
cat ~/.hermes/state/dream/<id>/exploration_tree.json | python3 -m json.tool
Pitfalls (v3 — dream_loop_v3.py)
Python scoping bugs to watch for
-
math vs _math alias — Top of file does import math as _math (line 52).
Any call to math.sqrt() must use _math.sqrt(). The NameError: name 'math' is not defined silently crashes mcts_backpropagate at line 350.
-
Local variable shadows global constant — generate_branches() defines a local
MAX_CHILDREN_PER_NODE variable (line ~180) that shadows the module-level constant.
F-strings inside the function see the local (unassigned) name → UnboundLocalError.
Rename the local variable to something like max_children.
-
read_meta / write_meta definition ordering — These are defined at lines 898-905,
well after mcts_loop (line 688) which calls them. Python does not hoist function
definitions. All helpers must be defined BEFORE the function that uses them.
Move read_meta and write_meta above mcts_loop.
Dashboard error misreporting
The dashboard.html error table only shows the first line of each traceback (the
"File" line) and categorises everything as FileNotFoundError. Actual error types
found in crashed dreams:
NameError: name 'math' is not defined — mcts_backpropagate line 350UnboundLocalError — generate_branches line 172NameError: name 'read_meta' is not defined — mcts_loop line 580
To get full tracebacks, read ~/.hermes/state/dream/<dream_id>/dream_output.log.
Research Papers
Key papers informing this architecture:
- Reflexion (2303.11366) — Verbal reinforcement + episodic memory buffer
- SwiftSage (2305.17390) — Fast/slow dual-process agent architecture
- SPOC (2506.06923) — Interleaved generate-verify in single pass
- MAPS (2506.23888) — Adaptive-depth iterative self-reflection
- Tree-of-Thoughts (2305.10601) — Deliberate problem solving with exploration
- MetaRAG (2402.11626) — Monitor → Evaluate → Plan metacognitive pipeline
- Branch-and-Browse (2510.19838) — Background reasoning + action memory
- ReTreVal (2601.02880) — ToT + self-refinement + reflexion memory
- LLM Metacognition (2505.13763) — LLMs can monitor their own thinking
