Add trader compatibility note

TRADER_COMPATIBILITY_NOTE.md

@@ -0,0 +1,44 @@
+# Trader-MCP compatibility note
+
+This note is for Hermes-MCP developers.
+
+## Trader taxonomy expected by Hermes
+
+Canonical strategy set currently being stabilized:
+- `grid`
+- `Exposure Protector` (defensive exposure rebalancer)
+- `trend_follower`
+- `idle`
+- `defensive`
+- `mean_reversion`
+- `breakout`
+- `event_driven`
+
+## Trader contract locations
+
+Primary contract and runtime docs live in `trader-mcp/`:
+- `trader-mcp/Hermes_Trader_Contract_v0.1.md`
+- `trader-mcp/Strategy_Contract.md`
+- `trader-mcp/Strategy_Runtime.md`
+- `trader-mcp/MCP_SURFACE_PROPOSAL.md`
+- `trader-mcp/TODO.md`
+
+## Hermes-facing data
+
+Hermes should read strategy snapshots via `report()`.
+Important fields:
+- `identity`
+- `control`
+- `fit`
+- `position`
+- `state`
+- `assessment`
+- `execution`
+
+## Hermes control path
+
+Hermes should use:
+- `set_strategy_policy()` for high-level policy (`risk_posture`, `priority`)
+- `control_strategy()` for lifecycle (`start`, `stop`, `pause`, `resume`, `reconcile`)
+
+Policies are applied on reconcile and instance creation.

hermes.md

@@ -0,0 +1,361 @@
+🔩 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.
+
+2. 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.
+
+3. 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"]
+}
+4. 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"
+}
+5. 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.
+
+2. get_narrative()
+
+Human-readable + structured explanation of current market interpretation.
+
+3. get_decision()
+
+Current control stance:
+
+active strategy
+risk mode
+recent changes
+4. explain_decision(decision_id | latest)
+
+Deep trace:
+
+signals → features → narrative → decision
+5. get_deltas(time_window)
+
+“What changed recently?”
+
+Super important for debugging + dashboards.
+
+6. 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
+3. Everything is traceable
+
+If you can’t answer:
+
+“why did this happen?”
+
+Hermes is broken.
+
+4. 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
+2. Too much LLM freedom
+
+Unconstrained LLM = hallucinated regimes
+
+You need:
+
+structured inputs
+bounded outputs
+3. 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"
+}

hermes_and_strategies.md

@@ -0,0 +1,231 @@
+The goal is not coverage of every idea, but:
+
+a small, orthogonal set of strategies that map cleanly to distinct market regimes
+
+🧠 First principle
+
+A strategy should exist only if it answers:
+
+“This behaves fundamentally differently from the others under different conditions.”
+
+If two strategies differ only by parameters → they should be one.
+
+🧱 The minimal useful axes
+
+You can reduce the entire market behavior space to a few dimensions:
+
+Trend vs Range
+Volatility (low / expanding / high)
+Event pressure (normal vs event-driven)
+Liquidity quality (normal vs thin/chaotic)
+
+That’s enough to define your taxonomy.
+
+🎯 Minimal Strategy Set (clean + complete)
+1. 🟢 idle / risk_off
+
+Purpose: Do nothing / capital preservation
+
+When:
+
+high uncertainty
+conflicting signals
+extreme event risk
+broken execution conditions
+
+This is NOT optional.
+This is what prevents dumb trades.
+
+2. 🔵 trend_following
+
+Purpose: Ride directional moves
+
+When:
+
+clear structure (higher highs / lower lows)
+sustained momentum
+decent liquidity
+
+Variants are internal, not separate strategies:
+
+slow trend
+strong trend
+3. 🟡 mean_reversion
+
+Purpose: Trade inside ranges
+
+When:
+
+sideways market
+low volatility
+no directional conviction
+
+Key trait:
+
+fades extremes, expects reversion
+4. 🟣 breakout
+
+Purpose: Capture volatility expansion
+
+When:
+
+compression → expansion
+levels about to break
+volatility increasing
+
+Important:
+This is NOT trend-following.
+It’s anticipating the move, not riding it.
+
+5. 🟠 grid / liquidity_harvesting
+
+Purpose: Monetize noise
+
+When:
+
+choppy, bounded markets
+decent liquidity
+no strong directional bias
+
+Difference to mean reversion:
+
+systematic order placement
+not signal-based entries
+6. 🔴 event_driven
+
+Purpose: React to external shocks
+
+When:
+
+major news
+macro releases
+sudden sentiment shifts
+
+Behavior:
+
+fast, defensive or opportunistic
+often temporary
+7. ⚫ defensive / unwind
+
+Purpose: Reduce exposure safely
+
+When:
+
+regime shift detected
+strategy mismatch
+execution degradation
+
+This is a transition strategy, not alpha-seeking.
+
+🧬 Why this set works
+
+You now cover:
+
+Regime	Strategy
+Trend	trend_following
+Range	mean_reversion
+Chop	grid
+Expansion	breakout
+External shock	event_driven
+Uncertainty	idle
+Transition/risk	defensive
+
+👉 That’s the full space, without redundancy.
+
+⚙️ Strategy metadata (critical for Hermes)
+
+Each strategy should declare its “natural habitat”:
+
+{
+  "name": "mean_reversion",
+  "expects": {
+    "trend": "none",
+    "volatility": "low",
+    "event_risk": "low"
+  },
+  "avoids": {
+    "volatility": "expanding",
+    "event_risk": "high"
+  },
+  "risk_profile": "medium"
+}
+
+Hermes uses this—not gut feeling.
+
+🧠 Hermes selection logic (conceptual)
+
+Hermes computes current state:
+
+{
+  "trend": "none",
+  "volatility": "low",
+  "event_risk": "low"
+}
+
+Then scores strategies:
+
+{
+  "mean_reversion": 0.9,
+  "grid": 0.7,
+  "trend_following": 0.1
+}
+🔁 Preventing flip-flopping (VERY important)
+
+Without this, Hermes will go insane.
+
+Add:
+
+1. Hysteresis
+don’t switch unless new strategy is significantly better
+2. Minimum hold time
+once active, stay active for X minutes unless strong signal
+3. Confidence threshold
+only switch if confidence > e.g. 0.65
+🧭 Subtle but powerful distinction
+mean_reversion vs grid
+
+This is where many systems fail:
+
+mean_reversion = signal-based
+grid = structure-based
+
+Keep both.
+
+🧪 Optional later (DO NOT start with this)
+
+Only after everything works:
+
+volatility_scalping
+cross-asset arbitrage
+market-making
+
+But don’t pollute v1.
+
+💡 Naming matters more than you think
+
+Use names that are:
+
+intuitive
+explainable to humans
+stable over time
+
+Avoid:
+
+“alpha_v3_dynamic”
+“strategy_7”
+🔚 Final minimal set (clean version)
+1. idle
+2. trend_following
+3. mean_reversion
+4. breakout
+5. grid
+6. event_driven
+7. defensive
+🧠 What you just achieved
+
+With this taxonomy:
+
+Hermes has a finite decision space
+Strategies remain coherent and specialized
+Explanations become natural language
+Debugging becomes possible