Cortex Lite

Statut

Cortex Lite est un runtime local first-party livré avec arka-deck. C’est :

• un runtime local — process propre, dépendances propres, cycle de vie propre ;
• un sidecar HTTP — exposé en loopback HTTP, appelé depuis arka-deck via les routes proxy /api/cortex-lite/* et des clients HTTP outbound dédiés ;
• la source locale d’artefacts runtime projet (ArkaDoc, mémoire, atoms, relations runtime) matérialisée sur le poste de travail ;
• PAS un addon in-process : bien que le code source vive sous addons/cortex-lite/, il n’est pas chargé comme un Addon TypeScript dans composition/addons/. Il est exclu du tsconfig.json racine (addons/cortex-lite a son propre tsconfig et son propre node_modules) et arka-deck s’y connecte uniquement via des clients HTTP ;
• PAS un plugin tiers chargé dynamiquement : il n’y a pas de marketplace tiers actif et pas de loader runtime pour des sidecars externes. Cortex Lite est câblé explicitement et géré par arka-deck.

Champ	Valeur
Emplacement source	addons/cortex-lite/ (tsconfig propre, package.json propre, exclu du build TS racine)
Manifest	addons/cortex-lite/manifest.json (informationnel ; non chargé comme addon in-process)
Runtime	Sidecar local Docker Compose (Express + SurrealDB)
Surface d’intégration	HTTP loopback (proxy /api/cortex-lite/*, clients outbound HttpCortexLite*Client)
Owner cycle de vie	DockerComposeCortexLiteServiceManager (composition root)
Maturité	stable (mode production)

SPEC-05 (décision C) — Cortex Lite doit être décrit publiquement comme : un runtime local, un sidecar HTTP, et la source locale d’artefacts runtime projet. Jamais comme un addon tiers chargé dynamiquement dans le process arka-deck.

Rôle

Cortex Lite fournit un Cortex local de projet pour matérialiser le contexte agentique — sans dépendre d’un Cortex distant pendant l’exécution locale.

Son rôle n’est pas de stocker des fichiers. Cortex Lite maintient un graphe local appuyé sur SurrealDB : projets, artefacts ArkaDoc, mémoire, atoms, profils, méthodes, rules, eventmaps et relations utiles au runtime. Les agents résolvent ce graphe via API/MCP pour comprendre quoi utiliser, quand l’utiliser et dans quel projet.

Le Cortex public reste la source de catalogue en lecture seule. Cortex Lite est la matérialisation locale d’exécution : il relie ce qui est utile au projet courant, avec un scope explicite.

Surfaces

Surface	Détail
API HTTP déclarées	health, projects, artifacts, memory, atoms
Outils MCP	cortex_project_context, cortex_memory_read, cortex_memory_write, cortex_artifact_create, cortex_atom_search
MCP runtime	MCP projet arka_runtime pour Codex/agents : squad, snapshot, ArkaDoc, tasks, mémoire et Mission Control
MCP externes projet	Connecteurs MCP connector_* attachés à un projet depuis Sources externes
Sidecar	Orchestration Docker Compose dédiée à Cortex Lite
Proxy arka-deck	Routes /api/cortex-lite/* côté serveur Fastify
Routes Runtime Hub	Routes /api/projects/:id/runtime/* pour snapshot projet, docs, tasks et mémoire
Routes Documentation	Routes /api/projects/:id/documentation/* pour index, blocs, relations et lecture complète ArkaDoc
Graphe local	SurrealDB v2 avec schéma graphe Cortex Lite

Modèle graphe

Cortex Lite matérialise des relations runtime plutôt qu’un simple stockage documentaire.

Exemples de relations :

• projet → artefacts ArkaDoc ;
• projet → mémoire locale ;
• projet → atoms et blocs synchronisés ;
• projet → profils autorisés ;
• projet → méthodes et rules disponibles ;
• projet → modules/packs actifs ;
• pack métier → documents, profils, méthodes, rules et eventmaps scopés au projet.

Ce modèle permet :

• de fournir aux agents un contexte résolu plutôt qu’un dossier brut ;
• d’auditer pourquoi un profil, une méthode ou une rule a été proposée ;
• d’isoler strictement les contextes entre projets ;
• de travailler localement sans exposer le projet à un Cortex distant.

Sécurité runtime

Les endpoints runtime acceptent le loopback par défaut et les hosts HTTPS *.arkalabs.app. Tout host externe arbitraire reste refusé sauf flag unsafe de développement explicitement activé (cf. ADR 0006).

MCP runtime agent

arka-deck peut exposer un serveur MCP local arka_runtime à Codex et aux agents compatibles. Ce MCP est runtime-first : il donne aux agents la squad active, le snapshot projet, les documents ArkaDoc, la liste des tasks, la mémoire et la flowmap Mission Control sans les pousser à inspecter directement le filesystem.

Ce MCP projet reste une surface de contexte. Il ne porte pas les commandes write d’orchestration : start/submit squad passent par le MCP session-bound arka_orchestration, gardé par le rôle leader de la squad active.

Les résumés de task exposent les deux ids quand c’est pertinent :

• dispatch_task_id : l’id du document ArkaDoc à utiliser dans les commandes de dispatch.
• business_task_id : l’id métier optionnel trouvé dans le payload ArkaDoc.

Le contrat de dispatch est explicite : les commandes runtime portent toujours payload.task_id, mais la valeur doit être le dispatch_task_id ArkaDoc, pas l’id métier.

Mission Control lit le guardian pack actif depuis Cortex Lite. arka-deck ne porte plus de pack de base hardcodé dans le runtime core : les packs de gouvernance sont matérialisés comme artefacts Cortex Lite et portent leur propre registre de modes, politique de transition, politique de tools, règles complètes, mini-rules, règles par mode, flowmap, event policy, templates de cards, couches d’injection et exigences documentaires. Les packets runtime sont adaptés par rôle : solo_agent, team_leader, team_worker, team_qa et team_observer.

Un projet a zéro ou un guardian pack actif. Les packs métier apportent leur propre guardian pack au lieu d’étendre ou d’overrider un pack de base partagé.

MCP externes par projet

Les connecteurs MCP externes ne sont pas globaux. Ils sont attachés à un projet depuis Sources externes → MCP projet et exposés aux agents sous un nom connector_*.

Deux sources sont supportées :

• une installation connecteur déjà configurée qui porte un endpoint MCP ;
• un endpoint custom HTTP/SSE validé par la politique runtime.

La configuration MCP projet ne porte pas de secret brut : elle référence l’installation connecteur ou une politique de secret. Les endpoints distants doivent utiliser HTTPS ; le HTTP loopback reste accepté pour les serveurs locaux.

Documentation projet et index ArkaDoc

La vue Documentation projet lit les documents ArkaDoc réels via les routes project-documentation. Chaque document reçoit un index de consultation : résumé, tags, estimation de tokens, blocs et liens.

Les agents disposent des mêmes primitives côté MCP :

• rechercher dans les index ;
• lire l’index d’un document ;
• lire un bloc précis ;
• lire les voisins entrants/sortants ;
• ouvrir le document complet seulement quand c’est nécessaire.

Cet index est aussi matérialisé dans Cortex Lite avec l’artefact ArkaDoc pour que le graphe local puisse guider la navigation documentaire.

Limites

Cortex Lite reste un runtime local dédié. Il ne remplace pas un Cortex dédié serveur — c’est une matérialisation locale destinée à l’exécution agentique sur poste de travail.

Il ne doit pas être présenté comme :

• un stockage de fichiers ;
• un Cortex serveur multi-utilisateurs ;
• une marketplace de contenus ;
• un fallback optionnel si arka-deck ne peut pas résoudre son contexte local ;
• un plugin tiers chargé dynamiquement dans le process arka-deck (c’est un sidecar joint en HTTP — cf. SPEC-05 décision C).

Pour aller plus loin

• Politique runtime URL : ADR 0006
• Contrat addon : contrat addon