Data Model

Audience: developer who needs to understand what Cortex stores, how entities relate to each other, and how the taxonomy is structured.

---

The ATOM model

Everything that Cortex stores and serves is an atom. Atoms are typed, versioned, queryable artefacts with six universal layers:

Layer 1 — Identity

Field	Type	Description
id	string	Unique identifier (e.g. atom:referentiel_rnq_v9, bloc:skill_typescript)
type	FEUILLE | COMPOSE	Leaf atom or composite atom
label	string	Human-readable name
sourceDocId	string	Reference to the source document that produced this atom
createdAt	string (ISO 8601)	Creation timestamp

Layer 2 — Classification

Field	Type	Description
famille	string	Top-level family (e.g. GOUVERNANCE, PROFIL, ARKA_DECK, ARKADOC_BLOC)
sousFamille	string	Sub-family within the family (e.g. SAFETY_BASELINE, gouvernance/template)

Layer 3 — Shape

Field	Type	Description
occurrence	string	Semver or domain-specific version (e.g. 1.0.0)
occurrenceKind	string?	Classification of the occurrence
selectionNature	string?	How this atom was selected
data	Record<string, unknown>?	Arbitrary structured payload

Layer 4 — Presence

Field	Type	Description
profiles	string[]?	Which HYOS profiles reference this atom

Layer 5 — Lifecycle

Field	Type	Description
version	string?	Semver version (e.g. 1.2.0)
status	string?	Lifecycle status
contributor	string?	Who last modified this atom

Layer 6 — Enrichment

Field	Type	Description
markdown	string?	Rendered markdown content
examples	string[]?	Usage examples
tags	string[]?	Searchable tags
contentHash	string?	SHA-256 hash of the content (used for idempotent ingestion)

The underlying storage type is GraphNode from @cortex/shared:

interface GraphNode {
  id: string;
  type: string;
  label: string;
  data: Record<string, unknown>;
  sourceDocId: string;
  createdAt: string;
  versionSemver?: string;
  contentHash?: string;
  updatedAt?: string;
}

---

Storage tables

Atoms are stored in SurrealDB across three primary tables, each with a distinct purpose:

atom table

Stores atomic units that are not part of the HYOS catalogue: modes, reglements (governance rules), pipelines, templates, schemas, services, arkadoc_blocs, and arkadoc_types.

Node ID format: atom:<slug> (e.g. atom:referentiel_rnq_v9, atom:adoc_bloc_hero_section).

bloc table

Stores HYOS catalogue blocks: skills, expertises, methods, tools, and scopes. These are the composable building blocks that agent profiles are assembled from.

Node ID format: bloc:<slug> (e.g. bloc:skill_typescript, bloc:methode_audit_technique).

The Bloc type:

interface Bloc {
  id: string;
  label: string;
  blocType: 'skill' | 'expertise' | 'methode' | 'tool' | 'scope';
  category: string;
  description: string;
  trigger?: Record<string, unknown> | string;
  content?: Record<string, unknown>;
  contentRef?: string;
  tags?: string[];
  auteur?: string;
  versionSemver: string;
  contentHash?: string;
  createdAt: string;
  updatedAt: string;
  usedByCount?: number;
}

profil_hyos table

Stores HYOS agent profiles. A profile describes an LLM agent identity: role, mission, mindset, which blocks it composes, what it should never do, and which other profiles it can hand off to.

Node ID format: profil_hyos:<slug> (e.g. profil_hyos:profil_developpeur_fullstack_expert).

interface ProfilHyos {
  id: string;
  label: string;
  serie: string;
  origin: 'modele' | 'sur_mesure' | 'variante';
  parentId?: string;
  owner?: string;
  role: string;
  mission: string;
  mindset?: string;
  keywords?: string[];
  sectors?: string[];
  description?: string;
  metiers?: string[];
  sousFamille?: string;
  famille?: string;
  branche?: string;
  auteur?: string;
  scopeIn?: string[];
  scopeOut?: string[];
  responsibilities?: string[];
  dna?: ProfilDna;
  versionSemver: string;
  contentHash?: string;
  createdAt: string;
  updatedAt: string;
}

Profile origins:

• modele — instantiated from a template model
• sur_mesure — custom-built from scratch
• variante — derived from an existing profile (has parentId)

Profile DNA

Each profile has a computed DNA fingerprint (ProfilDna) that scores it across nine dimensions:

Dimension	Key	Meaning
Specialisation	spe	How focused the profile is on a narrow domain
Autonomy	auto	How self-sufficient (scopes + tools)
Diversity	div	Variety of bloc types attached
Expertise ratio	exp	Expertise blocs vs skill blocs
Core focus	core	Ratio of core vs support blocs
Methodicity	met	Number of method blocs
Stability	stab	Age since creation
Popularity	pop	Number of derived variantes
Sectoricity	sec	Number of sectors covered

---

Taxonomy

The taxonomy organizes atoms into a three-level hierarchy: branche > famille > sous-famille.

Branches

Defined in the ingestion schema (HYOS_BRANCHES):

Branch	Purpose
equipement	Agent equipment (skills, tools, expertises, methods, scopes)
gouvernance	Governance rules, templates, modes
service	Service atoms (pipelines, schemas)
arkadoc_bloc	Document building blocks
arka_deck	Platform-specific atoms (arkadoc_types)

Type routing

The ingestion pipeline routes atoms to the correct storage table based on their type:

Type	Table	Branch
skill	bloc	equipement
expertise	bloc	equipement
methode	bloc	equipement
tool	bloc	equipement
scope	bloc	equipement
mode	atom	gouvernance
reglement	atom	gouvernance
pipeline	atom	service
template	atom	gouvernance
schema	atom	service
service	atom	service
arkadoc_bloc	atom	arkadoc_bloc
arkadoc_type	atom	arka_deck

Taxonomy nodes

Taxonomy is modeled as graph nodes connected by edges:

• famille:<slug> nodes represent top-level families (e.g. famille:canonique_gouvernance).
• sous_famille:<slug> nodes represent sub-families.

The canonical family ID format is famille:canonique_<famille_lowercase> (defined by FAMILLE_CANONIQUE_PREFIX in the ingestion schema).

---

Governance sous-familles

Governance atoms are organized into transversal sous-familles:

Sous-famille	Purpose
SAFETY_BASELINE	Safety baseline rules
META_COGNITION	Self-awareness and reasoning patterns
ERROR_RECOVERY	Error recovery procedures
UNCERTAINTY_MANAGEMENT	Handling uncertainty
SCOPE_CONTROL	Scope boundary enforcement
CONSISTENCY_CONTROL	Cross-layer consistency
GOAL_ALIGNMENT	Goal alignment verification
DISAGREEMENT_HANDLING	Conflict resolution
NAVIGATION_STRATEGY	Navigation strategy rules
gouvernance/template	Governance templates
gouvernance/methode	Governance methods
gouvernance/reglement	Governance regulations

---

Edge types

Cortex uses typed edges to connect nodes in the knowledge graph:

Edge type	From	To	Meaning
belongs_to_famille	atom/bloc	famille	Atom belongs to this family
belongs_to_sous_famille	atom/bloc	sous_famille	Atom belongs to this sub-family
equipe_de	bloc	profil_hyos	Bloc is attached to this profile
authored_by	atom	contributor	Atom was authored by this contributor
instantiated_from	instance	profil_hyos	Instance derived from this profile
belongs_to_project	mission/odm/task/cr	project	Entity belongs to this project
belongs_to_mission	odm/task/cr	mission	Entity belongs to this mission
belongs_to_odm	task/cr	odm	Entity belongs to this ODM
belongs_to_task	cr	task	CR belongs to this task
executed_by	artefact	contributor	Artefact executed by this contributor

Edge storage type:

interface GraphEdge {
  id: string;
  type: string;
  from: string;
  to: string;
  weight?: number;
  data: Record<string, unknown>;
  sourceDocId: string;
  createdAt: string;
}

---

Ingestion schemas

Two Zod schemas govern what enters the catalogue:

arka.hcm.block.v1 (HyosBlockV1Schema)

The canonical schema for blocks and atoms. Structure:

{
  _schema: 'arka.hcm.block.v1',
  _produced_at: string,
  _produced_by: string,
  registre: {
    id: string,
    type: HyosType,        // skill | expertise | methode | tool | scope | mode | reglement | ...
    branche: HyosBranche,  // equipement | gouvernance | service | arkadoc_bloc | arka_deck
    label: string,
    description: string,
    famille: string,
    sous_famille: string,
    tags: string[],
    sectors: string[],
    metiers: string[],
    version: string,
    auteur: string,
    artifact_ref: string,
    trigger: { keywords, contexts, signals, embedding },
    routing: { inject, delivery, priority, cost_tokens },
  },
  artefact: Record<string, unknown>,
}

arka.hcm.profil.v1 (HyosProfilV1Schema)

The canonical schema for HYOS profiles:

{
  _schema: 'arka.hcm.profil.v1',
  _produced_at: string,
  _produced_by: string,
  registre: {
    id: string,
    type: 'profil_hyos',
    branche: 'profil',
    label: string,
    description: string,
    famille: string,         // default: 'PROFIL'
    sous_famille: string,
    tags: string[],
    sectors: string[],
    metiers: string[],
    version: string,
    auteur: string,
    mission: string,
    mindset?: string,
  },
  scope?: { in_scope: string[], out_of_scope: string[] },
  responsibilities: string[],
  composition: {
    expertises: CompositionEntry[],
    skills: CompositionEntry[],
    tools: CompositionEntry[],
    scopes: CompositionEntry[],
    methodes: CompositionEntry[],
  },
}

Where CompositionEntry is:

{ bloc_id: string, poids: 'core' | 'support', raison?: string }

---

Workspace entities

The workspace layer manages project lifecycle entities stored in SurrealDB:

Entity	Table	Key fields
Project	project	label, status, code
Mission	mission	label, status, project_id
Mission Contract (MCT)	mission_contract	label, status, owner, cadrage, casting_mct
ODM (Ordre de Mission)	odm	label, status, priority, assigned_to, category
Task	task	label, status, assigned_to, qa_agent_id, sequence
CR (Compte Rendu)	cr	label, status, type, data
Dispatchmap	dispatchmap	status, steps
Resilience	resilience	status, protocol
Decision	decision	titre, decision, context
Transaction	transaction	transactionType, fromActor, refs

---

Memory entities

Per-project memory stored in SurrealDB:

Entity	Table	Purpose
Agent resume	memory_agent_resume	Agent state summary per project
Project resume	memory_project_resume	Project state summary
Decision	memory_project_decision	Explicit decisions with who/when/why
Error	memory_erreur	Errors encountered with correction and lesson
Pattern	memory_pattern	Recurring patterns observed
Feedback	memory_feedback	Agent-to-agent feedback
Blocage	memory_blocage	Blocking issues with tool/rule/workaround
Besoin	memory_besoin	Identified needs with context
Contradiction	memory_contradiction	Cross-agent contradictions
Resilience signal	memory_resilience_signal	Recovery signals from past incidents
Note Praxis	note_praxis	Operational notes (L1-L5 levels, H2A/A2A flux)
Checkpoint trace	checkpoint_trace	A2A handoff traces with checkpoint validation
CR Note	cr_note	Batch synthesis notes