Architecture

Architecture

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.

System Overview

┌─────────────────────────────────────────────────────────────────┐
│                         CortexPrism OS                          │
│                                                                 │
│   CLI (cortex agent chat / sandbox run / server start / ...)    │
│          │                                                      │
│          ▼                                                      │
│   ┌─────────────────────────────────────────────┐              │
│   │              kernel/loop.ts                  │              │
│   │  kernelTurn() → process register → dispatch  │              │
│   │  → token/cost accounting → agentTurn()       │              │
│   └──────────────┬──────────────────────────────┘              │
│                  │                                              │
│   ┌──────────────▼────────────────────────────┐                │
│   │              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                   │              │
│   │  kernel/ vfs/ memory/ tools/ sandbox/         │              │
│   │  security/ llm/ server/ scheduler/ voice/     │              │
│   │  codegraph/ computer-use/ plugins/ tui/       │              │
│   │  skills/ workflow/ channels/ triggers/        │              │
│   │  quartermaster/ model-quartermaster/          │              │
│   │  a2a/ hub/ remote/ memori/ mcp-gateway/      │              │
│   │  eval/ update/ projects/ desktop/ services/   │              │
│   │  observability/ ipc/ config/ db/              │              │
│   │  chrome-bridge/ supply-chain/ guardrails/      │              │
│   └──────────────────────────────────────────────┘              │
│                                                                 │
│   SQLite databases (WAL mode)                                   │
│   cortex.db · memory.db · lens.db · vault.db · plugins.db       │
└─────────────────────────────────────────────────────────────────┘

Core Components

Component	Directory	Purpose
OS Kernel	packages/infra/src/kernel/	System call dispatcher, capability enforcement, RBAC, process registry, resource accounting
Virtual FS	packages/gate/src/vfs/	/cortex/* namespace abstraction mapping virtual paths to real FS/DB locations
Agent Loop	src/agent/	Core turn processing, reflection, sub-agents, metacognition, soul, 10 built-in agents, 6-strategy orchestration, HEXACO personality
LLM Layer	packages/ai/src/llm/	30 provider adapters, model router, MQM, observable provider wrapper
Memory System	packages/ai/src/memory/	5-tier memory: episodic, semantic, reflection, graph, skills
Tool System	packages/ai/src/tools/	Registry, executor, 60 built-in tools, 12 capability groups
Security	packages/gate/src/security/	Parallax policy validator, LLM supervisor, AES-256-GCM vault, CPL, multi-user auth (PBKDF2, API tokens, federation)
HTTP Server	packages/server/src/ + src/server/	REST API (200+ endpoints), WebSocket chat, embedded SPA Web UI, OS API endpoints
Sandbox	packages/gate/src/sandbox/	Docker/gVisor code execution, auto-fix loop, environment replication, workspace snapshots, dev env as code, bug repro
Scheduler	packages/infra/src/scheduler/	SQLite-persisted cron jobs, stale job recovery
TUI	packages/cli/src/tui/	Full Deno-native TUI framework: VirtualScreen, Component tree, layout engine, 9 reusable components, 3 themes
Plugins	packages/core/src/plugins/	ESM/MCP/WASM plugin system with sandbox, dependency resolution
Pipeline	packages/ai/src/pipeline/	10-stage hook middleware architecture
Voice	packages/server/src/voice/	STT/TTS pipeline, VAD, audio streaming
Codegraph	packages/server/src/codegraph/	Tree-sitter code intelligence, call graph, FTS5 symbol search, polyglot cross-language FFI analysis
Computer Use	src/computer-use/	GUI automation via Xvfb + xdotool
Skills	packages/ai/src/skills/	Built-in skill definitions, SDK
Workflow	packages/infra/src/workflow/	Workflow engine with DAG execution
Channels	packages/server/src/channels/	9 channel adapters: Discord, Slack, Teams, Telegram, WhatsApp, Google Chat, Lark, Mattermost, RocketChat
Triggers	packages/infra/src/triggers/	Webhook + filesystem event triggers
QM / MQM	packages/infra/src/quartermaster/, packages/infra/src/model-quartermaster/	Tool orchestration + model selection learning
Observability	packages/infra/src/observability/	Prometheus metrics, OTLP export, Langfuse tracing, observable LLM provider wrapper
Remote / Hub	src/remote/, src/hub/	Distributed Hub ↔ Node architecture
Swarm	packages/infra/src/swarm/	Distributed agent swarm — cross-instance coordination via A2A, fleet topology, resource aggregation
A2A Protocol	packages/server/src/a2a/	Agent-to-Agent protocol for cross-instance communication (+ swarm directive transport)
MCP Gateway	packages/server/src/mcp-gateway/	Multi-server MCP gateway with routing and aggregation
MCP	packages/server/src/mcp/	Model Context Protocol server (stdio + HTTP)
Memori	packages/server/src/memori/	Conversation checkpoints, snapshot/restore, branching
Eval	packages/server/src/eval/	Agent evaluation runner
Update System	src/update/	Self-update checking, binary integrity verification
Projects	packages/server/src/projects/	Multi-project management with isolated workspace contexts
Desktop	src/desktop/	Desktop application integration
Services	packages/infra/src/services/	Micro-service registry and lifecycle management
IPC	packages/infra/src/ipc/	Inter-process communication between Cortex components
Config	packages/core/src/config/	Configuration loading, schema validation, path resolution, resource limits
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
Chrome Bridge	packages/ai/src/tools/builtin/chrome_bridge_manager.ts	Real-browser automation via CDP (60 tools)

Agent Loop

The core of CortexPrism. kernelTurn() in packages/infra/src/kernel/loop.ts wraps agentTurn() with process registration and resource accounting, then dispatches:

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 12 rounds):
   • LLM call (streamed or complete) — all calls observed via ObservableLLMProvider wrapper
   • Parse tool calls from response (5 format parser + structural JSON sanitization)
   • Validate each tool call against policy
   • LLM security supervisor review (for sensitive tools)
   • Execute tools (sub-agent calls run in true parallel via Promise.all)
   • 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. Capture memori checkpoint — fire-and-forget state snapshot (auto-prunes to 5 most recent)
10. Pipeline hooks (post-output)

Built-in Agent Profiles

Cortex ships with 10 pre-configured built-in agents with specialized soul prompts:

• Assistant — general-purpose default
• Developer — code writing, debugging, refactoring
• Researcher — web research, documentation, fact-finding
• Architect — system design, planning, trade-off analysis
• Analyst — SQL, data exploration, statistics
• Writer — technical documentation, changelogs, API references
• DevOps — Docker, Kubernetes, Terraform, CI/CD pipelines
• Security — OWASP auditing, CVE scanning, compliance review
• Code Reviewer — structured BLOCKER/SUGGESTION/NITPICK/QUESTION review format
• QA / Tester — test generation, coverage analysis, regression discipline

Built-in agents cannot be deleted but can be customized. The default agent has been migrated from default to assistant with full backward compatibility.

Checkpoint Restore

POST /api/memori/checkpoints/:id/restore rewinds a session to any saved Memori checkpoint, injecting a system message with the checkpoint's resume context (goals, tool history, workspace state). Message replay runs inside a transaction for atomicity.

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 (+ swarm transport)
• 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