Architecture - Condor

Each Trading Agent is a folder-based entity with structured files that define its behavior, track state, and accumulate learnings.

System Architecture

                ┌──────────────────────────── Trading Agent ───────────────────────────┐
                │                                                                       │
                │   Strategy (agent.md)        Journal (per session)     Learnings.md   │
                │   ───────────────────        ────────────────────       ────────────  │
                │   - system prompt            - summary                  cross-session │
                │   - default config           - decisions                lessons       │
                │   - skills/routines          - tick-by-tick log                       │
                │                              - snapshot_N.md                          │
                │                                                                       │
                │                            ┌──── TickEngine ────┐                     │
                │                            │  every N seconds:  │                     │
                │   Routines  ───────────►   │  1. run providers  │  ────► MCP Tools    │
                │  (deterministic            │  2. read journal   │       - candles     │
                │   data prep)               │  3. build prompt   │       - orderbook   │
                │                            │  4. ACP session    │       - executors   │
                │                            │  5. capture tools  │       - notify      │
                │                            │  6. write snapshot │                     │
                │                            └────────────────────┘                     │
                │                                                                       │
                └───────────────────────────────────────────────────────────────────────┘
                                                      │
                                                      ▼
                                         Hummingbot Executors
                                 (filtered by controller_id == agent_id)

Directory Structure

Each Condor Trading Agent (CTA) is a directory containing structured files:

trading_agents/
  my_strategy/
    agent.md                  # Strategy definition (frontmatter + LLM instructions)
    config.yml                # Runtime configuration (editable)
    learnings.md              # Cross-session insights (max 20)
    routines/                 # Deterministic Python helpers
    trading_sessions/
      session_N/
        journal.md            # Summary, decisions, ticks, executors
        snapshots/
          snapshot_1.md       # Full prompt + response for tick 1
          snapshot_2.md
    dry_runs/
      experiment_1.md         # One-shot dry-run results

Two Memory Files

File	Scope	Purpose
`journal.md`	Per-session	Short-term memory for the current trading session
`learnings.md`	Cross-session	Long-term memory that persists across all sessions

Journal: What the agent did in this session—tick log, decisions, executor states. Learnings: Lessons that apply to all sessions—common errors, configuration tips, market insights.

agent.md

The strategy definition uses YAML frontmatter for configuration and Markdown for instructions:

---
name: Grid Market Maker
tick_interval: 60
connectors:
  - binance_perpetual
  - jupiter

configs:
  trading_pair: SOL-USDC
  grid_levels: 5
  spread_percentage: 0.3

limits:
  max_position_size_quote: 500
  max_single_order_quote: 100
  max_daily_loss_quote: 50
  max_open_executors: 10
  max_drawdown_pct: 10
---

## Goal
Provide liquidity around the mid-price while managing inventory risk.

## Strategy Rules
1. Maintain symmetric grid unless inventory exceeds threshold
2. Widen spreads during high volatility (ATR > 2%)
3. Pause trading if funding rate exceeds 0.1% against position

Configs vs Limits

Configs

Agent-suggestible parameters that control trading behavior:

The agent can suggest changes based on learnings
User must approve before changes take effect
Examples: trading_pair, spread_percentage, tick_interval, grid_levels

Limits

User-only guardrails enforced by the Risk Engine:

Safety boundaries the agent cannot exceed
Only modifiable by the user, never by the agent
Examples: max_position_size_quote, max_daily_loss_quote, max_drawdown_pct

learnings.md

Persists across sessions, accumulating insights:

# Learnings

## Active Insights
- [2026-03-27 14:30] Wider spreads (0.5% vs 0.3%) reduced adverse selection during Asian session
- [2026-03-26 09:15] Grid rebalancing at 5% threshold outperforms 10% for SOL-USDC
- [2026-03-25 16:45] Funding rate spikes above 0.05% correlate with 2-hour reversals

Maximum 20 entries to prevent context bloat. New insights replace older ones.

Tick Loop

Each tick (TickEngine._tick) executes:

Resolve API client for the configured server
Run providers — executors and positions, filtered by controller_id
Read journal context — learnings, summary, last 3 decisions
Get risk state — exposure, drawdown, open count. If blocked, skip LLM
Build prompt — system prompt + strategy + provider summaries + journal
Spawn ACP session with MCP servers (Hummingbot tools, market data)
Persist — write snapshot, append tick to journal, update summary

Risk Engine

The Risk Engine (condor/trading_agent/risk.py) tracks state and enforces limits:

class RiskState:
    daily_pnl: float          # Today's realized P&L
    total_exposure: float     # Current open position value
    executor_count: int       # Number of active executors
    drawdown_pct: float       # Current drawdown percentage
    daily_cost: float         # LLM costs today
    is_blocked: bool          # Kill switch status
    block_reason: str         # Why blocked (if applicable)

Pre-tick Validation

Blocks the entire tick if:

daily_pnl < -max_daily_loss_quote
drawdown_pct > max_drawdown_pct
daily_cost > max_cost_per_day_usd

Per-executor Validation

Blocks executor creation if:

executor_count >= max_open_executors
order_amount > max_single_order_quote
total_exposure + new_amount > max_position_size_quote

Providers

Providers fetch deterministic data before each tick:

Provider	Output
`executors`	Active executors filtered by `controller_id`, with status and P&L
`positions`	Held positions from closed executors, with breakeven and unrealized P&L

Provider output has two parts:

data: Structured data for internal tracking
summary: Human-readable string included in the LLM prompt

Routines

Custom Python helpers in the routines/ directory:

# routines/process_candles.py
async def compute_vwap(candles):
    """Compute VWAP from candle data."""
    total_volume = sum(c.volume for c in candles)
    return sum(c.close * c.volume for c in candles) / total_volume

Routines are deterministic—same input always produces same output.

Inspecting Activity

Location	Content
`sessions/session_N/journal.md`	Chronological summary, decisions, tick log
`sessions/session_N/snapshots/snapshot_K.md`	Full tick: prompt, response, tool calls
`learnings.md`	Lessons the agent chose to keep
`dry_runs/experiment_N.md`	Dry-run results

Injecting Information

You can manually add to learnings.md—the agent doesn’t know whether it wrote the entry or you did. Useful for:

Pre-seeding knowledge before deployment
Adding market context the agent can’t observe
Correcting agent behavior

Via web dashboard: Trading Agents → Select agent → Learnings → Edit Via file: Edit trading_agents/my_strategy/learnings.md directly

​System Architecture

​Directory Structure

​Two Memory Files

​agent.md

​Configs vs Limits

​Configs

​Limits

​learnings.md

​Tick Loop

​Risk Engine

​Pre-tick Validation

​Per-executor Validation

​Providers

​Routines

​Inspecting Activity

​Injecting Information