Architecture Overview

CortexPrism is a single-process AI Agent Operating System written in TypeScript/Deno. It exposes a CLI, a REST API + WebSocket server, and a web UI. All state is persisted in SQLite databases using WAL mode via @libsql/client.

High-Level Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         CortexPrism                             │
│                                                                 │
│   CLI (cortex chat / run / serve / ...)                         │
│          │                                                      │
│          ▼                                                      │
│   ┌─────────────────────────────────────────────┐              │
│   │              agent/loop.ts                  │              │
│   │  userMessage → [memory inject] → LLM call   │              │
│   │  → [tool parse] → [validator] → [execute]   │              │
│   │  → [re-prompt loop] → response              │              │
│   │  → [episodic write] → [reflection]          │              │
│   └─────────────────────────────────────────────┘              │
│          │                                                      │
│   ┌──────┼──────────────────────────────────────┐              │
│   │      │         Subsystems                   │              │
│   │  memory/   tools/   sandbox/   security/    │              │
│   │  llm/      server/  scheduler/              │              │
│   └──────────────────────────────────────────────┘             │
│                                                                 │
│   SQLite databases (WAL mode)                                   │
│   cortex.db · memory.db · lens.db · vault.db · sess_*.db       │
└─────────────────────────────────────────────────────────────────┘

Core Components

Component	Description
Agent Loop	Core reasoning + tool loop that orchestrates LLM calls, tool execution, memory operations, and reflection
Memory System	5-tier memory with hybrid FTS5 keyword + vector embedding retrieval and exponential decay scoring
LLM Layer	24 provider implementations with unified LLMProvider interface and CascadeRouter
Tool System	Extensible tool registry with built-in tools for file I/O, shell, web search, and code execution
Security (Parallax)	3-stage policy validation gate with encrypted vault, regex deny rules, and full audit logging
Sandbox	Docker container sandbox (subprocess fallback) with resource limits and auto-fix loop
Daemon Supervisor	Background process manager for validator, executor, and scheduler daemons with auto-restart
HTTP Server	Built-in web server with REST API, WebSocket streaming, and web UI dashboard
Scheduler	SQLite-persisted cron job scheduler with retry
Model Quartermaster	Adaptive 6-signal model selection engine with reinforcement learning and context fingerprinting
Git Workspace	Agent-powered git porcelain with auto-commit messages, diff analysis, and branch management
GitHub Integration	PR, issue, and repository management with agent-powered code review and triage
Pipeline System	10-stage hook-based processing pipeline for the agent turn lifecycle (pre/post-assess, pre/post-reason, pre/post-tool, pre/post-reflect, pre/post-output)
Trigger System	File watchers, webhooks, and git hooks that launch agent tasks on external events
Workflow Engine	DSL-based workflow execution with steps, branches, parallel execution, and approval gates
Communication Channels	Plugin-based messaging platform integration (Discord, extensible)
Remote Agents	Distributed node execution via WebSocket hub with capability-based security tiers
MCP Server	Model Context Protocol server exposing Cortex tools and agents to MCP clients
Update System	Dual-mode updates (binary/source) with SHA-256 verification and rollback
Observability	Prometheus-compatible metrics registry and distributed tracing with OTLP export
Desktop Automation	Cross-platform GUI automation (screenshots, clicks, typing, clipboard) for Linux, macOS, Windows
Evaluation Framework	Agent benchmarking with 8 task categories, pattern scoring, and regression detection
Hub Node System	Distributed hub with WebSocket-based node registry, capability tiers, and session routing
Lens Audit Log	Immutable event log for all system actions — LLM calls, tool execution, policy decisions

Data Flow

1. User input enters through CLI, Web UI, or API
2. Agent loop processes input with context from memory
3. LLM provider generates response via the model router
4. Tool calls are executed through the Parallax security gate
5. Results are stored in memory and returned to the user

Core subsystems

• Agent Loop — Core execution engine
• Memory System — 5-tier memory architecture
• Security Parallax — Defense-in-depth security model
• Model Router — Intelligent LLM provider routing
• Daemon Supervisor — Background process management
• Plugin System — Plugin architecture
• Databases — SQLite database schemas
• Quartermaster — Model Quartermaster prediction engine
• Git Workspace — Agent-powered git porcelain
• GitHub Integration — PR/issue/repo management
• Pipeline System — 10-stage hook-based pipeline
• Channels — Communication channel plugins
• Triggers — Event-driven trigger system
• Workflow Engine — DSL-based workflow execution
• Remote Agents — Distributed agent nodes
• MCP Server — Model Context Protocol server
• Update System — Binary/source updates and rollback
• Observability — Metrics and tracing