Recall: memoria persistente per Claude Code su VPS

Cosa fa Recall per la memoria di Claude Code

Recall è un plugin per Claude Code che assegna a ogni progetto una memoria persistente tra le sessioni. Scrive due file Markdown in una cartella .recall/ all'interno del progetto: un log in modalità append-only con le attività svolte e un breve riepilogo del punto raggiunto. Un summarizer Python locale genera entrambi i file sulla macchina in uso, quindi la memoria non consuma token API.

Colma una lacuna limitata ma ricorrente. Martedì chiudi una sessione sul tuo VPS. Mercoledì, una nuova sessione non carica automaticamente la conversazione di martedì, anche se la funzione di memoria automatica integrata in Claude Code può conservare note tra le sessioni. Se tali note non indicano il punto in cui ti eri fermato, 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, rilasciata il 18 July 2026, è ancora l'ultima release a October 2026 e il progetto è distribuito con licenza MIT. È un plugin. Non effettua alcuna chiamata di rete.

Cosa serve sul VPS

Gli hook di acquisizione di Recall sono script Python distribuiti con il plugin. Non esistono dipendenze di terze parti, quindi l'unico requisito effettivo è un interprete.

python3 -V

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

sudo apt update && sudo apt install -y python3

NumPy è un acceleratore opzionale per un passaggio del riepilogatore. Non è necessario.

python3 -c "import numpy"

ModuleNotFoundError: No module named 'numpy' è una risposta accettabile in questo caso. Il riepilogatore 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 arriva durante brevi visite 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 durante la cancellazione. Mostra context.md, così la sessione si apre con il riepilogo visibile.
• Stop viene eseguito ogni volta che Claude completa una risposta. Aggiunge quel turno al log.
• SessionEnd viene eseguito quando la sessione si chiude e può rigenerare il riepilogo.

Da questa procedura vengono creati due file, entrambi all'interno di .recall/.

• history.md è il registro in sola aggiunta: 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/

Con la cattura abilitata, senza un indicatore di pausa e con una trascrizione disponibile, dovresti vedere history.md con del contenuto. È possibile che context.md non venga creato affatto: questo è il comportamento predefinito e non indica un errore. auto_save_context è off se non lo imposti, quindi il riepilogo viene scritto solo quando lo richiedi:

/recall:save

Questo comando esegue il riepilogo locale su history.md e riscrive context.md. L'algoritmo usa un punteggio TF-IDF (frequenza dei termini, frequenza inversa dei documenti) seguito dal ranking delle frasi con TextRank. È deterministico ed estrattivo, cioè seleziona frasi già presenti nel log. Non viene chiamato alcun modello, quindi il passaggio è gratuito e funziona anche quando la macchina è offline.

Configurare Recall per un progetto

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

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

• output_dir definisce 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 definisce 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 le statistiche del diff corrente e i commit recenti.
• max_input_chars limita la quantità di history.md che il riepilogatore legge in un'unica operazione.

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

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

Per sospendere temporaneamente la cattura senza modificare la configurazione, crea il marker di pausa. Eliminalo per riprendere la cattura.

touch .recall/.capture-paused

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

Quanto fa risparmiare Recall in termini di token?

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 deve ricostruirne il contesto 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 di uno o duemila token per il ripristino. Riprodurre una trascrizione completa precedente ricarica l'intera conversazione, per un totale nell'ordine di 85,000 token. Lasciare che il modello ricostruisca il progetto leggendo i file si colloca tra i due valori, intorno a 30,000 token, e questo numero aumenta con le dimensioni del repository. La riga CLAUDE.md serve come riferimento: ha un costo inferiore perché è breve e statica e comunica al modello le regole permanenti, non ciò che è successo la sera precedente.

Misura i tuoi valori. Un token corrisponde indicativamente a quattro caratteri di prosa inglese e a una quantità leggermente inferiore nel codice. Se passi il riepilogo anche a un modello locale sulla stessa VPS, controlla la finestra di contesto in cui viene inserito prima di fare affidamento sul ripristino, perché la lunghezza del contesto predefinita di Ollama dipende dalla VRAM disponibile.

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

All'interno di una sessione, /context mostra cosa è attualmente caricato nella finestra di contesto, mentre /cost riporta i totali della sessione. Avvia una sessione senza contesto, avvia quella successiva con un riepilogo già disponibile e confronta i risultati. Per una panoramica completa di come vengono utilizzati i token di una sessione, come Claude Code utilizza i token contiene la suddivisione dettagliata.

C'è una limitazione da considerare. Il riepilogo viene caricato all'avvio di ogni sessione, quindi un riepilogo che non utilizzi rappresenta un piccolo costo aggiuntivo, non un risparmio. Mantieni summary_sentences vicino al valore predefinito, a meno che le tue sessioni non durino a lungo. Una sessione più contenuta riduce anche l'altro costo, perché un agent orientato verso la modifica minima funzionante lascia un log più breve da classificare 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. Verifica se la cattura è disabilitata, se la directory di output è configurata altrove o se non è stata trovata alcuna trascrizione, prima di concludere che gli hook non siano 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; un sistema che non dispone di nessuno dei due restituisce stderr e il codice di uscita 127. Claude Code mostra una notifica non bloccante relativa all’errore dell’hook, contenente la prima riga di stderr.

history.md aumenta, 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 occuparsene.

I file vengono visualizzati nel progetto errato. Recall scrive in percorsi relativi alla directory dalla quale è stato avviato Claude Code. Se avvii una sessione dalla directory home, la memoria viene quindi salvata lì. Avvia la sessione dalla root del progetto e usa ls -la .recall/ per trovare la posizione effettiva dei file.

La cattura si è arrestata senza alcun avviso. Verifica la presenza dell’indicatore di pausa con ls -a .recall/. Un file .capture-paused creato la settimana scorsa continua a svolgere la propria funzione.

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

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

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

Dove si ferma Recall

Recall combina un log con un riepilogatore. È quindi importante chiarire cosa non include.

Il riepilogatore è estrattivo. TextRank seleziona frasi già presenti in history.md, quindi non valuta mai se una decisione fosse corretta. Una scelta sbagliata registrata martedì viene presentata esattamente come 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 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 in history.md con grep. Recall non offre coordinamento in tempo reale: due sessioni dello stesso progetto condividono il file di log, ma Recall non inserisce le nuove voci del log nel contesto dell'altra sessione. Quando una sessione deve sapere cosa sta facendo l'altra, le sessioni possono scambiarsi direttamente il testo mentre sono in esecuzione.

Non è utile all'interno di una sessione. Un context window che si riempie durante la sessione è un problema diverso, con soluzioni diverse, e la gestione del context window 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 identificato da un'etichetta, quindi Claude chiede conferma prima di basarsi su di esso. Questa progettazione è necessaria perché una directory .recall/ sottoposta a commit è un'area in cui chiunque disponga dei permessi di commit può scrivere testo che l'agente leggerà. Il numero di volte in cui l'agente chiede conferma su ciò che legge dipende dalla modalità dei permessi con cui viene avviata la sessione. Con Claude Code v2.1.283 o versioni successive, la modalità automatica è già la modalità iniziale integrata per le sessioni interattive nel terminale e in VS Code, con qualsiasi piano e provider; le organizzazioni con la configurazione HIPAA continuano ad avviarsi in modalità Manuale. Decidi una volta per tutte se .recall/ è personale o condiviso: aggiungilo a .gitignore per conservarvi la memoria personale, oppure sottoponilo a commit e revisionarlo come qualsiasi altro contributo. Se l'agente viene eseguito senza supervisione, eseguire Claude Code in sicurezza su un VPS descrive il perimetro più ampio.

La redazione è soggetta a limitazioni. Cerca di individuare schemi comuni come API key, token, blocchi PEM e assegnazioni .env. Leggi .recall/ prima di sottoporlo a commit.

Il numero di versione descrive con chiarezza il livello di maturità. Alla versione 0.4.0, ancora l'ultima release disponibile nell'ottobre 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 tuo computer, 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 con il computer offline. Il compromesso è che la sintesi è estrattiva: seleziona frasi dal log invece di scriverne di nuove.

Perché il mio .recall/context.md è assente 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, controlla capture_history, il marker .capture-paused e che sia disponibile una trascrizione della sessione: in questi casi gli hook in esecuzione non scrivono la cronologia. Verifica che il plugin sia caricato con /recall:show, quindi verifica che python3 -V risponda su quel computer, perché gli hook sono script Python.

Quanto salva Recall per sessione?

Il caricamento di una sintesi costa circa 1,200 token, rispetto ai tipici 30,000 token necessari a un modello che deve leggere nuovamente il repository per capire a che punto si trova. Sono valori indicativi. Misura il consumo del tuo ambiente 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 svolgono funzioni diverse. CLAUDE.md contiene ciò che scrivi intenzionalmente: le regole permanenti e i comandi di build. context.md viene generato in base a ciò che è realmente accaduto nella sessione precedente, quindi contiene la migrazione lasciata a metà che non penseresti mai di annotare manualmente. Mantienili entrambi.

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

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