Donner une mémoire à Claude Code : l'architecture que j'utilise en mission

Le problème : l'amnésie de session#

Claude Code est très bon sur la tâche du jour. Il est parfaitement amnésique sur tout le reste.

Chaque session rouvre le projet sans savoir ce qui a été tranché la semaine précédente, ni pourquoi. Les fichiers sont là, l'historique git est là, mais la décision, elle, n'est écrite nulle part. Le symptôme est toujours le même : on repropose une solution déjà écartée trois semaines plus tôt, pour une raison qu'on avait pourtant bien identifiée à l'époque.

Le contexte qui manque n'est d'ailleurs pas dans le code. Il est éclaté sur quatre outils : la messagerie d'équipe, Jira pour les tickets, Confluence pour la documentation, la forge pour le code. Chacun connaît un bout de l'histoire, aucun ne la connaît en entier. Et le contenu d'une conversation où l'on a arbitré entre deux approches n'entre dans aucun des quatre.

Ce que je voulais, c'est simple à formuler et moins simple à construire : qu'une session qui démarre retrouve la décision d'il y a trois semaines et le ticket qui l'a motivée.

Ce que j'ai monté#

Deux choses en local, qui ne se ressemblent pas et qui ne doivent surtout pas être confondues.

Un vault Obsidian, versionné dans un dépôt git. C'est la mémoire. J'y écris à la main mes notes de décision et mes fiches de contexte, et une note de session s'y ajoute à la fin de chaque session de travail.

Un index local, du SQLite avec des embeddings, qui ingère les quatre sources. C'est le substrat de recherche : il permet de poser une question en langage naturel sur l'ensemble du corpus et d'obtenir une réponse sourcée.

Les deux servent des besoins opposés. Le premier est petit et précieux. Le second est énorme et jetable.

Les trois étages#

C'est la distinction qui structure tout le reste, et celle qu'on rate le plus facilement.

L'erreur naturelle consiste à croire que remplir l'étage 1 remplit l'étage 3. Ingérer 1120 pages de documentation ne crée aucun nœud dans le graphe. Les deux étages ne se parlent pas, et c'est voulu.

Ce qui s'écrit tout seul, et ce qui ne s'écrit qu'à la main#

Trois types de contenu arrivent dans le vault, par trois chemins différents.

Les notes de session sont écrites automatiquement en fin de session : ce qui a été fait, ce qui a été tranché, ce qui reste ouvert. C'est le mécanisme qui transforme une suite de sessions isolées en continuité.

Les renvois sont des notes légères créées automatiquement, une par source citée : titre, lien, clés de tickets mentionnées. Aucun contenu recopié. Une page Confluence ou un ticket Jira est mutable et fait autorité : si j'en recopie le contenu, ma copie devient fausse en silence. Le renvoi, lui, ne contient que ce qui ne change pas, et il apporte la seule chose qui m'intéresse, une arête dans le graphe.

Les notes de décision et les fiches de contexte s'écrivent à la main. C'est la matière réfléchie, celle qui justifie tout le montage. Elle représente moins de 10 % des fichiers du vault et 100 % de sa valeur.

Les gabarits#

Cinq gabarits, pas un de plus. Chacun correspond à une question à laquelle une session devra répondre plus tard, et chacun impose un type en frontmatter, qui sert ensuite au filtrage.

La règle d'aiguillage est écrite dans le gabarit reference lui-même, et elle évite l'essentiel des hésitations : une référence est un fait stable, du genre liste d'appareils, matrice de compatibilité, convention de nommage. Si ça bouge à chaque sprint, c'est du contexte. Si c'est un arbitrage, c'est une décision.

Ce que chaque gabarit force à écrire#

Le gabarit ticket demande « ce qu'on fait vraiment », explicitement défini comme le besoin réel et non la reformulation du ticket. Il réclame aussi les pièges rencontrés, ce qui a coûté du temps, et les détails techniques qu'on ne retrouvera nulle part ailleurs.

Le gabarit decision tient en quatre sections : le choix, en une phrase, la décision et pas le débat ; les options écartées et pourquoi ; les conséquences, ce que ça engage et ce que ça ferme ; et « à revoir si », les conditions qui invalideraient la décision. Les options écartées sont la section qui a le plus de valeur six mois plus tard, et c'est précisément celle qu'on n'écrit jamais spontanément.

Le gabarit contexte a deux sections particulières, « État actuel » et « Contradictions repérées », la seconde servant à noter quand deux sources disent l'inverse l'une de l'autre, avec un statut par ligne : ouverte, tranchée, ou analyse fausse. La consigne qui va avec est bonne à retenir : corriger l'état actuel avant de trancher, sinon on fige l'erreur.

Le gabarit personne documente le périmètre réel, pas l'intitulé de poste, et surtout « à qui demander quoi », c'est-à-dire ce sur quoi cette personne est le bon interlocuteur et ce sur quoi elle ne l'est pas. Plus l'historique des échanges, ce qui évite de reposer une question déjà posée.

Le gabarit reference demande le fait, puis « ce qui l'invalide », les conditions dans lesquelles la référence cesse d'être vraie. Une référence sans date de péremption possible est une référence qu'on croira éternelle.

Un gabarit complet#

---
type: ticket
jira: PROJ-1841
statut: en cours
epic: refonte-paiement
tags: [paiement, ios]
maj: 14/08/2026
---
 
# Migration du parcours de paiement
 
## Ce qu'on fait vraiment
<!-- Le besoin réel, pas la reformulation du ticket -->
 
## Contexte
<!-- Pourquoi ça arrive maintenant, ce qui a mené là -->
 
## Décisions prises
<!-- Chaque arbitrage, qui a tranché, pourquoi -->
 
## Pièges / gotchas
<!-- Ce qui a coûté du temps, ce qu'on ne refera pas -->
 
## Détails techniques
<!-- Chemins, identifiants, valeurs. Ce qu'on ne retrouvera pas ailleurs -->
 
## État Jira
<!-- MAINTENU PAR LE DASHBOARD : ne pas éditer à la main, la passe le réécrit.
     Sans cette section, la note n'est jamais rafraîchie. -->
 
## Liens
- Confluence :
- PR :
- Voir aussi : [[]]
 
## Source
<!-- D'où vient ce qui est écrit ici : réunion, fil de discussion, page, ticket -->

La section est le contrat#

C'est le mécanisme central, et il tient dans une phrase inscrite en commentaire dans les gabarits : sans cette section, la note n'est jamais rafraîchie.

Les sections marquées « maintenu par le dashboard » sont le seul endroit où un job automatique a le droit d'écrire. « État Jira » dans un ticket, « État actuel » et « Contradictions repérées » dans un contexte. Tout le reste appartient à la main humaine et n'est jamais touché.

La conséquence est double, et c'est ce qui rend le montage vivable.

Une note qui ne déclare pas la section correspondante ne sera jamais mise à jour, et c'est un choix, pas un oubli : on décide note par note ce qu'on accepte de voir réécrit. À l'inverse, une note qui la déclare accepte que son contenu soit remplacé à chaque passe, ce qui tient parce que la passe réécrit plutôt qu'elle n'empile : ce qui tient est conservé, ce qui a changé est mis à jour, ce qui est faux disparaît.

Les garde-fous#

Un système qui écrit tout seul dans une base de connaissance a besoin de limites qui ne dépendent pas de la bonne volonté.

Un seul point d'écriture validé. Les routes qui préparent une fiche à partir d'une page de documentation sont en lecture seule : elles produisent un brouillon, rien de plus. La création passe par la route existante, celle qui demande une validation humaine. Un chemin d'écriture supplémentaire, c'est un endroit de plus où la règle « rien n'est publié sans relecture » peut être contournée.

Des sections déclarées. Un job automatique ne peut écrire que dans les sections qu'il a déclarées. Toute écriture en dehors est détectée et le fichier est restauré. La différence avec une consigne donnée dans un prompt est décisive : une consigne n'est pas vérifiable, une contrainte mécanique l'est.

Aucune copie de source mutable. Déjà dit plus haut, mais c'est un garde-fou autant qu'un choix de conception. Le jour où le vault se met à affirmer « en cours » pendant que le ticket dit « livré depuis trois semaines », la mémoire ne sert plus, elle nuit.

Ce que ça change#

Une session qui démarre ne part plus de zéro. Elle a accès à ce qui a été décidé, à la raison, et au ticket qui l'a motivé. Les impasses déjà explorées restent explorées.

Claude Code seul, c'est déjà utile. Claude Code avec une mémoire qui se construit d'une session à l'autre, c'est autre chose : le travail de la semaine dernière devient un acquis et non un souvenir.

Reste que construire cette mémoire ne se fait pas en important tout ce qui traîne. C'est même l'inverse, et c'est le sujet du second article : ce qui a marché et ce qui est passé à la trappe, chiffres à l'appui, quand j'ai voulu relier ce vault aux tickets et aux pages de la mission.

Sur le choix de l'outil lui-même, j'ai comparé ailleurs Claude Code et Cursor : ce montage tient d'ailleurs autant à la ligne de commande qu'au modèle.

Vous voulez mettre en place ce genre d'outillage dans votre équipe plutôt que de le bricoler seul ? C'est un des chantiers types de mon accompagnement IA. Prenons 30 minutes pour en discuter.