Mémoire des agents et récupération hiérarchique
Lorsque des agents IA autonomes entreprennent des tâches d'ingénierie complexes en plusieurs étapes, deux modes de défaillance récurrents apparaissent :
- Dérive d'objectif et sur-abstraction compensatoire (Goal Drift & Compensatory Over-Abstraction) : en cours de tâche, l'agent perd la trace des contraintes et de l'intention initiale de l'utilisateur. Il compense en créant des abstractions spéculatives, des couches intermédiaires superflues et une infrastructure incontrôlable.
- Saturation de la fenêtre de contexte et duplication (Context Window Bloat & Duplicate Fragmentation) : faute de moyens de recherche précis au niveau des lignes, l'agent injecte des fichiers entiers de plusieurs centaines de lignes dans le prompt, effaçant ainsi les instructions système fondamentales. Lors de la rédaction de documentation, incapable de repérer les routes existantes, il génère des pages en double.
Garantir la fiabilité d'un agent ne se résume pas à agrandir sa fenêtre de contexte. Cela exige une hiérarchie cognitive et de récupération multiniveau (Multi-Tiered Cognitive & Retrieval Hierarchy) dissociant l'alignement décisionnel humain de l'exploration syntaxique du code.
La pyramide cognitive à 4 niveaux
1. L0 : Intention et alignement (Why & What)
- Support : Décideur humain +
Basic Memory(ou documents d'alignement canoniques). - Entités clés :
Project,Decision,Boundary,Phase. - Rôle : Définit ce que le projet accomplit, ce qu'il lui est strictement interdit de faire et quand s'arrêter. Représente le consensus humain d'autorité et n'est jamais pollué par des journaux d'exécution temporaires.
2. L1 : Jardin conceptuel du domaine (Réutilisabilité transverse)
- Support : Réseau de notes Markdown sémantiques (ex.
QMD, Obsidian). - Entités clés :
Concept Note,Source Reference,Methodology. - Rôle : Abrite les principes méthodologiques généraux (ex. Isolation recherche quantitative et production, Architecture orientée événements). Consulté à la demande lors de choix de conception.
3. L2 : Couche syntaxique et symboles AST (Where & How)
- Support : Moteurs de recherche hybrides avec conscience de l'AST (ex.
zvec-grep(zg), Ripgrep). - Entités clés :
Class,Function,Docstring,Markdown Heading,Code Slice. - Rôle : Isole chirurgicalement les blocs de code et les plages de lignes avec une latence CPU inférieure à la seconde. Produit un format compact (~80 tokens) évitant tout déversement massif de fichiers.
4. L3 : Mémoire de travail éphémère (Now)
- Support : Fenêtre de contexte active et historique d'interaction du modèle.
- Rôle : Applique le patch immédiat, valide localement, restitue le résultat visible et s'arrête.
Matrice des outils et granularité des entités
| Dimension | Basic Memory | QMD | zvec-grep (zg) |
|---|---|---|---|
| Rôle principal | Source de vérité d'alignement humain-agent | Théorie transverse et preuves de sources | Localisateur chirurgical de symboles AST et lignes |
| Entités gérées | Decision, Boundary, Milestone | Concept, Theory, Paper Citation | Class, Function, Heading Slice |
| Moteur | Graphe structuré / MCP relationnel | Vecteur hybride + BM25 sur Markdown | Parseur AST + model2vec (CPU) + FTS |
| Coût en tokens | ~1 500 – 3 000 tokens (Note d'alignement complète) | ~1 000 – 2 000 tokens (Section conceptuelle) | ~80 tokens (Fichier, plage de lignes et signature) |
| Autorité d'écriture | Validation explicite de l'humain uniquement | Synthèse progressive revue | Cache local en lecture seule (ignoré par Git) |
| Emplacement type | knowledge/projects/*.md | knowledge/concepts/*.md | Dépôts actifs (Finance/, my-website/) |
Pipeline chirurgical de bout en bout
Au lieu de laisser l'agent explorer au hasard, le flux impose une gestion stricte des tokens :
Règles d'ingénierie et bonnes pratiques
1. La sonde d'entité préalable (Entity-First Probe)
« Avant de créer tout nouveau fichier, classe ou route, prouvez qu'il n'existe aucune entité équivalente dans la base. »
- Dans la documentation (ex. Docusaurus) :
Avant de rédiger un nouvel article, exécutez :
Si une page canonique ou une sous-section correspond, mettez à jour ou liez cette page existante. Ne fracturez jamais la base documentaire par des doublons.npx @zvec/zvec-grep query "<sujet ou mot-clé>" -g 'docs/**' --limit 3
- Dans le code source :
Avant d'implémenter un algorithme, explorez le projet pour identifier les modules purs existants (ex.
metrics.py), évitant ainsi de réinventer la roue.
2. Lecture chirurgicale restreinte (Surgical Read)
- Ne faites jamais de lecture intégrale non ciblée sur des fichiers de plus de 100 lignes ;
- Utilisez les coordonnées précises fournies par
zgpour restreindre la lecture à[StartLine, EndLine]; - Maintenez la consommation de contexte strictement limitée aux lignes pertinentes pour le correctif.
3. Contrainte de frontière unidirectionnelle
- Le niveau supérieur gouverne le niveau inférieur, sans pollution inverse :
- Les décisions stratégiques dans Basic Memory contraignent l'écriture du code ;
- Il est strictement interdit d'injecter des traces d'outils temporaires ou des résultats de tests locaux dans la base de connaissances à long terme ;
- Les habitudes de recherche et instructions spécifiques à un projet restent cantonnées au
AGENTS.mddu dépôt concerné, actives localement sans jamais déborder.
Dépôts officiels et sources des outils
- L0 Intention et limites : Basic Memory (GitHub) | PyPI
- L1 Jardin conceptuel : QMD (GitHub) | NPM
- L2 Recherche AST et syntaxe : zvec-grep (GitHub) | NPM