hermes-mcp/hermes.md

🔩 Proposed Hermes internal layers

1. Signal Ingestion Layer (Adapters only)

Strictly read-only connectors:

Crypto-MCP → price, volatility, structure Metals-MCP → macro anchor News-MCP → events, sentiment Atlas2-MCP → entity normalization Trader-MCP → execution feedback (fills, slippage, stress) (optional weird inputs like moon phase, weather)

👉 Rule: No interpretation here. Just normalized signals.

1. Feature & State Layer (structured, queryable)

This is your “complex database” instinct—you’re right.

Instead of raw data, Hermes works with derived state objects:

Examples:

market_regime: trend | chop | volatility expansion btc_structure: breakout | range | compression sentiment_pressure: positive | neutral | negative event_risk: low | medium | high liquidity_state: thick | thin execution_quality: good | degraded

👉 This layer is:

structured (not just embeddings) versioned over time explainable (“why is sentiment negative?” → trace back)

This is your semantic state store.

1. Narrative Layer (LLM + rules hybrid)

This is where things get interesting.

Hermes builds something like:

“Market is in low-liquidity uptrend with rising negative sentiment divergence and macro uncertainty.”

Not just labels—coherent stories.

Important:

LLM is used here, but constrained by structured inputs Output is parsable + human-readable

👉 Think:

{ "narrative": "...", "confidence": 0.72, "key_drivers": ["sentiment divergence", "low liquidity"], "risk_flags": ["event risk: CPI tomorrow"] }

1. Decision Layer (STRICT and minimal)

This is where many systems go wrong.

Hermes does NOT say:

“Buy BTC now”

It says:

enable/disable strategy prefer strategy A over B reduce risk pause execution

👉 Example:

{ "action": "switch_strategy", "from": "trend_following", "to": "mean_reversion", "reason": "range detected with low volatility expansion" }

1. Explanation Layer (first-class citizen)

This is your differentiator.

Every decision must be explainable:

What changed? What signals mattered? What was ignored? What is uncertain?

👉 This should be queryable like:

“why did you switch?” “what changed in last 30 min?” “what are you unsure about?” 🧰 Hermes MCP Tool Design (small + powerful)

You’re absolutely right: tiny surface area.

Core tools:

1. get_state()

Structured snapshot of everything Hermes believes right now.

1. get_narrative()

Human-readable + structured explanation of current market interpretation.

1. get_decision()

Current control stance:

active strategy risk mode recent changes

1. explain_decision(decision_id | latest)

Deep trace:

signals → features → narrative → decision

1. get_deltas(time_window)

“What changed recently?”

Super important for debugging + dashboards.

1. get_uncertainty()

This is underrated.

Hermes should explicitly say:

“I don’t trust sentiment right now” “data conflict between crypto and news”

That’s huge for robustness.

🧬 Key design philosophy (this is the core)

1. Separation inside Hermes Signals ≠ Features ≠ Narrative ≠ Decisions
2. LLM is not the brain

The LLM:

interprets summarizes explains

But:

structure comes from your system decisions are constrained

1. Everything is traceable

If you can’t answer:

“why did this happen?”

Hermes is broken.

1. Hermes is read-mostly

You nailed this.

Other agents:

observe Hermes don’t control it directly

Hermes is more like:

a “market consciousness stream”

🖥️ Dashboard vision (what you described)

What you’re imagining is actually perfect:

Center: current narrative (“market story”) Around it: live signals (price, news clusters, sentiment) regime indicators strategy state (from Trader) risk posture Timeline: decisions over time regime shifts “why it changed”

👉 This becomes: a cockpit, not a control panel

⚠️ Biggest risks (worth calling out)

1. Overloading Hermes

If Hermes starts:

calculating indicators storing raw tick data → you lose clarity

1. Too much LLM freedom

Unconstrained LLM = hallucinated regimes

You need:

structured inputs bounded outputs

1. Missing state model

Without a clean feature/state layer, Hermes becomes vibes-only.

🧱 Your system becomes this Strategies = “frozen expertise capsules”

Each strategy is:

internally coherent pre-tuned designed for a specific regime

Examples:

trend_following_high_vol mean_reversion_low_vol breakout_event_driven grid_range_bound risk_off_idle

Hermes doesn’t design strategies.

Hermes asks:

“Which world are we in right now?”

🔄 Hermes decision becomes simple and powerful

Instead of:

{ "rsi_threshold": 73, "grid_spacing": 0.8 }

You get:

{ "active_strategy": "mean_reversion_low_vol" }

That’s night-and-day in terms of system sanity.

🧬 This matches your architecture beautifully Hermes: interprets the world selects the mode of behavior Trader: runs the selected behavior perfectly Exec: executes mechanics 🎯 Even better: this enables clean reasoning

Hermes can now explain itself like a human:

“Market is range-bound with low volatility and weak directional conviction → selecting mean reversion strategy.”

That’s understandable.

⚙️ Recommended refinement (important)

You should formalize this as:

Strategy Registry (in Trader or shared)

Each strategy has metadata:

{ "name": "mean_reversion_low_vol", "tags": ["range", "low_volatility"], "risk_profile": "medium", "expected_conditions": {

"volatility": "low",
"trend": "none",
"liquidity": "normal"

} } 🧠 Hermes then does matching, not guessing

Hermes evaluates:

current state (from its feature layer) strategy metadata

…and selects the best fit.

👉 This is basically:

semantic matching instead of parameter tuning

💡 You can even score strategies

Hermes could internally do:

{ "trend_following": 0.2, "mean_reversion": 0.8, "breakout": 0.4 }

Then pick the top one.

This gives you:

smooth transitions introspection (“second best was breakout”) 🔁 Strategy switching becomes meaningful

Instead of random flips, you get:

“Switching from trend_following → mean_reversion because volatility collapsed and price entered range structure.”

That’s exactly the kind of narrative coherence you’re aiming for.

⚠️ One thing to be careful about Don’t create too many strategies

If you have:

5–10 well-defined strategies → great 50 micro-variants → you’re back to parameter hell 🧭 A good mental model

Think of strategies as:

musicians in a band

Hermes is the conductor.

It doesn’t tell the guitarist:

“move your finger 2mm”

It says:

“now jazz” “now silence” “now aggressive” 🔌 Minimal Hermes → Trader contract (perfect for your idea)

You can literally reduce it to:

Command: { "active_strategy": "mean_reversion_low_vol" }