CORTEX

Collaborative Optimized Reinforcement & Temporal Evolutionary eXecution

A GPU-accelerated, real-time multi-agent swarm intelligence research platform.

CORTEX simulates a living population of autonomous neural agents that learn, evolve, and cooperate entirely on your local hardware. Unlike prompt-engineered LLM systems, every agent carries a genuine PyTorch policy network that trains in real-time on your NVIDIA GPU via CUDA. No cloud APIs. No pretrained weights. Pure emergent intelligence.

---

Architecture

CORTEX implements a hybrid Social-Evolutionary Multi-Agent Learning (SEMAL) algorithm combining three distinct optimization pathways:

1. Individual Neural Policy (SocioNet)

Each agent runs a custom lightweight multilayer policy network (SocioNet) that maps 26-dimensional sensory inputs to three continuous action outputs:

Input Dimensions	Source
24 raycast channels (8 rays × 3 types)	Food proximity, hazard distance, peer position
1 normalized energy level	Internal metabolic state
1 base speed constant	Kinematic reference

Output	Range	Controls
Steering	[-1.0, 1.0]	Turning force (radians/step)
Thrust	[0.0, 1.0]	Acceleration magnitude
Cooperation	[0.0, 1.0]	Social energy sharing threshold

2. Social Learning — Cultural Policy Distillation

Every 25 frames, each agent scans its spatial neighborhood (160px radius) and moves its network weights toward the local elite peer:

$$\theta_i \leftarrow \theta_i + \beta \cdot (\theta_{\text{elite}} - \theta_i)$$

This replicates cultural transmission — the tendency of individuals in social systems to imitate high-performing neighbors, accelerating collective convergence.

3. Generational Evolution — Genetic Algorithm

At the end of each generation epoch (650 simulation steps), a genetic algorithm selects the next population:

• Elite Preservation: Top 15% of agents pass their weights directly to the next generation.
• Crossover: Remaining offspring are bred via uniform parameter tensor crossover between two tournament-selected parents.
• Gaussian Mutation: Each offspring's weights are perturbed with controlled noise (σ=0.12, p=0.15) to maintain genetic diversity.

4. Persistent Memory Vault

Whenever an agent surpasses 90% of the current fitness record, its brain weights are serialized and committed to a local SQLite database (cortex.db). On the next boot, CORTEX automatically loads the best historical checkpoint and seeds the entire population with it — so evolution picks up exactly where it left off.

---

Performance Architecture

CORTEX is engineered to run efficiently on a laptop GPU without overheating:

Optimization	Details
Batched GPU Inference	All alive agent sensor tensors are stacked into a single matrix and passed to the GPU in one forward pass per frame
Broad-Phase Raycast Filter	Agents skip intersection math for entities beyond sensor range using cheap squared-distance checks
Cached Homogeneity Index	Cultural homogeneity recalculates every 100 frames instead of every frame
GPU Load Balancer	Background daemon thread keeps GPU utilization between 60–70% using dynamic matrix workloads
OS Thread Yielding	Enforced 1ms sleep yields after each render tick to prevent CPU core saturation

---

Requirements

• Python 3.8+
• NVIDIA GPU with CUDA support (recommended — automatic CPU fallback is built in)
• VRAM: 4 GB minimum, 6 GB recommended

pygame>=2.0.0
numpy>=1.21.0
matplotlib>=3.4.0
psutil>=5.8.0
torch>=2.0.0  # CUDA build recommended

---

Quick Start

# Clone the repository
git clone https://github.com/your-username/CORTEX.git
cd CORTEX

# Launch CORTEX (auto-installs dependencies)
./run_cortex.bat       # Windows

The launcher audits your Python environment, verifies PyTorch and CUDA availability, and boots the simulation. On subsequent runs, it will automatically resume from the highest-fitness saved checkpoint.

---

Interface

CORTEX opens a cybernetic HUD split into two panels:

Simulation Playground (Left — 800×600)

• Agents: Triangular entities navigating in real-time.
  • 🟦 Cyan: Independent exploration mode.
  • 🟣 Purple: Social imitation active — currently copying an elite neighbor.
• Food (cyan dots): Consuming food awards +20 fitness and restores +30 energy.
• Hazards (red circles): Contact drains energy and penalizes fitness per step.
• Obstacles (orange lines): Static walls forcing navigational adaptation.
• Raycast Visualization: Click any agent to display its 8 directional sensor rays live.

Telemetry Panel (Right — 350px)

• Generation / Population / Fitness / Homogeneity real-time readouts.
• Live Fitness Chart: Average and peak fitness curves plotted across generations.
• Hyperparameter Sliders: Adjust mid-simulation without restarting:
  • Engine Speed (FPS) — Simulation tick rate
  • Mutation Rate — Genetic diversity noise magnitude
  • Social Learning Rate (β) — Peer weight interpolation speed
• System Log Console: Scrolling terminal with epoch completions, checkpoint saves, and resume events.

---

Project Structure

CORTEX/
├── main.py           # Main simulation loop, checkpoint resume, session management
├── swarm.py          # CortexSwarm & CortexAgent — physics, batched inference, evolution
├── model.py          # SocioNet — PyTorch policy network, mutation, crossover
├── environment.py    # CortexEnvironment — raycasting, collision physics, food spawning
├── gui.py            # CortexGUI — Pygame HUD, live charts, sliders, event handling
├── database.py       # CortexDatabase — SQLite session tracking, checkpoint persistence
├── gpu_balancer.py   # GPULoadBalancer — background GPU utilization regulation daemon
├── run_cortex.bat    # Windows launcher with dependency validation
├── cortex.db         # SQLite database (auto-created on first run)
└── requirements.txt  # Python dependency manifest

---

Fitness Scoring

Event	Fitness Delta	Energy Delta
Food consumed	+20.0	+30.0
Hazard contact (per step)	-0.2	-0.6
Energy shared with starving peer	+1.0	-5.0
Wall collision	0	0 (bounce)
Survival (passive, per step)	-0.15 thrust energy cost	-0.15

---

License

CORTEX is an open research project. Contributions, forks, and extensions are welcome.

"Intelligence is not a property of individuals — it is a property of populations."