Donner une mémoire à Claude Code sur un VPS

Fonctionnement de la mémoire de Recall pour Claude Code

Recall est un plugin Claude Code qui fournit une mémoire à chaque projet entre les sessions. Il écrit deux fichiers markdown dans un dossier .recall/ situé dans votre projet : un journal en ajout uniquement qui consigne ce qui s’est passé, et un court résumé de l’état atteint. Un summarizer Python local produit les deux fichiers sur la machine que vous utilisez. La mémoire elle-même ne consomme donc aucun token d’API.

Recall comble un manque limité mais constant. Vous fermez une session sur votre VPS mardi. Mercredi, Claude Code ne sait rien de ce qui s’est passé mardi. Vous réexpliquez le projet manuellement ou vous laissez le modèle relire la moitié du repository pour le comprendre. Les deux méthodes consomment des tokens, et la seconde en consomme beaucoup.

La version 0.4.0 de Recall est la version actuelle en juillet 2026, et le projet est sous licence MIT. Il s’agit d’un plugin. Il n’effectue aucun appel réseau.

Ce dont vous avez besoin sur le VPS

Les hooks de capture de Recall sont des scripts Python fournis avec le plugin. Ils n'ont aucune dépendance tierce. La seule exigence réelle est donc de disposer d'un interpréteur.

python3 -V

Ubuntu 24.04 répond Python 3.12.3. Recall prend en charge Python 3.9 et les versions ultérieures. Les images de conteneur minimales ne contiennent parfois aucun interpréteur. Le shell répond alors python3: command not found. Installez-en un avant de continuer.

sudo apt update && sudo apt install -y python3

NumPy est un accélérateur facultatif pour une étape du summarizer. Vous n'en avez pas besoin.

python3 -c "import numpy"

ModuleNotFoundError: No module named 'numpy' est une réponse acceptable ici. Le summarizer dispose d'un chemin d'exécution en Python pur. La suite de tests du projet vérifie que les deux chemins sélectionnent les mêmes phrases.

La mémoire de session est plus importante sur un serveur que sur un ordinateur portable, car les interventions sur un serveur se font lors de courtes visites réparties sur plusieurs jours. Si vous avez déjà Claude Code exécuté dans tmux sur un VPS, Recall est le composant qui reporte la session d'hier à aujourd'hui.

Installer Recall depuis la marketplace des plugins

Deux commandes, à saisir dans une session Claude Code :

/plugin marketplace add raiyanyahya/recall
/plugin install recall@recall

La seconde commande lit plugin@marketplace. Les deux noms sont recall ici. Cela ressemble à une erreur de copier-coller, mais ce n’en est pas une.

Vérifiez l’installation en exécutant l’une des propres commandes du plugin :

/recall:show

/recall:show affiche le récapitulatif actuel. Dans un projet entièrement nouveau, il n’y a encore rien à afficher. Vous vérifiez donc surtout que la commande existe. Si Claude Code ne reconnaît pas /recall:show, le plugin n’est pas chargé et aucun hook ne sera exécuté.

Pour l’exécuter depuis un checkout, clonez plutôt le dépôt et validez-le d’abord :

git clone https://github.com/raiyanyahya/recall ~/recall
cd ~/recall && claude plugin validate .

claude plugin validate . lit le manifeste dans .claude-plugin/ et indique si le plugin est correctement formé. Démarrez ensuite Claude Code depuis le répertoire de votre projet avec claude --plugin-dir ~/recall.

Ce que les hooks écrivent et quand

Recall enregistre trois hooks Claude Code. Chacun exécute un script Python depuis le répertoire du plugin.

• SessionStart se déclenche au démarrage, à la reprise et lors de l’effacement. Il affiche context.md afin que la session s’ouvre directement sur votre résumé.
• Stop se déclenche chaque fois que Claude termine une réponse. Il ajoute ce tour au log.
• SessionEnd se déclenche à la fermeture de la session et peut régénérer le résumé.

Deux fichiers sont générés, tous deux dans .recall/.

• history.md est l’enregistrement en ajout uniquement : prompts, réponses, fichiers modifiés et commandes exécutées.
• context.md est le digest généré : objectif, résumé, prochaines étapes, fichiers modifiés, commandes exécutées et contexte git.

Après une session réelle, examinez le répertoire.

ls -la .recall/

Vous devriez voir history.md avec du contenu. Il est possible que context.md soit absent. Il s’agit du comportement par défaut, pas d’une erreur. auto_save_context est off sauf si vous le définissez. Le résumé est donc écrit uniquement lorsque vous le demandez :

/recall:save

Cette commande exécute le summarizer local sur history.md et réécrit context.md. L’algorithme utilise un scoring TF-IDF (term frequency, inverse document frequency), puis un classement des phrases avec TextRank. Il est déterministe et extractif : il sélectionne des phrases déjà présentes dans votre log. Aucun modèle n’est appelé. L’opération est donc gratuite et fonctionne hors ligne sur la machine.

Configurer Recall pour un projet

La configuration se trouve dans un fichier recall.config.json à la racine du projet. Voici les valeurs par défaut fournies :

{
  "output_dir": ".recall",
  "capture_history": true,
  "summary_sentences": 8,
  "redact": true,
  "include_git": true,
  "max_input_chars": 200000
}

• output_dir définit l’emplacement des deux fichiers. Conservez-les dans le projet.
• capture_history active ou désactive le log history.md.
• auto_save_context accepte off ou on_end et utilise off par défaut.
• summary_sentences définit le nombre de phrases conservées dans context.md. Une valeur plus élevée produit un résumé plus long et augmente légèrement la charge au démarrage de la session.
• redact supprime les motifs courants de secrets avant toute écriture sur disque.
• include_git ajoute le diff actuel et les commits récents au résumé.
• max_input_chars limite la quantité de history.md que le summarizer lit en une seule passe.

Pour un projet hébergé sur un VPS, l’enregistrement automatique est la modification la plus utile. Sur un serveur, une session se termine souvent lorsque le terminal se ferme, et non lorsque vous décidez de l’arrêter.

{
  "auto_save_context": "on_end",
  "summary_sentences": 12
}

Pour suspendre temporairement la capture sans modifier la configuration, créez le marqueur de pause. Supprimez-le pour reprendre la capture.

touch .recall/.capture-paused

Faites-le avant une session pendant laquelle vous manipulez des identifiants de production. La redaction est un filtre, pas une garantie. Le même principe justifie le fait de ne pas exposer les secrets aux agents d’IA en général : un secret est sûr si l’agent ne le voit jamais.

Combien de tokens Recall permet-il d'économiser ?

Cela dépend de l'alternative. Charger un résumé au début de la session coûte peu. Ce qu'il remplace peut coûter cher, car un modèle qui ne connaît pas votre projet doit le redécouvrir en lisant les fichiers.

[
  {
    "label": "Recall context.md",
    "char_count": "4,800",
    "est_tokens": "1,200"
  },
  {
    "label": "Hand-written CLAUDE.md",
    "char_count": "3,200",
    "est_tokens": "800"
  },
  {
    "label": "Re-reading the repo",
    "char_count": "120,000",
    "est_tokens": "30,000"
  },
  {
    "label": "Full transcript replay",
    "char_count": "340,000",
    "est_tokens": "85,000"
  }
]

Ces chiffres sont indicatifs pour un projet de taille moyenne. Ils ne constituent pas une mesure de votre projet. Un résumé Recall se charge avec environ 1,200 tokens. Cela correspond à l'estimation publiée par le projet, soit 1 à 2 milliers de tokens pour une reprise. Rejouer l'intégralité d'une transcription précédente recharge toute la conversation, soit environ 85,000 tokens. Laisser le modèle redécouvrir le projet en lisant les fichiers se situe entre les deux, autour de 30,000 tokens. Ce nombre augmente avec la taille du dépôt. La ligne CLAUDE.md sert de référence d'échelle. Elle coûte moins cher parce qu'elle est courte et statique. Elle indique au modèle vos règles permanentes, et non ce qui s'est passé la veille.

Mesurez vos propres valeurs. Un token correspond approximativement à 4 caractères de prose anglaise, et à un peu moins pour du code.

wc -c .recall/context.md .recall/history.md
echo $(( $(wc -c < .recall/context.md) / 4 ))

Dans une session, /context affiche ce qui est actuellement chargé dans la context window, et /cost indique les totaux de la session. Démarrez une session vierge, puis démarrez la suivante avec un résumé déjà présent et comparez les résultats. Pour connaître précisément la répartition des tokens d'une session, consultez la façon dont Claude Code utilise les tokens.

Une réserve permet de nuancer cette affirmation. Le résumé est chargé au début de chaque session. Un résumé que vous n'utilisez jamais constitue donc une petite surcharge plutôt qu'une économie. Laissez summary_sentences à sa valeur par défaut, sauf si vos sessions durent longtemps.

Reconstruire le résumé sans session

Si vous avez cloné le dépôt, le summarizer possède son propre point d’entrée en ligne de commande. C’est utile sur un VPS lorsqu’une session s’est terminée avec le terminal et que vous voulez tout de même obtenir le récapitulatif.

python3 ~/recall/scripts/make_context.py --help

La sortie de l’aide répertorie les options acceptées : --cwd pour la racine du projet, --transcript pour spécifier un fichier de transcription, --quiet pour supprimer la sortie et --harness pour choisir entre claude et opencode. Indiquez-lui un projet :

python3 ~/recall/scripts/make_context.py --cwd /srv/projects/api

Il lit la transcription de la session et history.md, puis écrit context.md sous le répertoire indiqué. Si vous avez effectué l’installation via la marketplace, le plugin se trouve dans un répertoire géré par Claude Code, et /recall:save est la méthode prise en charge pour effectuer la même opération.

Pourquoi rien ne s’écrit

Aucun répertoire .recall/ après une session complète. Les hooks ne se sont jamais exécutés. Saisissez /recall:show pour confirmer que le plugin est chargé, puis exécutez python3 -V. La commande du hook essaie d’abord python3, puis python. Une machine qui ne contient aucun de ces deux éléments n’écrit rien et reste silencieuse.

history.md augmente, mais context.md ne change jamais. auto_save_context vaut off par défaut. Exécutez /recall:save, ou définissez la clé sur on_end et laissez le hook SessionEnd s’en charger.

Les fichiers apparaissent sous le mauvais projet. Recall écrit les chemins relatifs au répertoire depuis lequel Claude Code a été démarré. Si vous démarrez une session depuis votre répertoire personnel, la mémoire y est donc enregistrée. Démarrez depuis la racine du projet et utilisez ls -la .recall/ pour vérifier où les fichiers ont réellement été créés.

La capture s’est arrêtée sans avertissement. Vérifiez la présence du marqueur de pause avec ls -a .recall/. Un fichier .capture-paused que vous avez créé la semaine dernière continue de faire son travail.

Le résumé est peu détaillé après une longue session. max_input_chars limite l’entrée du summarizer à 200000 caractères. Un journal très long est donc tronqué. Faites-le tourner.

mv .recall/history.md .recall/history-2026-07-30.md

Exécutez ensuite une courte session et vérifiez à nouveau ls -la .recall/ pour confirmer qu’un nouveau history.md a été créé.

Limites de Recall

Recall associe un journal et un résumeur. Il est important de préciser ce que cela n'inclut pas.

Le résumeur est extractif. TextRank sélectionne des phrases déjà présentes dans history.md. Il ne détermine donc jamais si une décision était correcte. Une mauvaise décision consignée mardi est présentée exactement comme une bonne décision prise mercredi. Lorsque les enjeux sont importants, lisez context.md et corrigez-le manuellement. Il s'agit d'un fichier markdown que vous pouvez modifier librement.

Il n'y a pas de recherche. Vous disposez d'un résumé actuel et d'un journal qui s'enrichit pour chaque projet, mais pas d'une mémoire interrogeable entre les projets. Si vous cherchez ce que vous avez décidé au sujet de la base de données il y a trois semaines, vous devez utiliser grep sur history.md.

Recall n'est d'aucune aide pendant une session. Une context window qui arrive à saturation au milieu d'une session pose un autre problème, qui nécessite d'autres solutions. Consultez gérer la context window au sein d'une session dans le guide associé.

Par conception, le résumé est traité comme une entrée non fiable. context.md est injecté dans un bloc fenced et identifié comme tel, puis Claude demande confirmation avant de s'y fier. Cette conception est nécessaire, car un répertoire .recall/ commité est un emplacement où toute personne disposant des droits de commit peut écrire du texte que votre agent lira. Déterminez une fois pour toutes si .recall/ est personnel ou partagé : ajoutez-le à .gitignore pour la mémoire personnelle, ou commitez-le et relisez-le comme toute autre contribution. Si l'agent s'exécute sans surveillance, consultez exécuter Claude Code en toute sécurité sur un VPS pour traiter la question plus générale des limites de sécurité.

La suppression des données sensibles est effectuée au mieux. Elle cible les motifs courants tels que les clés d'API, les tokens, les blocs PEM et les affectations .env. Lisez .recall/ avant de le commiter.

Le numéro de version reflète honnêtement le niveau de maturité. En juillet 2026, la version 0.4.0 permet encore aux clés de configuration et à l'organisation des fichiers d'évoluer entre les releases. Lisez donc le changelog avant de mettre à niveau une configuration dont vous dépendez.

FAQ

Recall envoie-t-il mon code ou mes transcriptions quelque part ?

Non. Les hooks de capture et le summarizer sont des scripts Python qui s’exécutent sur votre propre machine. Le plugin ne contient aucune clé API et n’effectue aucun appel réseau. La synthèse utilise TF-IDF et TextRank, et non un modèle. Cette étape ne coûte donc rien et fonctionne hors ligne. En contrepartie, la synthèse est extractive : elle sélectionne des phrases dans votre journal au lieu d’en rédiger de nouvelles.

Pourquoi mon .recall/context.md est-il absent ou obsolète ?

auto_save_context utilise off par défaut. La synthèse est donc régénérée uniquement lorsque vous exécutez /recall:save. Définissez "auto_save_context": "on_end" dans recall.config.json pour qu’elle soit réécrite à la fin de chaque session. Si history.md est également absent, les hooks ne s’exécutent pas du tout. Vérifiez que le plugin est chargé avec /recall:show, puis vérifiez que python3 -V répond sur cette machine, car les hooks sont des scripts Python.

Combien Recall économise-t-il par session ?

Le chargement d’une synthèse coûte environ 1,200 tokens, contre généralement 30,000 tokens pour un modèle qui doit relire votre dépôt afin de déterminer où il en est. Ces chiffres sont indicatifs. Mesurez votre propre consommation avec wc -c .recall/context.md et la commande /context dans une session, en comparant un démarrage à froid avec une session reprise depuis une synthèse.

Ai-je toujours besoin d’un fichier CLAUDE.md ?

Oui, et ces deux fichiers ont des fonctions différentes. CLAUDE.md contient ce que vous rédigez volontairement : les règles permanentes et les commandes de build. context.md est généré à partir de ce qui s’est réellement passé lors de la dernière session. Il contient donc la migration commencée mais inachevée que vous n’auriez jamais pensé à noter. Conservez les deux.

Un même VPS peut-il conserver la mémoire de plusieurs projets ?

Oui. Recall conserve la mémoire dans .recall/ à l’intérieur de chaque répertoire de projet. Deux projets sur le même serveur conservent donc des journaux et des synthèses distincts. Lancez toujours Claude Code depuis la racine du projet, car les fichiers suivent le répertoire de travail et non le compte utilisateur.