Recall: memoria locale per Claude Code su VPS

Funzionamento della memoria di Recall per Claude Code

Recall è un plugin di Claude Code che fornisce a ogni progetto una memoria tra le sessioni. Scrive due file Markdown in una cartella .recall/ all'interno del progetto: un registro a cui aggiunge sempre nuovi contenuti, che documenta quanto è accaduto, 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ì Claude Code non sa nulla di martedì. Devi spiegare di nuovo il progetto manualmente oppure consentire al modello di leggere nuovamente metà del repository per ricostruire la situazione. 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 restituisce Python 3.12.3. Recall supporta Python 3.9 e versioni successive. Le immagini di container minimali a volte non includono alcun interprete; in tal caso la shell restituisce python3: command not found. Installane uno prima di procedere.

sudo apt update && sudo apt install -y python3

NumPy è un acceleratore facoltativo per un passaggio del summarizer. Non è necessario.

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 sui server si svolge in visite brevi distribuite nell'arco di diversi 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, da digitare all'interno di una sessione Claude Code:

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

Il secondo comando legge plugin@marketplace. Entrambi i nomi sono recall qui. Sembra un errore di copia e incolla, ma non lo è.

Verifica l'installazione eseguendo uno dei comandi propri del plugin:

/recall:show

/recall:show stampa il riepilogo corrente. In un progetto appena creato non c'è ancora nulla da stampare. Quindi stai verificando 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, clona prima il repository e convalidalo:

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. Poi avvia 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 si attiva all'avvio, alla ripresa e alla cancellazione. Mostra context.md, così la sessione si apre con il riepilogo visibile.
• Stop si attiva ogni volta che Claude completa una risposta. Accoda quel turno al log.
• SessionEnd si attiva alla chiusura della sessione e può rigenerare il riepilogo.

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

• history.md è il record a cui si aggiungono solo nuovi contenuti: 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 vedere history.md con del contenuto. È possibile che context.md non esista affatto: questo è il comportamento predefinito e non un errore. auto_save_context è off, a meno che non lo imposti; il riepilogo viene quindi scritto solo quando lo richiedi:

/recall:save

Questo comando esegue il riepilogatore locale su history.md e riscrive context.md. L'algoritmo usa il punteggio TF-IDF (frequenza dei termini, frequenza inversa dei documenti), seguito dalla 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.

Configurare Recall per un progetto

La configurazione si trova in un file recall.config.json nella 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 definisce la posizione dei 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 conservate 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 segreti 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 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 raccolta senza modificare la configurazione, crea il marker di pausa. Eliminalo per riavviare la raccolta.

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 segreti fuori dagli agenti AI in generale: il segreto più sicuro è quello che l'agente non vede.

Quanti token fa risparmiare Recall?

Dipende dall'alternativa. Caricare un riepilogo all'avvio della sessione è poco costoso. 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 medie dimensioni, non una misurazione del tuo progetto. Il riepilogo di Recall viene caricato con un costo di circa 1,200 token, in linea con la stima pubblicata dal progetto, pari a uno o duemila token per la ripresa. 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 il valore aumenta 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 è accaduto la sera 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.

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, mentre /cost riporta i totali della sessione. Avvia una sessione senza contesto, poi avviane un'altra con un riepilogo già disponibile e confronta i risultati. Per una panoramica completa della distribuzione dei token nella sessione, come Claude Code utilizza i token contiene la suddivisione.

C'è una precisazione importante. Il riepilogo viene caricato all'avvio di ogni sessione, quindi un riepilogo su cui non intervieni mai rappresenta un piccolo costo anziché un risparmio. Mantieni summary_sentences vicino al valore predefinito, a meno che le tue sessioni non durino a lungo.

Rigenerare il riepilogo senza una sessione

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

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

L'output della guida elenca i flag accettati: --cwd per la radice del progetto, --transcript per un file di trascrizione esplicito, --quiet per sopprimere l'output e --harness per scegliere tra claude e opencode. Indica 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 gestirla.

I file vengono creati nel progetto sbagliato. Recall scrive in percorsi relativi alla directory da cui è stato avviato Claude Code, quindi avviare una sessione dalla directory home salva la memoria in quella posizione. Avvia la sessione dalla radice del progetto e usa ls -la .recall/ per trovare la posizione effettiva dei file.

La raccolta si è interrotta senza alcun avviso. Verifica la presenza del marker di pausa con ls -a .recall/. Un file .capture-paused creato la settimana scorsa continua a svolgere la propria funzione.

Il riepilogo è poco dettagliato 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 quindi una sessione breve e controlla nuovamente ls -la .recall/ per verificare che sia comparso un nuovo history.md.

Dove si ferma Recall

Recall è un log con un componente di riepilogo. È importante chiarire cosa resta escluso.

Il componente di riepilogo è estrattivo. TextRank seleziona frasi già presenti in history.md, quindi non valuta mai se una decisione era corretta. Una scelta errata registrata martedì viene presentata esattamente come una buona decisione presa mercoledì. Quando la posta in gioco è concreta, leggi context.md e correggilo manualmente. È un file markdown e puoi modificarlo liberamente.

Non è disponibile alcuna ricerca. Per ogni progetto hai un riepilogo corrente e un log in continua crescita, non una memoria interrogabile tra i progetti. Se vuoi sapere cosa hai deciso sul database tre settimane fa, devi eseguire grep su history.md.

Non è utile all'interno di una sessione. L'esaurimento della finestra di contesto durante una sessione è un problema diverso, con soluzioni diverse. gestire la finestra di contesto all'interno di una sessione è l'articolo complementare a questa guida.

Per progettazione, il riepilogo viene trattato come input non attendibile. context.md viene inserito in un blocco delimitato e con un'etichetta, quindi Claude chiede conferma prima di basarsi su di esso. Questa progettazione è necessaria perché una directory .recall/ sottoposta a commit consente a chiunque abbia accesso al commit di scrivere testo che l'agente leggerà. Decidi una volta per tutte se .recall/ è personale o condivisa: aggiungila a .gitignore per la memoria personale, oppure sottoponila a commit e revisionarla come qualsiasi altro contributo. Se l'agente viene eseguito senza supervisione, eseguire Claude Code in sicurezza su un VPS tratta il perimetro più ampio.

La redazione è applicata nei limiti del possibile. Individua schemi comuni come chiavi API, token, blocchi PEM e assegnazioni .env. Leggi .recall/ prima di sottoporlo a commit.

Il numero di versione riflette correttamente il livello di maturità. 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 riepilogatore sono script Python eseguiti sul computer locale, il plugin non contiene alcuna API key e non effettua chiamate di rete. Il riepilogo usa TF-IDF e TextRank anziché un modello, quindi questa fase non ha costi e funziona anche quando il computer è offline. Il compromesso è che il riepilogo è estrattivo: 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 il riepilogo viene rigenerato solo quando esegui /recall:save. Imposta "auto_save_context": "on_end" in recall.config.json per riscriverlo 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 risparmia Recall per sessione?

Il caricamento di un riepilogo costa circa 1,200 token, rispetto ai tipici 30,000 token richiesti da 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 un riepilogo.

Mi serve ancora un file CLAUDE.md?

Sì, e svolgono due 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. Conservali entrambi.

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

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