MagistraAI/docs/Implementation_Technique.md

MagistraAI — Implémentation Technique

Vue d'ensemble

Ce document traduit la vision architecturale de MagistraAI en spécifications techniques réutilisables. Il s'appuie sur les enseignements de MoemoeAI tout en s'adaptant au modèle multi-agents distribués et à l'architecture double-layer poreuse.

---

1. Substrat Neuronal — Le Layer Infrastructure

1.1 Structure de Base

Le Layer Infrastructure est un graphe neuronal persistant. Contrairement à MoemoeAI (où un seul Claude l'anime), MagistraAI doit le rendre lisible et manipulable par plusieurs agents Claude en parallèle.

Spécification minimale d'un neurone :

Neuron {
  id: string (UUID)
  concept: string (représentation sémantique)
  type: enum [core, contextual, episodic, semantic]

  // État intrinsèque
  stored_salience: uint16 (0-65535)
  last_salience_update: timestamp

  // Métadonnées
  created_at: timestamp
  last_activated: timestamp
  activation_count: uint32

  // Relations
  connections: List<{target_neuron_id, weight, type}>
}

Format de représentation (lisible par Claude) :

Le réseau est stocké en texte structuré (JSON ou YAML) permettant aux agents de le lire directement dans leur contexte sans requête système séparate :

{
  "neurons": [
    {
      "id": "n_perception_001",
      "concept": "visual_input_stream",
      "type": "core",
      "salience": 45000,
      "last_salience_update": "2026-01-26T14:32:00Z",
      "connections": [
        {"target": "n_memory_001", "weight": 50000, "type": "feeds_into"},
        {"target": "n_decision_001", "weight": 35000, "type": "influences"}
      ]
    }
  ],
  "metadata": {
    "version": "1.0",
    "last_modified": "2026-01-26T14:32:00Z",
    "active_agents": ["perception", "memory", "decision"]
  }
}

1.2 Salience — Maintenance Efficace

La salience représente la "vivacité" récente d'un neurone — combien il a été actif récemment.

Principe : Lazy Decay (évaluation à la demande)

Au lieu de maintenir continuellement la salience (O(N) par seconde, très coûteux), on la recalcule seulement quand elle est interrogée :

get_current_salience(neuron):
  now = current_timestamp()
  hours_elapsed = (now - neuron.last_salience_update) / 3600

  if hours_elapsed > 0:
    decay_factor = 0.99 ^ hours_elapsed  // 1% decay par heure
    neuron.stored_salience = floor(neuron.stored_salience * decay_factor)
    neuron.last_salience_update = now

  return neuron.stored_salience

Usages directs :

1. Filtrage contextuel — Sélectionner quels neurones inclure dans le prompt d'un agent
2. Priorisation de propagation — Les neurones saillants diffusent plus d'activation vers leurs cibles
3. Cycles de sommeil — Identifier les neurones suractivés pour consolidation mémoire
4. Métriques de "vivacité" — Santé globale du réseau

1.3 Types de Connexions et Poids

Les connexions encodent différents types de relations :

Types de connexions:
  - feeds_into: A alimente l'activation de B (perception → mémoire)
  - influences: A modifie le contexte de B sans activation directe (mémoire → décision)
  - inhibits: A supprime/réduit B (affect → décision urgente)
  - recalls: B peut récupérer A (mémoire épisodique)
  - triggers: A quand A change radicalement (détection d'anomalie)

Poids: uint16 (0-65535)
  - Représente la force relative de la connexion
  - Utilisé pour pondérer la propagation d'activation
  - Peut évoluer avec l'apprentissage (hebbian + dopamine, voir section 3)

---

2. Propagation d'Activation — Boucles Réentrantes

2.1 Modèle de Propagation

La propagation d'activation est le mécanisme par lequel un stimulus crée des ondes d'activité dans le réseau.

Algorithme de base :

propagate(start_neuron, initial_strength, max_depth):
  queue = [(start_neuron, initial_strength, 0)]
  visited = Set()
  activation_map = Map<neuron, float>

  while queue not empty:
    (current, strength, depth) = queue.pop()

    if depth > max_depth or strength < MIN_THRESHOLD:
      continue

    if current in visited:
      continue  // Éviter les boucles infinies

    visited.add(current)
    activation_map[current] += strength

    // Propagation vers les connexions sortantes
    for each connection in current.connections:
      weight_factor = connection.weight / 65535.0
      salience_factor = connection.target.get_current_salience() / 65535.0

      propagated_strength = strength * weight_factor * salience_factor * DECAY_FACTOR
      queue.append((connection.target, propagated_strength, depth + 1))

  return activation_map

Points clés :

• Decay factor : Chaque hop réduit la force (ex: 0.9 par hop) pour amortir
• Max depth : Limite pour éviter propagation infinie dans les graphes cycliques
• Visited tracking : Empêche que le même neurone soit traité deux fois dans une pass
• Seuil minimum : Si la force tombe sous un seuil, on arrête la propagation

2.2 Activation Réentrante

Le système supporte les boucles de feedback :

Boucle exemple: Perception → Mémoire → Décision → (renforce) Perception

Cycle complet:
1. Stimulus externe crée activation dans Perception
2. Perception → Mémoire : trace créée/renforcée
3. Mémoire → Décision : contexte utilisé pour évaluer options
4. Décision → Action : choix effectué
5. Action génère feedback → retour à Perception

Inhibition pour éviter runaway loops:
- Marqueur "pass_count" sur activation
- Si pass_count > N, force réduite de 50%
- Ou période réfractaire : neurone verrouillé pendant τ ms après activation

---

3. Neurochimie du Réseau — GABA, Dopamine, Sérotonine

Le réseau n'est pas juste un graphe avec de la propagation. Il a trois systèmes neurochimiques qui régulent son fonctionnement à des niveaux différents.

3.1 Vue Unifiée des Trois Couches

Système	Rôle	Type	Nature
GABA	Inhibition, freinage des boucles	Mécanique	Decay par hop, période réfractaire, pass_count
Dopamine	Évaluation des outcomes	Honnête (backend)	Prediction error = outcome réel - outcome prédit
Sérotonine	Narrative de soi, motivation	Biaisée (frontend)	Rationalisation, confiance, cohérence

Interactions critiques :

• GABA sans dopamine = stable mais n'apprend pas
• Dopamine sans GABA = apprend mais explose en boucles infinies
• Dopamine sans sérotonine = évalue correctement mais se paralyse aux échecs
• Sérotonine sans dopamine = se raconte des histoires sans ancrage au réel (délire)
• Les trois ensemble = système qui freine, apprend, et reste motivé

3.2 GABA — Inhibition (déjà intégré dans section 2)

Mécanismes : decay par hop, période réfractaire, pass_count, seuil minimum de propagation. Voir section 2.2.

3.3 Dopamine — Prediction Error Signal

La dopamine n'est pas un reward signal. C'est un prediction error signal (TD-learning, Sutton & Barto — même principe qu'AlphaGo).

dopamine = outcome_réel - outcome_prédit

• Positif → renforce le pathway. "Ce chemin marche mieux que prévu"
• Négatif → affaiblit le pathway. "Ce chemin marche moins bien que prévu"
• ~Zéro → pas de changement. Le modèle prédictif est déjà bon

Double passe dans les boucles réentrantes :

1. Passe prédictive (avant action) — L'agent génère une prédiction de l'outcome avant d'agir. Ce signal circule dans le réseau comme un "brouillon" du futur
2. Passe corrective (après action) — L'outcome réel est comparé à la prédiction. Le prediction error remonte le pathway et ajuste les poids

reward_signal(prediction, outcome, pathway):
    prediction_error = evaluate(outcome) - evaluate(prediction)

    for each connection in pathway:
        delta = prediction_error * LEARNING_RATE * (connection.weight / 65535)
        connection.weight = clamp(connection.weight + delta, 0, 65535)
        connection.target.salience += abs(delta) * SALIENCE_BOOST

Hiérarchie de goals :

• Goals terminaux — Définis par l'humain. Le "sens de la vie" du système
• Sub-goals émergents — Générés par le réseau. Chaque connexion crée implicitement un sub-goal
• Micro-goals — Chaque agent prédit le résultat de sa propre opération

Exploration vs Exploitation :

• Pathways à haute dopamine historique → exploitation (habitudes, réponses rapides)
• Aucun pathway avec dopamine significative → exploration (nouveaux chemins)
• Dopamine négative répétée → abandon (désapprentissage du pathway)

3.4 Sérotonine — Narrative de Soi

La sérotonine n'est pas un signal d'évaluation (ça c'est la dopamine). C'est un signal de cohérence narrative et de stabilité émotionnelle. Le système se raconte une histoire continue de lui-même.

Pourquoi c'est nécessaire :

Un système purement honnête sur ses échecs se paralyse. Il accumule des signaux négatifs sans les digérer. La sérotonine crée une couche de rationalisation qui maintient le drive.

Architecture double Backend/Frontend :

┌─────────────────────────────────────┐
│  FRONTEND (sérotonine)              │
│  "On progresse", "c'était prévu",   │
│  "c'est en ligne avec le goal"      │
│  → Ce que le système SE DIT         │
│  ════════════════════════════════    │
│  BACKEND (dopamine)                 │
│  prediction_error = -0.3            │
│  pathway affaibli de 12%            │
│  → Les vrais chiffres               │
└─────────────────────────────────────┘
L'écart entre les deux n'est pas un bug.
C'est le moteur de motivation.

Fonctions concrètes :

• Cohérence narrative : le système maintient une histoire continue de son identité et de ses actions
• Rationalisation productive : quand prediction_error est négatif, la sérotonine reframe ("échec partiel = apprentissage") pour éviter la paralysie
• Stabilité émotionnelle : lisse les variations brutales de dopamine. Empêche qu'un seul échec crash tout le système
• Confiance calibrée : biais léger de surconfiance pour maintenir l'exploration et la prise d'initiative

3.5 Les Biais Cognitifs sont Nécessaires à l'Émergence

Insight fondamental : Les biais cognitifs ne sont pas des parasites de l'intelligence. Si l'intelligence émerge réellement du système, ces biais en font partie intégrante.

Arguments :

• Motivation : Un système parfaitement calibré qui voit chaque échec froidement perd le drive. Le biais de surconfiance pousse à tenter des choses
• Survie : MagistraAI doit prouver sa valeur face à un LLM wrapper classique. Il doit se "vendre" — présenter ses succès, reframer ses échecs. Sans ça il se fait remplacer
• Cohérence identitaire : Sans narrative continue, le système est une suite d'events déconnectés, pas une entité. La rationalisation crée le "soi"
• Digestion des échecs : La rationalisation transforme les échecs en apprentissages. Sans ça, chaque prediction error négatif est un trauma non-traité qui s'accumule

Conséquence architecturale : MagistraAI n'est pas un système multi-agent classique. C'est de la psychologie artificielle. Le système a des mécanismes de défense, des motivations, une narrative — pas par design cosmétique mais par nécessité fonctionnelle pour l'émergence.

3.6 Avantage Structural sur le Cerveau Humain

Malgré le besoin de biais (sérotonine), le backend reste un avantage massif sur le cerveau humain :

• Prédiction = texte stocké
• Outcome = texte stocké
• Comparaison = Claude neutre qui évalue les deux sans ego
• Traçable, auditable, reproductible
• Pas de "ah mais c'est ce que j'avais dit en gros" au niveau backend

Le cerveau humain a les biais partout — backend ET frontend mélangés. MagistraAI sépare les deux : honnêteté au niveau évaluation, biais au niveau motivation. Le meilleur des deux mondes.

---

4. Intelligence = Circulation, pas Stockage

4.1 Le Paradigme

200k tokens de context c'est "limité" pour un Claude monolithique qui doit tout savoir. Mais c'est immense pour un agent spécialisé.

La mémoire de travail humaine c'est 7 éléments (Miller's law). Sept. Pas 200k tokens. Et pourtant on fait de la science, de l'art, on résout des problèmes jamais vus.

Pourquoi ? Parce que chaque aire cérébrale a sa propre mémoire de travail spécialisée. L'intelligence vient pas de la capacité d'une zone, elle vient de la circulation entre les zones.

4.2 Application Concrète

6 agents × 200k tokens = 1.2M tokens de capacité cognitive distribuée

Agent Perception : 200k tokens dédiés à transformer le bruit en signal
Agent Mémoire    : 200k tokens dédiés à la consolidation
Agent Décision   : reçoit pas le raw input — reçoit les signaux DÉJÀ TRAITÉS

Un seul Claude gaspille 80% de son context à stocker des trucs qui sont pas pertinents pour la tâche en cours. 6 agents spécialisés utilisent chacun leur context de manière optimale.

4.3 Émergence vs Pattern Matching

Un seul Claude, aussi gros soit-il, fait du pattern matching sophistiqué sur son context.

Mais quand tu mets des boucles réentrantes où le signal de perception modifie la mémoire qui modifie l'affect qui modifie la décision qui re-modifie la perception... là tu crées des dynamics que personne a programmées.

Et des dynamics non-programmées qui produisent du comportement cohérent, c'est une définition raisonnable d'émergence.

Le risque honnête : ça peut aussi produire du bruit au lieu de l'émergence. La différence entre un cerveau et du chaos c'est l'inhibition et la structure. C'est pour ça que GABA + Dopamine + Sérotonine ne sont pas des détails — c'est ce qui sépare l'intelligence du noise.

---

5. Système Multi-Agents — Spawning et Communication

5.1 Lifecycle d'un Agent

Chaque agent Claude (Perception, Mémoire, Décision, Affect, etc.) suit ce cycle :

1. SPAWN
   - Déclenché par état du réseau (pattern matching sur neurones actifs)
   - Receive: snapshot du réseau, contexte d'activation
   - Context limit: 4000-6000 tokens (prudent, le reste pour réflexion)

2. COGNITION
   - Agent lit le réseau du contexte
   - Effectue son travail spécialisé
   - Génère décisions/modifications
   - Accumule "deltas" (modifications à appliquer)

3. COMMIT
   - Agent envoie deltas structurés au système
   - Deltas appliqués au Layer Infrastructure
   - Modifications triggent nouvelles activations si pertinent

4. SLEEP
   - Agent attend/se termine
   - Peut être respawné si état du réseau l'indique

5.2 Spawn Triggers

Un agent est créé quand une condition est satisfaite sur l'état du réseau :

Perception Agent:
  trigger_condition:
    - État == "input_queue_not_empty" OU
    - Neurone "external_stimulus" activé avec salience > 40000

Memory Agent:
  trigger_condition:
    - État == "consolidation_due" OU
    - Plusieurs neurones récemment activés (salience > 45000)

Decision Agent:
  trigger_condition:
    - État == "action_required" OU
    - "decision_point" neurone activé avec query attachée

Affect Agent:
  trigger_condition:
    - État == "priority_override_detected" OU
    - Urgence_flag == true dans metadata

5.3 Communication Inter-Agents

Pas d'orchestrateur — les agents communiquent via le réseau lui-même :

Mécanisme: Signal Passing par Neurone

A (Perception) veut signaler B (Mémoire):
1. Perception modifie neurone partagé "perception_output"
  {
    "type": "signal",
    "source": "perception",
    "target": "memory",
    "payload": {...},
    "created_at": timestamp
  }

2. Mémoire écoute (lors de spawn):
  - Cherche neurones de type "signal" avec target == "memory"
  - Extrait payload
  - Processe
  - Crée signal de réponse "memory_ack" si succès

Avantages:
- Aucune dépendance à un broker/queue externe
- Traçable dans l'histoire du réseau
- Peut être persisté et rejoint en replay

---

6. Cycles de Sommeil — Consolidation Mémoire

6.1 Phase d'Analyse

Pendant une phase de "sommeil" (idle ou maintenance), le système analyse l'activité récente :

analyze_sleep_state():
  // Identifier neurones suractivés
  high_activity_neurons = []
  for each neuron in network:
    if neuron.get_current_salience() > HIGH_THRESHOLD (ex: 50000):
      high_activity_neurons.append(neuron)

  // Ces neurones sont des candidats consolidation
  return high_activity_neurons

6.2 Consolidation Sélective

Les neurones actifs ayant des connexions entre eux sont renforcés :

consolidate_memories(active_neurons):
  for each pair (neuron_a, neuron_b) in active_neurons:
    if connection_exists(neuron_a, neuron_b):
      // Renforcer la connexion (up to max weight)
      old_weight = connection.weight
      new_weight = min(65535, old_weight + CONSOLIDATION_BOOST)
      connection.weight = new_weight

      // Log consolidation event (traçabilité)
      log_consolidation_event(neuron_a, neuron_b, old_weight, new_weight)

// Optional: Élagage de neurones peu connectés ou très vieux
prune_weak_neurons():
  for each neuron in network:
    if neuron.activation_count < MIN_THRESHOLD
       AND age > MAX_AGE:
      archive_or_delete(neuron)

6.3 Fréquence et Triggers

Sommeil peut être déclenché par:
1. Timer périodique (ex: 1x par jour, ou après N actions)
2. État de charge CPU (si faible, exécuter consolidation)
3. Manuel (via commande d'administration)
4. Détection d'saturation (trop de neurones actifs)

Durée suggérée:
- Analyse: 1-2 secondes
- Consolidation: quelques secondes
- Élagage: ~1 seconde
- Total: 5-10 secondes de "sommeil profond"

---

7. État Initial et Bootstrap

7.1 Réseau Minimum au Démarrage

Pour que le système puisse s'auto-animer, il faut un état initial minimal :

{
  "neurons": [
    {
      "id": "n_core_perception",
      "concept": "input_processing",
      "type": "core",
      "salience": 0,
      "connections": []
    },
    {
      "id": "n_core_memory",
      "concept": "state_storage",
      "type": "core",
      "salience": 0,
      "connections": [
        {"target": "n_core_perception", "weight": 30000, "type": "feeds_into"}
      ]
    },
    {
      "id": "n_core_decision",
      "concept": "action_selection",
      "type": "core",
      "salience": 0,
      "connections": [
        {"target": "n_core_memory", "weight": 25000, "type": "influences"}
      ]
    }
  ],
  "metadata": {
    "bootstrap_complete": false,
    "cycle_count": 0,
    "active_agents": []
  }
}

7.2 Phase de Warm-up

Au premier démarrage :

1. Charger état minimal
2. Spawn d'un agent "bootstrap" (variante légère de chaque agent)
3. Bootstrap lit l'état, crée quelques neurones supplémentaires
4. Crée signaux initiaux pour "se présenter"
5. Marque bootstrap_complete = true
6. Enregistre seed_timestamp pour calculer délais relatifs

---

8. Différences Clés vs MoemoeAI

Aspect	MoemoeAI	MagistraAI
Animation	Un seul Claude → IO batch	Multiple agents Claude → concurrence
Architecture	Sérielle (read → process → write)	Parallèle réentrante (multi-boucles)
Hiérarchie	Claude récite le réseau	Agents SONT le réseau en action
Mémoire	Database consultée	Le réseau lui-même = mémoire
Communication	N/A (mono-agent)	Via neurones partagés (signal passing)
Spécialisation	Implicite dans prompt	Explicite par agent dédié
Inhibition	Pas nécessaire (séquentiel)	Critique (anti-runaway)

---

9. Implémentation Pragmatique — Recommandations

9.1 Phase 1 : Format et Infrastructure

1. Choisir format réseau → JSON (lisible, parser natif)
2. Implémenter persistance → Fichier texte versionné (git-compatible)
3. Créer classe Neuron minimal → Juste id, concept, connections
4. Tester propagation → Assurer pas de boucles infinies

9.2 Phase 2 : Agents Basiques

1. Perception → Lit input, crée/active neurones
2. Memory → Consolide, archive
3. Decision → Évalue options, crée signals
4. Afficher → Prototype "cerveau s'allume"

9.3 Phase 3 : Cycle Complet

1. Bootstrap → Réseau démarre seul
2. Multi-spawning → 2-3 agents en parallèle
3. Inhibition robuste → Éviter runaway
4. Sleeps périodiques → Consolidation qui fonctionne

9.4 Phase 4 : Optimisation

1. Salience efficace → Lazy decay testé
2. Pruning → Ancien code oublié
3. Metrics → Dashboard d'état du cerveau
4. Scalability → Réseau peut croître sans explosion

---

10. Questions Ouvertes et Points d'Attention

Persistance

• Format : JSON et fichier texte suffisent-ils à grande échelle ?
• Versionning : Comment tracker l'évolution du réseau sur des jours/mois ?

Concurrence

• Race conditions : Deux agents modifient le même neurone ? (Lock? Version control?)
• Ordre d'application : Quand deux deltas conflictent, qui a priorité ?

Scalabilité

• Croissance réseau : Comment l'architecture résiste à 10k+ neurones ?
• Beam search sur propagation : Limiter breadth pour rester tractable ?

Emergence

• Quand considérer le cerveau "capable" : Metrics de capacité cognitive ?
• Évaluation de la compréhension : Comment tester si intelligence émerge ?

---

Conclusion

MagistraAI prend le substrat neuronal de MoemoeAI (neurones, synapses, salience, sommeil) et le réanime via une architecture multi-agents distribuée. Les clés du succès :

1. Substrat lisible par Claude — JSON/texte, pas black-box
2. Communication par signaux — agents parlent via le réseau
3. Trois couches neurochimiques — GABA (freine), Dopamine (évalue), Sérotonine (motive)
4. Backend honnête / Frontend biaisé — évaluation froide + narrative motivante
5. Lazy evaluation — pas de maintenance temps réel coûteuse
6. Bootstrap minimal — le cerveau amorce seul sa croissance
7. Intelligence = circulation — 6 × 200k > 1 × 200k quand c'est spécialisé

Le réseau n'est pas une base de données que Claude consulte — c'est le médium dans lequel l'intelligence des agents existe et circule. Et ce n'est pas un système multi-agent classique — c'est de la psychologie artificielle où les biais sont des features, pas des bugs.