1. Découpage de la douleur : la mémoire n'est pas « du Markdown en plus »
(1) Dérive des frontières : verser journaux, brouillons et préférences stables dans MEMORY.md fait remonter des hypothèses périmées comme des faits ; mélanger la doc produit du workspace avec la « mémoire persona » empoisonne la couche. (2) Bruit à la récupération : une recherche naïve par mots-clés ou un découpage grossier fusionne des formulations proches mais des décisions différentes — le modèle « se souvient » du mauvais passage. (3) Engorgement des jetons : prompts système, rubriques de canal, JSON d'outils, schémas MCP et extraits mémoire partagent un même budget ; les pics de latence résident souvent dans les préfixes cachés, pas dans le chat visible. Si doctor et canaux semblent sains alors que la latence monte, auditez le contexte avant de changer de modèle (voir l'échelle dans l'article passerelle silencieuse). (4) Décalage des chemins en distant : sur une passerelle Mac distante, ~/.openclaw et le workspace peuvent différer du modèle mental de votre portable — amnésie apparente classique après des modifications sous le mauvais utilisateur (même famille de problèmes que la migration).
2. Stratification : quoi ranger où
| Couche | Contenu | Anti-modèles |
|---|---|---|
| Préférences longue durée / glossaire | Faits stables, termes métier, limites d'approbation | Élever des conclusions ponctuelles ; absence de version ou de date |
| Documents du workspace projet | Conception versionnée, contrats d'API, runbooks | Secrets, cookies, secrets de webhook en clair |
| Session / tampon court | Objectifs de fil, questions ouvertes, intermédiaires d'outils | Croissance sans borne sans résumé ni durée de vie |
3. Déploiement en cinq étapes
- Publier un contrat MEMORY : ce qui peut être écrit automatiquement vs validé par un humain ; chaque entrée longue durée porte une portée (canal / projet) et une date de dernière vérification.
- Fixer les garde-fous de récupération : filtrer canal / répertoire d'abord, puis vecteur / mots-clés ; interdire les balayages par défaut sur toute la bibliothèque.
- Versionner les résumés glissants : les résumés portent génération + empreinte ; après mise à jour, comparer pour éviter la double injection.
- Réduire la surface d'outils : n'exposer que les outils nécessaires à la tâche — réduire le coût des préfixes schéma / exemples (runbook MCP).
- Aligner l'environnement distant : launchd définit explicitement
HOME,PATH, chemins des secrets ; après redémarrage, exécuter un test fumée lecture / écriture mémoire (guide d'onboarding).
4. Seuils citables
Chiffres utilisables dans une note interne (à recalibrer sur vos journaux) :
- Lorsque retours d'outils + extraits mémoire dépassent ensemble de façon récurrente environ 8k jetons (à ajuster selon la fenêtre du modèle) et que la latence p95 augmente, réduisez les outils ou mettez la récupération en étages avant d'ajouter des lignes mémoire.
- Si les résumés glissants injectent la même conclusion trois fois ou plus par famille de tours, il manque probablement une déduplication ou deux générations de résumé coexistent.
- Plus de trois heures par semaine sur « mauvaise mémoire / explosion de contexte / amnésie après upgrade » justifie d'élever mémoire + configuration passerelle au rang de critères de release, plutôt que d'éditer MEMORY à la main indéfiniment.
5. Échelle diagnostic d'engorgement des jetons
| Étape | Inspecter | Cause racine fréquente |
|---|---|---|
| 1) Profil du préfixe | Prompt système, règles de canal, mentions fixes | Blocs multi-canaux copiés-collés en double |
| 2) Outils & MCP | Taille de charge par appel, JSON imbriqué | Pas de pagination, pas de projection de champs, schémas trop larges |
| 3) Récupération mémoire | Top-K et plafonds par extrait | Injection de fragments à faible score « par précaution » |
| 4) Résumés de session | Croissance vs nombre de tours | Pas de troncature, fusion ni politique d'expiration |
6. FAQ : auto-amélioration, canaux, Mac distant
Q : Appliquer automatiquement les écritures d'auto-amélioration ? Préférer une validation humaine ou séparer auto à faible risque vs revue à fort risque ; sinon les erreurs deviennent « mémoire d'organisation ».
Q : Un seul réservoir mémoire pour tous les canaux ? Séparer selon conformité et bruit ; support et ingénierie ne devraient pas partager un même espace vectoriel sans filtres de métadonnées.
Q : Chemins sur Mac distant ? Se fier au HOME du processus passerelle, pas au compte avec lequel vous vous connectez en SSH.
Q : Amnésie après mise à jour ? Comparer répertoire d'état vs workspace après déplacement plist ou conteneur — voir migration et matrice passerelle / retour arrière.
7. Approfondissement : du chat aux opérations
En 2026, les agents d'entreprise sont jugés sur une mémoire auditable et un contexte prévisible. La sécurité demande quelles lignes sont personnelles vs organisationnelles, et si elles peuvent être supprimées ou exportées — sans portée et rétention dans le contrat, on ne fait que supprimer des fichiers pour corriger.
Côté ingénierie, la mémoire se confond avec la RAG : Markdown d'un côté, vecteurs de l'autre. Une défaillance fréquente est le décalage de double écriture — MEMORY à jour mais index non reconstruit, donc récupération d'extraits périmés. Les revues doivent exiger une source de vérité unique ou un runbook de reconstruction.
Les Mac distants en hébergement passerelle 24/7 ajoutent disque et sauvegarde : les instantanés doivent couvrir ~/.openclaw et le workspace ; après restauration, décider de reconstruire ou non les index mémoire — même logique de stabilité que le déploiement distant.
À la passerelle, plafonner nombre maximal de lignes mémoire, octets par ligne et mode dégradé (en cas de timeout de récupération, ne garder que le résumé de session) pour que la latence de queue reste explicable.
8. Observabilité
Journaliser par requête : nombre et jetons des extraits mémoire injectés, taux de requêtes vides, p95 de la charge utile par nom d'outil, nombre de réécritures de résumé. Une dérive conjointe sur ces quatre signaux suggère une dérive de configuration ; une latence seule avec des compteurs mémoire stables pointe plutôt vers outils / MCP.
| Signal | Méthode | Suspect |
|---|---|---|
| Jetons d'injection mémoire | Journal structuré par requête | Top-K trop large, extraits trop longs, pas de déduplication |
| Taux de succès de récupération | Questions de référence horaires | Index périmé, mauvais filtre de portée |
| Taille des charges d'outils | Percentiles par outil | Pas de pagination, journaux de trace dans les réponses |
9. Dossier de preuves
Au-delà des captures d'écran : version du contrat MEMORY, tableau des paramètres de récupération, diff des préfixes avant / après mise à jour, fils d'échec avec mémoire attendue. Les revues sans cas d'échec survivent rarement à la première semaine de trafic réel.
10. Clôture : les portables de dev pardonnent ; la production exige la prévisibilité
(1) Limites : les politiques mémoire par défaut bruissent facilement ; outils et MCP gonflent les préfixes ; multi-canal et chemins distants dérivent.
(2) Intérêt du Mac distant : utilisateur et plist fixes, posture sommeil / sauvegarde unifiée, même comportement macOS que dans nos autres guides OpenClaw.
(3) MACGPU : nœuds Apple Silicon louables et point d'entrée aide publique si vous souhaitez héberger la passerelle sans empiler des VPS hétérogènes — l'appel à l'action ci-dessous renvoie vers les offres et l'aide sans connexion.
11. Note de terrain : sous-agents et planifications
Avec sous-agents ou planifications, définir la propriété d'écriture session parente vs branche pour éviter la corruption concurrente de MEMORY ; déporter la récupération lourde vers des workers et garder à la passerelle une orchestration à surface d'outils réduite. À combiner avec nos articles webhooks / exécution non supervisée pour la conception des déclencheurs.