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 :

```json
{
  "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)
```

---

## 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. Système Multi-Agents — Spawning et Communication

### 3.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
```

### 3.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
```

### 3.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
```

---

## 4. Cycles de Sommeil — Consolidation Mémoire

### 4.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
```

### 4.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)
```

### 4.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"
```

---

## 5. État Initial et Bootstrap

### 5.1 Réseau Minimum au Démarrage

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

```json
{
  "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": []
  }
}
```

### 5.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
```

---

## 6. 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) |

---

## 7. Implémentation Pragmatique — Recommandations

### 7.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

### 7.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"

### 7.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

### 7.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

---

## 8. 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. **Inhibition intelligente** — éviter boucles infinies
4. **Lazy evaluation** — pas de maintenance temps réel coûteuse
5. **Bootstrap minimal** — le cerveau amorce seul sa croissance

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.