Mémoire d'un agent IA entre les sessions : fichier de progression, journal des décisions, git et script d'init

Pourquoi l'agent ne se souvient de rien

Le modèle ne conserve pas d'état entre deux lancements. Tout ce que l'agent « sait » de votre tâche se trouve dans la fenêtre de contexte de la session en cours : fichiers lus, sortie des commandes, dialogue avec vous. La session se ferme ou le contexte déborde : la suivante repart de zéro et ne voit que ce qui est écrit sur le disque.

Un modèle utile : un ingénieur brillant qui arrive chaque matin au travail avec une mémoire totalement effacée. Il comprend vite le code, mais il ne se rappelle pas quelle architecture a été choisie la veille, pourquoi les autres options ont été rejetées, ni dans quel état sont les tests. Sans notes, il perdra quinze à vingt minutes à explorer et risque fort de refaire ce que vous aviez délibérément écarté.

La mémoire d'un agent IA n'est donc pas une propriété du modèle, mais une partie du harnais : un ensemble de fichiers et de règles que vous concevez vous-même. La bonne nouvelle : aucune base vectorielle ni service spécialisé n'est nécessaire. Quelques fichiers Markdown, git et de la discipline suffisent.

Pourquoi une grande fenêtre de contexte ne résout pas le problème

On pourrait croire qu'il suffit d'attendre un modèle à la fenêtre plus grande. Mais une tâche complexe remplit n'importe quelle fenêtre : l'agent lit la base de code, accumule l'historique des décisions, reçoit une sortie de tests bavarde et garde tout le dialogue. Les besoins grandissent avec la fenêtre. C'est un problème d'architecture, et non une question de volume.

Il existe aussi un second effet. Près de la limite de la fenêtre, plusieurs modèles commencent à se presser de conclure : ils sautent la vérification, choisissent la solution simple au lieu de la bonne. Anthropic décrit cette observation pour ses propres modèles, et l'ampleur de l'effet varie d'un modèle à l'autre. Une session longue, poussée à la limite du contexte, risque donc non seulement de perdre des informations, mais aussi de dégrader la qualité du travail.

Compaction : ce qui est conservé et ce qui se perd

La compaction consiste à résumer la partie ancienne du dialogue pour libérer de la place dans la même session. Dans Claude Code, la commande /compact la déclenche, et elle se produit aussi automatiquement à l'approche de la limite. La commande /clear, au contraire, efface l'historique et recommence la conversation.

Le problème de la compaction est que le résumé garde en général le « quoi » et perd le « pourquoi ». Le code achevé reste dans les fichiers, mais les raisonnements — pourquoi l'option B, pourquoi ne pas prendre telle bibliothèque, pourquoi on a délibérément renoncé à une optimisation — se réduisent à quelques mots ou disparaissent. L'étape suivante de l'agent « améliore » alors une décision volontaire, puisqu'il ne voit plus les raisons.

Règle pratique, sans métriques complexes : quand la tâche a occupé environ 60 % de la fenêtre, arrêtez d'écrire du code et préparez la relève. Si le contexte n'est occupé qu'à 40 % et que la fin de la tâche est proche, la compaction suffit.

Quatre artefacts qui composent la mémoire de l'agent

Plutôt que de compter sur la mémoire du modèle, tenez un journal de bord. Il comporte quatre parties, chacune avec son rôle.

1. PROGRESS.md — où nous en sommes.
2. DECISIONS.md — pourquoi on a fait ainsi plutôt qu'autrement.
3. Commits git — des points de contrôle gratuits de l'état.
4. Protocole de relève dans AGENTS.md — quoi faire à l'arrivée et au départ.

PROGRESS.md : le fichier de progression

Il répond à une seule question : dans quel état se trouve le projet à cet instant. L'agent le lit en premier au début de la session et le met à jour en dernier avant de partir. Le fichier est court, on le réécrit au lieu de le compléter indéfiniment : l'historique vit dans git.

# PROGRESS.md

## Objectif actuel
Recherche dans le catalogue de produits (fonctionnalité search-01)

## État
- HEAD : 4f2a9c1
- make check : vert, 142/142 tests
- Fait : index PostgreSQL (tsvector), route GET /search
- Vérifié : tests unitaires + requête curl manuelle sur 3 requêtes

## Blocages
- Pas de données de morphologie pour la langue kazakhe : on attend une décision

## Prochaine étape
Ajouter la pagination à GET /search, critère : test sur la 2e page

Remarquez les quatre champs suffisants pour une relève : le hash du commit, la part des tests qui passent, les blocages et la prochaine étape. Si une session neuve ne peut pas reprendre le travail sans ambiguïté à partir de ce fichier, c'est qu'il manque un champ dans le modèle.

DECISIONS.md : le journal des décisions

Il conserve précisément le « pourquoi » qui se perd à la compaction. Format d'une entrée : la décision, la raison, ce qui a été écarté et pourquoi, les contraintes.

## 2026-03-14 — Cache des paramètres utilisateur dans Redis
- Décision : Redis, TTL 5 minutes, invalidation active à l'écriture.
- Raison : lu à chaque requête, volume de données minime.
- Écarté : vue matérialisée dans PostgreSQL — modifications trop fréquentes,
  la maintenance ne se justifie pas.
- Contrainte : ne pas mettre en cache les paramètres de paiement.

La ligne la plus précieuse ici est « Écarté ». C'est elle qui empêche la session suivante de « réoptimiser » la décision vers une option déjà examinée et rejetée. Contrairement au fichier de progression, le journal des décisions ne fait que s'enrichir : on ne supprime pas les anciennes entrées, on les marque comme remplacées par les nouvelles.

L'historique git comme points de contrôle

Les commits sont déjà des instantanés versionnés de l'état du travail. L'agent peut lire git log et git diff et reconstituer ce qui a changé. Pour que l'historique fasse office de mémoire, le message du commit doit expliquer l'intention, et non répéter le diff.

# mauvais
git commit -m "update search.py"

# bon
git commit -m "search : index tsvector à la place de LIKE

LIKE '%q%' n'utilise pas d'index, sur 200k produits la requête dure 1,8 s.
La pagination n'est pas encore faite, voir PROGRESS.md."

De petits commits fréquents, après chaque passage vert des tests, offrent en plus un point de retour. Si la session a pris un mauvais chemin, il est plus simple de revenir au dernier état vérifié que de démêler des modifications à moitié finies.

Protocole de relève dans AGENTS.md

Les fichiers d'état ne servent à rien si l'agent ne les connaît pas. On écrit donc dans le fichier d'instructions d'entrée (AGENTS.md ou CLAUDE.md) un court protocole : quoi faire à l'arrivée et au départ.

## Prise de poste
1. Lire PROGRESS.md et DECISIONS.md.
2. Trouver la tâche active dans .agent/feature_list.json.
3. Lancer make check — vérifier que le dépôt est cohérent.
4. Reprendre à partir de la « Prochaine étape », sans rouvrir ce qui est déjà tranché.

## Fin de poste
1. Lancer make check, committer l'état vert.
2. Mettre à jour PROGRESS.md : HEAD, tests, blocages, prochaine étape.
3. Ajouter les nouvelles décisions dans DECISIONS.md.
4. Ne laisser aucun travail à moitié fini dans l'arbre de travail.

Il vaut mieux garder le protocole court : quelques lignes dans le fichier d'entrée, pas un pavé à part.

Script d'init : accélérer le démarrage de la session

Pour que l'agent n'ait pas à reconstituer la situation à la main, donnez-lui un seul script qui vérifie l'environnement et affiche l'état. Le script doit être idempotent — on peut le lancer autant de fois qu'on veut — et se terminer par un message explicite de disponibilité.

#!/usr/bin/env bash
set -euo pipefail

echo "== 1. Environnement =="
command -v uv >/dev/null || { echo "FAIL: uv n'est pas installé"; exit 1; }
uv sync --frozen

echo "== 2. Dépôt =="
if [ -n "$(git status --porcelain)" ]; then
  echo "WARN: l'arbre de travail n'est pas propre"
else
  echo "OK: propre"
fi
echo "HEAD: $(git log -1 --oneline)"

echo "== 3. Vérification =="
make check

echo "== 4. État =="
cat PROGRESS.md

echo "Prêt à travailler"

Dans le protocole de prise de poste, une seule ligne suffit alors : « lance scripts/init.sh ». Dans Claude Code, ce lancement peut être automatisé par un hook au démarrage de session (événement SessionStart), mais même sans hook, l'agent exécutera le script selon l'instruction du fichier.

Ce qu'il faut mettre dans la mémoire de l'agent, et ce qu'il ne faut pas

La principale erreur est de transformer la mémoire en fourre-tout. Chaque ligne que l'agent lit au démarrage occupe de la place dans le contexte, et le superflu noie l'essentiel.

Séparez aussi selon la durée de vie. Les règles du projet changent rarement et concernent toutes les tâches : elles ont leur place dans le fichier d'instructions d'entrée. L'état change à chaque session : il a sa place dans le fichier de progression. Si l'on mélange les deux, le fichier d'entrée se remplit vite de notes périmées.

La première session : l'initialisation comme phase à part

La mémoire entre les sessions ne sert à rien si la première session a tourné au chaos. Scénario typique : vous demandez sur un dépôt vierge « ajoute la recherche », et une demi-heure plus tard on découvre que le framework de tests est mal configuré et que le format des migrations ne convient pas. La recherche est là, mais les fondations sont bancales.

La raison : la réalisation et l'initialisation optimisent des choses différentes. La première vise le nombre de fonctionnalités finies dans cette session, la seconde la vitesse et la fiabilité de toutes les sessions suivantes. L'agent penche vers le résultat visible, donc vers le code. Il faut donc isoler l'initialisation dans une session à part, avec un critère de fin en quatre points.

• Démarrer : make setup et make dev fonctionnent sur un clone propre.
• Se vérifier : make test existe et au moins un vrai test passe.
• Voir la progression : le fichier d'état existe et se lit.
• Reprendre le travail : il existe une liste de tâches avec des critères d'acceptation.

Si vous démarrez souvent de nouveaux projets, créez un modèle de dépôt : Makefile, framework de tests, squelette d'AGENTS.md, dossier .agent/, scripts/init.sh, linter et CI. L'initialisation se réduira alors à la spécificité du projet.

Comment vérifier que la mémoire fonctionne

La mesure la plus honnête : le temps entre le lancement d'une nouvelle session et la première modification de code qui ait du sens. Sans artefacts, c'est en général quinze à vingt minutes d'exploration ; avec une bonne relève, deux ou trois. Mesurez une fois avant et après, et vous verrez si la discipline en vaut la peine.

Seconde méthode : le test de démarrage à froid. Ouvrez une session neuve, écrivez « continue » et posez cinq questions : quel est l'objectif actuel, dans quel état sont les tests, quelle décision a été prise sur le sujet clé et pourquoi, qu'est-ce qui bloque, quelle est la prochaine étape. Si l'agent répond aux cinq à partir des fichiers, sans deviner, la mémoire est bien construite. Chaque réponse hésitante révèle un champ manquant dans le modèle.

Erreurs typiques

• Le fichier de progression ne fait que grossir. Au bout d'un mois, il compte des centaines de lignes d'historique. Réécrivez-le pour l'état actuel : l'historique reste dans git.
• Pas de ligne « écarté ». Un journal des décisions sans variantes rejetées ne protège pas contre les débats répétés.
• L'agent met à jour l'état « à vue de nez ». Notez comment c'est vérifié : la commande et le résultat, et non « tout fonctionne ».
• Relève à la limite de la fenêtre. Près de la limite, l'agent se presse déjà ; commencez le handoff à l'avance, vers 60 %.
• Arbre de travail sale à la sortie. Des modifications à moitié finies sans commit déroutent la session suivante.

En résumé

La mémoire d'un agent IA entre les sessions repose non sur le modèle, mais sur des fichiers : PROGRESS.md garde l'état actuel, DECISIONS.md les raisons et les variantes écartées, les commits git sont des points de contrôle avec l'intention expliquée, et le protocole de relève dans AGENTS.md oblige à lire et mettre à jour le tout. Le script d'init réduit le démarrage à une seule commande, et le test de démarrage à froid montre si les notes suffisent. Le journal de bord de l'agent et le contrat d'amorçage sont présentés en pratique dans le cours de harness engineering.