Vai al contenuto principale
Casi d’usoIntermedio6 min di lettura

Turnbook: la memoria locale per gli agenti di coding, senza una chiamata al modello

i
iaLocale Team
•
Turnbook: la memoria locale per gli agenti di coding, senza una chiamata al modello

Il tuo agente di coding dimentica tutto quando la sessione finisce. Hai deciso lunedì quale database usare per il servizio di fatturazione, e mercoledì — con un altro agente, o con lo stesso dopo un /clear — ricominci da zero: stessa domanda, stessa risposta, stesso tempo perso.

La risposta standard è aggiungere un livello di memoria: il modello riscrive la conversazione in "fatti" o note che verranno recuperate dopo. Funziona, ma ha un prezzo nascosto: ogni conversazione passa di nuovo da un modello, con i relativi token e la relativa possibilità che qualcosa si perda o si inventi sul percorso.

Turnbook (ex Graph-MIND) è l'approccio opposto. Non fa mai una chiamata al modello per salvare: tiene ogni conversazione parola per parola in un file SQLite sul tuo PC, e quando una domanda ha bisogno del passato recupera da solo le poche righe che ci rispondono. Il modello che già usi fa solo il lavoro finale.

Come funziona

Il principio si riassume in una frase: nessun LLM in scrittura, nessun LLM in ricerca.

1. Cattura automatica. Un servizio in background legge le trascrizioni dei tuoi agenti (Claude Code, Codex, Cursor, Copilot CLI, Gemini CLI, OpenCode) e salva ogni turno parola per parola. Nessun tag manuale, nessuna decisione su "cosa merita di essere ricordato": se l'hai detto, è in memoria.

2. Ricerca locale. A ogni messaggio, Turnbook cerca nella memoria con tre segnali combinati: ricerca per parole, embedding generati da un modello locale (EmbeddingGemma, 300M di parametri, 4-bit, formato ONNX, nessuna GPU) e il momento in cui la cosa è stata detta. Un piccolo modello appreso riordina i risultati.

3. Consegna breve. L'agente riceve un pacchetto di qualche migliaio di token — i turni che rispondono alla domanda, non l'intera storia — e poi il tuo modello risponde come sempre.

Sotto il cofano è un classico RAG sulla cronologia delle conversazioni, con tutto l'impianto già assemblato: raccolta, suddivisione (un turno = un blocco), embedding locale, archiviazione in un solo file SQLite, retrieval e prompt assembly via MCP. A te resta il pezzo che cambia più spesso: il modello che risponde.

I numeri

Il benchmark di riferimento per la memoria di lungo periodo è LongMemEval: 500 domande su circa 50 sessioni passate ciascuna. I numeri di Turnbook usano gpt-5-mini come modello di risposta e il giudice ufficiale del benchmark (gpt-4o); una domanda senza risposta conta come errore.

Cosa legge il modello di rispostaAccuratezzaToken di modello spesi per salvare
3,1k token (default)91,8% (459/500)0
25k token93,0% (465/500)0

Per confronto: la memoria osservazionale di Mastra riporta 94,9% con lo stesso modello di risposta, ma il modello legge circa 30k token di osservazioni scritte da un altro modello (gemini-2.5-flash) durante il salvataggio. La questione non è battere quel numero, è che i 3 punti di divario si comprano spendendo zero, e che il salvataggio costa letteralmente niente.

Altre cifre che contano:

  • Il ri-ranker fa la differenza: senza (solo fusione di ranking, nessun peso addestrato sui benchmark) il punteggio scende a 87,0% sulle 500 domande. Aiuta soprattutto quando la risposta è sparsa su più sessioni.
  • Resiste alla crescita: su LoCoMo (1.536 domande), con la memoria fatta crescere dieci volte perché contiene anche conversazioni di altre persone, il turno giusto resta tra i primi 30 risultati nel 92,7% dei casi (era 92,6% prima della crescita). Una ricerca impiega 30 ms con circa 6.000 turni e 116 ms con circa 56.000.
  • Non rallenta il PC: il servizio in background usa circa il 2% di un core quando non succede niente, e il server di memoria di un'app tiene circa 525 MB di RAM. Una ricerca dura circa 40 ms (46 ms al 95° percentile), la prima dopo l'avvio circa 1,4 s.

Dove perde

Le memorie che riscrivono sono più forti dove Turnbook perde: dei 41 errori su LongMemEval, 33 sono domande che combinano più sessioni, ragionano sulle date o richiedono l'ultimo valore di qualcosa che è cambiato. Se i tuoi agenti vivono soprattutto di "cosa abbiamo deciso di recente, e cosa ha sostituito cosa", le memorie a riscrittura LLM sono ancora in vantaggio — a prezzo dei token di salvataggio.

Altri limiti da tenere a mente:

  • Non è multiutente: oggi è la memoria personale di un PC. Un'API Python e una modalità server multiutente non esistono ancora.
  • Più uso quotidiano su Windows: macOS e Linux passano tutti i test in CI a ogni modifica, ma hanno meno uso reale.
  • L'embedding è di Google: EmbeddingGemma è coperto dai termini Gemma di Google, non dalla licenza Apache-2.0 di Turnbook.

Come lo provi

Zero a funzionante, in cinque passi:

1. Installa. Su macOS o Linux: curl -LsSf https://raw.githubusercontent.com/goyohan0611-png/turnbook/main/scripts/install.sh | sh (su Windows, doppio clic su Turnbook-Setup.cmd; in alternativa pip install turnbook && turnbook-install).

2. Riavvia i tuoi agenti. L'installer li trova e li collega da solo; dopo un'installazione nuova puoi rileggerlo con attenzione e fissare una versione.

3. Lascia lavorare per qualche sessione normale. Ogni turno viene salvato automaticamente; i segreti (API key, password, numeri di carta) vengono mascherati prima di essere scritti.

4. Apri una nuova sessione — anche con un altro agente o un altro modello — e chiedi: "Dove eravamo rimasti ieri?", "Quale database abbiamo scelto per il servizio di fatturazione, e perché?". Se risponde con i dettagli giusti, la memoria funziona.

5. Se non va, turnbook-uninstall stacca tutte le app e ferma il servizio, lasciando la memoria in ~/.turnbook (aggiungi --purge per cancellarla davvero).

Se vuoi solo i tool di ricerca, senza la cattura automatica, configura MCP a mano: claude mcp add turnbook -- python -m turnbook.mcp_server.

Puoi anche portare i documenti del progetto nella stessa ricerca: turnbook docs add FOLDER tiene i file Markdown e di testo indicizzati accanto alle conversazioni, e aggiornati quando cambiano.

In sintesi

Turnbook è la risposta "tutto in locale" alla memoria degli agenti di coding: salva ogni conversazione parola per parola senza spendere un token, cerca con un modello di embedding da 300M che non vuole una GPU, e raggiunge 91,8% su LongMemEval leggendo 3,1k token a risposta. Perde tre punti rispetto alle memorie che riscrivono con un LLM, ma compra quel divario a costo di salvataggio pari a zero, e la memoria non lascia mai il tuo PC. Se i tuoi agenti ripetono ogni settimana le stesse spiegazioni, è uno di quei casi in cui l'infrastruttura locale smette di essere un esperimento.

Fonti

Articolo generato con IA

In questi percorsi

Condividi:

Ti è piaciuto questo articolo?

Iscriviti alla newsletter per ricevere nuovi tutorial e guide.

Dopo l'iscrizione ricevi una email di conferma (double opt-in). Senza conferma non inviamo nulla. Nessuno spam, ti promettiamo.

Articoli Correlati