Architecture

Architecture

CortexPrism is a single-process agentic harness 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.

System Overview

┌─────────────────────────────────────────────────────────────────┐
│                         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 · plugins.db       │
└─────────────────────────────────────────────────────────────────┘

Core Components

Component	Directory	Purpose
Agent Loop	src/agent/	Core turn processing, reflection, sub-agents, metacognition
LLM Layer	src/llm/	24 provider adapters, model router, MQM
Memory System	src/memory/	5-tier memory: episodic, semantic, reflection, graph, skills
Tool System	src/tools/	Registry, executor, 35+ built-in tools
Security	src/security/	Parallax policy validator, AES-256-GCM vault, CPL
HTTP Server	src/server/	REST API, WebSocket chat, embedded Web UI
Sandbox	src/sandbox/	Docker/gVisor code execution, auto-fix loop
Scheduler	src/scheduler/	SQLite-persisted cron jobs
Plugins	src/plugins/	ESM/MCP/WASM plugin system with sandbox
Pipeline	src/pipeline/	10-stage hook middleware architecture
Voice	src/voice/	STT/TTS pipeline, VAD, audio streaming

Agent Loop

The core of CortexPrism. agentTurn() handles one complete user→agent exchange:

1. Inject relevant memories into system prompt
2. Persist user message
3. Tool loop (up to 8 rounds):
   • LLM call (streamed or complete)
   • Parse tool calls from response
   • Validate each tool call against policy
   • Execute tools
   • Format results and re-prompt
4. Persist assistant response
5. Write episodic memory (fire-and-forget)
6. Run reflection if enabled (fire-and-forget)

Databases

Database	Purpose
cortex.db	Sessions, jobs, policies, services, nodes, skills, workspace config
memory.db	5-tier memory: episodic, semantic, reflection, graph
lens.db	Cortex Lens audit log — full activity timeline
vault.db	AES-256-GCM encrypted credential vault
plugins.db	Plugin registry with versions and permissions

Pipeline Hooks

10 middleware hooks intercept the agent loop at key stages:

Hook	Stage	Priority	Purpose
@cortex/injection-guard	pre-reason	5	Prompt injection detection
@cortex/model-quartermaster	pre-llm, post-llm	5	MQM intelligent model selection
@cortex/quartermaster	pre-tool, post-tool	6	Legacy tool orchestration learning
@cortex/summarization	pre-reason	8	Context compaction at 80K tokens
@cortex/content-safety	pre-output	10	Content filtering
@cortex/loop-detection	pre-tool	12	Per-file edit tracking
@cortex/tool-output-sandbox	post-tool	15	Large output capture
@cortex/pre-completion-checklist	post-reason	20	Build-Verify-Fix enforcement
@cortex/audit-log	post-output	150	Session/turn logging
@cortex/cost-tracker	post-tool, post-output	200	Token/cost metrics

See Also

• Request Flow — Mermaid diagrams of the full request lifecycle
• Agent Loop — Deep dive into the agent turn processing
• Memory System — Memory architecture and retrieval