VEX Architecture

System design and component breakdown for VEX.

System Overview

Code

┌─────────────────────────────────────────────────────────────┐
│                     Gateway Layer                           │
│  vex-api: Axum HTTP + JWT + Rate Limiting + Circuit Breaker │
├─────────────────────────────────────────────────────────────┤
│                   Intelligence Layer                        │
│  vex-llm              │  vex-adversarial                    │
│  DeepSeek/OpenAI      │  Red/Blue Debate Engine             │
├─────────────────────────────────────────────────────────────┤
│                    Execution Layer                          │
│  vex-runtime          │  vex-queue                          │
│  Orchestrator/Executor│  Async Worker Pool                  │
├─────────────────────────────────────────────────────────────┤
│                      Core Layer                             │
│  vex-core             │  vex-temporal                       │
│  Agent/Genome/Merkle  │  Episodic Memory + Decay            │
├─────────────────────────────────────────────────────────────┤
│                   Persistence Layer                         │
│  vex-persist: SQLite + Migrations + Audit Logs              │
└─────────────────────────────────────────────────────────────┘

Key Concepts

Fractal Agents

Agents are hierarchical and can spawn child agents for subtasks. Each agent has:

Genome — Evolutionary traits mapped to LLM parameters
Context — Hashable context packets with TTL
Shadow — Optional Red agent for verification

Adversarial Verification

Every Blue agent can have a Red shadow that challenges its outputs:

Blue agent generates response
Shadow detects potential issues
Multi-round debate if needed
Consensus voting determines final output

Temporal Memory

Bio-inspired memory with automatic decay:

Horizon	Duration	Max Entries
Immediate	5 min	10
ShortTerm	1 hour	25
MediumTerm	24 hours	50
LongTerm	1 week	100
Permanent	∞	500

Merkle Proofs

All agent decisions are hash-chained:

SHA-256 content hashing
Merkle tree construction
Tamper-evident audit trails
Proof verification in O(log n)

Data Flow

Code

User Request
    │
    ▼
┌─────────┐
│ vex-api │ ─── JWT Auth + Rate Limit
└────┬────┘
     │
     ▼
┌─────────────┐
│ vex-runtime │ ─── Orchestrator
└──────┬──────┘
       │
       ▼
┌──────────────┐     ┌────────────────┐
│  Blue Agent  │ ◄── │  vex-temporal  │
└──────┬───────┘     │  (Memory)      │
       │             └────────────────┘
       ▼
┌──────────────┐
│   vex-llm    │ ─── DeepSeek/OpenAI
└──────┬───────┘
       │
       ▼
┌────────────────┐
│ vex-adversarial│ ─── Shadow verification
└───────┬────────┘
        │
        ▼
   Final Response
   + Merkle Proof

Crate Dependencies

Code

vex-api
├── vex-runtime
│   ├── vex-core
│   ├── vex-adversarial
│   │   └── vex-core
│   └── vex-llm
├── vex-persist
├── vex-queue
└── vex-llm