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 → [pipeline hooks]             │              │
│   │  → [memory inject] → [MQM route] → LLM call │              │
│   │  → [tool parse] → [policy validate]         │              │
│   │  → [LLM supervisor gate] → [execute]        │              │
│   │  → [re-prompt loop] → response              │              │
│   │  → [episodic write] → [reflection]          │              │
│   └─────────────────────────────────────────────┘              │
│          │                                                      │
│   ┌──────┼────────────────────────────────────────────┐        │
│   │      │         Subsystems                         │        │
│   │  memory/   tools/   sandbox/   security/          │        │
│   │  llm/      server/  scheduler/ voice/             │        │
│   │  codegraph/ computer-use/ plugins/ pipeline/      │        │
│   │  skills/   workflow/  channels/ triggers/         │        │
│   │  quartermaster/ model-quartermaster/              │        │
│   │  a2a/  hub/  remote/  memori/  mcp-gateway/      │        │
│   │  eval/  update/  projects/  desktop/  services/   │        │
│   └───────────────────────────────────────────────────┘       │
│                                                                 │
│   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, soul
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, 60 built-in tools
Security	src/security/	Parallax policy validator, LLM supervisor, AES-256-GCM vault, CPL
HTTP Server	src/server/	REST API (200+ endpoints), WebSocket chat, embedded SPA 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
Codegraph	src/codegraph/	Tree-sitter code intelligence, call graph, FTS5 symbol search
Computer Use	src/computer-use/	GUI automation via Xvfb + xdotool
Skills	src/skills/	Built-in skill definitions, SDK
Workflow	src/workflow/	Workflow engine with DAG execution
Channels	src/channels/	13 channel adapters: Discord, Slack, Teams, Telegram, WhatsApp, Google Chat, Lark, Mattermost, RocketChat
Triggers	src/triggers/	Webhook + filesystem event triggers
QM / MQM	src/quartermaster/, src/model-quartermaster/	Tool orchestration + model selection learning
Observability	src/observability/	Prometheus metrics, OTLP export, Langfuse tracing
Remote / Hub	src/remote/, src/hub/	Distributed Hub ↔ Node architecture
A2A Protocol	src/a2a/	Agent-to-Agent protocol for cross-instance communication
MCP Gateway	src/mcp-gateway/	Multi-server MCP gateway with routing and aggregation
MCP	src/mcp/	Model Context Protocol server (stdio + HTTP)
Memori	src/memori/	Conversation checkpoints, snapshot/restore, branching
Eval	src/eval/	Agent evaluation runner
Update System	src/update/	Self-update checking, binary integrity verification
Projects	src/projects/	Multi-project management with isolated workspace contexts
Desktop	src/desktop/	Desktop application integration
Services	src/services/	Micro-service registry and lifecycle management
IPC	src/ipc/	Inter-process communication between Cortex components
Config	src/config/	Configuration loading, schema validation, path resolution
Database	src/db/	libSQL client, migration engine, session/lens/vault stores
PKM	PKM system	Personal Knowledge Management with backlinks, tags, knowledge graph
Prompt Lab	Prompt Lab	Prompt engineering IDE with A/B testing and versioning
TUI	src/tui/	Terminal UI

Agent Loop

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

1. Pipeline hooks (pre-assess, pre-reason)
2. Inject relevant memories into system prompt
3. MQM model selection decision
4. Persist user message
5. Tool loop (up to 8 rounds):
   • LLM call (streamed or complete)
   • Parse tool calls from response
   • Validate each tool call against policy
   • LLM security supervisor review (for sensitive tools)
   • Execute tools
   • Format results and re-prompt
6. Persist assistant response
7. Write episodic memory (fire-and-forget)
8. Run reflection if enabled (fire-and-forget)
9. Pipeline hooks (post-output)

Databases

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

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
• Security — Security model and LLM supervisor
• Code Intelligence — Tree-sitter code analysis
• Computer Use — GUI automation
• Plugin System — Extensibility architecture
• A2A Protocol — Agent-to-Agent cross-instance communication
• MCP Gateway — Multi-server MCP routing and aggregation
• Distributed Nodes — Hub ↔ Node remote architecture
• Memori Checkpoints — Conversation snapshot/restore
• Eval System — Agent evaluation runner
• Update System — Self-update and integrity verification
• Projects — Multi-project workspace management
• TUI — Terminal UI
• Triggers — Webhook + filesystem event triggers
• Workflow Engine — DAG-based workflow execution
• Glossary — Terminology reference