Recall: memoria persistente per Claude Code su VPS

Cosa fa Recall per la memoria di Claude Code

Recall è un plugin di Claude Code che fornisce a ogni progetto una memoria persistente tra le sessioni. Scrive due file Markdown in una cartella .recall/ all’interno del progetto: un log in sola append con le attività svolte e un breve riepilogo del punto raggiunto. Entrambi vengono generati sul computer in uso da un summarizer Python locale, quindi la memoria non consuma token API.

Recall colma una lacuna piccola ma ricorrente. Martedì chiudi una sessione sul tuo VPS. Mercoledì Claude Code non sa nulla di quanto è successo martedì. Devi spiegare di nuovo il progetto manualmente oppure lasciare che il modello rilegga metà del repository per ricostruire il contesto. Entrambe le opzioni consumano token, ma la seconda ne consuma molti.

La versione 0.4.0 di Recall è quella corrente a luglio 2026 e il progetto è distribuito con licenza MIT. È un plugin. Non effettua chiamate di rete.

Cosa serve sul VPS

Gli hook di acquisizione di Recall sono script Python inclusi nel plugin. Non ci sono dipendenze di terze parti, quindi l'unico requisito effettivo è un interprete.

python3 -V

Ubuntu 24.04 soddisfa Python 3.12.3. Recall supporta Python 3.9 e versioni successive. Le immagini container minimali a volte non includono alcun interprete; in tal caso la shell restituisce python3: command not found. Installane uno prima di proseguire.

sudo apt update && sudo apt install -y python3

NumPy è un acceleratore opzionale per una fase del summarizer. Non è necessario installarlo.

python3 -c "import numpy"

ModuleNotFoundError: No module named 'numpy' è una risposta accettabile in questo caso. Il summarizer dispone di un percorso in puro Python e la suite di test del progetto verifica che entrambi i percorsi selezionino le stesse frasi.

La memoria della sessione è più importante su un server che su un laptop, perché il lavoro sul server si svolge durante visite brevi distribuite nell'arco di più giorni. Se hai già Claude Code in esecuzione in tmux su un VPS, Recall è il componente che trasferisce la sessione di ieri a quella di oggi.

Installare Recall dal marketplace dei plugin

Due comandi, eseguiti all'interno di una sessione di Claude Code:

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

Il secondo comando legge plugin@marketplace. In questo caso entrambi i nomi sono recall, il che sembra un errore di copia e incolla, ma non lo è.

Verificare l'installazione eseguendo uno dei comandi del plugin:

/recall:show

/recall:show stampa il riepilogo corrente. In un progetto appena creato non c'è ancora nulla da stampare, quindi il controllo effettivo consiste nel verificare che il comando esista. Se Claude Code non riconosce /recall:show, il plugin non è caricato e nessun hook verrà eseguito.

Per eseguire il plugin da un checkout, clonare invece il repository e convalidarlo prima:

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

claude plugin validate . legge il manifest in .claude-plugin/ e segnala se il plugin è strutturato correttamente. Quindi avviare Claude Code dalla directory del progetto con claude --plugin-dir ~/recall.

Cosa scrivono gli hook e quando

Recall registra tre hook di Claude Code. Ognuno esegue uno script Python dalla directory del plugin.

• SessionStart viene eseguito all'avvio, alla ripresa e quando la sessione viene azzerata. Mostra context.md, così la sessione si apre con il riepilogo in primo piano.
• Stop viene eseguito ogni volta che Claude termina una risposta. Aggiunge quel turno al log.
• SessionEnd viene eseguito alla chiusura della sessione e può rigenerare il riepilogo.

Da questa procedura vengono prodotti due file, entrambi in .recall/.

• history.md è il record in modalità append: prompt, risposte, file modificati e comandi eseguiti.
• context.md è il riepilogo generato: obiettivo, sintesi, passaggi successivi, file modificati, comandi eseguiti e contesto git.

Dopo una sessione reale, controlla la directory.

ls -la .recall/

Dovresti trovare history.md con del contenuto. Potresti non trovare affatto context.md, e questo è il comportamento predefinito, non un errore. auto_save_context è off se non lo imposti, quindi il riepilogo viene scritto soltanto quando lo richiedi:

/recall:save

Questo comando esegue il riepilogatore locale su history.md e riscrive context.md. L'algoritmo usa un punteggio TF-IDF (frequenza del termine, frequenza inversa del documento) seguito da una classificazione delle frasi con TextRank. È deterministico ed estrattivo: seleziona frasi già presenti nel log. Non viene chiamato alcun modello, quindi il passaggio è gratuito e funziona anche quando la macchina è offline.

Configura Recall per un progetto

La configurazione si trova in un file recall.config.json nella directory radice del progetto. Questi sono i valori predefiniti forniti:

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

• output_dir specifica dove vengono salvati i due file. Mantienili all'interno del progetto.
• capture_history abilita o disabilita il log history.md.
• auto_save_context accetta off o on_end e, per impostazione predefinita, usa off.
• summary_sentences specifica quante frasi vengono mantenute in context.md. Aumentando questo valore si ottiene un riepilogo più lungo e un carico leggermente maggiore all'avvio della sessione.
• redact rimuove i pattern comuni dei secret prima che qualsiasi dato venga scritto su disco.
• include_git aggiunge al riepilogo il diff corrente e i commit recenti.
• max_input_chars limita la quantità di history.md che il riepilogatore legge in un singolo passaggio.

Per un progetto eseguito su un VPS, la modifica più utile è il salvataggio automatico, perché una sessione su un server spesso termina quando il terminale si disconnette, non quando si decide di interromperla.

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

Per interrompere temporaneamente la raccolta senza modificare la configurazione, crea il marker di pausa. Eliminalo per avviare nuovamente la raccolta.

touch .recall/.capture-paused

Esegui questa operazione prima di una sessione in cui gestisci le credenziali di produzione, perché la redazione è un filtro e non una garanzia. Lo stesso principio si applica a tenere i secret fuori dagli agenti AI in generale: il secret più sicuro è quello che l'agente non vede mai.

Quanto risparmio in token con Recall?

Dipende dall'alternativa. Caricare un riepilogo all'avvio della sessione ha un costo ridotto. Ciò che sostituisce può essere costoso, perché un modello che non conosce il progetto lo ricostruisce leggendo i file.

[
  {
    "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"
  }
]

Questi sono valori tipici per un progetto di dimensioni medie, non una misurazione del tuo progetto. Un riepilogo di Recall viene caricato con circa 1,200 token, in linea con il valore dichiarato dal progetto, compreso tra mille e duemila token per un resume. Riprodurre una trascrizione precedente completa ricarica l'intera conversazione, per circa 85,000 token. Lasciare che il modello ricostruisca il progetto leggendo i file si colloca tra i due valori, vicino a 30,000 token, e questo numero cresce con le dimensioni del repository. La riga CLAUDE.md serve come riferimento: è più economica perché è breve e statica e comunica al modello le regole permanenti, non ciò che è successo la notte precedente.

Misura i tuoi valori. Un token corrisponde approssimativamente a quattro caratteri di prosa inglese e a un numero leggermente inferiore di caratteri nel codice. Se invii il riepilogo anche a un modello locale sullo stesso VPS, controlla la finestra in cui viene inserito prima di fare affidamento sul resume, perché Ollama tronca i prompt lunghi in corrispondenza di una lunghezza di contesto predefinita ridotta invece di segnalare che ha eliminato la parte finale.

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

All'interno di una sessione, /context mostra ciò che è attualmente caricato nella finestra di contesto e /cost riporta i totali della sessione. Avvia una sessione senza contesto, quindi avviane un'altra con un riepilogo già disponibile e confronta i risultati. Per una panoramica completa della distribuzione effettiva dei token in una sessione, come Claude Code utilizza i token contiene il dettaglio.

Una precisazione rende corretta questa stima. Il riepilogo viene caricato all'avvio di ogni sessione, quindi un riepilogo che non utilizzi comporta un piccolo costo invece di un risparmio. Mantieni summary_sentences vicino al valore predefinito, salvo che le sessioni siano lunghe. Una sessione più contenuta aiuta sull'altro lato del bilancio, perché un agent indirizzato verso la modifica minima funzionante lascia un log più breve da analizzare per il riepilogatore.

Ricostruire il riepilogo senza una sessione

Se hai clonato il repository, il summarizer dispone di un proprio punto di ingresso da riga di comando. È utile su un VPS quando una sessione si è interrotta insieme al terminale e vuoi comunque ottenere il riepilogo.

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

L'output della guida elenca i flag accettati: --cwd per la root del progetto, --transcript per specificare un file di trascrizione, --quiet per sopprimere l'output e --harness per scegliere tra claude e opencode. Indicalo per un progetto:

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

Legge la trascrizione della sessione e history.md, quindi scrive context.md nella directory specificata. Se hai eseguito l'installazione tramite il marketplace, il plugin si trova in una directory gestita da Claude Code e /recall:save è il metodo supportato per eseguire la stessa operazione.

Perché non viene scritto nulla

Nessuna directory .recall/ dopo una sessione completa. Gli hook non sono mai stati eseguiti. Digita /recall:show per verificare che il plugin sia caricato, quindi esegui python3 -V. Il comando dell’hook prova prima python3 e poi python, quindi un sistema che non dispone di nessuno dei due non scrive nulla e non segnala il problema.

history.md cresce, ma context.md non cambia mai. Per impostazione predefinita, auto_save_context è off. Esegui /recall:save oppure imposta la chiave su on_end e lascia che sia l’hook SessionEnd a eseguire l’operazione.

I file vengono creati nel progetto sbagliato. Recall scrive in percorsi relativi alla directory da cui è stato avviato Claude Code, quindi l’avvio di una sessione dalla directory home salva lì la memoria. Avvia la sessione dalla root del progetto e usa ls -la .recall/ per individuare la posizione effettiva dei file.

La raccolta si è interrotta e non hai ricevuto alcun avviso. Verifica la presenza del marker di pausa con ls -a .recall/. Un file .capture-paused creato la settimana scorsa continua a essere utilizzato.

Il riepilogo è scarno dopo una sessione lunga. max_input_chars limita l’input del summarizer a 200000 caratteri, quindi un log molto lungo viene troncato. Ruota il log.

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

Esegui poi una sessione breve e controlla di nuovo ls -la .recall/ per verificare che sia comparso un nuovo history.md.

Dove si ferma Recall

Recall combina un log e un riepilogatore. È importante chiarire cosa rimane escluso.

Il riepilogatore è estrattivo. TextRank seleziona frasi già presenti in history.md, quindi non valuta mai se una decisione era corretta. Una scelta sbagliata registrata martedì ha lo stesso aspetto di una decisione corretta presa mercoledì. Quando la posta in gioco è alta, leggi context.md e correggilo manualmente. È un file markdown e nulla impedisce di modificarlo.

Non è disponibile alcuna ricerca. Per ogni progetto hai un solo riepilogo corrente e un log in crescita, non una memoria interrogabile tra progetti diversi. Se vuoi sapere cosa hai deciso sul database tre settimane fa, devi cercare con grep in history.md. Recall non trasferisce neppure informazioni tra sessioni: due sessioni aperte contemporaneamente sullo stesso VPS non possono vedere i rispettivi log. Quando una deve sapere cosa sta facendo l'altra, le sessioni possono passarsi direttamente il testo mentre sono in esecuzione.

Non è utile all'interno di una sessione. Una finestra di contesto che si riempie durante la sessione è un problema diverso, con soluzioni diverse. La gestione della finestra di contesto all'interno di una singola sessione è il contenuto complementare a questa guida.

Per progettazione, il riepilogo viene trattato come input non attendibile. context.md viene inserito in un blocco delimitato e contrassegnato, e Claude chiede conferma prima di farvi affidamento. Questa scelta è necessaria perché una directory .recall/ sottoposta a commit è un'area in cui chiunque disponga dell'accesso in scrittura al repository può inserire testo che l'agente leggerà. La frequenza con cui l'agente chiede conferma sul contenuto che legge dipende dalla modalità di autorizzazione con cui viene avviata la sessione. Inoltre, la modalità automatica diventa l'impostazione predefinita di Claude Code il 14 agosto 2026. Decidi una volta se .recall/ è personale o condiviso: aggiungilo a .gitignore per conservarvi memoria personale, oppure sottoponilo a commit e revisionarlo come qualsiasi altro contributo. Se l'agente viene eseguito senza supervisione, l'esecuzione sicura di Claude Code su un VPS descrive il perimetro più ampio.

La redazione è effettuata con la massima attenzione possibile, ma non è garantita. Vengono rilevati schemi comuni, come chiavi API, token, blocchi PEM e assegnazioni .env. Leggi .recall/ prima di eseguire il commit.

Il numero di versione riflette il livello di maturità del progetto. Alla versione 0.4.0, nel luglio 2026, le chiavi di configurazione e la struttura dei file possono ancora cambiare tra una release e l'altra. Leggi quindi il changelog prima di aggiornare una configurazione da cui dipendi.

FAQ

Recall invia il mio codice o le trascrizioni da qualche parte?

No. Gli hook di acquisizione e il summarizer sono script Python eseguiti sul computer locale, il plugin non contiene alcuna chiave API e non effettua chiamate di rete. La sintesi usa TF-IDF e TextRank invece di un modello, quindi non ha costi e funziona anche quando il computer è offline. Il compromesso è che la sintesi è estrattiva: seleziona frasi dal log invece di generarne di nuove.

Perché il mio .recall/context.md manca o non è aggiornato?

auto_save_context è impostato per impostazione predefinita su off, quindi la sintesi viene rigenerata solo quando esegui /recall:save. Imposta "auto_save_context": "on_end" in recall.config.json per riscriverla al termine di ogni sessione. Se manca anche history.md, gli hook non sono in esecuzione: verifica che il plugin sia caricato con /recall:show, quindi verifica che python3 -V risponda su quel sistema, perché gli hook sono script Python.

Quanto salva Recall per sessione?

Il caricamento di una sintesi costa circa 1,200 token, rispetto ai 30,000 token tipici necessari a un modello che deve rileggere il repository per capire a che punto si trova. Sono valori indicativi. Misura i tuoi con wc -c .recall/context.md e il comando /context all'interno di una sessione, confrontando un avvio a freddo con una sessione che riprende da una sintesi.

Mi serve ancora un file CLAUDE.md?

Sì, e i due file hanno funzioni diverse. CLAUDE.md contiene ciò che scrivi intenzionalmente: le regole permanenti e i comandi di build. context.md viene generato in base a quanto è accaduto realmente nell'ultima sessione, quindi contiene la migrazione lasciata a metà che non penseresti mai di annotare. Conservali entrambi.

Un singolo VPS può conservare la memoria di più progetti?

Sì. Recall conserva la memoria in .recall/ all'interno della directory di ogni progetto, quindi due progetti sullo stesso server mantengono log e sintesi separati. Avvia Claude Code dalla root del progetto ogni volta, perché i file seguono la directory di lavoro e non l'account utente.