hermes-mcp/HERMES_CYCLE.md

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.