Cortex concepts
Ce contenu n’est pas encore disponible dans votre langue.
This document explains product terms in logical order: from the atomic data unit to the orchestration abstractions built on top.
An atom is the fundamental unit of knowledge in Cortex. Everything that Cortex stores and serves is an atom — a typed, versioned, queryable artefact identified by a stable identifier.
Every atom shares six universal layers:
| Layer | Fields | Purpose |
|---|---|---|
| 1 — Identity | id, type, label, sourceDocId, createdAt | Who is this artefact? |
| 2 — Classification | famille, sousFamille | Where does it belong in the taxonomy? |
| 3 — Shape | occurrence, occurrenceKind, selectionNature, data | What does it contain? |
| 4 — Presence | profiles[] | Which profiles or contexts use it? |
| 5 — Lifecycle | version_semver, status, contributor | What version is it? Who contributed? |
| 6 — Enrichment | markdown, examples, tags, contentHash | Human-readable content and integrity check. |
Atoms come in two structural types:
- FEUILLE — a leaf atom, indivisible.
- COMPOSE — a composite atom that references other atoms.
The taxonomy organizes atoms into familles (top-level categories) and sous-familles (sub-categories), modeled as nodes connected by belongs_to_famille and belongs_to_sous_famille edges in the graph.
A bloc is a catalogue block — a structured, executable instruction that an agent can receive to frame its behavior. Blocs are a specialization of atoms stored in the bloc table.
Cortex defines five bloc types:
| Bloc type | Purpose | Example |
|---|---|---|
| skill | A practical capability the agent can perform | ”Write a technical spec from user stories” |
| expertise | Deep domain knowledge in a specific area | ”French labor law compliance” |
| methode | A step-by-step process to follow | ”7-axis QA audit method” |
| tool | An external tool the agent is allowed to use | ”MCP server for SurrealDB” |
| scope | A boundary or permission declaration | ”Can execute in dev environment only” |
Each bloc has a category, a description, optional tags, a versionSemver and a contentHash. Blocs can carry structured content (a JSON object with domain-specific payload) or a contentRef pointing to an external resource.
Blocs are the building blocks that compose profiles.
HYOS profile
Section titled “HYOS profile”A HYOS profile describes an LLM agent identity. It is not a free-form system prompt; it is a structured entity stored in the profil_hyos table.
A profile carries:
- label — human-readable name (e.g. “QA Auditor”, “Legal Advisor”)
- role — the role the agent plays
- mission — what the agent is expected to accomplish
- mindset — behavioral guidance (e.g. “end_to_end_ownership”, “zero_tolerance”)
- scopeIn / scopeOut — what the agent should and should not do
- responsibilities — explicit list of duties
- keywords — searchable terms
- sectors — industry domains (e.g. “legal”, “finance”, “healthcare”)
Profiles compose blocs through equipe_de graph edges. The principle: the profile carries identity, blocks carry techniques. A profile must be coherent even without its blocks.
Profile origins
Section titled “Profile origins”| Origin | Meaning |
|---|---|
| modele | Template profile from the catalogue, ready to be instantiated |
| sur_mesure | Custom profile created from scratch |
| variante | Derived from an existing profile with modifications |
Profile DNA
Section titled “Profile DNA”Each profile has a computed DNA — a multi-dimensional score derived from its attached blocs:
- spe (specialization) — how focused the profile is
- auto (autonomy) — how self-sufficient
- div (diversity) — how many bloc types it uses
- exp (expertise vs skill) — ratio of deep knowledge to practical capability
- core (focus) — core vs support balance
- met (methodicity) — how method-driven
- stab (stability) — how long the profile has been around
- pop (popularity) — how many variants have been derived from it
- sec (sectority) — how many sectors it covers
Governance pack
Section titled “Governance pack”A governance pack is a collection of atoms from transversal governance sous-familles. These atoms define the behavioral rules that frame what agents can and cannot do.
Cortex governance covers multiple axes:
- SAFETY_BASELINE — foundational safety rules
- META_COGNITION — self-awareness and reflection rules
- ERROR_RECOVERY — how to handle and recover from errors
- UNCERTAINTY_MANAGEMENT — behavior under ambiguity
- SCOPE_CONTROL — staying within declared boundaries
- CONSISTENCY_CONTROL — maintaining coherence across outputs
- GOAL_ALIGNMENT — staying aligned with the mission
- DISAGREEMENT_HANDLING — resolving inter-agent conflicts
- NAVIGATION_STRATEGY — how to move through complex tasks
Governance rules are enforced server-side by Cortex. When a request violates a rule, Cortex returns a structured 4xx error — it does not rely on the LLM’s ability to self-police.
Mission contract (MCT)
Section titled “Mission contract (MCT)”A mission contract is the top-level agreement that frames a unit of work. It contains:
- cadrage — summary, objectives, scope (in and out), risks, constraints
- casting_mct — the team composition (leader, experts, QA, human PM) with lane assignments and capacity
- odm_plan — the ordered list of ODMs (work orders) to be executed
- dates — start, end, deadline
- outputs_expected — deliverables with acceptance criteria
- audit trail — history of events and amendments
Mission contracts follow a lifecycle: DRAFT -> SUBMITTED -> VALIDATED -> IN_PROGRESS -> COMPLETED (or REFUSED, AMENDED).
ODM (Ordre de mission)
Section titled “ODM (Ordre de mission)”An ODM is an individual work order within a mission contract. It represents a bounded unit of work assigned to one or more contributors.
Each ODM carries:
- A summary and objectives
- scope_in / scope_out boundaries
- casting_odm — which contributors are assigned, with roles (expert, QA, leader_signataire)
- dependencies on other ODMs
- outputs_expected with acceptance criteria
- dod (definition of done)
- rejection_criteria and limitations
ODM statuses: DRAFT -> VALIDATED -> READY_TO_DISPATCH -> IN_PROGRESS -> COMPLETED (or CANCELLED, ARCHIVED).
Priority levels: P0 (critical), P1 (high), P2 (normal), P3 (low).
A task is the executable unit within an ODM. It is assigned to a specific agent, has a QA agent and a QA method, and tracks its own lifecycle:
DRAFT -> PENDING -> READY -> IN_PROGRESS -> DELIVERED -> QA_IN_PROGRESS -> VERDICT_READY -> SIGNED (or REWORK, FAILED, PAUSED_ASK).
Each task carries:
- inputs — references or inline content the agent needs
- outputs — what the agent must produce, with links to dependent tasks
- acceptance_criteria and rejection_criteria
- dod (definition of done)
When a task is completed, the agent produces a Task CR (completion report) with implementation details, evidence, test results and a DOD validation checklist.
CR (Completion report)
Section titled “CR (Completion report)”A CR is a structured report produced by an agent after executing a task. Cortex distinguishes:
- Task CR — the expert’s delivery report (files created/modified, evidence, DOD validation, verdict)
- QA CR — the QA agent’s review (method applied, dimensions evaluated, blocking issues, recommendations, pass/fail verdict)
QA verdicts: PASS, FAIL, RESERVE, NOT_OBSERVABLE.
Memory
Section titled “Memory”Cortex stores per-project memory in dedicated tables. Memory is not chat history — it is a semantic extraction of what is worth reusing across sessions.
Agent-level memory
Section titled “Agent-level memory”| Type | What it captures |
|---|---|
| MemoryDecision | Explicit decisions: what, why, impact, status |
| MemoryErreur | Errors and their corrections, lessons learned |
| MemoryPattern | Recurring patterns observed during execution |
| MemoryFeedback | Feedback from other agents |
| MemoryBlocage | Blockers: what, which tool/rule, workaround |
| MemoryBesoin | Needs identified during execution |
Project-level memory
Section titled “Project-level memory”| Type | What it captures |
|---|---|
| MemoryProjectDecision | Project-wide decisions with contributors |
| MemoryProjectRisque | Risks detected, severity, mitigation |
| MemoryProjectConvention | Conventions adopted by the team |
| MemoryProjectReserve | Reserves (issues deferred for later) |
| MemoryContradiction | Contradictions between agents, with perspectives |
Praxis notes and checkpoints
Section titled “Praxis notes and checkpoints”- NotePraxis — operational notes written by agents, with levels L2 through L5 and a CR level. Can be H2A (human-to-agent) or A2A (agent-to-agent).
- CheckpointTrace — handoff traces between agents in structured missions, with validation mode, resilience protocol and pass/fail status.
- MemoryResilienceSignal — recovery signals from past incidents.
Memory entries support optional embeddings for semantic similarity and a lastReferencedAt timestamp for recency tracking.
Versioning
Section titled “Versioning”Every artefact in Cortex has a versionSemver (semantic version) and a contentHash (SHA-256). The versioning system provides:
Automatic version bumps
Section titled “Automatic version bumps”When an artefact is mutated, a change classifier (detectChangeType) determines whether the change is a patch (cosmetic), minor (additive) or major (breaking). The version is bumped accordingly.
Immutable instances
Section titled “Immutable instances”When a project instantiates a catalogue artefact, Cortex creates an instance — an immutable snapshot tied to a specific version. Later, the project can check whether the catalogue version has drifted.
Drift detection
Section titled “Drift detection”A ProjectDrift report lists all instantiated artefacts that have diverged from the current catalogue version, with field-by-field diffs.
Changelog
Section titled “Changelog”Cortex uses SurrealDB’s CHANGEFEED to maintain a per-table changelog with timestamps, actions (CREATE, UPDATE, DELETE), version bumps, changed fields and content hashes. Retention varies by strate: 365 days for catalogue tables, 90 days for workspace tables, 365 days for memory tables.
Divergence and cross-pollination
Section titled “Divergence and cross-pollination”When multiple instances of Cortex run independently (e.g. different teams, different projects), their catalogues evolve separately.
Snapshots
Section titled “Snapshots”A snapshot captures the full state of an instance: blocs, profiles, modeles, governance atoms, taxonomy, patterns and blockers. Each snapshot carries its own content hash for integrity.
Divergence report
Section titled “Divergence report”A divergence report compares two snapshots across five weighted axes:
| Axis | Weight | What it measures |
|---|---|---|
| Topology | 15% | Nodes/edges added, removed, modified; density ratio |
| Catalogue | 30% | Blocs created, modified, unused; emerging categories |
| Profiles | 25% | Modeles used/unused; variants and custom profiles created |
| Governance | 15% | SOPs modified, governance atoms added |
| Learning | 15% | Patterns detected, blockers detected, conventions adopted |
The global score (0-100) tells you how much two instances have diverged.
Cross-pollination
Section titled “Cross-pollination”A cross-pollination signal is emitted when two independent instances produce the same or semantically similar artefact. Signals carry a confidence score and a recommendation: promote_to_souche (merge into the shared catalogue), investigate, or ignore.
Workspace and projects
Section titled “Workspace and projects”A workspace is the top-level container in Cortex. Within a workspace, you create projects. Each project has its own lifecycle (ACTIVE, PAUSED, ARCHIVED) and its own memory scope.
Projects contain missions, ODMs, tasks, CRs, decisions and interventions. The workspace layer lets you manage multiple independent work contexts from a single Cortex instance.
What next?
Section titled “What next?”- See the vocabulary at a glance: glossaire
- Explore use cases: 04-use-cases
- Understand the API surfaces: 06-rest-and-mcp