Une skill Claude Code pour ranger sa mémoire auto

Le problème

Une MEMORY.md typique après quelques mois :

# Memory

## Skills directory structure

- Skills are stored in `~/.claude/skills/`
- Each skill has a `SKILL.md` with frontmatter

## Existing skills

- `data-pipeline` — ETL orchestration
- `incident-response` — runbook structure
  [...11 lignes...]

## Skills rewrite (2026-03-10)

- Both `data-pipeline` and `release-checklist` rewritten to match standards
- Now use: checklist progression, parallel agents, ultrathink
- Key updates: runtime validation, deprecated schemas [...230 chars sur une ligne...]

## release-checklist architecture

- `SKILL.md` — Main orchestration
- `STAGES.md` — 8 deploy stages
  [...]

46 lignes, six sections multi-paragraphes. Deux d'entre elles entièrement reproductibles avec un ls. Une qui ressemble à un changelog de session. Une qui décrit une skill lisible directement dans son dossier.

Le contenu n'est pas faux — il est chargé à chaque conversation sans valeur ajoutée. Le harness charge MEMORY.md automatiquement au démarrage, tronque au-delà de 200 lignes, et tout ce qui s'y trouve vit dans le contexte de chaque thread.

Restait à savoir comment ranger. Et là, aucune doc publique.

Des règles internes, non documentées

La mémoire auto est définie dans le system prompt interne de Claude Code, dans une section auto memory. Invisible, mais présente à chaque session. Elle décrit :

• 4 types stricts de mémoire : user, feedback, project, reference
• Un format de body obligatoire pour feedback et project (lignes **Why:** et **How to apply:**)
• Des règles strictes pour MEMORY.md (pas de frontmatter, lignes < 150 chars, pur index)
• Une liste de choses à ne jamais sauvegarder (catalogues dérivables, historique git, fixes de bugs, doublons CLAUDE.md)

Rien de tout ça dans la doc publique d'Anthropic. Le concept de mémoire est mentionné pour les managed agents, mais ni le format ni les règles internes du CLI. D'où l'idée d'encoder ces règles dans une skill qui audite et refactore.

Ce que ça donne

Une commande /memory-reorganize, et 30 secondes plus tard :

## Audit de la mémoire — 2026-04-28

**État actuel** : 3 fichiers + MEMORY.md (46 lignes)

### Violations critiques
- MEMORY.md L3-6 "Skills directory structure" : entièrement dérivable de `ls`
- MEMORY.md L8-19 "Existing skills" : 12 lignes dérivables d'un `ls`
- MEMORY.md L21-27 "Skills rewrite" : 7 lignes inline (devrait être supprimé)
- MEMORY.md L26 fait ~280 caractères (>150)

### Violations moyennes
- release-checklist.md : champ `originSessionId` non standard
- data-pipeline.md : section "Architecture" dérivable de `ls`

### Contenu dérivable à supprimer
- 60% de release-checklist.md : catalogue de fichiers support

La skill propose ensuite un plan de refactor structuré et demande validation explicite avant de toucher à quoi que ce soit. Elle backup tout en *.backup-YYYY-MM-DD avant d'écrire la moindre ligne.

Résultat sur la mémoire d'exemple : 46 lignes de MEMORY.md ramenées à 5, trois fichiers refactorés (en moyenne -50 % de longueur, ajout des Why/How manquants), aucune perte d'info de valeur.

Les règles, condensées

4 types stricts

Tout fichier qui ne rentre dans aucun de ces types est suspect. « Memory : structure du projet » n'est ni user, ni feedback, ni project, ni reference : c'est dérivable du filesystem, donc pas une mémoire.

Format Why / How to apply

Pour feedback et project, deux lignes obligatoires :

**Why:** [motivation, incident, contrainte]
**How to apply:** [quand/où cette règle s'applique]

Sans elles, impossible de juger les cas limites plus tard. Une mémoire qui dit « ne pas commit le vendredi » sans Why devient ambiguë dans deux mois : no-deploy ou no-commit ? Toute la journée ou seulement après 16 h ? On reste face à la règle nue, sans les invariants qui l'ont produite.

MEMORY.md = pur index

• Pas de frontmatter
• Une ligne par mémoire, format - [Title](file.md) — one-line hook
• Chaque ligne < 150 caractères
• Total < 200 lignes (au-delà = tronqué par le harness)
• Aucun contenu écrit directement, juste des pointeurs
• Sections sémantiques par sujet, pas chronologiques

Si votre MEMORY.md contient le mot « we », ou liste des choses, ou décrit une architecture : c'est cassé.

Ce qu'il NE FAUT PAS sauvegarder

Même sur demande explicite :

• Patterns de code, architecture, chemins (dérivables)
• Historique git, qui-a-fait-quoi (git log est autoritaire)
• Recettes de debug ou fixes (le fix est dans le code)
• Tout ce qui est déjà dans CLAUDE.md
• État éphémère (tâches en cours, contexte de la conversation actuelle)
• Listes dérivables d'un ls

Le test mental : « où trouver cette info plus tard ? ». Si la réponse est ls, git log ou CLAUDE.md, ce n'est pas une mémoire.

Dates absolues

Toujours 2026-04-28. Jamais « récemment », « la semaine dernière », « il y a 2 jours ». La mémoire vit pendant des mois ; les dates relatives deviennent de la fiction.

Architecture de la skill

La skill vit dans ~/.claude/skills/memory-reorganize/ (voir sur GitHub) :

memory-reorganize/
├── SKILL.md              (orchestrateur, 171 lignes)
├── BEST_PRACTICES.md     (règles complètes, 86 lignes)
└── EXAMPLES.md           (avant/après concrets, 203 lignes)

Le pattern suit la recommandation Anthropic de progressive disclosure : SKILL.md reste lean, les règles détaillées et les exemples ne sont chargés que quand la skill en a besoin. Ce n'est pas cosmétique, ça se mesure en tokens économisés à chaque invocation.

Le workflow orchestré par SKILL.md :

Phase 1  : Inventaire (lister fichiers, lire MEMORY.md)
Phase 2  : Audit individuel vs BEST_PRACTICES.md
Phase 3  : Audit de MEMORY.md (format index)
Phase 4  : Détection duplicats / chevauchements
Phase 5  : Détection contenu dérivable
Phase 6  : Vérification de fraîcheur (refs cassées, dates relatives)
Phase 7  : Rapport des violations
Phase 8  : Plan de refactor (avec consultation EXAMPLES.md)
Phase 9  : Validation utilisateur (AskUserQuestion)
Phase 10 : Backup + application + vérif finale

BEST_PRACTICES.md capture les règles internes du system prompt sous forme de tableau et de checklist. C'est la source de vérité des phases 2 à 6, chargée uniquement pendant l'audit.

EXAMPLES.md est le fichier le plus surprenant en termes d'impact. Sans exemples concrets, Claude refactore correctement mais le style varie d'un appel à l'autre. Avec trois exemples avant/après bien choisis, le style devient déterministe — un transfert de goût par démonstration. Les trois cas couverts : mémoire project sans Why/How (la violation la plus fréquente), MEMORY.md du chaos vers l'index pur (la transformation la plus visible), et mémoire bien structurée mais trop bavarde (le cas subtil). Plus une table d'anti-patterns pour calibrer la détection.

Un cas concret

Une mémoire project typique du genre « bien intentionnée mais cassée » :

---
name: release-checklist skill architecture
description: Architecture of the release-checklist skill (refactored 2026-04-14)
type: project
originSessionId: 00000000-0000-0000-0000-000000000000
---

Pre-deploy validation skill for backend services.

Architecture (after 2026-04-14 refactor):

- `SKILL.md` (118 lines) — Lean orchestrator
- `STAGES.md` — 8 deploy stages with gating criteria
- `ROLLBACK.md` — 4 rollback procedures
- `KPIS.md` — measurable thresholds per stage

Key rules:

- No deploy on Friday after 16:00 (SRE policy)
- Mandatory canary 5% before full rollout
- Rollback within 15min if error rate > 1%
- Postmortem required for any P1/P2

Le diagnostic : frontmatter avec originSessionId non standard, section « Architecture » entièrement dérivable d'un ls, absence de **Why:** et **How to apply:** (obligatoires pour type=project), et « Key rules » à garder absolument puisque non dérivables.

Après refactor :

---
name: release-checklist skill
description: Pre-deploy validation skill for backend services. Blocks risky deploys and enforces mandatory SRE checks.
type: project
---

Pre-deploy skill for internal backend services.

**Why:** Reduce rollbacks (12% of deploys before introduction). Enforce canary, no-deploy-Friday, and automatic rollback <15min on >1% error rate, after the 3 P1 incidents in Q4 2025.

**How to apply:** Invoke for any release/deploy preparation. Architecture details in support files — do NOT duplicate here.

## Non-derivable operational rules

- **No deploy Friday > 16:00** (SRE policy)
- **Mandatory 5% canary** before full rollout
- **Rollback < 15min** if error rate > 1%
- **Postmortem required** for any P1/P2

26 lignes vers 16, plus aucune duplication avec le filesystem, un Why qui raconte l'incident ayant motivé la règle et un How to apply explicite. Dans trois mois, face à un edge case du type « peut-on déployer un patch critique vendredi à 17 h pour fixer une fuite de données ? », on a la motivation pour décider — pas juste la règle nue.

Garde-fous

La skill modifie des fichiers, donc :

• Backup systématique : chaque fichier modifié est copié en *.backup-YYYY-MM-DD avant la moindre écriture
• Validation utilisateur explicite (Phase 9, via AskUserQuestion)
• Pas de modif hors du dossier mémoire : ni CLAUDE.md, ni settings.json, ni skills
• Préservation du contenu de valeur : une mémoire qui viole les règles mais contient de l'info utile est refactorée, pas supprimée
• Aucune invention : la skill réorganise ce qui est là, elle ne crée pas ex nihilo

Tester

Relancez Claude Code (les skills se chargent au démarrage), puis :

/memory-reorganize
/memory-reorganize duplicats
/memory-reorganize frontmatter
/memory-reorganize index

Comptez 30 secondes à 2 minutes selon la taille de la mémoire.

Ce que ça apprend

Les règles internes de Claude Code ne sont pas documentées publiquement. Tout est dans le system prompt. C'est délibéré — les internes peuvent évoluer — mais ça implique de lire son system prompt courant ou de demander les règles à Claude lui-même. La skill les encode dans BEST_PRACTICES.md pour les rendre explicites, au prix de devenir potentiellement obsolète.

Le Why change tout. Une version de la skill demandait juste type + contenu, l'autre exigeait Why + How to apply. La seconde produit des mémoires encore utilisables à six mois ; la première, des notes opaques dès deux mois. La motivation est ce qui transforme une note en règle actionnable.

Le contenu dérivable est l'ennemi principal. Sur la mémoire d'exemple, 60 % du volume : liste de skills (ls), architecture des dossiers (tree), changelogs de session (git log). Ce contenu pollue chaque session sans rien apporter. Le test « où trouver cette info plus tard ? » avant chaque sauvegarde divise par deux la taille des mémoires.

Progressive disclosure marche vraiment. Éclater la skill en trois fichiers fait gagner ~30 % sur la taille de SKILL.md, et les fichiers ne sont chargés qu'au besoin. Mesurable en tokens économisés à chaque invocation.

La validation utilisateur n'est pas négociable. Une skill qui modifie des fichiers sans demander finira par effacer quelque chose d'important. AskUserQuestion ajoute dix secondes par exécution — rien comparé au coût de restaurer un backup, encore moins de récupérer un fichier sans backup.

Les limites

C'est un outil, pas une autorité. La skill applique des règles, mais certaines mémoires les « violent » tout en étant utiles — typiquement une mémoire qui mêle project et reference. Elle détecte l'ambiguïté et demande plutôt que de trancher seule, et peut se tromper sur le type proposé, surtout sur les mémoires courtes.

Elle ne génère pas de mémoires : si la vôtre est vide, elle n'inventera rien. Enrichir la mémoire, c'est l'usage normal qui le fait.

Enfin, elle dépend de la stabilité du format interne. Si Anthropic change le format, BEST_PRACTICES.md devient potentiellement faux — la skill est une photographie des règles à un moment donné.

Pour le cas d'usage visé, un grenier qui dérape au fil des mois, c'est un outil de ménage trimestriel : 30 secondes pour auditer, 2 minutes pour valider, et la mémoire repart propre.