Cortex Lite

Status

Cortex Lite is a first-party local runtime shipped with arka-deck. It is:

• a local runtime — own process, own dependencies, own lifecycle;
• an HTTP sidecar — exposed over loopback HTTP, called from arka-deck through /api/cortex-lite/* proxy routes and dedicated outbound HTTP clients;
• the local source of runtime project artefacts (ArkaDoc, memory, atoms, runtime relationships) materialised on the workstation;
• NOT an in-process addon: although the source code lives under addons/cortex-lite/, it is not loaded as a TypeScript Addon in composition/addons/. It is excluded from the root tsconfig.json (addons/cortex-lite has its own tsconfig and its own node_modules) and arka-deck connects to it through HTTP clients only;
• NOT a dynamically-loaded third-party plugin: there is no active third-party marketplace and no runtime loader for foreign sidecars. Cortex Lite is wired explicitly and managed by arka-deck.

Field	Value
Source location	addons/cortex-lite/ (own tsconfig, own package.json, excluded from root TS build)
Manifest	addons/cortex-lite/manifest.json (informational; not loaded as an in-process addon)
Runtime	Local Docker Compose sidecar (Express + SurrealDB)
Integration surface	Loopback HTTP (/api/cortex-lite/* proxy, HttpCortexLite*Client outbound clients)
Lifecycle owner	DockerComposeCortexLiteServiceManager (composition root)
Maturity	stable (production mode)

SPEC-05 (decision C) — Cortex Lite must be described publicly as: a local runtime, an HTTP sidecar, and the local source of runtime project artefacts. Never as a third-party addon dynamically loaded into the arka-deck process.

Role

Cortex Lite provides a local project Cortex to materialize agentic context — without depending on a remote Cortex during local execution.

Its role is not to store files. Cortex Lite maintains a local graph backed by SurrealDB: projects, ArkaDoc artifacts, memory, atoms, profiles, methods, rules, eventmaps and runtime relationships. Agents resolve this graph through API/MCP to understand what to use, when to use it and in which project.

The public Cortex remains the read-only catalogue source. Cortex Lite is the local execution materialization: it links what is useful to the current project with an explicit scope.

Surfaces

Surface	Detail
Declared HTTP APIs	health, projects, artifacts, memory, atoms
MCP tools	cortex_project_context, cortex_memory_read, cortex_memory_write, cortex_artifact_create, cortex_atom_search
Runtime MCP	arka_runtime project MCP for Codex/agents: squad, snapshot, ArkaDoc, tasks, memory and Mission Control
External project MCP	connector_* MCP connectors attached to a project from External sources
Sidecar	Dedicated Docker Compose orchestration for Cortex Lite
arka-deck proxy	/api/cortex-lite/* routes on the Fastify server
Runtime Hub routes	/api/projects/:id/runtime/* routes for project snapshot, docs, tasks and memory
Documentation routes	/api/projects/:id/documentation/* routes for ArkaDoc indexes, blocks, relations and full reads
Local graph	SurrealDB v2 with the Cortex Lite graph schema

Graph model

Cortex Lite materializes runtime relationships rather than simple document storage.

Example relationships:

• project → ArkaDoc artifacts;
• project → local memory;
• project → synced atoms and blocs;
• project → authorized profiles;
• project → available methods and rules;
• project → active modules/packs;
• business pack → documents, profiles, methods, rules and eventmaps scoped to the project.

This model enables:

• giving agents resolved context instead of a raw folder;
• auditing why a profile, method or rule was proposed;
• strictly isolating contexts between projects;
• working locally without exposing the project to a remote Cortex.

Runtime security

Runtime endpoints accept loopback by default and HTTPS hosts *.arkalabs.app. Any arbitrary external host remains refused unless an explicit unsafe development flag is set (see ADR 0006).

Agent runtime MCP

arka-deck can expose a local arka_runtime MCP server to Codex and compatible agents. This MCP is runtime-first: it gives agents the active squad, project snapshot, ArkaDoc documents, task list, memory and Mission Control flowmap without requiring them to inspect the filesystem directly.

This project MCP remains a context surface. It does not carry orchestration write commands: squad start/submit goes through the session-bound arka_orchestration MCP, guarded by the active squad leader role.

Task summaries expose both ids when relevant:

• dispatch_task_id: the ArkaDoc document id to use in dispatch commands.
• business_task_id: the optional business id found inside the ArkaDoc payload.

The dispatch contract is explicit: runtime commands still carry payload.task_id, but the value must be the ArkaDoc dispatch_task_id, not the business id.

Mission Control reads the active guardian pack from Cortex Lite. arka-deck does not ship a hardcoded base guardian pack in the core runtime: governance packs are materialized as Cortex Lite artifacts and carry their own mode registry, transition policy, tool policy, complete rules, mini-rules, mode rules, flowmap, event policy, card templates, prompt layers and document requirements. Runtime packets are role-scoped for solo_agent, team_leader, team_worker, team_qa and team_observer.

A project has zero or one active guardian pack. Business packs bring their own guardian pack instead of extending or overriding a shared base pack.

External project MCP

External MCP connectors are not global. They are attached to a project from External sources → Project MCP and exposed to agents under a connector_* name.

Two sources are supported:

• an already configured connector installation carrying an MCP endpoint;
• a custom HTTP/SSE endpoint validated by the runtime policy.

The project MCP configuration does not carry raw secrets: it references the connector installation or a secret policy. Remote endpoints must use HTTPS; loopback HTTP remains accepted for local servers.

Project Documentation and ArkaDoc indexes

The Project Documentation view reads real ArkaDoc documents through project-documentation routes. Each document gets a consultation index: summary, tags, token estimate, blocks and links.

Agents get the same primitives through MCP:

• search document indexes;
• read one document index;
• read a precise block;
• read incoming/outgoing neighbors;
• open the full document only when needed.

This index is also materialized in Cortex Lite with the ArkaDoc artifact so the local graph can guide document navigation.

Boundaries

Cortex Lite remains a dedicated local runtime. It does not replace a server-side dedicated Cortex — it is a local materialization intended for agent execution on a workstation.

It must not be presented as:

• file storage;
• a multi-user Cortex server;
• a content marketplace;
• an optional fallback when arka-deck cannot resolve its local context;
• a third-party plugin dynamically loaded into the arka-deck process (it is a sidecar reached over HTTP — see SPEC-05 decision C).

Going further

• Runtime URL policy: ADR 0006
• Addon contract: addon contract