Mémoire & apprentissage — architecture à trois niveaux

Mémoire & apprentissage du harness agentique

Cette page décrit comment le harness agentique se souvient (mémoire à trois niveaux), retrouve l'information pertinente (rappel sémantique par similarité vectorielle) et capitalise ses erreurs et succès en règles réutilisables (boucle cicatrices → apprentissage → leçons).

1. Mémoire à trois niveaux

Le système distingue trois mémoires de granularité et de discipline d'écriture croissantes.

┌─────────────────────────────────────────────────────────────────┐
│ NIVEAU 1 — Mémoire réflexe                                      │
│   Chargée dans CHAQUE session. Règles dures, feedbacks,         │
│   références. Stricte, une entrée par ligne dans l'index.       │
├─────────────────────────────────────────────────────────────────┤
│ NIVEAU 2 — Base de connaissance (Zettelkasten)                  │
│   Le « pourquoi » : décisions, doctrine, concepts. Exploratoire.│
│   Zone brouillon = dépôt libre ; zone consolidée = validation   │
│   humaine obligatoire.                                          │
├─────────────────────────────────────────────────────────────────┤
│ NIVEAU 3 — Index sémantique vectoriel                           │
│   Index vectoriel HNSW (similarité cosinus, 1024 dimensions)    │
│   couvrant l'ensemble des deux niveaux précédents + tables DB.  │
│   Permet le rappel RAG (Retrieval-Augmented Generation).        │
└─────────────────────────────────────────────────────────────────┘

Niveau 1 — Mémoire réflexe

• Un fichier index liste toutes les entrées actives (une ligne par entrée, ≤ 200 caractères chacune).
• Les détails vivent dans des fichiers thématiques : retours d'expérience, préférences utilisateur, références de projet.
• Ces fichiers sont injectés automatiquement dans le contexte de chaque session : aucun rappel explicite n'est nécessaire. Seules les vraies doctrines à fort impact y figurent — la discipline de saisie est stricte.

Niveau 2 — Base de connaissance Zettelkasten

• Organisée en sous-espaces distincts : notes permanentes (consolidées), boîte de réception (brouillons), tables des matières, journaux quotidiens, notes éphémères.
• Les notes s'inter-référencent par des liens wiki ; un frontmatter YAML indique le type et le statut de chaque note.
• Règle de promotion : la boîte de réception est la seule zone où l'agent écrit librement. La zone permanente n'est jamais modifiée sans ordre explicite d'un opérateur humain. Aucune fusion automatique entre les deux zones n'est autorisée — c'est un garde-fou architectural.

Niveau 3 — Index sémantique vectoriel

• Les vecteurs sont de dimension 1024, produits par un modèle d'embedding dédié.
• L'index utilise la structure HNSW (Hierarchical Navigable Small World) avec la similarité cosinus, ce qui garantit des recherches approximatives très rapides même sur des corpus volumineux.
• Une contrainte d'unicité par paire (type de source, identifiant de source) évite les doublons lors des mises à jour.

2. Indexation

Deux automates distincts alimentent les niveaux 2 et 3. Il est important de ne pas les confondre : le premier alimente un index structurel de la base de connaissance (utilisé par les interfaces et la recherche par critères) ; le second alimente l'index vectoriel sémantique (utilisé pour le rappel RAG).

2.1 Automate d'indexation structurelle de la base de connaissance

Cet automate parcourt l'ensemble des sous-espaces de la base de connaissance et maintient une représentation structurée de chaque note dans la base de données relationnelle.

• Périmètre : notes permanentes, boîte de réception, tables des matières, journaux quotidiens, notes éphémères.
• Traitement : extraction du frontmatter YAML et des liens inter-notes de chaque fichier.
• Synchronisation incrémentale : comparaison de la date de modification du fichier avec la valeur en base ; seules les notes modifiées sont recalculées. Les notes supprimées sont retirées de l'index.
• Données conservées par note : chemin relatif, type, titre, tags, frontmatter complet, corps, liens sortants, taille, horodatages.
• Options : mode force (réindexation complète) et mode stats (comptage sans écriture).
• Cadence : toutes les 15 minutes. L'opération est idempotente.

2.2 Automate d'embedding et de synchronisation vectorielle

Cet automate produit les vecteurs sémantiques de l'ensemble des sources et les insère dans l'index vectoriel. Il utilise un modèle d'embedding externe (1024 dimensions).

Les sources indexées et leur volume indicatif sont :

Type de source	Origine	Volume indicatif
Cicatrices	Erreurs enregistrées par le moteur de réflexes (toutes entrées avec description)	~740
Victoires	Succès enregistrés par le moteur de réflexes	~4
Mémoire réflexe	Fichiers de la mémoire de niveau 1 (hors index principal)	~226
Base de connaissance	Notes des différents sous-espaces Zettelkasten	~14
Doctrines	Règles doctrinales actives	~25
Chantiers	Projets en cours	~10
Agents	Descripteurs d'agents	~30
Exercices (drills)	Scénarios d'entraînement	~31
Conduites	Procédures opérationnelles actives	~17
Itérations ReAct	Triplets raisonnement / action / observation des boucles agentiques	~16

Mécanismes clés de l'automate :

• Déduplication par empreinte : chaque chunk reçoit une empreinte SHA-256 de son contenu. Si la paire (type, identifiant) existe déjà avec la même empreinte, le chunk est ignoré — aucun appel au service d'embedding n'est effectué.
• Chunking : dans la version actuelle, chaque document constitue un chunk unique, tronqué au-delà d'un seuil de caractères. Un découpage plus fin est prévu en phase ultérieure.
• Traitement par lots : les appels au service d'embedding regroupent 50 inputs par requête afin de limiter la latence réseau.
• Insertion : chaque vecteur est inséré ou mis à jour atomiquement selon la contrainte d'unicité (type, identifiant).
• Options : mode rebuild (purge complète puis réembedding total), filtre par type de source, mode dry-run (simulation sans écriture).

2.3 Réindexation immédiate d'une cicatrice

Lorsqu'une cicatrice est gravée pendant une boucle agentique active (cycle ReAct), une procédure de réindexation unitaire est déclenchée immédiatement : la cicatrice devient searchable dans le RAG sans attendre la synchronisation nocturne suivante. Ce mécanisme garantit que l'agent peut bénéficier d'une leçon apprise quelques secondes après l'avoir enregistrée, y compris au sein du même run.

2.4 Cadences de maintenance

Les différents automates de mémoire s'exécutent selon les plannings suivants :

• Indexation structurelle de la base de connaissance : toutes les 15 minutes.
• Synchronisation vectorielle complète (incrémentale) : quotidienne, tôt le matin. La réindexation unitaire des cicatrices (§ 2.3) reste active en parallèle pour l'immédiateté.
• Boucle de consolidation nocturne : nuit, peu après minuit — propose des synthèses de la boîte de réception vers la zone permanente (validation humaine requise).
• Détecteur de patterns : hebdomadaire (dimanche).
• Détecteur de propositions de compétences : hebdomadaire (dimanche) et surveillance horaire.
• Métriques mémoire : quotidien, matin.
• Consolidation mensuelle : 1^er du mois.
• Cadran de maintenance : quotidien, tôt le matin.

Note architecturale : aucun de ces automates ne modifie la zone permanente de la base de connaissance sans validation humaine explicite. L'ensemble du pipeline est conçu pour être idempotent : une exécution supplémentaire ne produit pas d'effet de bord indésirable.

Recall RAG

Le moteur de rappel sémantique permet d'interroger la mémoire indexée du système via une requête en langage naturel. Il opère selon trois modes de recherche complémentaires, fusionnés par défaut en un mode hybride.

Flux de traitement

La requête entrante est traitée selon le mode sélectionné :

• Mode sémantique : la requête est vectorisée par le modèle d'embedding (vecteurs 1024 dimensions), puis comparée à l'index par distance cosine. Les résultats sont triés par similarité décroissante.
• Mode lexical : les mots de trois caractères ou plus sont extraits et combinés en une requête OR. La correspondance est calculée par score de rang textuel sur le contenu indexé en français. Ce mode ne fait appel à aucune API externe — aucune clé n'est requise. Il rattrape efficacement les slugs et noms propres que l'embedding tend à flouter.
• Mode hybride (défaut) : les deux classements précédents sont fusionnés par Reciprocal Rank Fusion (RRF, paramètre k=60). Le score combiné est score = Σ 1/(60 + rang_i). Un document absent d'un des deux modes reçoit un score nul pour ce mode, sans pénaliser l'autre.

Un filtre de périmètre (scope) commun aux trois modes permet de restreindre la recherche à certaines catégories de sources : historique d'itérations, cicatrices, victoires, mémoire de référence, doctrine, chantiers en cours, profils d'agents, protocoles, ou la totalité des sources.

Re-classement par importance et récence

Après la première sélection, un sur-fetch (par défaut trois fois le nombre de résultats demandés) permet un re-classement enrichi, appliqué aux cicatrices uniquement. La formule est :

score_final = similarité × (1 + importance/10) × exp(−âge_jours / 365)

Effet concret : une cicatrice récente de haute importance est boostée d'un facteur ~2×, tandis qu'une cicatrice ancienne de faible importance voit son score réduit à ~0,4×. Ce mécanisme garantit que les apprentissages frais et critiques remontent en tête.

Anti-oubli : incrémentation du compteur de rappel

Chaque cicatrice effectivement servie voit son compteur de rappel incrémenté de 1 et sa date de dernier rappel mise à jour. Cette opération est non bloquante : une erreur éventuelle est silencieuse et ne perturbe pas la réponse. Le système de cron d'archivage ne purge que les cicatrices dont le compteur de rappel est resté à zéro — celles qui ont été rappelées au moins une fois sont préservées.

Interprétation des scores

• En mode sémantique : score > 0,75 → très pertinent ; 0,65–0,75 → pertinent ; < 0,65 → à valider manuellement.
• En mode hybride (défaut) : les scores RRF sont sur une échelle différente (typiquement < 0,1). Se fier au rang relatif, pas aux seuils absolus.

Options de la commande de rappel

• --k : nombre de résultats à retourner.
• --mode lex|sem|hybrid : mode de recherche (défaut : hybrid).
• --scope : périmètre de sources à interroger.
• --json : sortie machine au format JSON.

Déclenchement automatique avant création

Un déclencheur automatique s'active avant toute création de nouveau chantier. Il extrait le titre de la tâche et lance une recherche hybride sur les quatre résultats les plus proches. En cas d'indisponibilité de l'API d'embedding (limite de débit atteinte), le mode lexical prend le relais. Les résultats sont injectés dans le flux de diagnostic avant la création, de façon non bloquante. L'objectif est d'éviter de réinventer une cicatrice, une doctrine ou un chantier déjà connu — la recherche sémantique rattrape les entrées que l'index linéaire de mémoire manquait.

Harness d'évaluation du recall

Le système de non-régression du recall repose sur un harness d'évaluation automatisé. Il charge un golden dataset — un ensemble de requêtes associées aux identifiants de sources attendus, effectivement présents dans l'index vectoriel — et mesure la qualité de la recherche sans jamais muter les compteurs de rappel (mode lecture seule strict).

Métriques calculées

Métrique	Définition
recall@k	Fraction des sources attendues retrouvées dans le top-k, moyennée sur l'ensemble des requêtes.
mrr@10	Inverse du rang du premier résultat pertinent dans le top-10 (0 si absent), moyenné sur les requêtes.
top1_accuracy	Fraction des requêtes pour lesquelles le premier résultat correspond à une source attendue.

La correspondance entre un résultat retourné et une source attendue est évaluée par inclusion de sous-chaîne (insensible à la casse), ce qui la rend robuste aux variations de préfixes de chemin et de formats d'identifiants.

Gestion du débit API

Pour les modes faisant appel à l'API d'embedding, un délai de temporisation de 1,3 secondes est introduit entre chaque appel. En cas de réponse de limitation de débit (HTTP 429), un backoff exponentiel est appliqué jusqu'à cinq tentatives. Le mode lexical seul ne sollicite aucune API et ne requiert aucun délai.

Commandes et codes de sortie

Mode / option	Effet	Code de sortie
(aucune option)	Mode gate : compare les métriques courantes au baseline figé. Échoue si la régression dépasse la tolérance.	0 (succès) / 1 (régression)
--baseline	Fige un nouveau baseline en lançant l'évaluation en mode hybride.	0
--mode-sweep	Compare les trois modes (lexical, sémantique, hybride) à titre informatif, sans gate.	0
--tol <valeur>	Tolérance de régression acceptable (défaut : 0,05).	—
--json	Sortie au format machine.	—
(baseline absent)	Avertissement : aucun baseline de référence trouvé.	2

Note opérationnelle : le harness d'évaluation ne modifie jamais l'état de la base de données. Il est conçu pour s'exécuter en intégration continue sans effet de bord sur les compteurs anti-oubli ni sur les métadonnées des cicatrices indexées.

Boucle d'apprentissage : erreurs, vérifications, suggestions et leçons

C'est le cœur de la capitalisation. Une erreur (ou un succès) devient une donnée, puis une suggestion concrète, puis — après validation humaine — une règle chargée dans toutes les sessions futures.

Le flux général se déroule en quatre temps :

1. Une tâche résolue (ou un pattern reproductible) est enregistrée dans le registre des leçons.
2. Un moteur de suggestion lit les entrées marquées comme apprises et produit une proposition structurée.
3. Un opérateur humain valide, refuse ou modifie chaque proposition depuis le tableau de bord.
4. La règle validée est appliquée dans la destination appropriée et devient active dès la session suivante.

4.1 Le registre des leçons

Le registre des leçons est la source unique de vérité pour toute la capitalisation. Chaque entrée documente soit un échec résolu, soit un succès reproductible. Les champs clés sont :

• Le type d'entrée (kind) : distingue les échecs, les succès et quelques catégories historiques (convention, pattern, bug). La grande majorité des entrées sont des échecs résolus.
• La leçon (check_added) : pour un échec, ce qu'on a ajouté pour ne pas recommencer ; pour un succès, le pattern à reproduire.
• Le score d'importance : calculé automatiquement par un modèle de langage au moment de l'enregistrement, via le moteur de routage IA. Non bloquant — si le modèle est indisponible, le score est renseigné lors de la prochaine maintenance nocturne. L'importance pondère la fréquence de rappel (un bonus est accordé aux entrées les plus critiques).
• L'indicateur d'apprentissage (learnable) : porte d'entrée du moteur de suggestion. Seules les entrées marquées true sont traitées.

Bonne pratique — graver un succès : passer par la skill dédiée (/victoire) plutôt que par du SQL direct. Le champ tags doit être fourni au format tableau PostgreSQL littéral ("{a,b,c}"), pas une liste Python — une leçon apprise en production.

4.2 Le moteur de suggestion : de la leçon à la proposition

Le moteur de suggestion lit le registre des leçons, filtre les entrées marquées comme apprenables et non encore traitées, puis appelle un modèle de langage pour produire une proposition structurée. Le pipeline en détail :

1. Sélection : les entrées apprenables absentes du journal de propositions, triées par importance décroissante puis par date, dans la limite de 50 par exécution.
2. Purge des données personnelles avant envoi au modèle. L'output du modèle est également filtré avant insertion — défense en profondeur.
3. Appel LLM : le modèle retourne un objet JSON contenant la destination cible, le texte de la suggestion, et les différences avant/après (diff_before / diff_after).
4. Insertion dans le journal de propositions avec le statut pending. L'opération est idempotente ; un délai court entre chaque appel évite de saturer l'API.

Les six destinations possibles pour une proposition :

Destination	Sens
Directive orchestrateur	Règle à ajouter ou modifier dans le fichier de directives principal de l'agent
Configuration hooks	Paramètre de permissions, hooks ou variables d'environnement
Note persistante (niveau 1)	Réflexe immédiat injecté dans chaque briefing via la mémoire courante
Boîte de réception conceptuelle	Nouvelle note Zettelkasten (concept ou doctrine à maturation)
Skill	Création ou amélioration d'une skill invocable
Chantier ou outil	Nouveau chantier automatisé ou script utilitaire

4.3 Validation humaine et journal d'audit

Aucune proposition n'est appliquée automatiquement. Le tableau de bord expose trois opérations :

• Consulter le flux (lecture) : liste des propositions en attente.
• Appliquer (écriture) : la proposition passe au statut applied et une entrée est créée dans le journal d'audit avec l'identifiant de l'opérateur et un instantané du diff.
• Refuser ou modifier (écriture) : la proposition passe au statut refused ou modified.

Le journal d'audit conserve pour chaque action : la référence à la proposition, l'auteur de la décision, l'horodatage et l'instantané du diff appliqué.

4.4 Leçons post-chantier (bilan structuré)

En complément de la boucle cicatrices → suggestions, un outil de bilan post-chantier permet d'extraire des leçons après la clôture d'un chantier. Il est invocable par un agent dédié via la skill correspondante.

Le mécanisme charge un bundle d'audit complet : métadonnées du chantier, travaux, tâches, itérations récentes, cicatrices liées et journaux d'exécution tronqués. Le volume d'entrée est plafonné pour rester sous les limites du modèle.

• Garde-fou ROI : un chantier comptant moins de trois travaux est refusé par défaut (contournable via un flag explicite).
• Modèle par défaut : l'appel LLM passe par le binaire Claude via un wrapper en lecture seule (outils Read, Grep, Glob uniquement), avec deux tentatives et une pause entre les deux.
• Fallback : si le binaire est absent ou si un mode alternatif est explicitement demandé, un second fournisseur est utilisé, avec jusqu'à trois tentatives et un backoff exponentiel.
• Prompt figé en cinq sections : écart tokens estimés/réels, top 3 erreurs récurrentes, top 3 patterns à standardiser, une doctrine candidate, un outil à créer.
• Sortie : une note de leçon au format Zettelkasten, avec statut draft, déposée dans la boîte de réception du Vault.
• Promotion : jamais automatique. L'opérateur déplace manuellement la note vers la mémoire permanente (RAG) ou la mémoire courante (réflexe) après relecture.

4.5 Détection de patterns et propositions de skills

Un second pipeline, distinct de la boucle cicatrices, transforme les patterns récurrents observés dans les boucles de travail en propositions de skills invocables. C'est le mécanisme d'auto-amélioration des capacités de l'écosystème.

Journal des itérations de tâches (actions/observations terminées)
      │ scan hebdomadaire (dimanche 04h UTC)
      ▼
Détecteur de patterns (LLM-first via sous-processus, timeout 3 min)
      │ repère les patterns présents dans ≥ 3 tâches
      │ vérifie l'absence de doublons (skill existante ou proposition déjà pendante)
      │ INSERT proposition (status='pending', itérations sources, évidence LLM)
      ▼
Tableau de bord des propositions de skills ── validation HUMAINE (fondateur)
      │ liste / valider / rejeter
      ▼
Promotion vers le registre des skills natives (invocable par /<slug>)

• Détecteur opérationnel (cron hebdomadaire, dimanche 04h UTC) : charge les itérations récentes au statut done ou pass, passe le batch au modèle de langage qui identifie les patterns méritant une skill, puis insère les propositions dans le journal après déduplication. Flags --dry-run et --limit disponibles.
• Moniteur de propositions (cron horaire) : alerte le fondateur si le nombre de propositions en attente dépasse un seuil configurable. Cool-down d'une heure pour éviter les doublons d'alerte. Les statistiques incluent les totaux par statut, le temps moyen de validation et les ajouts dans la dernière heure. L'alerte transite par la façade email centrale — jamais par une connexion SMTP directe.
• Validation humaine : une page dédiée du tableau de bord liste les propositions et permet de valider ou rejeter chacune. Une proposition validée est promue vers le registre des skills natives.

À ne pas confondre : le détecteur opérationnel décrit ci-dessus est le seul à alimenter réellement le journal de propositions. Il existe un second module-squelette (cron dominical 03h UTC) dont la docstring précise explicitement qu'il scanne et journalise sans encore créer de propositions — la logique de détection y est à venir. Ce n'est pas lui qui produit les propositions actives.

4.6 Automates connexes de la boucle d'apprentissage

Consolidation nocturne (boucle de maintenance)

Un automate de maintenance nocturne (exécution quotidienne à 04h UTC) consolide les apprentissages en dix fonctionnalités distinctes. Chaque fonctionnalité résout son modèle de langage depuis le routeur IA central. La règle transversale absolue : aucun déplacement automatique de la boîte de réception vers la mémoire permanente ou courante — toute promotion reste humaine. Le mode sans écriture (--dry-run) est le défaut.

• Détection de cicatrices répétées : compare les nouvelles entrées du jour aux entrées passées via similarité vectorielle. Si au moins deux occurrences similaires sont trouvées, un brouillon de promotion est généré dans la boîte de réception.
• Compaction de sessions : analyse les journaux de session du jour (maximum 30, en sautant ceux contenant des secrets détectés par regex), extrait de 3 à 5 faits durables (décision, livraison, cicatrice, constat) et les consigne dans le journal quotidien. En mode dry-run, aucun appel LLM n'est effectué.
• Récapitulatif matinal : email de synthèse envoyé via la façade email centrale, uniquement si des brouillons ou des journaux ont été produits dans la nuit.
• Audit de divergence documentaire : vérifie les paliers tarifaires canoniques, scanne les patterns obsolètes définis dans un fichier de configuration, et signale les tableaux à forte densité numérique qui gagneraient à être stockés en base de données. Les écarts sont déposés en brouillon dans la boîte de réception.
• Réflexion nocturne : pour chaque agent actif, les 20 cicatrices résolues les plus saillantes alimentent un LLM qui produit 3 questions introspectives et 3 abstractions, déposées en brouillon. En mode dry-run, seul le comptage des agents éligibles est effectué.
• Courbe d'oubli : archive (sans effacement) les cicatrices très anciennes sans aucun rappel enregistré, dans la limite de 200 par exécution. L'archivage les rend invisibles au moteur de rappel sémantique mais reste réversible.
• Pro-activité chantier : scrute les chantiers avec contacts externes actifs, relie automatiquement les emails entrants et sortants correspondants, et soumet le fil reconstitué à un LLM qui classe la situation : à archiver, action requise, en attente de réponse externe, ou aucune action nécessaire.
• Audit d'obsolescence interne : évalue les chantiers inactifs depuis un seuil de jours configurable, calcule leurs signaux d'obsolescence, et produit un verdict (toujours pertinent / peut-être obsolète / archivage recommandé) persisté dans le journal d'obsolescence. Les verdicts non-« toujours pertinent » remontent dans l'email matinal pour décision de l'opérateur.
• Audit de dérive de persona : exécuté uniquement le 1er du mois. Compare le profil actuel de chaque agent à sa configuration de référence, calcule un score de dérive, le persiste en historique, et remonte le top 3 des agents les plus dérivés dans l'email matinal.
• Ticket de coût quotidien : agrège les coûts IA de la veille par agent, compare à la moyenne sur 7 jours, et envoie une alerte email si le delta dépasse 20 % pour un agent donné.

Classificateur de cicatrices

Un automate de qualification classe les cicatrices non encore catégorisées. Le modèle de langage retourne un objet structuré contenant :

• Une catégorie proposée pour le type d'erreur.
• Une sévérité réestimée (mise à jour si différente de l'actuelle).
• Un indice de confiance et un raisonnement.
• Des tags proposés.

Note : l'indicateur d'apprentissage (learnable) n'est pas écrit directement dans la colonne correspondante par cet automate. Il est sérialisé en préfixe du champ de raisonnement sous la forme learnable:true|false — comportement documenté et intentionnel.

Hygiène de la mémoire courante

Un pipeline de consolidation mensuel (premier du mois, 00h00 UTC, avec verrou anti-overlap) nettoie la mémoire courante en quatre étapes séquentielles :

1. Validation d'environnement : vérifie que les variables d'environnement requises et les chemins sont accessibles. En cas d'échec, le pipeline s'arrête sans exécuter les étapes suivantes.
2. Détection de liens morts : scanne le fichier d'index de la mémoire et produit un rapport des références brisées. Cette étape s'exécute même en mode dry-run et peut écrire des rapports sur le disque.
3. Archivage des fichiers obsolètes : déplace les fichiers marqués comme démantelés ou obsolètes vers une zone d'archive hors-dépôt, supprime les références correspondantes dans l'index.
4. Déduplication par empreinte : identifie et supprime les fichiers strictement identiques (empreinte SHA-256).

Un rapport JSON est généré à chaque exécution, indiquant pour chaque étape le statut, la durée et les éventuelles erreurs. Les codes de sortie sont :

Code	Sens
0	Pipeline complet réussi (ou validation seule réussie)
1	Validation d'environnement échouée — aucune étape exécutée
2	Erreur fatale dans une étape — pipeline interrompu
3	Mode dry-run terminé — aucune modification réelle

Flags disponibles : --dry-run (étapes 3 et 4 court-circuitées ou simulées, étape 2 toujours active), --validate-only (arrêt après l'étape 1).

Important : le module de formation documentant ce pipeline (support de formation consolidation) est lu en dur par le quiz de non-régression. Le supprimer sans adapter le quiz au préalable ferait échouer au moins quatre vérifications et bloquerait le pipeline de validation.

Observabilité de la mémoire courante

Un automate quotidien (06h00 UTC) enregistre une série temporelle sur 90 jours : nombre de fichiers, taille totale, nombre de lignes dans l'index, liens morts et références orphelines. Des alertes sont émises dans le système de supervision si les seuils configurés sont dépassés. Flags : --json, --dry-run.

4.7 Rappel du modèle utilisateur (canal structuré)

Le rappel sémantique vectoriel n'est pas l'unique canal de mémoire. Un module dédié charge le modèle utilisateur depuis la base de données — un profil structuré en dimensions JSONB — et l'injecte dans les briefings agents. Ce rappel est ciblé et structuré, pas vectoriel.

• Dimensions disponibles : style de communication, horaires, profil, compétences, historique, préférences, données strictement privées réservées à l'opérateur principal.
• Tranche composite core : agrège le style de communication, les préférences cognitives et les créneaux de rendez-vous, calibrée pour l'injection briefing (moins de 1 000 tokens). N'inclut jamais les données privées réservées.
• API : get_profile(slice=…) retourne un dictionnaire ; format_for_briefing(…) retourne un texte prêt à l'injection. Une interface en ligne de commande permet d'interroger ces tranches directement, avec options --json et --format-briefing.

Boucle de maintenance nocturne

La boucle de maintenance nocturne constitue la méta-couche au-dessus des cycles d'apprentissage : un orchestrateur qui s'exécute chaque nuit, inspecte la fidélité de la documentation par rapport au code, mesure la santé globale du système, répare mécaniquement les références mortes, déclenche la régénération autonome des chapitres dérivés, puis pousse un instantané assaini vers synedre.com.

La séquence d'étapes s'enchaîne dans l'ordre suivant :

1. Perception initiale — le détecteur de dérive mesure l'écart entre documentation et code.
2. Couverture — le détecteur d'angles morts identifie les zones non documentées.
3. Réparation — le correcteur de références mortes traite mécaniquement les liens brisés.
4. Régénération profonde — la réécriture approfondie, soumise à des gardes-fous, reconstruit les chapitres dérivés.
5. Proposition — un cycle de mise en attente produit des brouillons en zone de staging.
6. Publication documentation — les chapitres passent des portes anti-fuite, anti-dérive et de style avant activation.
7. Re-perception — le détecteur de dérive effectue une seconde mesure après régénération, afin que le bilan de santé reflète l'état réel post-régénération et non l'état de début de nuit.
8. Bilan de santé — les cinq dimensions vitales sont agrégées et un commentaire de soin est rédigé.
9. Publication snapshot — un instantané assaini est poussé vers synedre.com (mode best-effort).

Le déclenchement automatique a lieu chaque jour à 05 h 00 UTC via le planificateur de tâches du système. Les journaux d'exécution sont conservés dans le répertoire de logs dédié à cette boucle.

Orchestrateur de la boucle

L'orchestrateur constitue l'unique point d'entrée de la boucle nocturne. Il embarque plusieurs gardes-fous globaux :

• Coupe-circuit en base : si l'entrée correspondant à cette boucle dans la table de configuration des automates indique active = 0, l'exécution s'interrompt silencieusement.
• Verrou anti-chevauchement : un fichier de verrou temporaire portant le PID courant est créé au démarrage. Si un processus identifié par ce PID est déjà actif, la boucle s'arrête immédiatement. Le verrou est systématiquement supprimé en fin d'exécution, même en cas d'exception dans une sous-étape.
• Codes de retour sémantiques : les codes 1 et 2 signalent respectivement « dérive présente » et « santé critique » — ce sont des statuts informatifs, non des échecs fatals. Le seul cas de sortie non-zéro bloquante est le crash réel d'une sous-étape.
• Rapport quotidien : en fin de boucle, un enregistrement idempotent est inséré dans la table de rapport du matin, résumant le code de retour de chaque étape.

Les options de pilotage disponibles sont les suivantes :

Option	Effet
(aucune)	Exécution complète en mode live
--dry-run	Toutes les sous-étapes opèrent en simulation ; le coupe-circuit DB est contourné
--no-deep	Saute l'étape de régénération profonde
--deep-max N	Plafond dur du nombre de chapitres traités en profondeur (défaut : 4) ; la convergence réelle reste bornée par le budget-temps
--deep-budget-sec N	Budget-temps maximal en secondes pour la régénération profonde (défaut : 4 500 s / 75 min) ; aucun nouveau chapitre n'est lancé au-delà de ce seuil

Bilan de santé multi-dimensionnel

Le composant de bilan de santé agrège cinq dimensions vitales en un instantané idempotent par date d'exécution, visible dans le tableau de bord du matin.

Dimension	Ce qui est mesuré	Seuil critique
Proprioception	Table de dérive documentaire	≥ 1 chapitre avec référence morte
Couverture	Table de couverture documentaire	≥ 1 unité non couverte
Dette	Backlog de tâches priorisées	≥ 1 tâche de priorité maximale en attente
Apprentissage	Vue matérialisée des indicateurs de cicatrices	Rafraîchissement absent depuis plus de 3 jours
Automates	Journal d'erreurs cron + registre des automates	≥ 1 script du périmètre vaisseau-mère désactivé involontairement

Périmètre des automates surveillés : seuls les automates appartenant au périmètre vaisseau-mère et marqués actifs sont pris en compte. Les automates appartenant à un tenant client ou désactivés volontairement ne dégradent pas la métrique de santé globale.

Note de soin : l'agent Nightingale (Gardien de la Santé) lit les signes vitaux agrégés et rédige une note de soin en trois phrases maximum, en anglais. Cette note est stockée dans le champ JSON de l'enregistrement global du bilan de santé. Si l'agent est indisponible, le champ reste vide sans bloquer le reste de la boucle.

Options disponibles : --dry-run (affiche le bilan sans écriture), --no-voice (métriques seules, sans note de soin). Codes de sortie : 0 = nominal, 1 = avertissement, 2 = critique.

Publication du snapshot assaini vers synedre.com

Ce composant lit en lecture seule les derniers instantanés de santé et de dérive sur le VPS du vaisseau-mère, applique une passe d'assainissement automatique (suppression des adresses IP, chemins internes et identifiants clients), puis pousse un instantané JSON vers la base de données du VPS synedre.com.

Gardes-fous :

• Aucune écriture n'est effectuée sur la base du vaisseau-mère : la connexion est strictement en lecture.
• La table de destination est créée idempotement au premier lancement si elle n'existe pas.
• Un seul snapshot est conservé par date (UPSERT sur la clé date).
• Une erreur lors de la poussée vers le VPS synedre.com génère un log d'erreur et un code de retour 2, mais n'interrompt pas la boucle nocturne (mode best-effort).

Le snapshot expose la santé globale et par dimension (scores, statuts, résumés assainis), la liste des chapitres en dérive (avec leur score), et la note de soin de l'agent Nightingale. Ces données alimentent le cadran de maintenance accessible depuis la section documentation de synedre.com.

Options : --dry-run (affiche le JSON sans écriture). Codes de sortie : 0 = nominal, 1 = erreur lecture vaisseau-mère, 2 = erreur poussée vers synedre.com.

Façade IA centralisée

L'ensemble des appels à des services d'intelligence artificielle au sein du système passe par une façade unique. Cette doctrine garantit que toute modification de fournisseur, de modèle ou de clé se fait en un seul endroit, sans toucher aux automates métier.

Deux fonctions canoniques sont exposées :

• Vectorisation (embed) : transforme un texte en vecteur flottant, utilisé pour la recherche sémantique et le rappel de mémoire.
• Complétion (complete) : envoie une mission et un contexte à un modèle de langage et retourne la réponse textuelle ou JSON.

Routage par base de données

Lorsque le paramètre fournisseur est réglé sur auto, la façade lit la table de routage IA en base pour déterminer quel fournisseur et quel modèle utiliser selon la fonctionnalité demandée. Cette table expose une ligne de repli global ainsi qu'une ligne par fonctionnalité nommée, fusionnée avec le repli.

Avantage clé : changer de fournisseur revient à modifier une seule ligne en base — aucun redéploiement n'est nécessaire. La boucle nocturne relit la configuration à chaque exécution. Si la base est inaccessible ou vide, des valeurs par défaut canoniques prennent le relais (mode fail-soft).

Fournisseurs et modèles par défaut :

Usage	Fournisseurs supportés	Modèle par défaut
Vectorisation	Mistral, Voyage, OpenAI	mistral-embed / voyage-3 / text-embedding-3-small
Complétion	Anthropic (Claude), Mistral, OpenAI	claude-haiku-4-5 / mistral-large-latest / gpt-4o-mini

Le fournisseur de vectorisation canonique est Mistral, retenu pour des raisons de souveraineté européenne des données.

Complétion Anthropic : deux chemins de facturation

Le fournisseur Anthropic dispose de deux chemins d'appel distincts, sélectionnés automatiquement à l'exécution :

• Appel API directe : si la clé API du fournisseur Anthropic est présente dans l'environnement ou passée en paramètre, la façade appelle directement l'API REST. Ce chemin est utilisé pour les clients disposant d'un compte Console propre (facturation séparée). Il inclut une logique de réessai sur les erreurs temporaires (code 429 ou 5xx), un suivi de consommation en base (tokens, coût estimé, étiquette de facturation par tenant), et la résolution d'alias courts (haiku, sonnet, opus) vers les identifiants complets de modèle.
• Appel via l'agent interne : en l'absence de clé API dans l'environnement, la façade délègue à l'agent Gauss (persona neutre), qui utilise le forfait interne. Ce chemin est réservé à l'usage interne du vaisseau-mère.

Complétion Mistral

Les appels Mistral passent par l'API REST avec une température nulle (sorties déterministes) et un mode JSON si demandé. La façade effectue jusqu'à trois tentatives en cas d'erreur temporaire (code 429 ou 5xx) avec une attente croissante entre chaque essai. Les erreurs 4xx non temporaires (paramètre invalide, quota dépassé définitivement, etc.) sont considérées comme permanentes et ne déclenchent pas de réessai. Tout retour None est journalisé sur la sortie d'erreur.

Suivi de consommation

Chaque complétion effectuée via l'API directe Anthropic est tracée en base : fournisseur, modèle, étiquette fonctionnelle, nombre de tokens en entrée et en sortie, coût estimé en USD. Ce mécanisme permet la refacturation par tenant. L'écriture en base est encapsulée dans un bloc de protection : une erreur de traçage ne bloque jamais la complétion elle-même.

Clés API et sécurité

Règle absolue : aucune valeur de clé ou de secret n'apparaît dans cette documentation ni dans le dépôt versionné. Toutes les clés sont lues depuis des fichiers d'environnement exclus du contrôle de version.

La façade lit les variables d'environnement suivantes au démarrage :

Fournisseur	Variable d'environnement	Usage
Mistral	Clé API Mistral	Vectorisation et complétion Mistral
Voyage	Clé API Voyage	Vectorisation Voyage
OpenAI	Clé API OpenAI	Vectorisation et complétion OpenAI
Anthropic	Clé API Anthropic	Complétion API directe (chemin clients)
Base de données	Mot de passe de la base principale	Connexion au moteur de persistance du vaisseau-mère

Le chargement s'effectue au démarrage depuis les fichiers d'environnement situés à la racine du dépôt, via os.environ.setdefault (les valeurs déjà présentes dans l'environnement système ne sont pas écrasées).

Connexion à la base de données

Le moteur de persistance du vaisseau-mère est un service PostgreSQL conteneurisé. Les automates Python s'y connectent en spécifiant le bon nom de base et le schéma dédié au vaisseau-mère via l'option search_path. Le port d'exposition sur la machine hôte est distinct du port interne du conteneur afin d'éviter toute collision.

Tous les accès en lecture (rappel sémantique, synchronisation de vecteurs) comme en écriture (journaux, bilans de santé, rapports quotidiens) utilisent la même chaîne de connexion, garantissant un point de configuration unique pour l'ensemble des automates.

Tableau récapitulatif des composants

Ce tableau liste l'ensemble des composants qui constituent la boucle d'apprentissage et de mémoire de Synedre OS, classés par rôle fonctionnel.

Composants d'indexation et de mémoire

Composant	Type	Rôle
Indexeur de notes	Tâche périodique (toutes les 15 min)	Transforme les notes du cerveau documentaire en entrées relationnelles consultables.
Synchroniseur de vecteurs	Tâche nocturne + déclenchement en ligne	Calcule et stocke les représentations vectorielles (1024 dimensions) de toutes les sources ; mode incrémental la nuit, recalcul unitaire à la demande lors d'un cycle de raisonnement.
Table des vecteurs	Table	Stocke les vecteurs sémantiques avec index HNSW cosine pour la recherche approximative de plus proches voisins.
Table des notes indexées	Table	Représentation relationnelle du Zettelkasten documentaire, alimentée par l'indexeur de notes.
Dataset doré de rappel	Fichier de référence	Jeu de questions-réponses de référence utilisé par le harnais d'évaluation du rappel.
Baseline de rappel	Fichier de référence figé	Scores de référence figés (rappel@k, MRR, top-1) servant de seuil de non-régression.

Composants de rappel et d'évaluation

Composant	Type	Rôle
Moteur de rappel	RAG	Combine recherche lexicale, sémantique et hybride (fusion par rang réciproque, k=60) ; sélectionne les top-K résultats, les re-classe et remonte leur score d'usage.
Harnais d'évaluation du rappel	Assurance qualité	Mesure recall@k, MRR@10 et précision top-1 sur le dataset doré ; bloque toute régression par rapport à la baseline figée.
Rappel pré-chantier	Crochet d'événement (déclenchement avant création)	Exécute un rappel hybride top-4 avant toute création de structure de chantier ; non bloquant, enrichit le contexte de l'agent sans interrompre le flux.
Rappel utilisateur	Personnalisation	Exploite le modèle utilisateur multidimensionnel pour produire des briefings contextualisés à destination des agents.
Table du modèle utilisateur	Table	Stocke les dimensions JSONB du profil de chaque utilisateur, utilisées pour personnaliser les briefings de rappel.

Composants de maintenance nocturne

Composant	Type	Rôle
Orchestrateur de maintenance nocturne	Tâche nocturne (vers 5 h)	Coordonne la boucle complète de régénération : perception → couverture → réparation → régénération → proposition → publication de documentation → re-perception → soin → publication.
Bilan de santé	Diagnostic	Évalue cinq dimensions de santé du système et enregistre le résultat dans les tables de suivi ; alimente également le journal quotidien de l'équipe.
Synchroniseur public de santé	Export assaini	Produit un instantané sanitisé (sans données sensibles) des indicateurs de santé et de dérive, synchronisé vers le VPS public.
Table des snapshots de santé	Table	Historique des évaluations de santé par date et par dimension (cinq dimensions + score global).
Table des snapshots publics	Table	Instantanés assainis jour par jour, répliqués vers le VPS public pour exposition sur synedre.com.
Moteur de consolidation nocturne	Tâche toutes les 4 h	Consolide dix fonctionnalités de mémoire à long terme ; s'exécute en mode simulation par défaut (aucune écriture sans validation explicite).
Hygiène mensuelle de la mémoire	Tâche mensuelle	Nettoie le corpus mémoriel : suppression des liens morts, archivage des entrées obsolètes, déduplication par empreinte de contenu ; produit un rapport de consolidation daté.
Métriques mémoire	Tâche toutes les 6 h	Calcule les indicateurs de volumétrie et de qualité de la mémoire ; conserve une série temporelle sur 90 jours et émet des alertes si des seuils sont franchis.
Table des métriques mémoire	Table	Série temporelle des indicateurs mémoire sur 90 jours de rétention.

Composants d'apprentissage et de qualification

Composant	Type	Rôle
Réflexe post-chantier	Rétrospective	Produit une leçon structurée à l'issue de chaque chantier et l'injecte dans la boîte de réception du cerveau documentaire ; utilise un modèle de langage avancé par défaut, avec repli automatique vers un modèle alternatif.
Moteur de suggestions d'apprentissage	Moteur LLM	Analyse les leçons marquées comme apprenables et génère des suggestions d'amélioration en attente de validation humaine.
Qualificateur de leçons	Classification LLM	Attribue à chaque leçon un type d'erreur, un niveau de sévérité, un score de confiance et un raisonnement ; préfixe les leçons apprenables pour les distinguer dans la file d'attente.
Table des leçons	Table	Stocke les leçons (échecs et victoires), leur importance et leur statut apprenable.
Table des suggestions d'apprentissage	Table	File d'attente des suggestions LLM en attente de validation par l'équipe.
Journal d'audit des apprentissages	Table	Trace immuable de chaque suggestion validée et appliquée.

Composants de détection de patterns et de compétences

Composant	Type	Rôle
Détecteur de compétences émergentes	Tâche hebdomadaire (dimanche 4 h)	Analyse les patterns d'itérations récurrentes et soumet des propositions de nouvelles compétences pour validation humaine. Composant fonctionnel : les propositions sont réellement insérées en base.
Moniteur de propositions	Tâche horaire	Émet une alerte à destination de l'équipe fondatrice si le nombre de propositions de compétences en attente dépasse un seuil configurable.
Squelette de détection de patterns	Tâche hebdomadaire (dimanche 3 h) — MVP inactif	Parcourt et journalise les patterns sans créer de propositions. Composant en cours de développement, distinct du détecteur de compétences émergentes.
Table des propositions de compétences	Table	File d'attente des propositions de nouvelles compétences en attente de validation humaine.
Table des compétences natives	Table	Référentiel des compétences actives du système ; cible de promotion des propositions validées.
Interface de validation des compétences	Interface utilisateur (cadran hub)	Permet à l'équipe de valider ou rejeter les propositions de compétences directement depuis le hub de pilotage.

Composants transverses

Composant	Type	Rôle
Façade IA	Abstraction	Point d'entrée unique pour toutes les opérations d'inférence (embedding et complétion) ; route chaque appel vers le fournisseur et le modèle appropriés selon une table de routage centrale ; supporte deux chemins d'accès au modèle principal (API directe et interface CLI) ; enregistre chaque appel pour le suivi de consommation et la refacturation.
Table de routage IA	Table	Source de vérité unique définissant, pour chaque fonctionnalité, le fournisseur d'embedding, le fournisseur de complétion, le modèle cible et des paramètres étendus au format structuré.
Table de consommation IA	Table	Enregistre chaque appel API avec le fournisseur, le modèle, l'étiquette de mesure, le nombre de tokens en entrée et en sortie, et le coût estimé en dollars ; utilisé pour la facturation par tenant.
Interface de rappel utilisateur	Compétence (interface utilisateur)	Permet à un utilisateur d'interroger explicitement la mémoire du système via une interface dédiée.
Interface de rétrospective	Compétence (interface utilisateur)	Déclenche manuellement la production d'une leçon post-chantier.
Interface de victoire	Compétence (interface utilisateur)	Enregistre et valorise les succès notables dans le corpus mémoriel.

Note d'architecture : l'ensemble de ces composants forme un système fermé d'auto-amélioration. Les leçons alimentent les suggestions, les suggestions alimentent les compétences, les compétences améliorent les futurs chantiers, et les chantiers produisent de nouvelles leçons. La façade IA et la table de routage centrale garantissent que chaque évolution de modèle ou de fournisseur se répercute uniformément sur l'intégralité de la boucle sans modification des composants individuels.