# Hermes Cycle

This note captures the working model for Hermes as discussed in chat.

## Purpose
Hermes sits above Trader, Crypto, Metals, and News. It observes the world, evaluates coverage, derives state, forms a narrative, makes a decision, and then optionally acts on Trader.

Hermes is read-mostly and explainable. It should not become a trading engine itself.

## Core idea
Hermes runs in cycles.

Each cycle answers:
- What concerns do we have?
- What changed since the last cycle?
- What does the state mean?
- What narrative best explains the current picture?
- What decision should follow?
- Should Hermes act, or only recommend?
- Did anything remain uncovered?

## Cycle inputs
### Concerns
Concerns define what Hermes watches.

Examples:
- account alpha, market xrpusd
- account beta, market btcusd
- strategy coverage on a trader instance

Concerns can come from:
- Hermes config
- Trader inventory
- manual registration

Hermes should mirror Trader coverage, but in v1 it should not create instances automatically.

### Sources
Primary sources for v1:
- crypto-mcp, especially market regime
- trader-mcp, especially strategy inventory and execution context

Later sources:
- news-mcp
- metals-mcp
- additional sentiment inputs

## Cycle stages
### 1. Poll
For each concern, Hermes polls the relevant adapters.

Example:
- crypto-mcp returns market regime for the concern’s assets
- trader-mcp returns strategy inventory and control state

### 2. Store observations
Hermes stores raw adapter outputs as observations.

This layer is factual and should not interpret anything.

### 3. Derive state
Hermes converts observations into compact state fields.

Examples:
- market_regime
- volatility_state
- liquidity_state
- sentiment_pressure
- event_risk
- execution_quality

### 4. Build narrative
Hermes writes a short explanation of the current picture.

The narrative should be human-readable, but still structured enough for dashboards and debugging.

### 5. Make decision
Hermes decides one of the following:
- observe
- recommend
- act

If acting, Hermes may send a control command to Trader.

### 6. Execute action
Hermes logs the outbound action and the response.

Decision and execution must remain separate.

### 7. Record gaps
If Hermes finds missing coverage, it records a gap and recommendation.

This is important and should not be merged into decisions.

## Data model
The SQLite schema should keep these layers separate:
- concerns
- cycles
- observations
- states
- narratives
- decisions
- actions
- coverage_gaps

## First implementation target
Start with:
1. concerns registry
2. cycle runner
3. crypto polling
4. raw observation storage
5. state derivation
6. narrative stub
7. decision stub
8. action logging stub

That gives Hermes a real spine before we add more inputs.

## Guiding rule
Do not store the same idea twice.
Raw facts, derived state, prose, and control intent all belong in different places.