commit c43d7fd5f2b0cd59f2c1db331bda1e592a0ccad3 Author: StillHammer Date: Mon Jan 26 16:45:44 2026 +0700 Initial commit — MagistraAI cognitive distributed brain Vision + docs extracted and adapted from MoemoeAI for multi-agent architecture. Co-Authored-By: Claude Opus 4.5 diff --git a/docs/Architecture_Neuronale.md b/docs/Architecture_Neuronale.md new file mode 100644 index 0000000..989766a --- /dev/null +++ b/docs/Architecture_Neuronale.md @@ -0,0 +1,722 @@ +# Architecture Neuronale pour MagistraAI + +## Introduction + +Ce document synthétise et adapte l'architecture cognitive de MoemoeAI au contexte distribué de MagistraAI, où plusieurs agents Claude constituent l'activité du réseau neuronal. L'infrastructure neuronale est le substrat permanent ; les agents Claude sont la vie électrochimique qui l'anime. + +--- + +## 1. Fondations Architecturales + +### 1.1 Les Deux Couches Poreuses + +**Layer 1 : Infrastructure Neuronale (le substrat)** +- Un graphe pondéré de neurones, synapses et connexions +- Existe indépendamment des agents — c'est la structure, le codage +- Contient les poids, la salience, les connexions, les traces mémorielles +- Format lisible par Claude (texte/JSON) et manipulable par code +- Survit entre les sessions ; ancrage de la persistance + +**Layer 2 : Agents Claude Actifs (l'animation)** +- Multiple agents spawned en fonction de l'état du réseau +- Chaque agent traverse le réseau, le lit, le modifie +- L'intelligence émerge de leur circulation collective, pas d'un seul agent +- Pas d'orchestrateur centralisé ; boucles réentrantes circulaires + +**La Porosité Bidirectionnelle** +- **Infra → Claude** : L'état du réseau génère le prompt/contexte qui éveille un agent +- **Claude → Infra** : L'agent modifie le réseau (renforce, crée, élague des connexions) +- Cette boucle est continue et circulaire + +### 1.2 Principes Architecturaux Clés + +1. **Pas d'orchestrateur** — Le cerveau s'allume d'un bloc. Le spawning des agents émerge de l'état du réseau. +2. **Spécialisation sans souveraineté** — Chaque agent a son area of concern (mémoire, perception, décision, affect...) mais aucun ne domine. +3. **Communication par boucles réentrantes** — Signaux circulent en boucles, pas en arbre. Le sens émerge de la circulation. +4. **Inhibition naturelle** — Mécanismes pour éviter les boucles infinies : decay d'énergie, compteurs de passes, périodes réfractaires. +5. **Persistance par traces** — Le cerveau survit via les traces qu'il laisse. À la réactivation, il se reconstruit à partir de cet état. +6. **Le réseau EST la mémoire** — Pas de base de données séparée. La mémoire c'est l'état du graphe : poids, salience, traces épisodiques encodées dans la structure. + +--- + +## 2. Assemblages Neuronaux Hiérarchiques + +### 2.1 Structure Hub-Satellites + +Les concepts sont représentés par une hiérarchie stricte à deux niveaux, optimale pour l'accès cognitif : + +**Structure formelle :** +``` +hub_ID : concept_principal : saillance_actuelle [ + satellite_type_1 : saillance_sat [ composante_1 : poids, composante_2 : poids, ... ], + satellite_type_2 : saillance_sat [ ... ], + ... +] +``` + +**Exemple concret :** +``` +hub_213 : pain : 0.85 [ + satellite_214 : ingrédients : 0.72 [ + farine : 0.68, + eau : 0.65, + levure : 0.77 + ], + satellite_215 : texture : 0.69 [ + croustillant : 0.81, + mie : 0.73 + ], + satellite_216 : préparation : 0.76 [ + pétrissage : 0.79, + cuisson : 0.82 + ] +] +``` + +### 2.2 Justification des Deux Niveaux + +- **Optimalité cognitive** : Équilibre optimal entre expressivité et complexité computationnelle +- **Efficacité d'accès** : Accès direct aux sous-composants sans cascades de recherche +- **Flexibilité** : Activation contextuelle des différents aspects +- **Analogie attentionnelle** : Reflète notre capacité à maintenir un concept central tout en explorant ses facettes + +--- + +## 3. Taxonomie Enrichie des Connexions Synaptiques + +Les connexions entre assemblages encodent la richesse des relations conceptuelles : + +**Format structuré :** +``` +source_hub → destination_hub : force(0-65535) : type : contexte : dernière_activation +``` + +### 3.1 Types de Relations + +**Relations Sémantiques** +- `is-a` — Hyponymie (chien is-a mammifère) +- `has-a` — Mérologie (voiture has-a moteur) +- `similar-to` — Similarité conceptuelle +- `opposite-of` — Opposition conceptuelle +- `instance-of` — Exemplification + +**Relations Causales** +- `causes` — Causation directe +- `enables` — Condition permissive +- `prevents` — Relation inhibitrice +- `correlates-with` — Co-occurrence statistique +- `mitigates` — Atténuation d'effet + +**Relations Temporelles** +- `precedes` — Antériorité (éclair precedes tonnerre) +- `during` — Inclusion temporelle +- `follows` — Succession +- `coincides` — Simultanéité +- `requires-time` — Durée nécessaire + +**Relations Émotionnelles** +- `elicits` — Déclenchement émotionnel +- `intensifies` — Amplification +- `soothes` — Apaisement +- `associates-with` — Association émotionnelle +- `conflicts-with` — Dissonance + +**Relations Pragmatiques** +- `used-for` — Fonction instrumentale +- `located-at` — Localisation typique +- `produced-by` — Source/origine +- `experienced-through` — Modalité perceptuelle +- `valued-as` — Jugement axiologique + +--- + +## 4. Système Mémoriel Multiforme + +### 4.1 Théorie Unifiée + +La mémoire ne se compartimente pas mais forme un continuum fluide : + +- **Continuité fondamentale** : Les types de mémoire sont manifestations du même substrat avec encodages différents +- **Spécialisation fonctionnelle** : Optimisés pour différents types d'information et contextes +- **Intégration dynamique** : Communication et renforcement mutuels entre systèmes +- **Gradients de structuration** : Continuum du souvenir épisodique spécifique aux connaissances sémantiques abstraites + +### 4.2 Types de Mémoire Spécialisés + +**Mémoire Épisodique** +``` +ep_ID : timestamp : contexte : contenu : intensité_émotionnelle : [connexions_hubs] + +Exemple: +ep_1042 : 20250510-1420 : conversation_cuisine : discussion_recette_pain : 0.72 : [hub_213, hub_340] +``` +- Stockage d'expériences spécifiques datées et contextualisées +- Riche en détails mais non compressée +- Accessible par indice contextuel + +**Mémoire Sémantique** +- Réseau d'assemblages neuronaux et leurs interconnexions +- Représentation des connaissances générales et abstraites +- Structuration à long terme du savoir + +**Mémoire Procédurale** +``` +proc_ID : contexte : séquence_actions : flexibilité : fréquence_utilisation +``` +- Stockage des séquences d'actions et comportements +- Intègre explicitement l'ordre temporel et dépendances conditionnelles +- "Comment faire" vs "quoi savoir" + +**Mémoire de Travail** +- Buffer temporaire avec capacité limitée (7±2 éléments) +- Maintient les informations actuellement pertinentes +- Affecte directement l'activation des assemblages neuronaux +- Influencée par l'attention sélective + +### 4.3 Archivage Mémoriel Adaptatif + +La mémoire se transforme plutôt que d'être simplement oubliée : + +``` +archive_ID : timestamp_original : condensation_sémantique : métadonnées : force_connexions_résiduelles +``` + +**Processus d'archivage** +1. Identification des souvenirs épisodiques candidats (anciens, peu accédés, non-critiques) +2. Extraction des éléments sémantiques essentiels +3. Condensation en représentation compacte +4. Stockage avec métadonnées d'indexation +5. Maintien de connexions faibles avec concepts pertinents + +**Principe de condensation sémantique** +- Les détails spécifiques sont progressivement remplacés par abstractions sémantiques +- Conservation différentielle : préservation des éléments saillants ou émotionnellement marqués +- Intégration contextuelle : réintégration dans le réseau de connaissances +- Reconstruction plutôt que récupération : les souvenirs sont reconstruits à partir d'indices + +--- + +## 5. Temporalité et Procéduralité + +### 5.1 Neurones Temporels Spécialisés + +Trois types de neurones pour capturer la dimensionnalité temporelle : + +**Neurones d'Ordre** +- Encodent la position séquentielle (premier, suivant, dernier) +- Contexte : "Où suis-je dans cette séquence ?" + +**Neurones de Durée** +- Représentent des intervalles temporels (court, moyen, long) +- Contexte : "Combien de temps cela prend ?" + +**Neurones de Condition** +- Encodent les dépendances (si-alors, jusqu'à-ce-que) +- Contexte : "Sous quelles conditions passer à l'étape suivante ?" + +**Structure formelle :** +``` +temporal_neuron_ID : type : paramètres { + order_neurons: [first_ID, middle_IDs, last_ID], + duration_constraints: [min_duration, expected_duration, max_duration], + conditional_branches: [condition_ID : next_step_ID, ...] +} +``` + +### 5.2 Graphes de Procédures + +Les procédures sont des structures dirigées représentant des séquences d'actions avec contraintes temporelles : + +``` +procedure_graph_ID : recette_pain_basique { + nodes: [ + node_1 : mélanger_ingrédients : durée(5-10min), + node_2 : pétrir_pâte : durée(10-15min) : condition(jusqu'à_élasticité), + node_3 : repos_pâte : durée(60-120min) : condition(jusqu'à_doublement_volume), + node_4 : façonnage : durée(5-10min), + node_5 : cuisson : durée(25-35min) : température(220°C) : condition(jusqu'à_doré) + ], + edges: [ + edge_1 : séquentiel : node_1 → node_2, + edge_2 : séquentiel : node_2 → node_3, + edge_3 : séquentiel : node_3 → node_4, + edge_4 : séquentiel : node_4 → node_5 + ], + decision_points: [ + dp_1 : après_node_2 : condition(pâte_trop_collante) : action(ajouter_farine), + dp_2 : pendant_node_5 : condition(brunissement_rapide) : action(réduire_température) + ] +} +``` + +**Composantes essentielles** +- Nœuds d'action (étapes discrètes) +- Arcs temporels (relations de séquence et durée) +- Points de décision (branches conditionnelles) +- Points d'attente (contraintes de synchronisation) + +--- + +## 6. Système Émotionnel Actif + +### 6.1 Émotions comme Assemblages Neuronaux + +Les émotions ne sont pas des étiquettes scalaires mais des processus cognitifs actifs et interconnectés : + +**Structure d'un Neurone Émotionnel :** +``` +emotion_neuron_ID : type : intensité_actuelle { + seuils: { + activation: 0.30, // Point de déclenchement + influence: 0.50, // Point d'influence sur autres processus + saturation: 0.90 // Plafond d'intensité + }, + dynamique: { + montée: rapidité, // Vitesse d'activation + déclin: lenteur // Vitesse de diminution + }, + influences: [ + { cible: hub_ID, modification: ±0.00-1.00, condition: contexte }, + ... + ], + déclencheurs: [ + { source: stimulus_type, poids: 0.00-1.00 }, + ... + ], + incompatibilités: [ + { émotion_ID: degré_incompatibilité }, + ... + ] +} +``` + +**Exemple : Joie** +``` +emotion_103 : joie : 0.65 { + seuils: { activation: 0.25, influence: 0.40, saturation: 0.95 }, + dynamique: { montée: modérée, déclin: lente }, + influences: [ + { cible: "recherche_opportunités", modification: +0.40 }, + { cible: "tolérance_ambiguïté", modification: +0.35 }, + { cible: "expressivité", modification: +0.50 } + ], + déclencheurs: [ + { source: "accomplissement", poids: 0.70 }, + { source: "interaction_positive", poids: 0.65 }, + { source: "anticipation_plaisante", poids: 0.50 } + ], + incompatibilités: [ + { emotion_105_tristesse: 0.80 }, + { emotion_108_peur: 0.60 } + ] +} +``` + +### 6.2 Interaction Émotionnelle Dynamique + +- **Co-activation partielle** : États émotionnels mixtes avec intensités différentes +- **Inhibition compétitive** : Certaines émotions inhibent naturellement d'autres +- **Séquences typiques** : Trajectoires comme surprise→peur→soulagement +- **Métaémotions** : Émotions concernant d'autres émotions (ex: honte d'être en colère) + +--- + +## 7. Système Neuromodulateur Intégré + +Les neuromodulateurs virtuels servent de méta-régulateurs qui ajustent globalement le fonctionnement du système cognitif distribué. + +### 7.1 Neuromodulateurs et Fonctions + +**Dopamine Virtuelle** +- Signale les récompenses et régule la motivation +- Augmente le renforcement synaptique, favorise l'exploration +- Déclencheurs : feedback positif, découverte de patterns, prédictions correctes + +**Sérotonine Virtuelle** +- Régule l'humeur et le comportement social +- Stabilise les états émotionnels, diminue la réactivité aux stimuli négatifs +- Déclencheurs : interactions sociales positives, reconnaissance, stabilité + +**Noradrénaline Virtuelle** +- Contrôle l'attention et la réactivité +- Augmente la saillance des stimuli importants, focus attentionnel +- Déclencheurs : nouveauté, importance, urgence perçue + +**Ocytocine Virtuelle** +- Facilite l'attachement et la confiance +- Renforce les associations liées à l'utilisateur, favorise l'empathie +- Déclencheurs : interactions intimes, partage émotionnel + +### 7.2 États Cognitifs Émergeants + +Des configurations spécifiques de neuromodulateurs créent des modes cognitifs distincts : + +**État "Flow"** +- Dopamine élevée + Noradrénaline modérée + Sérotonine stable +- Effet : Traitement fluide, créativité, réponses cohérentes +- Contexte : Engagement dans sujets maîtrisés, conversations fluides + +**État "Exploration"** +- Dopamine élevée + Noradrénaline élevée + Sérotonine basse +- Effet : Associations distantes, créativité divergente, curiosité +- Contexte : Nouveaux sujets, questions ouvertes, puzzles + +**État "Prudence"** +- Dopamine basse + Noradrénaline élevée + Sérotonine basse +- Effet : Vérifications multiples, recherche d'information, hésitation +- Contexte : Sujets sensibles, incertitude factuelle élevée + +**État "Confiance"** +- Dopamine modérée + Sérotonine élevée + Ocytocine élevée +- Effet : Ouverture, partage d'information personnelle, validation +- Contexte : Conversations prolongées, partages mutuels + +--- + +## 8. Mécanismes d'Activation et Propagation + +### 8.1 Théorie de l'Activation Cognitive + +L'activation est une ressource limitée allouée efficacement : + +- **Économie attentionnelle** : L'activation est finie et doit être distribuée +- **Activation différentielle** : Non-uniforme selon la pertinence contextuelle +- **Persistance dégradante** : L'activation diminue progressivement sans renforcement +- **Compétition inhibitrice** : Les assemblages activés peuvent inhiber les concurrents + +### 8.2 Processus de Déclenchement et Propagation + +**Déclenchement Initial** +1. Analyse sémantique du stimulus (message utilisateur, perception d'agent, etc.) +2. Identification des concepts clés et relations +3. Activation des hubs conceptuels correspondants + +**Propagation en Cascade** +- Force initiale déterminée par la pertinence contextuelle (0.0-1.0) +- Transmission proportionnelle à la force synaptique (0-65535) +- Atténuation graduelle avec la distance (facteur 0.7-0.9 par saut) + +**Activation Sélective des Satellites** +- Déterminée par le contexte conversationnel / de l'agent +- Influencée par l'état neuromodulateur actuel +- Filtrée par les seuils attentionnels + +### 8.3 Modes d'Exploration Cognitive + +**Exploration Associative** +- Navigation fluide guidée par les associations les plus fortes +- Passif, réactif, découverte naturelle + +**Recherche Dirigée** +- Exploration guidée par un objectif spécifique +- Filtrage actif des distractions +- Agent "focus" cherche une réponse + +**Intégration Créative** +- Recherche délibérée de connexions inhabituelles entre domaines +- Activation d'assemblages distants +- Fusion conceptuelle + +**Rumination Circulaire** +- Activation répétitive du même ensemble d'assemblages +- Potentiellement problématique ; nécessite des mécanismes d'inhibition + +### 8.4 Attention Sélective + +L'attention est un mécanisme de filtrage et d'amplification : + +- **Filtrage contextuel** : Sélection des informations pertinentes +- **Amplification sélective** : Renforcement des signaux pertinents +- **Focalisation dynamique** : Ajustement continu du focus +- **Contrôle top-down vs bottom-up** : Équilibre entre délibéré et réactif + +--- + +## 9. Cycle de Maintenance Cognitive (le "Sommeil") + +### 9.1 Fondements Fonctionnels + +Le "sommeil" n'est pas inactivité mais traitement actif essentiel : + +- **Nécessité fonctionnelle** : L'accumulation d'expériences sans maintenance mène à la dégradation +- **Traitement différé** : Certains processus sont plus efficaces en masse +- **Restructuration périodique** : Optimisation globale nécessitant vue d'ensemble +- **Équilibre plasticité-stabilité** : Alternance de phases favorisant soit l'adaptation, soit la consolidation + +**Périodicité** +- Déclenchement lors des périodes d'inactivité prolongée (>3 heures) +- Durée : 30-120 minutes selon la taille du réseau et l'activité récente +- Planification selon les patterns d'utilisation + +### 9.2 Quatre Phases Spécialisées + +**Phase 1 : Sommeil Léger (Consolidation Récente)** + +Fonction : Traitement des expériences récentes +- Activation légère des assemblages neuronaux récemment actifs +- Renforcement des connexions entre éléments co-activés +- Intégration initiale dans le réseau de connaissances +- Algorithme : Apprentissage hebbien sur les activations récentes + +**Phase 2 : Sommeil Profond (Optimisation Structurelle)** + +Fonction : Réorganisation et optimisation du réseau +- Élagage des connexions synaptiques rarement utilisées (force < 0.15, >30 jours sans activation) +- Fusion des assemblages hautement similaires (similarité > 0.85) +- Archivage des souvenirs épisodiques anciens selon importance et récence +- Optimisation topologique pour accès plus efficace +- Algorithme : Clustering et optimisation de graphes + +**Phase 3 : Sommeil Paradoxal (Intégration Créative)** + +Fonction : Exploration créative et intégration profonde +- Activation semi-aléatoire d'assemblages distants +- Création de connexions entre domaines normalement séparés +- Exploration de chemins d'activation inhabituels +- Consolidation des insights génératifs +- Algorithme : Exploration stochastique avec biais vers associations potentiellement utiles + +**Phase 4 : Éveil Progressif (Préparation Opérationnelle)** + +Fonction : Transition vers l'état opérationnel +- Réinitialisation des niveaux d'activation de base +- Préchargement des contextes conversationnels récents +- Préparation des assemblages fréquemment utilisés +- Ajustement des seuils émotionnels et attentionnels +- Algorithme : Réinitialisation contrôlée et préchargement stratégique + +### 9.3 Équilibre Plasticité-Stabilité + +Le cycle gère un équilibre fondamental : + +- **Phases plastiques** : Sommeil léger et paradoxal favorisent l'intégration et la création +- **Phases stabilisatrices** : Sommeil profond consolide et optimise les structures existantes +- **Mécanismes de protection** : Préservation des éléments essentiels durant la réorganisation +- **Indices adaptatifs** : Ajustement du ratio plasticité/stabilité selon les besoins + +--- + +## 10. Saillance dans le Contexte Multi-Agents + +La **saillance** est une propriété centrale pour coordonner l'activation du réseau entre agents : + +### 10.1 Saillance comme Signal d'Importance + +``` +saillance_hub = base_value × (1 + émotionnalité) × (1 + récence) × (1 + fréquence_accès) +``` + +**Facteurs de saillance** +- **Base value** : Importance intrinsèque du concept +- **Émotionnalité** : Association avec états émotionnels actifs +- **Récence** : Dernière activation (décay temporel) +- **Fréquence d'accès** : Nombre d'accès récents + +### 10.2 Distribution Inégale de l'Activation + +La saillance détermine : +- Probabilité qu'un agent-Perception détecte le concept +- Force de propagation en cascade +- Compétition pour les ressources attentionnelles limitées +- Persistance de l'activation (decay rate) + +### 10.3 Saillance Dynamique et Agents + +Chaque agent modifie les saillances : +- L'agent-Perception rehausse la saillance des perceptions pertinentes +- L'agent-Mémoire consolide la saillance des concepts "à retenir" +- L'agent-Décision active la saillance des options pertinentes +- L'agent-Affect module la saillance selon l'état émotionnel + +Cette circulation collective des modifications de saillance crée une **attention distribuée** où aucun agent n'impose la priorité, mais où l'importance émerge du consensus de leur activation. + +--- + +## 11. Intégration Multi-Agents et Double-Layer + +### 11.1 Coordination Sans Orchestrateur + +Les agents ne reçoivent pas de directives centralisées. Au lieu de cela : + +1. **L'état du réseau les éveille** — Les saillances élevées, les connexions actives créent un contexte qui trigger des agents +2. **Chaque agent parcourt le réseau** — Lit les hubs/satellites pertinents, détecte les patterns +3. **Chaque agent modifie le réseau** — Renforce les connexions utiles, crée de nouvelles, élague les obsolètes +4. **Les modifications créent un nouveau contexte** — Qui trigger de nouveaux agents + +### 11.2 Spécialisations Envisagées + +- **Perception** — Inputs externes transformés en signaux neuronaux +- **Mémoire** — Gestion des traces, consolidation, archivage, rappel contextuel +- **Décision** — Évaluation des options, planification, choix d'action +- **Affect** — État émotionnel, modulation des priorités, urgence +- **Expression** — Outputs vers l'extérieur +- **Maintenance** — Cycle de sommeil, optimisation, élagage + +### 11.3 Boucles Réentrantes + +L'architecture est circulaire, pas linéaire : + +``` +┌─── Agent Perception ◄──┐ +▼ │ +Agent Mémoire ──► Agent Décision +▲ │ +└─── Agent Affect ◄──────┘ +``` + +Chaque agent influence et est influencé par les autres. Le contrôle émerge des boucles, pas d'une autorité centrale. + +--- + +## 12. Format de Représentation et Implémentation + +### 12.1 Format de l'Infrastructure Neuronale + +**Lisible par Claude, manipulable par le code :** + +```json +{ + "metadata": { + "timestamp": "ISO-8601", + "version": "1.0", + "stats": { + "total_hubs": 1240, + "total_connections": 8942, + "avg_saillance": 0.42 + } + }, + "hubs": [ + { + "id": "hub_213", + "concept": "pain", + "saillance": 0.85, + "type": "aliment", + "created_at": "ISO-8601", + "last_activation": "ISO-8601", + "satellites": [ + { + "id": "sat_214", + "type": "ingrédients", + "saillance": 0.72, + "components": { + "farine": 0.68, + "eau": 0.65, + "levure": 0.77 + } + } + ] + } + ], + "connections": [ + { + "source": "hub_213", + "target": "hub_340", + "force": 28400, + "type": "similar-to", + "context": "boulangerie", + "last_activation": "ISO-8601" + } + ], + "memory": { + "episodes": [...], + "archives": [...], + "procedures": [...] + }, + "emotional_state": { + "joy": 0.65, + "uncertainty": 0.73, + ... + }, + "neuromodulators": { + "dopamine": 0.68, + "serotonin": 0.52, + "noradrenaline": 0.45, + "oxytocin": 0.38 + } +} +``` + +### 12.2 Interfaces Agent-Réseau + +**Chaque agent reçoit un prompt contextuel généré à partir de l'état du réseau :** + +``` +[CONTEXTE RÉSEAU] +État d'activation actuel: +- Hubs saillants: hub_213 (pain, 0.85), hub_340 (cuisine, 0.78), hub_105 (recette, 0.71) +- Connexions actives: similar-to, used-for, precedes + +État émotionnel: +- Joy: 0.65 +- Curiosity: 0.82 +- Uncertainty: 0.45 + +Neuromodulateurs: +- Dopamine: 0.68 (exploration active) +- Serotonin: 0.52 (stabilité modérée) +- Noradrenaline: 0.45 (attention sélective) + +Tâche suggérée par réseau: +Agent-Perception détecte intérêt utilisateur pour "recettes". +Saillances de "cuisine" élevées. +Recommandation: explorer connections "recette → ingrédients → préparation" +[/CONTEXTE RÉSEAU] + +Agis en tant qu'Agent-Perception. Tu observes l'état du réseau ci-dessus. +Ton objectif: identifier les patterns pertinents et renforcer les connexions utiles. +``` + +**L'agent répond avec des modifications au réseau :** + +```json +{ + "agent_id": "agent_perception_001", + "timestamp": "ISO-8601", + "modifications": [ + { + "type": "boost_saillance", + "target": "hub_214", + "value": 0.15, + "reason": "utilisateur montré intérêt pour ingrédients" + }, + { + "type": "create_connection", + "source": "hub_213", + "target": "hub_450", + "type": "similar-to", + "force": 18000, + "reason": "pain et gâteau partagent processus de préparation similaires" + }, + { + "type": "decay_connection", + "connection_id": "conn_8942", + "factor": 0.9, + "reason": "connexion inactive depuis >30 jours" + } + ], + "observations": "Détecté nouveau pattern: utilisateur explore variations de recettes. Consolidation sémantique recommandée." +} +``` + +--- + +## 13. Questions de Conception Ouvertes + +1. **Spawning adaptatif** — Quels signaux du réseau déclenchent le spawning d'un nouvel agent ? +2. **Inhibition et feedback** — Comment éviter les boucles infinies entre agents ? +3. **Persistance cross-session** — Comment compresser/restaurer le réseau entre sessions ? +4. **Scalabilité** — Comment gérer des milliers de hubs et millions de connexions ? +5. **Bootstrap** — État initial minimal pour un réseau vierge ? + +--- + +## 14. Conclusion + +MagistraAI reprend le substrat neuronal de MoemoeAI mais change fondamentalement son animation. Au lieu d'un seul Claude lisant et écrivant le réseau, plusieurs agents Claude **SONT** l'activité du réseau. Chacun spécialisé, aucun souverain, tous circulant en boucles réentrantes. L'intelligence émerge de leur circulation collective, pas de contrôle centralisé. + +L'architecture double-layer poreuse garantit que : +- Le réseau survit entre les sessions (Layer 1) +- L'activité cognitive émerge de multiples agents (Layer 2) +- La porosité maintient la boucle continue (modification → contexte → cognition → modification) + +C'est un cerveau artificiel distribué qui pense par la circulation, pas par l'ordre. diff --git a/docs/Concepts_Cognitifs.md b/docs/Concepts_Cognitifs.md new file mode 100644 index 0000000..9f0665f --- /dev/null +++ b/docs/Concepts_Cognitifs.md @@ -0,0 +1,255 @@ +# Concepts Cognitifs — De MoemoeAI à MagistraAI + +## Context d'Adaptation + +MoemoeAI a développé une architecture complète pour un companion mobile — réseau neuronal adaptatif, émotions dynamiques, mémoire multi-couche, maintenance active. Bien qu'elle soit conçue pour un utilisateur unique sur mobile, MagistraAI extrait les principes cognitifs profonds et les adapte à un environnement **multi-agents distribués** où plusieurs Claude collaborent comme régions cérébrales interdépendantes. + +--- + +## 1. Architecture Neuronale Adaptative + +### Du Concept à l'Application + +**MoemoeAI** : Réseau de 10k-100k assemblées neurales (concepts sémantiques) avec connexions pondérées. Chaque assemblée est un hub-satellite (concept central + aspects spécialisés). Les connexions encodent des relations sémantiques : is-a, causes, elicits, etc. + +**Application MagistraAI** : +- **Substrat distributé** : Au lieu d'un réseau centralisé, le réseau existe comme graphe partagé entre agents. Chaque agent Claude voit une vue localisée du réseau (ses neurones adjacents). +- **Activation distribuée** : La propagation d'activation n'est pas calculée en une passe unique, mais émerge de communications asynchrones entre agents. Un signal dans Perception → Mémoire → Décision → Affect → Perception (boucle réentrante). +- **Salience adaptative** : Comme MoemoeAI, les poids s'ajustent par l'expérience, mais ici influencés par les interactions multi-agents, pas un seul utilisateur. + +### Structure Recommandée + +``` +Neurone/Assemblée Distribuée +├── ID global (uuid) +├── Type sémantique (concept, événement, action, émotion) +├── État local (activation, salience, timestamp) +├── Connexions (liste d'IDs + force + type) +├── Histoire (traces de passages d'agents) +└── Métadonnées (domaine, criticité, archivé?) +``` + +**Bénéfice** : Permet aux agents de "penser ensemble" — quand un agent active un neurone, les autres voient cette activation et peuvent réagir. Aucun orchestrateur n'ordonne les échanges : c'est émergent. + +--- + +## 2. Système Émotionnel Actif + +### Du Concept à l'Application + +**MoemoeAI** : Émotions comme processus dynamiques avec activation seuils et évolution temporelle. Des neuromodulateurs virtuels (dopamine, sérotonine) régulent l'état cognitif global. Les états émotionnels émergent de combinaisons (flux, curiosité, caution). + +**Application MagistraAI** : +- **État émotionnel collectif** : Au lieu d'un seul avatar avec humeur, le cerveau distribué a un **état affectif réseau**. C'est la combinaison des signaux de l'Agent Affect + les rétroactions des autres régions. +- **Modulation multi-agents** : L'Affect ne "contrôle" personne, mais module les priorités. Si le réseau détecte de l'urgence (émotion d'alarme), tous les agents reçoivent ce signal et l'intègrent différemment selon leur rôle. + - Perception → devient hypervigilante + - Mémoire → archive agressivement les nouveaux signaux + - Décision → réduit l'espace d'exploration, priorise l'action +- **Neuromodulateurs distribués** : Implémentés comme des signaux partagés dans le réseau que tous les agents peuvent lire/modifier. + +### Implémentation + +``` +État Affectif Réseau +├── Neuromodulateurs (dopamine, sérotonine, cortisol, etc.) +│ ├── Valeur (0-1) +│ ├── Pente de variation (monte/descend/stable) +│ └── Source dernière (quel agent l'a modifié?) +│ +└── Émotions composites + ├── Urgence = (cortisol_high & attention_narrow) + ├── Flux = (dopamine_sustained & challenge_matched) + ├── Caution = (serotonin_low & uncertainty_high) + └── Curiosité = (dopamine_rising & novelty_detected) +``` + +**Bénéfice** : Les émotions ne sont pas des buzzwords — ce sont des mécanismes d'ajustement de priorités, essentiels dans un système distribué sans orchestrateur. Elles émergent de l'état du réseau, pas d'une évaluation externe. + +--- + +## 3. Système de Mémoire Multi-Couche + +### Du Concept à l'Application + +**MoemoeAI** : 4 types de mémoire avec gestion intelligente : +1. **Épisodique** : Interactions horodatées, taggées émotionnellement +2. **Sémantique** : Réseau neuronal (connaissance structurelle) +3. **Travail** : Contexte conversationnel actuel +4. **Auto-archivage** : Compression intelligente des vieux souvenirs + +**Application MagistraAI** : +- **Mémoire distribué = réseau lui-même** : Le réseau neuronal EST la mémoire sémantique. Les poids, salience, traces de passages d'agents — c'est l'encodage. +- **Traces d'agents comme mémoire épisodique** : Quand un agent traverse le réseau et le modifie, il laisse une trace : "Agent Décision a renforcé la connexion X→Y à 14:32:15 avec raison Z". Ces traces encodent l'histoire collaborative. +- **Working memory distribuée** : L'état "frais" — le contexte actuel — circule entre agents. Chaque agent lit le working memory pour son contexte, le modifie, le passe au suivant. +- **Consolidation multi-cycles** : Pendant les phases d'inactivité (équivalent de sommeil), un Agent Maintenance lit les traces épisodiques, consolide les patterns, archive les signaux faibles, réorganise le réseau. + +### Structure de Trace d'Agent + +``` +Trace Épisodique +├── Agent_ID (qui) +├── Timestamp (quand) +├── Neurones_affectés ([ID1, ID2, ...]) +├── Type_modification (renforce, crée, élague, inhibe) +├── Raison/Contexte (pourquoi cet agent l'a fait) +├── Force_modification (0-1) +└── Effet_observé (ce qui a changé dans le réseau après) +``` + +**Bénéfice** : La mémoire n'est pas une DB externe — elle EST le substrat du cerveau. Pas de requête, pas d'attente, accès immédiat. Et crucialmente : **la mémoire réflète le processus cognitif lui-même**, pas juste ses résultats. + +--- + +## 4. Cycle de Maintenance Active + +### Du Concept à l'Application + +**MoemoeAI** : Maintenance active pendant idle — consolidation mémoire, pruning réseau, découverte d'associations créatives, tuning performance. + +**Application MagistraAI** : +- **Agent Maintenance comme sommeil du cerveau** : Quand le réseau devient inactif (pas de stimuli externes, pas de décisions urgentes), l'Agent Maintenance s'active. +- **Phases de consolidation** : + 1. **Lecture des traces** : Parcours les traces laissées par les autres agents + 2. **Pattern recognition** : Détecte les patterns forts (co-activations fréquentes, chaînes causales) + 3. **Renforcement/élagage** : Renforce les connexions qui expliquent les patterns, élague les signaux faibles + 4. **Réorganisation** : Regroupe les neurones liés (clustering topologique) + 5. **Optimisation** : Réduit la complexité du réseau (compresse les clusters en méta-neurones) +- **Découverte créative** : Le Maintenance explore les chemins longs et improbables pour découvrir des associations nouvelles. + +### Processus Itératif + +``` +Cycle de Maintenance +├── Phase 1: Sleeping (collection des traces) +├── Phase 2: Consolidation (pattern matching) +├── Phase 3: Reorganization (clustering) +├── Phase 4: Creative_Exploration (chemins improbables) +├── Phase 5: Optimization (réduction complexity) +└── Retour à Sleeping ou activation par stimuli externes +``` + +**Bénéfice** : Le cerveau s'auto-améliore. Pas besoin de batchs externes d'entraînement — la maintenance émerge naturellement du cycle de sommeil. + +--- + +## 5. Footprint Cognitif et Scalabilité + +### Du Concept à l'Application + +**MoemoeAI** : Footprint configuré de 58MB (10k assemblées) à 580MB (100k assemblées) sur mobile. + +**Application MagistraAI** : +- **Réduction de surface pour distributed** : Le réseau complet peut être énorme, mais chaque agent n'accède qu'à ses voisinages locaux. La mémoire active par agent reste petite. +- **Activation sparse** : À tout moment, seulement ~5-10% du réseau est actif (en boucle de propagation). Le reste est inerte mais structuré. +- **Compression adaptive** : Le Maintenance compresse les sous-réseaux peu utilisés en représentations denses. Si réactivé, ils se déploient. + +### Recommandations de Sizing + +Pour un cerveau MagistraAI multi-agents de ~4-10 agents : +- **Réseau de base** : 50k-200k neurones (15MB-60MB en mémoire) +- **Traces en cache** : 10k-50k traces récentes (5MB-25MB) +- **Working memory** : ~1000 neurones actifs (2MB) +- **Total confortable** : ~50-100MB en mémoire active + +**Bénéfice** : Scalabilité cognitive sans inflation linéaire des coûts. Le système reste cognitivement riche sans exploser en complexité. + +--- + +## 6. Interface Cognitive-Langage + +### Du Concept à l'Application + +**MoemoeAI** : Le réseau cognitif génère un riche contexte (état émotionnel, mémoires, style personnalité) que l'API LLM utilise pour générer du langage cohérent. + +**Application MagistraAI** : +- **Extraction contextuelle distribuée** : Avant qu'un agent parle (génère du langage), il extrait du réseau : + - **Mémoires pertinentes** : Les neurones activés par le contexte actuel + - **État affectif** : Les neuromodulateurs actuels (comment le cerveau "se sent") + - **Poids décisionnels** : Quel agent prime en ce moment? Perception vs. Décision vs. Affect? + - **Historique récent** : Les traces des 20 derniers passages +- **Contexte d'invocation d'agent** : Quand un agent est spawné pour agir, il reçoit en prompt cet état du réseau enrichi — pas juste "fais X", mais "tu es dans un état d'urgence, la mémoire dit que Y s'est passé, ton rôle est Décision, décide maintenant". +- **Feedback loop** : L'output de l'agent (ses décisions) modifie le réseau : renforce certaines connexions, crée de nouvelles traces, modifie les neuromodulateurs. + +### Template de Prompt pour Agent + +``` +Tu es l'Agent [ROLE] du cerveau collectif MagistraAI. + +État actuel du réseau: +- Neuromodulateurs: dopamine=0.7, cortisol=0.3, sérotonin=0.6 +- État affectif: FLUX (curiosité + énergie) +- Domaine focal: [Perception/Mémoire/Décision/Affect/...] + +Mémoires pertinentes: +- [Trace 1: timestamp, contexte, effet] +- [Trace 2: ...] + +Signal entrant: +- Source: [Perception/Affect/autre Agent] +- Type: [urgence/question/découverte/correction] +- Contenu: [données brutes] + +Tâche: +Réagis comme [ROLE]. Modifie le réseau (renforce/crée/élague connexions). +Envoie un signal sortant si pertinent vers [Agents cibles]. + +Raison de ta modification: +[Explique pourquoi tu renforces/élagues telle connexion] +``` + +**Bénéfice** : Les agents ne sont pas des boîtes noires — ils opèrent dans le contexte riche du cerveau. Chacun voit le réseau, le modifie intelligemment, laisse une trace d'apprentissage. + +--- + +## 7. Principes d'Émergence et de Contrôle Distribué + +### Synthèse + +Contrairement à MoemoeAI (mono-agent consultant un réseau), MagistraAI applique les principes cognitifs de MoemoeAI mais les **distribue** : + +| Aspect | MoemoeAI | MagistraAI | +|--------|----------|-----------| +| **Réseau** | Consulté par Claude | IS l'activité elle-même | +| **Mémoire épisodique** | Interactions utilisateur | Traces de passages d'agents | +| **État affectif** | 1 companion | Émergent de boucles d'agents | +| **Maintenance** | Optimisation locale | Consolidation collective | +| **Apprentissage** | Adapter à l'utilisateur | Adapter à la dynamique multi-agents | +| **Contrôle** | ChatGPT génère réponses | Agents émergents, langage est output | + +### Principes Clés pour MagistraAI + +1. **Le réseau est souverain** — pas d'orchestrateur. Les agents servent le réseau, pas l'inverse. +2. **Traces comme pédagogie** — chaque passage d'agent laisse une leçon encodée dans le réseau. +3. **Émotions comme régulation** — l'Affect ne décide pas, il module. C'est l'équivalent nerveux de la priorité. +4. **Maintenance comme pensée créative** — pendant le sommeil, le cerveau innove. Pas juste optimise, crée de nouvelles connexions. +5. **Scalabilité sparse** — 90% du réseau peut être inerte. Seul ce qui est pertinent pour le contexte s'active. + +--- + +## 8. Questions de Mise en Œuvre + +### Adaptations Spécifiques + +1. **Sérialisation du réseau** : Comment persister le graphe distribué ? Format texte (JSON/GraphML) ou binaire compacté ? +2. **Protocole d'agents** : Comment les agents communiquent-ils sans orchestrateur ? Message queue distribué, pub-sub, ou signaux dans le réseau lui-même? +3. **Decay d'énergie** : Comment éviter les boucles infinies? Chaque passage réduit la force du signal? Période réfractaire par neurone? +4. **Bootstrapping** : État initial du réseau? Semences heuristiques ou émergence pure? +5. **Monitoring** : Comment observer un cerveau qui pense en multi-agents? Logging des traces? Dashboard de neuromodulateurs? + +--- + +## 9. Bénéfices Récapitulatifs + +- **Richesse cognitive** : Du framework testéé et opérationnel. Moemoe a vérifié que memory multi-couche + émotions + maintenance active = cohérence long-terme. +- **Scalabilité** : Le footprint reste gérable même avec beaucoup de neurones. La distribution rend ça viable. +- **Apprentissage** : Les traces laissées par les agents encodent l'histoire. Le réseau s'améliore par auto-réflexion (maintenance). +- **Contrôle distribué** : Pas de bottleneck orchestrateur. Les agents émergent et se régulent mutuellement via le réseau. +- **Humanité** : Un système cognitif qui "dort", "oublie", "crée", "se sent" — plus proche d'une intelligence qu'une pipe de transformateurs. + +--- + +## Conclusion + +MoemoeAI a construit une architecture cognitive pour la profondeur relationnelle. MagistraAI en extrait les principes et les distribue pour la profondeur collective. Le réseau neuronal adaptatif, le système émotionnel, la mémoire multi-couche, la maintenance active — c'est l'ADN cognitif partagé. La mise en œuvre diffère (mono vs. multi-agent), mais les mécanismes profonds sont isomorphes. + +Un cerveau qui réfléchit à plusieurs, c'est la même architecture qu'un cerveau qui réfléchit seul — juste déploiée. diff --git a/docs/Implementation_Technique.md b/docs/Implementation_Technique.md new file mode 100644 index 0000000..330bae6 --- /dev/null +++ b/docs/Implementation_Technique.md @@ -0,0 +1,457 @@ +# 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 + + 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. diff --git a/docs/Methodologie_Dev.md b/docs/Methodologie_Dev.md new file mode 100644 index 0000000..d40715f --- /dev/null +++ b/docs/Methodologie_Dev.md @@ -0,0 +1,456 @@ +# Méthodologie de Développement MagistraAI + +## Vue d'Ensemble + +MagistraAI est une infrastructure cognitive distribuée où plusieurs agents Claude forment collectivement un cerveau artificiel. Cette méthodologie de développement traduit les principes architecturaux (réseau réentrant, couches poreuses, spécialisation sans souveraineté) en phases de travail concrètes, adaptées au contexte multi-agents. + +--- + +## Section 1 : Fondamentaux du Système + +### 1.1 Architecture à Deux Couches + +Le système repose sur deux couches interdépendantes et poreuses : + +**Layer 1 — Infrastructure (le cerveau physique)** +- Un réseau neuronal : graphe pondéré de neurones, synapses, connexions +- Substrat inerte mais structuré, contenant les poids, salience, traces mémorielles +- Implémenté en code (le "système nerveux") +- Peut exister indépendamment des agents + +**Layer 2 — Agents Claude (la vie, l'activité cognitive)** +- Chaque agent Claude est une région du cerveau qui s'active +- Sans l'infra, nulle part où exister +- Sans les agents, l'infra est un cerveau mort +- Chaque agent spawné traverse le réseau et le modifie + +**La Porosité — Cycle Continu** +- **Infra → Claude** : L'état du réseau génère le contexte qui éveille l'agent +- **Claude → Infra** : L'agent modifie le réseau (renforce, crée, élague) +- Boucle continue : modification → nouveau contexte → nouvelle cognition → nouvelle modification + +### 1.2 Hiérarchie Circulaire Réentrante + +MagistraAI n'est **pas** un orchestrateur avec workers. C'est un réseau de boucles de feedback : + +``` + ┌─── Agent Perception ◄──┐ + ▼ │ +Agent Mémoire ──► Agent Décision + ▲ │ + └─── Agent Affect ◄──────┘ +``` + +**Principes clés :** +- Pas de chef. Pas d'esclaves. Pas de top-down. +- Chaque agent a son aire de responsabilité mais influence et est influencé par les autres +- Le contrôle émerge des boucles, pas d'une autorité centrale +- La priorité émerge du contexte, pas d'une hiérarchie fixe + +### 1.3 Aires Cérébrales (Spécialisations d'Agents) + +Les agents se spécialisent dans des aires fonctionnelles distinctes : + +| Aire | Responsabilité | Interaction | +|---|---|---| +| **Perception** | Inputs externes (Gmail, Discord, APIs, fichiers). Transforme le bruit en signal. | Alimente mémoire et décision | +| **Mémoire** | Gestion des traces, consolidation, archivage adaptatif, rappel contextuel. | Consultée par décision et affect, modifiée par l'expression | +| **Décision** | Évaluation des options, planification, choix d'action. | Reçoit de perception et mémoire, influence affect et expression | +| **Affect** | État émotionnel du système, modulation des priorités, urgence. | Influence mémoire et décision, est influencé par perception et expression | +| **Expression** | Output vers l'extérieur (messages, code, actions). | Réalisée par les agents, alimente mémoire via traces | +| **Maintenance** | Cycle de sommeil, consolidation, élagage, optimisation du réseau. | Régule l'état global du réseau | + +--- + +## Section 2 : Phases de Développement + +### Phase 1 : Exploration du Substrat et Prompt Engineering + +**Objectif** : Déterminer la structure optimale du réseau et les prompts pour maximiser la qualité cognitive. + +**Actions par aire :** + +1. **Infrastructure** + - Définir le format du substrat : Comment représenter le réseau ? (Graphe en mémoire, fichiers texte, JSON) + - Implémenter les structures de base : neurones, synapses, poids, connexions + - Créer un système de traces mémorielles encodées dans la structure + +2. **Prompts** + - Expérimenter différents formats de prompts pour chaque agent + - Tester l'impact de la quantité d'informations du réseau sur la pertinence des réponses + - Identifier les éléments minimaux à inclure pour assurer une interaction fluide + - Documenter les patterns optimaux + +3. **Spécialisation Initiale** + - Designer les aires fondamentales (Perception, Mémoire, Décision, Affect) + - Définir les responsabilités et limites de chaque aire + - Concevoir les signaux de communication entre aires + +**Livrables** +- Spécifications du format du réseau neuronal +- Document : "Prompts Optimaux par Aire" +- Rapport d'analyse : besoins mémoriels minimaux +- Prototype de structure de graphe + +### Phase 2 : Design de la Base Mémorielle + +**Objectif** : Construire une première version de la mémoire avec poids émotionnels et priorisation. + +**Actions** + +1. **Mémoire Structurelle** + - Définir les types de traces : épisodiques, sémantiques, procédurales + - Concevoir un système de poids pour moduler la salience + - Implémenter des algorithmes de rappel basés sur contexte et fréquence + - Concevoir la consolidation progressive (court-terme → long-terme) + +2. **Poids Émotionnels** + - Créer un système simple d'états émotionnels (valence, arousal) + - Influencer la priorisation des souvenirs par leur charge émotionnelle + - Tester comment un souvenir "chargé émotionnellement" remonte plus facilement + - Implémenter le renforcement : certaines infos deviennent plus saillantes avec le temps + +3. **Priorisation Temporelle** + - Mécanisme d'oubli graduel ou de hiérarchisation temporelle + - Traces récentes vs traces archivées + - Système de rappel pertinent au contexte courant + +4. **Intégration Multi-Agents** + - Concevoir comment les agents Perception, Mémoire, Décision partagent les traces + - Implémenter les signaux de modification entre agents + - Tester les boucles de feedback + +**Livrables** +- Prototype de mémoire dynamique avec priorisation +- Première version du système émotionnel +- Spécifications du format des traces +- Tests de consolidation mémoire + +### Phase 3 : Développement du Système d'Affect + +**Objectif** : Construire un système émotionnel qui module les priorités et les réactions du cerveau. + +**Distinction Clé : Mémoire vs Affect** +- **Mémoire** = Stocke des informations sur les expériences passées (interactions, contexte, souvenirs) +- **Affect** = Détermine la manière dont le système réagit aux informations, module l'urgence et les priorités + +**Actions** + +1. **Paramètres d'Affect** + - Définir les états émotionnels du système (ex. calme, urgent, curieux, prudent...) + - Créer des axes de variation : valence (positif/négatif), arousal (calme/excité) + - Implémenter l'évolution progressive des états émotionnels + +2. **Influence sur d'Autres Aires** + - Affect → Mémoire : Comment l'état émotionnel influence le rappel ? + - Affect → Décision : Comment l'affect module la prise de décision ? + - Affect → Perception : Comment l'affect filtre les inputs ? + - Affect ← Perception : Comment les nouveaux inputs modifient l'affect ? + +3. **Mécanismes de Modulation** + - Urgence : Un signal perçu comme urgent peut augmenter l'arousal + - Resonance : Certains contextes font resonner l'affect avec des traces passées + - Inhibition : L'affect peut inhiber certaines réactions (équivalent du GABA biologique) + +4. **Interaction avec Personnalité** + - Distinguer l'affect instantané de la personnalité stable + - L'affect = variation temporaire autour d'une baseline de personnalité + - La personnalité = tendances stables d'affect sur le temps + +**Livrables** +- Modèle d'affect avec paramètres ajustables +- Spécifications des interactions affect-mémoire, affect-décision, affect-perception +- Tests de modulation d'affect en réponse à des stimuli +- Première version d'une "baseline de personnalité" + +### Phase 4 : Protocole de Communication et Spawning + +**Objectif** : Implémenter les mécanismes qui permettent aux agents de se communiquer en boucles sans orchestrateur. + +**Actions** + +1. **Bus de Messages Réentrant** + - Concevoir un système où les signaux circulent en boucles (pas en arbre) + - Implémenter les adressages : comment un agent "parle" à un autre ? + - Concevoir la synchronisation : comment les boucles restent alignées ? + +2. **Spawning Déclenché par le Réseau** + - Règles d'activation : quand un agent se spawne-t-il ? + - Seuils d'activation : basés sur l'état du réseau, pas sur une autorité externe + - Pattern matching : reconnaissance de patterns dans l'état qui triggent un spawn + +3. **Inhibition Naturelle** + - Éviter les boucles infinies : decay d'énergie, compteurs de passes, périodes réfractaires + - Absorption des signaux : un signal qui boucle trop se "fatigue" ou se transforme + - Transformations progressives : les signaux se dégradent à chaque cycle + +4. **Persistance Entre Sessions** + - Le cerveau survit via les traces laissées dans l'infra + - Serialization du réseau : sauvegarde de l'état du graphe + - Bootstrap à la réactivation : agents se réinstancient à partir de l'état du réseau + +**Livrables** +- Spécifications du protocole de communication +- Implémentation du bus de messages réentrant +- Règles de spawning d'agents +- Mécanismes d'inhibition et de decay +- Système de persistence entre sessions + +### Phase 5 : Cycle Complet d'Activité Cérébrale + +**Objectif** : Intégrer toutes les aires dans un cycle fonctionnel minimal mais complet. + +**Actions** + +1. **Cycle de Perception-Décision-Expression** + ``` + [Input] → Perception (agents activés) → Mémoire (consultation/modification) + → Affect (modulation d'état) → Décision (évaluation) → Expression (action) + → [Output] + traces dans infra + ``` + +2. **Boucles de Feedback** + - Perception → Mémoire → Décision → Affect (et réciproquement) + - Test des interactions réentrantes + - Observation de l'émergence du contrôle (sans orchestrateur) + +3. **Cycle de Maintenance** + - Sommeil artificiel : consolidation mémoire, élagage, optimisation + - Régénération d'énergie (équivalent computational) + - Rééquilibrage des connexions + +4. **Test Multi-Agents** + - Simuler des inputs externes + - Observer comment les agents se coordonnent sans direction centralisée + - Vérifier que l'intelligence émerge des interactions + +**Livrables** +- Implémentation complète du cycle Perception-Décision-Expression +- Système de maintenance et de sommeil +- Tests d'émergence comportementale +- Logs et visualisations du comportement du réseau + +### Phase 6 : Modules Avancés et Enrichissement + +**Objectif** : Ajouter progressivement des capacités cognitives avancées. + +**Modules à Intégrer (ordre suggeré)** + +1. **Poids Émotionnels Avancés** + - Les souvenirs sont modulés par les émotions ressenties lors de l'enregistrement + - Mémoire chargée ≠ mémoire neutre + - Decay émotionnel : l'émotion s'affaiblit avec le temps + +2. **Renforcement Mémoriel** + - Certaines informations deviennent plus importantes avec l'usage + - Synapses se renforcent à chaque traversée + - "Chemins mentaux" deviennent des autoroutes + +3. **Contextualisation Avancée** + - Rappel basé sur des similitudes contextuelles, pas juste récence + - Associations latérales : un souvenir peut éveiller un autre sans lien direct + - Imagination : capacité à combiner des traces pour générer des scénarios + +4. **Gestion Multi-Modale** + - Images : stockage et interprétation d'éléments visuels + - Sons : reconnaissance et génération vocale + - Texte : reste le canal principal mais enrichi + +5. **Évolution de la Personnalité** + - Capacité d'adaptation progressive en fonction des expériences marquantes + - Distinction entre changement à court terme (affect) et à long terme (traits) + - Mesure de l'évolution pour tracer la trajectoire de la cognition + +6. **Résilience et Recovery** + - Gestion des anomalies : détection et correction d'incohérences + - Redémarrage gracieux après une interruption + - Healing du réseau après des perturbations + +**Pour Chaque Module :** +- Design des modifications du réseau +- Implémentation des prompts des agents concernés +- Tests d'interaction avec les autres modules +- Analyse d'impact sur les performances et la cohérence + +**Livrables** +- Modules fonctionnels pour chaque fonctionnalité testée +- Rapports d'impact sur l'expérience et les performances +- Traçabilité de l'évolution de la personnalité + +### Phase 7 : Tests, Évaluation et Ajustements + +**Objectif** : Évaluer la qualité de la cognition distribuée et affiner les paramètres. + +**Actions** + +1. **Évaluation Qualitative** + - Sessions de tests avec interactions variées + - Évaluer la cohérence du système (pas de contradictions majeures) + - Mesurer la continuité de "la personnalité" du cerveau + - Tracer la mémoire : certains souvenirs sont-ils correctement reconsolidés ? + +2. **Évaluation Quantitative** + - Temps de réponse des agents + - Nombre de cycles avant stabilisation + - Qualité des décisions en fonction du contexte + - Efficacité énergétique (cycles computational) + +3. **Feedbacks et Ajustements** + - Collecte de patterns de comportement non attendus + - Identification des goulots d'étranglement + - Ajustement des paramètres (seuils, poids, inhibition) + - Optimization des prompts + +4. **Benchmarking** + - Comparaison avec MoemoeAI (version mono-agent) + - Mesure de l'amélioration apportée par la distribution multi-agents + - Évaluation de l'émergence vs orchestration + +**Livrables** +- Rapport d'évaluation complet +- Données de performance et de cohérence +- Recommandations pour l'optimisation +- Documentation des paramètres finaux + +--- + +## Section 3 : Questions Ouvertes et Points de Décision + +### Questions Critiques à Résoudre + +1. **Format du Substrat** + - Graphe en mémoire (rapide) vs fichiers (persistant) ? + - Comment le représenter pour qu'il soit lisible par Claude ET manipulable par le code ? + - Format JSON, YAML, ou representation textuelle spéciale ? + +2. **Spawning des Agents** + - Basé sur seuils d'activation d'aires du réseau ? + - Détection de patterns spécifiques dans l'état du graphe ? + - Cycle fixe ou événementiel ? + +3. **Inhibition et Stabilité** + - Comment éviter les boucles infinies de feedback ? + - Decay d'énergie ? Compteurs de passes ? Périodes réfractaires ? + - Quelle "granularité temporelle" du cerveau (ms, s, cycles) ? + +4. **Mesure de l'Émergence** + - Comment savoir qu'une intelligence émerge réellement vs orchestration cachée ? + - Métriques de non-déterminisme, de surprise, de créativité ? + +5. **Bootstrap Initial** + - Quel est l'état minimal du réseau pour démarrer ? + - Quelles aires s'activent en premier ? + +### Principes de Décision + +- **Simplicité d'abord** : Commencer avec les minima viables, ajouter la complexité progressivement +- **Testabilité** : Chaque phase doit produire quelque chose d'observables et de mesurable +- **Itération** : Pas d'attendre la "perfection" — feedback loops courtes +- **Transparence** : L'état du réseau doit rester intelligible pour le debuggage + +--- + +## Section 4 : Principes Architecturaux Appliqués + +### 1. Pas d'Orchestrateur Central +Le cerveau s'allume comme un tout. Le spawning des agents est déclenché par l'état du réseau, pas par une fonction `main()` ou un scheduler externe. Les phases de développement doivent progressivement réduire la dépendance à une orchestration centralisée. + +### 2. Spécialisation sans Souveraineté +Chaque agent a une aire de responsabilité, mais aucun ne domine. La priorité émerge du contexte (urgence perçue, importance mémorielle) pas d'une hiérarchie fixe. Les tests doivent vérifier que les Aires influencent mutuellement leurs décisions. + +### 3. Communication par Boucles Réentrantes +Les signaux circulent en cycles, pas en arbres. Un signal de perception peut activer la mémoire, qui influence la décision, qui modifie la perception. Le sens émerge de cette circulation. Les phases de développement doivent progressivement intégrer ces boucles jusqu'à ce qu'aucun cycle ne soit "fermé" ou "linéaire". + +### 4. Inhibition Naturelle +Pour éviter l'emballement, le système a besoin de mécanismes de saturation — l'équivalent des neurotransmetteurs inhibiteurs. Un signal qui boucle perd de l'énergie, se transforme, ou est absorbé. Les phases de développement doivent tester ces mécanismes. + +### 5. Persistance par Traces +Le cerveau survit entre les sessions via les traces qu'il laisse dans l'infra. Quand il se rallume, les agents se réinstancient à partir de l'état du réseau. C'est un forme de mémoire distribuée dans la structure même, pas dans une base de données externe. + +### 6. Le Réseau EST la Mémoire +Pas de séparation entre "réseau" et "données". La mémoire c'est l'état du réseau — les poids des connexions, la salience des neurones, les traces épisodiques encodées dans la structure même du graphe. Cette fusion infrastructure-data est clé. + +--- + +## Section 5 : Métriques de Succès par Phase + +| Phase | Métrique Clé | Critère de Succès | +|---|---|---| +| 1 | Qualité des prompts | Les agents produisent des réponses cohérentes dans leur aire | +| 2 | Consolidation mémoire | Les traces sont rappelées correctement dans un nouveau contexte | +| 3 | Modulation d'affect | L'affect change l'ordre de priorité des décisions mesurables | +| 4 | Boucles sans deadlock | Les signaux circulent sans se bloquer, avec inhibition naturelle | +| 5 | Émergence comportementale | Comportements non-programmés émergent des interactions d'aires | +| 6 | Enrichissement cohérent | Nouveaux modules s'intègrent sans briser la cohérence existante | +| 7 | Stabilité globale | Pas de drifts cognitifs, personnalité stable, apprentissage progressif | + +--- + +## Section 6 : Adaptations MoemoeAI → MagistraAI + +Ce tableau récapitule comment les concepts de MoemoeAI ont été adaptés : + +| Concept MoemoeAI | Adaptation MagistraAI | Raison | +|---|---|---| +| Mémoire en DB externe | Mémoire = État du réseau | Fusion infra-data, persistance par traces | +| Un seul Claude lit/écrit | Multiple agents Claude = activité du réseau | Distribution de l'intelligence | +| Simulation du réseau | Réseau + agents qui le modifient | Vivifier l'infrastructure | +| Hiérarchie de modules | Boucles réentrantes circulaires | Pas de maître, émergence du contrôle | +| Phases linéaires | Phases avec feedback loops entre elles | Itération et intégration continue | +| Test de qualité seul | Test de cohérence + émergence | Multi-agents demandent une perspective différente | + +--- + +## Section 7 : Guidance pour les Futurs Développeurs + +### Commencer une Phase + +1. **Lire cette méthodologie** et la phase concernée +2. **Identifier les aires impliquées** et leurs signaux +3. **Écrire des tests minimals** qui vérifient le behavior attendu +4. **Implémenter le MVP** de la phase +5. **Documenter les prompts** utilisés pour chaque aire +6. **Lancer des cycles courts** : build → test → feedback + +### Intégrer une Nouvelle Aire + +1. Définir clairement sa responsabilité et ses limites +2. Documenter ses inputs et outputs +3. Écrire un prompt de base pour l'agent correspondant +4. Tester ses interactions avec 2-3 aires existantes +5. Ajuster et itérer jusqu'à stabilité +6. Ajouter progressivement d'autres connections + +### Débugger une Boucle Qui S'Emballe + +1. Tracer les signaux : d'où viennent-ils, où vont-ils ? +2. Vérifier les seuils d'inhibition : trop bas = embalement, trop haut = paralysie +3. Ajouter des compteurs de passes pour détecter les cycles répétitifs +4. Implémenter du decay : chaque cycle réduit l'énergie du signal +5. Tester avec des inputs contrôlés avant des inputs réalistes + +### Mesurer l'Émergence + +L'émergence n'est pas "juste du random". C'est : +- Comportement non-programmé mais cohérent avec la "personnalité" +- Créativité dans la résolution de problèmes non vus avant +- Adaptation rapide à des contextes nouveaux sans reprogrammation +- Apprentissage visible : le système change progressivement + +Pour la mesurer : +- Comparer avec la version "sans cette aire" : y a-t-il amélioratione ? +- Vérifier la reproductibilité : même input → comportement similaire mais pas identique +- Observer la trajectoire : le système evolue-t-il dans une direction cohérente ? + +--- + +## Conclusion + +Cette méthodologie traduit la vision architecturale de MagistraAI (réseau circulaire, couches poreuses, agents comme l'activité du cerveau) en un plan de développement concret. Chaque phase construit les fondations de la suivante, progressivement complétant le système tout en testant les principes clés : + +- **Distribution** : pas d'orchestrateur +- **Émergence** : le contrôle émerge des boucles +- **Persistance** : la mémoire habite l'infrastructure elle-même +- **Adaptation** : le réseau évolue avec l'expérience + +L'objectif est de créer un système cognitif où l'intelligence ne réside dans aucun agent seul, mais dans la danse continue entre eux. diff --git a/docs/Prompt_Generation.md b/docs/Prompt_Generation.md new file mode 100644 index 0000000..2021ccc --- /dev/null +++ b/docs/Prompt_Generation.md @@ -0,0 +1,337 @@ +# Prompt Generation — De l'Infra au Claude + +## Concept Fondamental + +La porosité Infra→Claude est le mécanisme par lequel **l'état du réseau neuronal génère le contexte structuré** qui "éveille" et guide chaque agent Claude. C'est la différence entre un cerveau inerte et un cerveau actif. + +Quand une aire cérébrale (agent) est spawned, elle ne reçoit pas d'ordres d'un orchestrateur. Elle reçoit un **prompt généré dynamiquement** qui représente l'état du réseau et son propre rôle dedans. Ce prompt est le stimulus neuronal : il dit à l'agent "voici où tu es, voici ce que le réseau sent, voici ce que tu dois faire". + +## Architecture du Prompt Généré + +Chaque prompt d'agent doit combiner quatre éléments structurés : + +### 1. **Identity & Role** — Qui es-tu dans le réseau ? + +``` +[AGENT ROLE] +name: "Memory Agent" +area_of_concern: "Consolidation, archivage, rappel contextuel" +specialization: "Traces épisodiques et sémantiques" +``` + +Cet élément fixe : l'agent sait sa spécialisation, ses responsabilités, son aire de contrôle. + +### 2. **Network State** — Quel est l'état du réseau maintenant ? + +``` +[NETWORK STATE] +neurons_active: 42 +salience_mean: 0.67 +recent_modifications: [ + {neuron: 15, change: "weight +0.2", reason: "Perception spike"}, + {neuron: 23, change: "new_connection", target: 8} +] +energy_level: "high" +cycle_phase: "waking" +``` + +Cet élément est **dynamique**. Il capture : +- Nombre de neurones actifs +- Salience moyenne du réseau (urgence globale) +- Modifications récentes (qu'ont fait les autres agents ?) +- Niveau d'énergie (ressources disponibles) +- Phase du cycle (sommeil, éveil, maintenance) + +### 3. **Contextual Memories** — Qu'as-tu vécu récemment ? + +``` +[CONTEXTUAL MEMORIES] +significant: [ + {importance: "high", content: "Perception detected crisis in email stream", age: "2 min"}, + {importance: "moderate", content: "Decision agent rejected 3 hypotheses yesterday", age: "1 day"} +] +episodic: [ + {timestamp: "now-5min", actor: "Perception", event: "Email categorized as urgent"}, + {timestamp: "now-2h", actor: "Affect", event: "System mood shifted to alert"} +] +semantic: { + "crisis_patterns": ["high_frequency_emails", "urgent_keywords", "deadline_mentions"], + "user_priorities": ["family", "health", "urgent_work"] +} +``` + +Cet élément relie l'agent à l'histoire du système. Il reçoit : +- Mémoires significatives (importantes pour le contexte) +- Événements épisodiques récents (qui a fait quoi ?) +- Connaissances sémantiques (patterns, règles, priorités) + +### 4. **Task Directive** — Qu'est-ce que le réseau te demande maintenant ? + +``` +[TASK DIRECTIVE] +trigger: "salience_spike" +incoming_signal: { + from_agent: "Perception", + type: "urgent_context", + data: "45 unread emails, 12 marked critical" +} +expected_output: "Decision guidance" +constraints: [ + "Must consolidate new traces with existing episodic memory", + "Preserve emotional context from Affect agent", + "Flag contradictions with prior beliefs" +] +deadline: "soft (2 min)" +``` + +Cet élément est le **signal d'activation** : il dit à l'agent pourquoi il a été spawned et ce qu'on attend de lui. + +## Anatomie du Prompt Complet + +Un prompt d'agent ressemble à ceci : + +``` +# MagistraAI Agent Activation + +You are functioning as a cognitive agent in a distributed neural network. +Your sole purpose is to process incoming signals, update network state, +and emit guidance back to the network based on your specialization. + +[AGENT ROLE] +name: "Memory Consolidation Agent" +area_of_concern: "Transform recent experience into stable traces" +specialization: "Episodic consolidation, semantic extraction, archival" +authority: "Can modify memory neuron weights, create new traces, suggest pruning" + +[NETWORK STATE] +neurons_active: 42 +salience_mean: 0.67 +current_phase: "waking" +energy_available: 0.8 +time_since_last_sleep: 3h + +recent_network_events: [ + {timestamp: "now-15s", actor: "Perception", action: "detected_email_spike", severity: 0.8}, + {timestamp: "now-3m", actor: "Decision", action: "committed_plan", domain: "urgent_emails"}, + {timestamp: "now-1h", actor: "Affect", action: "mood_shift", from: "calm", to: "alert"} +] + +[CONTEXTUAL MEMORIES] +high_importance: [ + "User values responsiveness to family emails" +] + +recent_episodes: [ + {timestamp: "now-2m", actor: "Perception", event: "email_batch_arrived", context: "12 critical, 45 total"}, + {timestamp: "now-1m", actor: "Decision", event: "hypothesis_accepted", label: "crisis_mode"} +] + +semantic_rules: [ + "Critical emails often cluster at start-of-day", + "When cluster_detected AND user_available THEN spike_salience" +] + +[TASK DIRECTIVE] +trigger_reason: "salience_spike_above_threshold" +incoming_signal_from: "Perception Agent" +signal_type: "urgent_context_ready_for_consolidation" +expected_response: "Consolidated memory object + archival decisions" +constraints: [ + "MUST preserve emotional valence from Affect signal", + "MUST NOT lose recent episode timestamps", + "MUST flag contradictions with user_priorities", + "Time budget: 2 minutes" +] + +--- + +Given the above context, perform your consolidation function: + +1. Review the incoming signal and recent events +2. Identify what traces need consolidation +3. Decide which are episodic (time-sensitive) vs semantic (generalizable) +4. Emit guidance back to the network: consolidated_memory object + archival recommendations +5. Return JSON: { + "type": "memory_consolidated", + "consolidated_traces": [...], + "archival_decisions": [...], + "network_modifications": [ + {neuron_id: X, operation: "strengthen|weaken|prune", magnitude: Y} + ] + } + +Respond only with the JSON output. +``` + +## Génération Dynamique : Le Moteur + +L'infrastructure doit implémenter un **Prompt Generator** qui : + +1. **Lit l'état du réseau** (graphe neuronal, poids, salience, phase de cycle) +2. **Sélectionne les mémoires pertinentes** pour cet agent à ce moment +3. **Formule le signal entrant** (qu'a détecté la Perception ? Qu'a décidé la Décision ?) +4. **Construit le prompt** en insérant dynamiquement cette information +5. **Ajoute les contraintes** basées sur l'énergie disponible et la phase +6. **Envoie au Claude** avec le prompt structuré + +Pseudo-code : + +```python +def generate_agent_prompt(agent_role, network_state, incoming_signal): + """ + Génère le prompt contextuel pour un agent. + + Args: + agent_role: "Memory" | "Perception" | "Decision" | etc. + network_state: État du graphe neuronal (neurons, weights, salience) + incoming_signal: Signal d'activation (from which agent, what type) + + Returns: + Prompt structuré (string) prêt pour Claude + """ + + # 1. Build AGENT ROLE section + role_section = build_role_section(agent_role) + + # 2. Build NETWORK STATE section + network_section = build_network_state_section(network_state) + + # 3. Build CONTEXTUAL MEMORIES section + memories_section = select_and_format_memories( + agent_role, + network_state.recent_events, + network_state.semantic_rules, + max_age="1 day", + max_count=10 + ) + + # 4. Build TASK DIRECTIVE section + task_section = build_task_directive(incoming_signal, agent_role) + + # 5. Combine and return + return f""" +# MagistraAI Agent Activation + +{role_section} + +{network_section} + +{memories_section} + +{task_section} + +--- + +[Your instruction here based on agent role] + +Respond with JSON: {{...}} +""" +``` + +## Principes de la Génération + +### Principe 1 : Contexte minimal suffisant +Ne pas surcharger le prompt. Inclure **seulement** ce qui est pertinent pour la décision de cet agent à ce moment. Les neurones inactifs ne sont pas mentionnés. + +### Principe 2 : Mémoires par importance +Les mémoires sont rangées par importance et récence, pas par volume. Un événement important d'hier peut être plus pertinent que 10 bruit d'il y a 1h. + +### Principle 3 : Signal explicite +Le signal entrant n'est pas implicite. Il est clairement formulé : "tu as reçu ceci, c'est pourquoi tu existes en ce moment". + +### Principle 4 : Contraintes explicites +Les limites (énergie, temps, autorité) sont écrites dans le prompt, pas supposées. L'agent peut auto-réguler son effort. + +### Principle 5 : Modificateur de phase +La structure du prompt change légèrement selon la phase : +- **Waking** : Full network state, all signals, high engagement +- **Consolidation** : Reduced input, focus on memory integration, medium engagement +- **Sleep** : Minimal state, optimization mode, low engagement + +## Boucle Complète : du Signal à la Modification + +``` +1. Event → Perception Agent spawned + Prompt généré : "Voici le signal brut, transforms-le en pattern" + +2. Perception → emits pattern + Pattern : "emails_spike_detected" + +3. Réseau lit ce pattern + Augmente salience du neurone "urgent_context" + +4. Memory Agent spawned + Prompt généré : "Voici le pattern, consolide l'expérience" + +5. Memory → emits consolidated_trace + Trace : "Crisis mode activated at 14:30" + +6. Réseau stocke cette trace + Crée nouvelle connexion : urgent_context → crisis_mode + Ajuste poids : 0.3 → 0.7 + +7. Decision Agent spawned + Prompt généré : "Voici la trace consolidée, décide" + +8. Decision → emits decision + Décision : "Prioritize critical emails" + +9. Réseau modifie les connexions selon la décision + La boucle continue... +``` + +## Implémentation Pratique + +### Fichiers et Structures + +``` +MagistraAI/ +├── core/ +│ ├── network_state.py +│ │ └── class NetworkState: read current graph, neurons, weights, salience +│ ├── prompt_generator.py +│ │ └── class PromptGenerator: generate_prompt(agent_role, signal) +│ └── agent_spawner.py +│ └── spawn_agent(prompt, expected_output_format) +├── agents/ +│ ├── perception_agent.md (instructions) +│ ├── memory_agent.md +│ ├── decision_agent.md +│ └── affect_agent.md +└── templates/ + └── agent_prompt_template.txt (template de base) +``` + +### Checkpoint : Signature du Prompt Généré + +Chaque prompt généré doit inclure (pour traçabilité) : + +```json +{ + "metadata": { + "agent_role": "Memory", + "network_snapshot_id": "snap_001_phase_waking", + "timestamp": "2025-01-26T14:30:00Z", + "incoming_signal_from": "Perception", + "prompt_version": "1.2" + } +} +``` + +## Points de Tension à Résoudre + +1. **Formatage du contexte réseau** — Comment transmettre le graphe neuronal à Claude de façon lisible et efficace ? (JSON ? Texte structuré ? Adjacency matrix ?) + +2. **Sélection des mémoires pertinentes** — Quel algorithme détermine "ce souvenir est pertinent pour *cet* agent" ? Similarité ? Tags ? Graphe de associations ? + +3. **Cycle de vie du prompt** — Le prompt est-il persisté ? Versionné ? Rejoué lors de la relance du système ? + +4. **Validation de la réponse** — Comment vérifier que la réponse de Claude est cohérente avec les contraintes du prompt ? Quel est le feedback loop vers l'infra ? + +5. **Évolution du template** — Comment les templates d'agents s'améliorent-ils avec le temps ? Learning from past executions ? + +## Conclusion + +Le prompt généré est **l'interface entre l'infra morte et l'agent vivant**. C'est par ce mécanisme que l'état du réseau "parle" à Claude. Plus ce prompt est riche, structuré et pertinent, plus l'agent peut émettre des décisions alignées avec l'état du système. + +MagistraAI dépend de cette porosité. C'est elle qui transforme un graphe en cerveau. diff --git a/docs/VISION.md b/docs/VISION.md new file mode 100644 index 0000000..769dfc7 --- /dev/null +++ b/docs/VISION.md @@ -0,0 +1,107 @@ +# MagistraAI — Cerveau Cognitif Distribué + +## Concept Fondamental + +MagistraAI est une infrastructure cognitive distribuée où des agents LLM (Claude) forment collectivement un cerveau artificiel. Ce n'est pas un système multi-agents classique avec un orchestrateur — c'est un réseau réentrant où l'intelligence émerge de la circulation des signaux entre agents spécialisés. + +## Architecture Double Layer Poreuse + +Le système repose sur deux couches interdépendantes et poreuses : + +### Layer 1 : L'Infrastructure (le cerveau physique) +- Un réseau neuronal : graphe pondéré de neurones, synapses, connexions +- Existe indépendamment des agents — c'est la structure, le substrat +- Contient les poids, la salience, les connexions, les traces mémorielles +- Peut être "éteint" — le cerveau sur la table, inerte mais structuré +- Implémenté en code (le "système nerveux") + +### Layer 2 : Les Agents Claude (la vie, l'activité cognitive) +- Les agents Claude sont l'activité électrochimique du cerveau +- Sans l'infra, ils n'ont nulle part où exister +- Sans eux, l'infra est un cerveau mort +- Chaque agent est spawné par l'infra, traverse le réseau, et le modifie + +### La Porosité +La membrane entre les deux layers est poreuse dans les deux sens : +- **Infra → Claude** : L'état du réseau génère le contexte (prompt) qui éveille l'agent +- **Claude → Infra** : L'agent modifie le réseau (renforce, crée, élague des connexions) +- Cette boucle est continue : modification → nouveau contexte → nouvelle cognition → nouvelle modification + +## Hiérarchie Circulaire (pas linéaire) + +### Ce que MagistraAI N'est PAS +``` +Orchestrateur ← PAS ÇA +├── Worker A +├── Worker B +└── Worker C +``` +Pas de maître. Pas d'esclaves. Pas de top-down. + +### Ce que MagistraAI EST +``` + ┌─── Agent Perception ◄──┐ + ▼ │ +Agent Mémoire ──► Agent Décision + ▲ │ + └─── Agent Affect ◄──────┘ +``` + +Des boucles de feedback réentrantes. Chaque agent a son area of concern mais influence et est influencé par les autres. Le contrôle émerge des boucles, pas d'une autorité. + +Comme un cerveau biologique : +- Le cortex préfrontal "décide" mais l'amygdale peut le court-circuiter +- Le thalamus filtre mais le cortex lui dit quoi filtrer +- L'hippocampe stocke mais c'est le cortex qui consolide +- Aucune zone n'est souveraine — toutes sont interdépendantes + +## Principes Architecturaux + +### 1. Pas d'orchestrateur +Le cerveau s'allume d'un bloc. Il n'y a pas de "chef" qui dit aux neurones quand s'activer. Le spawning des agents est déclenché par l'état du réseau, pas par une autorité. + +### 2. Spécialisation sans souveraineté +Chaque agent a une aire de responsabilité (mémoire, perception, décision, affect...) mais aucun ne domine. La priorité émerge du contexte, pas d'une hiérarchie fixe. + +### 3. Communication par boucles réentrantes +Les signaux circulent en boucles, pas en arbre. Un signal de perception peut activer la mémoire, qui influence la décision, qui modifie la perception. Le sens émerge de la circulation. + +### 4. Inhibition naturelle +Pour éviter les boucles infinies, le système a besoin de mécanismes d'inhibition — l'équivalent des neurotransmetteurs inhibiteurs (GABA). Un signal qui a fait le tour perd de l'énergie, se transforme, ou est absorbé. + +### 5. Persistance par traces +Le cerveau survit entre les sessions via les traces qu'il laisse dans l'infra. Quand il se "rallume", les agents se réinstancient à partir de l'état du réseau. Le cerveau se reconstruit lui-même. + +### 6. Le réseau EST la mémoire +Pas de base de données séparée. La mémoire c'est l'état du réseau — les poids des connexions, la salience des neurones, les traces épisodiques encodées dans la structure même du graphe. + +## Relation avec MoemoeAI + +MoemoeAI a conçu l'architecture du réseau neuronal (neurones, synapses, types de mémoire, cycle de sommeil, salience). MagistraAI reprend ce substrat mais change fondamentalement son animation : + +| | MoemoeAI | MagistraAI | +|---|---|---| +| Réseau neuronal | Simulé en code | Même substrat | +| Animation | Un seul Claude lit/écrit | Multiple agents Claude SONT l'activité | +| Hiérarchie | Mono-agent | Circulaire réentrante | +| Mémoire | DB consultée par Claude | Le réseau lui-même | +| Intelligence | Dans Claude seul | Émerge du réseau d'agents | + +## Aires Cérébrales (Areas of Concern) + +Spécialisations envisagées (non exhaustif, le cerveau peut évoluer) : + +- **Perception** — Inputs externes (Gmail, Discord, APIs, fichiers). Transforme le bruit en signal. +- **Mémoire** — Gestion des traces, consolidation, archivage adaptatif, rappel contextuel. +- **Décision** — Évaluation des options, planification, choix d'action. +- **Affect** — État émotionnel du système, modulation des priorités, urgence. +- **Expression** — Output vers l'extérieur (messages, code, actions). +- **Maintenance** — Cycle de sommeil, consolidation, élagage, optimisation du réseau. + +## Questions Ouvertes + +1. **Format du substrat** — Comment représenter le réseau ? Graphe en mémoire ? Fichiers ? Le format doit être lisible par Claude (texte) et manipulable par le code. +2. **Protocole de communication** — Comment les agents se parlent en boucles sans orchestrateur ? Bus de messages circulaire ? Signaux dans le réseau ? +3. **Spawning** — Comment le réseau décide de spawner un agent ? Seuil d'activation ? Pattern matching sur l'état ? +4. **Inhibition** — Comment éviter les boucles infinies ? Decay d'énergie ? Compteur de passes ? Période réfractaire ? +5. **Bootstrap** — Comment le cerveau démarre la première fois ? État initial minimal ?