Cortex (AIngle)

Cortex is an HTTP sidecar binary (aingle-cortex) that provides Mayros with a persistent RDF triple store built on AIngle. It powers semantic memory, the knowledge graph, P2P synchronization, and observability tracing.

Architecture

mermaidCopy
graph LR
    A[Mayros CLI / TUI] -->|HTTP| B[CortexClient]
    B -->|REST API| C[aingle-cortex sidecar]
    C -->|QUIC gossip| D[Remote Cortex nodes]
    C -->|RDF store| E[Local data ~/.mayros/cortex-data/]

Mayros communicates with Cortex exclusively through CortexClient, a TypeScript HTTP client that wraps all REST calls with circuit-breaker resilience.

Auto-start lifecycle

Cortex is managed automatically by Mayros:

Graceful shutdown flushes all data (graph + Ineru snapshots) to disk before exiting via SIGTERM/SIGINT.

Seamless binary updates

When Mayros updates the Cortex binary (via mayros update), it coordinates a zero-data-loss flow:

1. Flush — sends POST /api/v1/flush to persist all in-memory data
2. Stop — SIGTERM with 10s timeout, then SIGKILL if needed
3. Replace — new binary is written to ~/.mayros/bin/
4. Restart — sidecar restarts with the same --db path, data intact

REST API

Cortex exposes a REST API consumed by CortexClient:

Data model

All data is stored as RDF triples: subject → predicate → object. Values can be strings, numbers, booleans, or node references.

mayros:agent:main → mayros:memory:convention → "Use ESM imports"
mayros:plan:abc123 → mayros:plan:phase → "explore"
file:src/index.ts → defines:function → "main"

Triples are namespaced with a configurable prefix (default: mayros) to enforce isolation between projects and agents.

Paths

Configuration

json5Copy
{
  cortex: {
    host: "127.0.0.1",       // Cortex host
    port: 19090,              // Cortex port
    autoStart: true,          // Auto-spawn sidecar
    dataDir: undefined,       // Data directory (default: ~/.mayros/cortex-data/)
    binaryPath: undefined,    // Override binary location
    authToken: undefined,     // Auth token (or CORTEX_AUTH_TOKEN env)
    requireAuth: false,       // Require authentication
    strictVersionCheck: false, // Block on version mismatch
    p2p: {
      enabled: false,         // Enable native P2P
      port: 19091,            // QUIC gossip port
      seed: undefined,        // Shared secret for peer auth
      manualPeers: [],        // Peer addresses
      mdns: false,            // mDNS discovery
    },
    resilience: {
      timeoutMs: 5000,        // Request timeout
      maxRetries: 2,          // Retry count
      retryDelayMs: 300,      // Base retry delay
      circuitThreshold: 5,    // Failures before circuit opens
      circuitResetMs: 30000,  // Recovery timeout
    },
  },
}

Related

• P2P Sync — synchronize triples between instances
• Knowledge Graph — code indexing and project memory
• Cortex Resilience — circuit breaker and graceful degradation
• Memory — agent and session memory