P2P Sync

Cortex embeds native peer-to-peer synchronization via QUIC transport and bloom-filter gossip. Multiple Mayros instances can share knowledge graphs, memory, and trace data automatically.

Dual sync modes

Mayros supports two synchronization modes:

ModeTransportLatencyMechanism
NativeQUIC gossipNear-zeroBloom-filter set reconciliation
PolledREST HTTPInterval-basedDelta sync polling

On startup, Mayros probes the Cortex P2P API (/api/v1/p2p/status). If the sidecar has P2P enabled, sync automatically uses native mode. Otherwise, it falls back to polled mode.

Seed-based authentication

Nodes authenticate using a shared seed:

  1. Both nodes are configured with the same cortex.p2p.seed value
  2. Cortex derives a handshake key via blake3(seed)
  3. Only nodes with a matching seed can connect and exchange data

Bloom-filter gossip

In native mode, nodes synchronize through gossip rounds:

  1. Announce — each node broadcasts a bloom filter of its known triple IDs
  2. Request — receiving nodes identify IDs they're missing (false-positive-aware)
  3. Send — the announcing node sends the missing triples
  4. Tombstones — deleted triples propagate as tombstone markers with a 24-hour TTL

Gossip stats (round number, pending announcements, known IDs, bloom FPR) are visible via mayros sync status.

Peer discovery

  • Manual peers: configure cortex.p2p.manualPeers or use mayros sync pair
  • mDNS: enable cortex.p2p.mdns for local network auto-discovery (service type: _mayros-cortex._tcp)

Pairing walkthrough

1

Enable P2P in config

On both machines, set a shared seed:

json5
{
  cortex: {
    p2p: {
      enabled: true,
      port: 19091,
      seed: "my-shared-secret",
    },
  },
}
2

Start Machine A

bash
mayros   # starts normally with P2P enabled
3

Connect Machine B

Either configure the peer in config:

json5
{
  cortex: {
    p2p: {
      enabled: true,
      seed: "my-shared-secret",
      manualPeers: ["10.0.0.5:19091"],
    },
  },
}

Or pair at runtime:

bash
mayros sync pair machine-a http://10.0.0.5:8080
4

Verify connection

bash
mayros sync status

In native mode, this shows connected peers, gossip round, known IDs, and sync statistics.

Graceful degradation

When Cortex lacks the P2P feature or p2p.enabled is false, Mayros transparently falls back to polled REST sync. The cortex.sync.nativeP2pPreferred option (default: true) controls whether native mode is preferred when available.

Configuration reference

KeyDefaultDescription
cortex.p2p.enabledfalseEnable native P2P
cortex.p2p.port19091QUIC gossip port (1024–65535)
cortex.p2p.seed—Shared secret for peer authentication (alphanumeric)
cortex.p2p.manualPeers[]List of peer addresses (host:port)
cortex.p2p.mdnsfalseEnable mDNS local discovery