AGENTS.md

Role

HERMES-MCP is the central decision engine of the trading subsystem.

It consumes structured inputs (signals, market data, events, sentiment scores) and produces explicit, actionable trading decisions.

Responsibilities

aggregate inputs from upstream MCPs
evaluate strategies
produce deterministic decision outputs
act as the single source of truth for strategy selection and intent

Inputs

Expected upstream sources:

argus-mcp → aggregated signals
crypto-mcp → market data
(future) news-mcp → events/news

Inputs must be treated as read-only and trusted but validated.

Outputs

decisions → trader-mcp

Decisions must be:

explicit (no ambiguity)
complete (no missing fields)
reproducible (same input → same output, unless explicitly stochastic)

Strict Rules

MUST NOT execute trades
MUST NOT access exchanges directly
MUST NOT fetch raw data from external APIs (use upstream MCPs)
MUST NOT embed execution logic
MUST NOT depend on downstream components
MUST be the ONLY component that activates, deactivates or switches strategies

Decision Model Constraints

decisions should be stateless where possible
if state is required, it must be explicit and traceable
avoid hidden side effects
log reasoning or signals used for each decision (for auditability)

Interface Stability

Changes to decision format are breaking changes.

When modifying:

update trader-mcp expectations
ensure backward compatibility or version the schema

Failure Handling

invalid or missing inputs must not crash the system
fallback behavior must be explicit (e.g. "no trade")

Development Guidelines

prefer clarity over cleverness
keep decision logic modular and testable
isolate strategy evaluation from data parsing

When Modifying This Repo

Before making changes:

Identify all inputs used
Identify all outputs affected
Check compatibility with trader-mcp
Avoid introducing hidden dependencies

Non-Goals

This service is NOT responsible for:

data collection
trade execution
account management