Cortex — AI Compute Operating System

Model-agnostic, harness-agnostic, protocol-agnostic dispatch kernel for AI workloads.

npm install @sleekai/cortex
npx cortex init            # scaffold .cortex/ state directory
npx cortex add-worker      # register a worker (interactive; or --provider)
npx cortex dispatch "task" # dispatch to best available worker
npx cortex plan "task"     # preview dispatch plan, zero model calls
npx cortex locate "query"  # deterministic code pointers, zero model calls

What is Cortex?

Cortex is the OS for AI compute. It manages dispatch — deciding which AI worker (model, provider, or local process) gets each task, how much context to give it, and whether the result passes validation.

Key properties:

• Capability-planned — intent compiler classifies tasks into 11 capability dimensions; expected-utility planner selects the optimal worker from a registry.
• Budget-capped — hard token budget (default 2500), degrade-cascade that drops lowest-ranked context before expanding.
• Harness-agnostic — CLI subprocess and HTTP/JSON are built-in; the harness registry is extensible (MCP, A2A, browser).
• Stateful metrics, stateless dispatch — per-worker reliability is learned from an append-only JSONL log; every dispatch is a fresh invocation.
• Zero neural dependencies — retrieval uses TF-IDF over identifier tokens, not embeddings.

Architecture

Task → Intent Compiler → Capability Planner → Context Compiler
      → UCP v2 Packet → Budget Controller → Harness → Validated Output

The pipeline lives in one place — the kernel (src/kernel/kernel.ts: planTask / prepareDispatch / runTask). The CLI and the MCP server are thin surfaces over it; every surface persists artifacts, state, and metrics identically.

• Intent compiler — deterministic regex-based classifier (zero model calls)
• Capability planner — expected-utility ladder (EU = quality × reliability / cost × latency)
• Progressive context compiler — 5 levels (L0 file names → L4 full source), budget-aware
• UCP v2 — Ultra-Compact Packet grammar, versioned, single-letter keys
• Worker registry — JSON data, not privileged code; project overlays
• Validation loop — apply → hooks → error-only retry, max 3 iterations
• DAG executor — dependency-ordered parallel dispatch with checkpointing, resume (settled nodes never re-run), and cooperative cancellation

See docs/ARCHITECTURE.md for subsystem designs and docs/AUDIT.md for the repository audit, gap analysis, and deliberate deferrals.

Commands

| Command | Description | |---------|-------------| | cortex init | Scaffold .cortex/ state directory | | cortex dispatch <task> | Dispatch a task to the best worker | | cortex plan <task> | Print dispatch plan, zero model calls | | cortex locate <query> | Deterministic code pointers | | cortex workers | List registered workers | | cortex metrics | Per-worker reliability stats | | cortex add-worker [provider] | Register a worker from a template |

cortex run is an alias for cortex dispatch.

Adding workers

Interactive with no flags, or one-shot:

cortex add-worker opencode                          # zero-config adapter
cortex add-worker claude-cli                        # zero-config adapter
cortex add-worker openai --model gpt-4o-mini --id openai-cheap
cortex add-worker anthropic --model claude-sonnet-4-20250514
cortex add-worker ollama --model llama3.2 --base-url http://localhost:11434
cortex add-worker cli --id my-llamafile --bin ./llamafile

Workers land in .cortex/workers.json — data, hot-swappable, no kernel code.

MCP Server

cortex-mcp (stdio) exposes the kernel to any MCP client: cortex_plan, cortex_locate, cortex_workers, cortex_metrics, cortex_dispatch, cortex_init, plus a cortex://registry resource.

{ "mcpServers": { "cortex": { "command": "npx", "args": ["cortex-mcp"] } } }

Configuration

• CORTEX_DIR env var — override state directory path
• --state-dir flag — per-invocation override (takes precedence)
• .cortex/workers.json — project-local worker registry overlay
• .cortex/state.json — distilled facts, no history
• .cortex/metrics.jsonl — append-only dispatch records
• .cortex/artifacts/<taskId>/ — persisted typed artifacts per task
• .cortex/runs/<runId>.json — execution-graph checkpoints (non-failure node results; failed or cancelled nodes re-run on resume)

UCP v2 Packet Format

See docs/UCP-SPEC.md for the canonical wire format spec.

License

MPL-2.0