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 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 utilisée. La mémoire elle-même ne consomme donc aucun token d’API.

Recall comble un manque limité, mais récurrent. Vous fermez une session sur votre VPS mardi. Mercredi, une nouvelle session ne recharge pas automatiquement la conversation de mardi, même si la mémoire automatique intégrée à Claude Code peut conserver des notes entre les sessions. Si ces notes n’indiquent pas où vous vous êtes arrêté, vous devez réexpliquer le projet manuellement ou laisser le modèle relire la moitié du dépôt pour le déterminer. Les deux méthodes consomment des tokens. La seconde en consomme beaucoup.

La version 0.4.0 de Recall, publiée le 18 July 2026, est toujours la dernière release en octobre 2026. Le projet est 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 se déclenche au démarrage, à la reprise et après un effacement. Il affiche context.md pour que la session s’ouvre avec votre résumé sous les yeux.
• Stop se déclenche chaque fois que Claude termine une réponse. Il ajoute ce tour au journal.
• SessionEnd se déclenche à la fermeture de la session et peut régénérer le résumé.

Deux fichiers sont créés, tous les 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 condensé 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/

Lorsque la capture est activée, qu’aucun marqueur de pause n’est présent et qu’une transcription est disponible, vous devriez voir history.md avec du contenu. Il est possible que context.md soit totalement absent. C’est le comportement par défaut, pas une erreur. auto_save_context est off tant que vous ne le définissez pas. 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 score 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’étape 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 au résumé les statistiques du diff courant et les commits récents.
• max_input_chars limite la quantité de history.md que le résumeur lit en une seule passe.

Pour un projet sur un VPS, le changement utile consiste à activer l’enregistrement automatique, car une session sur un serveur se termine souvent lorsque le terminal disparaît, plutôt que 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 rédaction automatique est un filtre et non une garantie. Le même principe justifie le fait de ne pas exposer de secrets aux agents IA en général : un secret est sûr lorsque l’agent ne le 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, et non une mesure de votre projet. Le chargement d’un résumé Recall consomme environ 1,200 tokens, ce qui correspond à l’estimation publiée par le projet : entre 1 et 2 000 tokens pour un résumé. 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, et ce nombre augmente avec la taille du dépôt. La ligne CLAUDE.md sert de référence : 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 approximativement à 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 à la reprise, car la longueur de contexte par défaut d’Ollama dépend de la VRAM disponible.

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é déjà chargé, et comparez les résultats. Pour comprendre précisément où sont utilisés les tokens d’une session, comment Claude Code utilise les tokens en présente le détail.

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 représente donc un petit coût plutôt qu’une économie. Laissez summary_sentences à 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 à analyser pour le résumé.

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 n’est écrit

Aucun répertoire .recall/ après une session complète. Vérifiez si la capture est désactivée, si le répertoire de sortie est configuré ailleurs ou si aucune transcription n’a été trouvée avant de conclure que les hooks n’ont jamais été 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 échoue avec stderr et le code de sortie 127. Claude Code affiche une notification d’erreur de hook non bloquante contenant la première ligne de stderr.

history.md augmente, mais context.md ne change jamais. auto_save_context est défini sur 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é lancé. 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 créé la semaine dernière continue de fonctionner.

Le résumé est trop succinct 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 pivoter.

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

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

Ce que Recall ne couvre pas

Recall combine un journal et un outil de synthèse. Il est important de préciser ce que cela exclut.

L’outil de synthèse 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 enregistrée mardi est présentée exactement comme une bonne décision prise mercredi. Lorsque les enjeux sont importants, consultez context.md et corrigez-le manuellement. Il s’agit d’un fichier Markdown que rien ne vous empêche de modifier.

Il n’y a pas de recherche. Vous disposez d’une synthèse actuelle et d’un journal qui s’enrichit pour chaque projet, mais pas d’une mémoire interrogeable entre les projets. Si vous cherchez à savoir 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 ne fournit pas de coordination en temps réel : deux sessions du même projet partagent le fichier journal, mais Recall ne transmet pas les nouvelles entrées du journal au contexte de l’autre session. 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 au cours d’une session est un problème différent, qui nécessite d’autres solutions. Consultez la gestion de la fenêtre de contexte dans une même session, le complément de ce guide.

La synthèse est considérée comme une entrée non fiable par conception. context.md est injecté dans un bloc délimité et identifié, 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. Le niveau de vérification appliqué par l’agent à ce qu’il lit dépend du mode d’autorisation au démarrage de la session. Avec Claude Code v2.1.283 ou version ultérieure, le mode auto est déjà le mode de démarrage intégré pour les sessions interactives dans le terminal et VS Code, avec tous les plans et fournisseurs. Un classifieur examine donc la plupart des actions à votre place. Les organisations utilisant la configuration HIPAA démarrent toujours en mode Manual. Déterminez une fois pour toutes si .recall/ est personnel ou partagé : ajoutez-le à .gitignore pour une mémoire personnelle, ou commitez-le et examinez-le comme toute autre contribution. Si l’agent s’exécute sans surveillance, l’exécution sécurisée de Claude Code sur un VPS couvre le périmètre plus large.

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

Le numéro de version reflète honnêtement le niveau de maturité. En 0.4.0, qui reste la dernière release en octobre 2026, les clés de configuration et l’organisation des fichiers peuvent encore changer entre les releases. Consultez donc le changelog avant de mettre à niveau une installation 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 génération du résumé utilise TF-IDF et TextRank, et non un modèle. Cette étape ne coûte donc rien et fonctionne hors ligne. En contrepartie, le résumé est extractif : il 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. Le résumé est donc régénéré uniquement lorsque vous exécutez /recall:save. Définissez "auto_save_context": "on_end" dans recall.config.json pour le réécrire à la fin de chaque session. Si history.md est également absent, vérifiez capture_history, le marqueur .capture-paused et la disponibilité d’une transcription de session : dans ces cas, les hooks exécutés ignorent l’écriture de l’historique. Vérifiez que le plugin est chargé avec /recall:show, puis confirmez que python3 -V répond sur cette machine, car les hooks sont des scripts Python.

Combien de tokens Recall économise-t-il par session ?

Le chargement d’un résumé 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. Il s’agit de valeurs indicatives. Mesurez votre propre résultat avec wc -c .recall/context.md et la commande /context dans une session, en comparant un démarrage à froid avec une session qui reprend à partir d’un résumé.

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 hébergés sur le même serveur conservent donc des journaux et des résumés distincts. Lancez toujours Claude Code depuis la racine du projet, car les fichiers dépendent du répertoire de travail et non du compte utilisateur.