Mémoire — Système de Gestion de la Mémoire

Ce document présente le mécanisme de gestion de la mémoire Managed Auto-Memory (mémoire automatique gérée) de Qwen Code, ses déclencheurs et les détails d’implémentation.

Table des matières

1. Aperçu
2. Structure de stockage
3. Types de mémoire
4. Format des entrées mémoire
5. Cycle de vie principal
6. Extract — Extraction
7. Dream — Intégration
8. Recall — Rappel
9. Forget — Oubli
10. Reconstruction d’index
11. Télémétrie

Aperçu

Managed Auto-Memory est un système de mémoire persistante qui accumule, intègre et récupère automatiquement les connaissances pertinentes sur l’utilisateur au fil des sessions de chat avec l’IA. Il maintient le cycle de vie de la mémoire via quatre opérations principales :

Structure de stockage

Organisation des répertoires

~/.qwen/                                      ← répertoire de base global (par défaut)
└── projects/
    └── <sanitized-git-root>/                 ← identifiant de projet (basé sur la racine Git)
        ├── meta.json                         ← métadonnées (horodatages extraction/intégration, état)
        ├── extract-cursor.json               ← curseur d’extraction (décalage de dialogue déjà traité)
        ├── consolidation.lock                ← verrou d’exclusion mutuelle pour le processus Dream
        └── memory/                           ← répertoire principal de la mémoire
            ├── MEMORY.md                     ← fichier d’index (généré automatiquement, résume toutes les entrées)
            ├── user.md                       ← mémoire des préférences utilisateur (exemple)
            ├── feedback.md                   ← mémoire des règles de feedback (exemple)
            ├── project/
            │   └── milestone.md              ← mémoire de projet (sous-répertoires possibles)
            └── reference/
                └── grafana.md                ← mémoire de ressource externe

Variables d’environnement de remplacement :

• QWEN_CODE_MEMORY_BASE_DIR : remplace le répertoire de base global
• QWEN_CODE_MEMORY_LOCAL=1 : utilise le chemin .qwen/memory/ dans le projet

Description des fichiers clés

Types de mémoire

Le système prend en charge quatre types de mémoire intégrés, chacun correspondant à une dimension d’information différente :

Ce qui ne doit pas être stocké en mémoire : modèles/conventions de code, historique Git, solutions de débogage, état de tâches temporaires, contenu déjà documenté dans QWEN.md / AGENTS.md.

Format des entrées mémoire

Chaque fichier thématique utilise le format YAML frontmatter + corps Markdown :

---
name: nom de la mémoire
description: description en une phrase (pour juger de la pertinence au rappel, doit être spécifique)
type: user|feedback|project|reference
---
 
Contenu principal de la mémoire (ligne de résumé)
 
Why: raison sous-jacente (permet à l’IA de comprendre les cas limites plutôt que de suivre aveuglément la règle)
How to apply: contexte et manière de l’appliquer

Pour les types feedback et project, il est fortement recommandé de renseigner Why et How to apply afin que la mémoire reste correctement appliquée dans les cas limites.

Cycle de vie principal

Extract — Extraction

Déclenchement

Déclenché automatiquement après chaque réponse de l’IA par scheduleAutoMemoryExtract (arrière-plan non bloquant).

Logique d’ordonnancement (extractScheduler.ts)

Raisons de saut (skipped) :

Processus d’extraction principal (extract.ts)

Note : La garde isUnderMemoryPressure se trouve dans MemoryManager.runExtract(), pas dans ce flux. Lorsque le moniteur signale une pression hard/critical, MemoryManager saute l’extraction et n’avance pas le curseur.

Curseur d’extraction (Cursor) :

• Champs : { sessionId, processedOffset, updatedAt }
• Avant l’extraction, lire la progression actuelle avec readExtractCursor, puis ne traiter que la partie non lue via history.slice(processedOffset)
• Après chaque extraction, mettre à jour processedOffset avec la longueur actuelle de l’historique (params.history.length)
• En cas de changement de session (sessionId différent), repartir de l’offset 0
• Note : On ne construit plus de transcript via buildTranscriptMessages / loadUnprocessedTranscriptSlice — hasNewUserMessages est déterminé par history.slice(startOffset).some(m => m.role === 'user' && partToString(m.parts).trim().length > 0), la sérialisation légère ne se fait que sur la tranche non lue, l’historique complet n’est plus traité

Règles de filtrage des patches :

• Résumé de moins de 12 caractères → rejeté
• Résumé se terminant par ? → rejeté (phrase interrogative)
• Contenant des mots-clés temporaires (today/now/currently/temporary, etc.) → rejeté
• Combinaison topic:summary identique → dédoublonné

Dream — Intégration

Déclenchement

Déclenché automatiquement après chaque réponse de l’IA par scheduleManagedAutoMemoryDream (arrière-plan non bloquant). Mais protégé par plusieurs conditions de garde, il est souvent sauté.

Conditions de déclenchement (dreamScheduler.ts)

Paramètres des gardes :

Mécanisme de verrou :

• Le verrou se trouve dans <project-state-dir>/consolidation.lock
• Contenu : le PID du processus qui le détient
• Vérification : si le processus du PID n’existe plus (kill(pid, 0) échoue) ou que le verrou a plus d’une heure → considéré comme expiré, nettoyé automatiquement

Processus d’intégration (dream.ts)

Logique de déduplication mécanique :

1. Dans chaque fichier thématique : dédupliquer par summary.toLowerCase(), fusionner les champs why / howToApply
2. Re-tri alphabétique par summary
3. Entre fichiers : les entrées avec la même type:summary sont fusionnées dans le fichier découvert en premier, le fichier en double est supprimé

Recall — Rappel

Déclenchement

Avant que l’IA ne traite une requête utilisateur, resolveRelevantAutoMemoryPromptForQuery est déclenché automatiquement pour injecter les mémoires pertinentes dans le prompt système.

Processus de rappel (recall.ts)

Règles de score (heuristique) :

Mots-clés caractéristiques par type :

• user : user, preference, background, role, terse
• feedback : feedback, rule, avoid, style, summary
• project : project, goal, incident, deadline, release
• reference : reference, dashboard, ticket, docs, link

Règles de construction du prompt :

• Injecter au maximum 5 documents (MAX_RELEVANT_DOCS)
• Chaque document est tronqué à 1200 caractères (MAX_DOC_BODY_CHARS)
• Si tronqué, ajouter la note : “NOTE: Relevant memory truncated for prompt budget.”
• Inclure l’information de fraîcheur du document (basée sur le mtime du fichier)

Forget — Oubli

Déclenchement

Déclenché manuellement par l’utilisateur via la commande /forget <query>.

Processus d’oubli (forget.ts)

Conception des ID d’entrée :

• Fichier à une seule entrée (cas courant) : relativePath (ex. feedback/no-summary.md)
• Fichier à plusieurs entrées : relativePath:index (ex. feedback/style.md:2)
• Utiliser des ID stables permet au modèle de cibler précisément une entrée sans affecter les autres dans le même fichier

Reconstruction d’index

MEMORY.md est l’index de navigation de tous les fichiers thématiques. Il est reconstruit après chaque Extract ou Dream via rebuildManagedAutoMemoryIndex :

- [Préférences utilisateur](user/preferences.md) — L’utilisateur est un ingénieur Go expérimenté, découvre React
- [Règles de feedback](feedback/style.md) — Réponses concises, pas de résumé final
- [Jalon projet](project/milestone.md) — Fenêtre de gel avant la branche de release mobile

Limites de l’index :

• Maximum 150 caractères par ligne (tronqué avec … si dépassé)
• Maximum 200 lignes
• Taille totale inférieure à 25 000 octets

Télémétrie

Le système intègre trois catégories d’événements de télémétrie pour surveiller les performances et l’efficacité des opérations mémoire.

Télémétrie Extract

Télémétrie Dream

Télémétrie Recall

Index des fichiers source associés