Donner une mémoire à Claude Code sur un VPS

Ce que Recall apporte à la mémoire de Claude Code

Recall est un plugin Claude Code qui donne à chaque projet une mémoire conservée entre les sessions. Il écrit deux fichiers Markdown dans un dossier .recall/ situé dans votre projet : un journal auquel les entrées sont ajoutées sans modification, et un court résumé indiquant où vous vous êtes arrêté. Un summarizer Python local produit ces deux fichiers sur la machine où vous travaillez. 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 dépôt pour le comprendre. Les deux approches 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 distribué sous licence MIT. Il s’agit d’un plugin. Il n’effectue aucun appel réseau.

Ce qu’il vous faut 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 en pur Python. 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 par courtes sessions réparties sur plusieurs jours. Si vous avez déjà Claude Code qui s’exécute dans tmux sur un VPS, Recall transfère la session d’hier à celle d’aujourd’hui.

Installer Recall depuis la marketplace de plugins

Deux commandes, saisies dans une session Claude Code :

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

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

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

/recall:show

/recall:show affiche le résumé actuel. Dans un projet entièrement neuf, 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 exécuter le plugin depuis un checkout, clonez d’abord le dépôt et validez-le :

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

claude plugin validate . lit le manifest 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 à quel moment

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

• SessionStart s’exécute au démarrage, lors de la reprise et après un effacement. Il affiche context.md afin que la session s’ouvre avec votre résumé visible.
• Stop s’exécute chaque fois que Claude termine une réponse. Il ajoute ce tour au journal.
• SessionEnd s’exécute à la fermeture de la session et peut régénérer le résumé.

Deux fichiers sont ainsi créés dans .recall/.

• history.md est l’enregistrement en ajout seul : prompts, réponses, fichiers modifiés et commandes exécutées.
• context.md est le résumé généré : objectif, synthèse, 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. C’est le comportement par défaut, pas une erreur. auto_save_context vaut 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 (fréquence des termes, fréquence inverse des documents), puis un classement des phrases avec TextRank. Il est déterministe et extractif : il sélectionne des phrases déjà présentes dans votre journal. 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 journal 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 correspondant à des 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 lue par le summarizer en une seule passe.

Pour un projet hébergé sur un VPS, le changement utile consiste à activer l’enregistrement automatique. Sur un serveur, une session se termine souvent lorsque le terminal disparaît, 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 au cours de laquelle vous manipulez des identifiants de production, car la redaction est un filtre et non une garantie. Le même principe justifie l’exclusion des secrets des agents IA en général : le secret le plus sûr est celui que l’agent ne voit jamais.

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

Cela dépend de la solution de remplacement. 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 typiques d’un projet de taille moyenne. Ils ne correspondent pas à vos propres mesures. Le chargement d’un résumé Recall utilise environ 1,200 tokens. Cela correspond à l’estimation publiée par le projet, soit 1 000 à 2 000 tokens pour un résumé. Rejouer une transcription complète 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 repère : elle est moins coûteuse parce qu’elle est courte et statique, et elle indique au modèle vos règles permanentes plutôt que les événements de la veille.

Mesurez vos propres valeurs. Un token correspond environ à 4 caractères de prose anglaise, et à un peu moins pour du code. Si vous transmettez également le résumé à un modèle local sur le même VPS, vérifiez la fenêtre de contexte utilisée avant de vous fier au résumé. Ollama tronque les prompts longs avec une longueur de contexte par défaut réduite au lieu d’indiquer qu’il a supprimé la fin.

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 fenêtre de contexte, et /cost indique les totaux de la session. Démarrez une session sans contexte, puis démarrez la suivante avec un résumé en place et comparez les résultats. Pour comprendre précisément où vont les tokens d’une session, la façon dont Claude Code utilise les tokens fournit le détail.

Une réserve permet de nuancer ce résultat. Le résumé est chargé au début de chaque session. Un résumé sur lequel vous n’effectuez aucune action représente donc un petit coût plutôt qu’une économie. Laissez summary_sentences proche de sa valeur par défaut, sauf si vos sessions sont longues. Une session plus calme réduit aussi les coûts, car un agent orienté vers la plus petite modification fonctionnelle produit un journal plus court à classer pour le générateur de résumés.

Reconstruire le résumé sans session

Si vous avez cloné le dépôt, le summarizer dispose 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 malgré tout obtenir le digest.

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

L’aide liste les flags acceptés : --cwd pour la racine du projet, --transcript pour indiquer explicitement 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 dans le répertoire que vous avez indiqué. Si vous l’avez installé depuis 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 dispose d’aucun des deux n’écrit rien et ne le signale pas.

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

Les fichiers apparaissent dans le mauvais projet. Claude Code écrit les chemins relatifs par rapport au répertoire depuis lequel il 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 trouver l’emplacement réel des fichiers.

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 produire cet effet.

Le résumé est trop court 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 est apparu.

Ce que Recall ne couvre pas

Recall est un journal accompagné d’un résumeur. Il est utile de préciser ce que cela exclut.

Le résumeur est extractif. TextRank sélectionne des phrases déjà présentes dans history.md. Il ne vérifie 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é courant 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é à propos de la base de données il y a trois semaines, vous devez utiliser grep sur history.md. Recall ne transmet pas non plus les informations entre sessions : deux sessions ouvertes simultanément sur le même VPS ne peuvent pas consulter les journaux de l’autre. Lorsqu’une session doit savoir ce que fait l’autre, les sessions peuvent s’échanger directement du texte pendant leur exécution.

Recall n’est d’aucune aide à l’intérieur d’une session. Le remplissage de la fenêtre de contexte en cours de session est un autre problème, qui se résout différemment. La gestion de la fenêtre de contexte dans une même session est le complément de ce guide.

Le résumé est volontairement traité comme une entrée non fiable. context.md est injecté dans un bloc délimité et identifié, et Claude demande confirmation avant de s’y fier. Cette conception est nécessaire, car un répertoire .recall/ versionné permet à toute personne disposant des droits de commit d’écrire du texte que votre agent lira. Le niveau de contrôle exercé par l’agent sur ce qu’il lit dépend du mode de permission utilisé au démarrage de la session. Le mode automatique devient le mode par défaut de Claude Code le 14 août 2026. Décidez une fois pour toutes si .recall/ est personnel ou partagé : ajoutez-le à .gitignore pour une mémoire personnelle, ou versionnez-le et relisez-le comme toute autre contribution. Si l’agent s’exécute sans surveillance, l’exécution sûre de Claude Code sur un VPS couvre le périmètre plus large.

La rédaction de données sensibles est effectuée au mieux. Elle cible les formats courants, comme les clés d’API, les tokens, les blocs PEM et les affectations .env. Lisez .recall/ avant de le versionner.

Le numéro de version reflète honnêtement le niveau de maturité du projet. 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. Consultez donc le changelog avant de mettre à niveau une installation dont vous dépendez.

FAQ

Mon code ou mes transcriptions sont-ils envoyés quelque part par Recall ?

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.

Quelle quantité Recall enregistre-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. Ce sont des valeurs indicatives. Mesurez vos propres valeurs 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 interrompue que vous n’auriez jamais pensé à documenter. 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 séparés. Lancez toujours Claude Code depuis la racine du projet, car les fichiers dépendent du répertoire de travail et non du compte utilisateur.