Sync Modes

Mayros synchronizes Cortex data between instances using one of two modes: native (QUIC gossip) or polled (REST delta sync). The mode is selected automatically at startup.

Mode selection

mermaidCopy
flowchart TD
    A[Mayros starts] --> B{Cortex healthy?}
    B -->|No| C[No sync]
    B -->|Yes| D{probeP2p succeeds?}
    D -->|Yes| E{nativeP2pPreferred?}
    E -->|Yes| F[Native mode]
    E -->|No| G[Polled mode]
    D -->|No| G

probeP2p() calls GET /api/v1/p2p/status and checks if the Cortex sidecar reports P2P as enabled with a valid node ID.

Native mode

In native mode, synchronization is handled entirely by the Cortex gossip layer:

• Transport: QUIC with TLS
• Mechanism: Bloom-filter set reconciliation in gossip rounds
• Latency: Near-zero (push-based)
• Deletion: Tombstone propagation with 24h TTL
• Overhead: Minimal — no REST polling

When native mode is active:

• mayros sync status shows P2P peers, gossip stats (round, known IDs, bloom FPR), and sync stats (successful/failed syncs)
• mayros sync now defers to gossip — shows current stats instead of triggering REST sync
• mayros sync pair adds both a REST peer and a P2P peer connection
• The agent_end hook skips REST polling sync (gossip handles propagation)

Polled mode

In polled mode, Mayros manages synchronization via REST:

• Transport: HTTP REST
• Mechanism: Delta sync (POST /api/v1/sync/delta) with timestamp-based filtering
• Latency: Interval-based (configurable, default 300s)
• Peer management: PeerManager tracks known peers

When polled mode is active:

• mayros sync status shows the peer list and last sync timestamps
• mayros sync now triggers an immediate delta sync to all or a specific peer
• mayros sync pair adds a REST peer only
• The agent_end hook triggers auto-sync when autoSync is enabled

Configuration

Monitoring

In native mode, gossip metrics are available via mayros sync status:

• Gossip round: current round number
• Known IDs: total triple IDs tracked
• Bloom FPR: false positive rate of the bloom filter
• Successful syncs / Failed syncs: cumulative counters

Related

• P2P Sync — pairing, seed auth, and discovery
• Cortex (AIngle) — sidecar overview
• sync CLI — command reference