Salta al contenuto principale

01 - Letta (ex-MemGPT): memoria persistente per agents

Come un agente ricorda oltre la finestra di contesto: blocchi di memoria, archivio, MemFS e Agent SDK di Letta, con un modello da eseguire.

Cosa ne pensi di questo articolo?

01 - Letta (ex-MemGPT): memoria persistente per agents
Agentic PlatformsFoto:Pavel DanilyukPexels

In Breve

Come un agente ricorda oltre la finestra di contesto: blocchi di memoria, archivio, MemFS e Agent SDK di Letta, con un modello da eseguire.

Il problema: un agente che ricomincia da zero a ogni conversazione

Un modello linguistico non ricorda niente tra una chiamata e l'altra: vede solo il testo che gli mandi, cioè la finestra di contesto. Se Alice ti parla del suo progetto lunedì e torna giovedì, l'agente sa chi è soltanto se tu gli rimandi tutto ciò che è stato detto lunedì. Rimandare tutto costa token a ogni turno e prima o poi non entra più. Letta, il nome attuale di MemGPT, nasce per questo: è l'agente stesso a decidere che cosa tenere nel prompt, che cosa archiviare e quando andarlo a riprendere.

La risposta breve è che la memoria persistente di Letta è fatta di due cose. Ci sono pochi blocchi di testo piccoli e sempre presenti nel prompt, che dicono chi è l'agente e chi è l'utente. E c'è un archivio fuori dal prompt, che l'agente interroga con una ricerca quando gli serve. La parte che cambia più in fretta è tutto il resto: il prodotto, nel novembre 2026, non è più quello descritto da molti tutorial, e lo vedremo con le fonti in mano.

L'idea di MemGPT, in un modello che puoi eseguire

L'idea nasce nel paper MemGPT: Towards LLMs as Operating Systems (Packer e altri, arXiv 2310.08560, ottobre 2023). Gli autori propongono la virtual context management: come un sistema operativo fa sembrare grande la memoria spostando dati tra memoria veloce e lenta, un agente può sembrare avere un contesto illimitato spostando informazioni tra il prompt e un archivio. Il post del blog di Letta sui blocchi di memoria (14 maggio 2025) descrive la forma concreta: due blocchi nel prompt, human e persona, che l'agente può riscrivere e che hanno un limite di caratteri.

Le tre zone di memoria, nell'ordine in cui il testo si allontana dal modello, sono queste:

  • Blocchi nel prompt: piccoli, con un tetto di caratteri, riscritti dall'agente; il modello li vede a ogni turno.
  • Finestra dei messaggi: la conversazione recente; quando sfora il budget, i messaggi più vecchi escono dal prompt.
  • Archivio: tutto ciò che è uscito, più ciò che l'agente ha scelto di salvare; si recupera solo con una ricerca esplicita.

Il criterio che tiene insieme l'elenco è il costo di presenza: ogni carattere nel prompt si paga a ogni turno, ogni carattere in archivio si paga solo quando lo cerchi. Per questo i blocchi hanno un tetto: senza, l'agente li gonfierebbe fino a ricostruire il problema che doveva risolvere. L'ordine dell'elenco non è casuale: va dalla zona più vicina al modello alla più lontana, e il costo scende a ogni passo.

Per vedere il meccanismo senza chiave, senza modello e senza server, ho scritto un modello didattico in Python. Non è codice di Letta e non lo imita riga per riga: la ricerca è una sovrapposizione di parole, non un embedding, e la finestra si misura in parole e non in token. Serve a rendere visibili tre comportamenti: il rifiuto di un blocco troppo lungo, lo sfratto dei messaggi vecchi in archivio, il recupero con una ricerca.

Gerarchia di memoria in miniatura (modello didattico, non Letta)
"""Modello didattico della gerarchia di memoria di MemGPT: NON e' codice di Letta."""
import re


class LimiteBlocco(Exception):
    pass


class Memoria:
    def __init__(self, limite_blocco=120, budget_contesto=60):
        self.blocchi = {"human": "", "persona": "Assistente tecnico, risposte concise."}
        self.limite_blocco = limite_blocco          # caratteri per blocco, come nel MemGPT originale
        self.budget_contesto = budget_contesto      # parole ammesse nella finestra dei messaggi
        self.finestra = []                          # messaggi recenti, nel contesto
        self.archivio = []                          # memoria esterna, fuori dal contesto
        self.riassunto = ""

    # --- memoria "core": sempre nel prompt, piccola, modificabile dall'agente
    def blocco_aggiungi(self, nome, testo):
        nuovo = (self.blocchi[nome] + " " + testo).strip()
        if len(nuovo) > self.limite_blocco:
            raise LimiteBlocco(f"{nome}: {len(nuovo)} caratteri, limite {self.limite_blocco}")
        self.blocchi[nome] = nuovo

    def blocco_sostituisci(self, nome, testo):
        if len(testo) > self.limite_blocco:
            raise LimiteBlocco(f"{nome}: {len(testo)} caratteri, limite {self.limite_blocco}")
        self.blocchi[nome] = testo

    # --- memoria "archival": fuori dal contesto, si interroga con una ricerca
    def archivio_inserisci(self, testo):
        self.archivio.append(testo)

    def archivio_cerca(self, domanda, k=2):
        parole = set(re.findall(r"\w+", domanda.lower()))
        punteggi = [(len(parole & set(re.findall(r"\w+", t.lower()))), -i, t)
                    for i, t in enumerate(self.archivio)]
        return [t for p, _, t in sorted(punteggi, reverse=True)[:k] if p > 0]

    # --- finestra dei messaggi: quando sfora, i piu' vecchi vanno in archivio
    def messaggio(self, testo):
        self.finestra.append(testo)
        while sum(len(m.split()) for m in self.finestra) > self.budget_contesto:
            espulso = self.finestra.pop(0)
            self.archivio_inserisci(espulso)
            self.riassunto = f"[{len(self.archivio)} messaggi in archivio]"

    def prompt(self):
        blocchi = "\n".join(f"<{n}>{t}</{n}>" for n, t in self.blocchi.items())
        return f"{blocchi}\n{self.riassunto}\n" + "\n".join(self.finestra)


m = Memoria()
m.blocco_aggiungi("human", "Alice, ingegnera software.")
try:
    m.blocco_aggiungi("human", "Preferisce risposte tecniche dettagliate, con esempi di codice, " * 2)
except LimiteBlocco as e:
    print("rifiutato:", e)
m.blocco_sostituisci("human", "Alice, ingegnera software. Vuole esempi di codice.")

for i in range(1, 7):
    m.messaggio(f"turno {i}: " + "parola " * 9)
m.messaggio("turno 7: il bug di React era un re-render inutile nel componente Tabella")
print("finestra:", len(m.finestra), "messaggi | archivio:", len(m.archivio), "messaggi")
print("ricerca mentre il messaggio e' ancora in finestra:", m.archivio_cerca("bug React re-render"))
m.messaggio("turno 8: " + "parola " * 50)
print("finestra:", len(m.finestra), "messaggi | archivio:", len(m.archivio), "messaggi")
print("ricerca dopo lo sfratto:", m.archivio_cerca("bug React re-render", k=1))
print("riga nel prompt:", m.riassunto)

# Output:
# rifiutato: human: 154 caratteri, limite 120
# finestra: 5 messaggi | archivio: 2 messaggi
# ricerca mentre il messaggio e' ancora in finestra: []
# finestra: 1 messaggi | archivio: 7 messaggi
# ricerca dopo lo sfratto: ['turno 7: il bug di React era un re-render inutile nel componente Tabella']
# riga nel prompt: [7 messaggi in archivio]

Le righe che contano sono tre. blocco_aggiungi rifiuta il testo che porterebbe il blocco oltre limite_blocco e solleva LimiteBlocco: nel sistema reale è l'errore che costringe l'agente a riscrivere il blocco invece di accodare. messaggio è il cuore dello sfratto: finché le parole nella finestra superano il budget, il messaggio più vecchio passa in archivio. archivio_cerca ordina per parole in comune, con l'indice del messaggio come spareggio, così l'uscita è la stessa a ogni esecuzione.

L'uscita racconta la sequenza: il secondo inserimento in human viene rifiutato perché porta il blocco a 154 caratteri contro un limite di 120. Dopo sette messaggi la finestra ne tiene cinque e l'archivio due, e la ricerca sul bug di React non trova niente, perché quel messaggio è ancora nel prompt e non serve cercarlo. Solo dopo il messaggio lungo del turno 8 il turno 7 esce dalla finestra, finisce in archivio e la stessa ricerca lo restituisce. Quando non usare questo schema: se la conversazione sta sempre dentro il contesto, l'archivio è complessità inutile.

Che cosa è Letta oggi

Qui il testo cambia registro, perché i fatti sono cambiati. Il README di letta-ai/letta dice oggi che il codice attivo vive in letta-ai/letta-code, e che il server API di prima, quello della V1, è stato ritirato e sta nel ramo archive. Il pacchetto letta-ai citato da molti tutorial non esiste su PyPI (la richiesta al registro risponde 404); esiste letta, la cui ultima versione, la 0.34.12 del 12 ottobre 2026, si presenta come «Letta Code: stateful agents in your terminal». Letta Code e Agent SDK sono Apache-2.0, come il repository storico.

AspettoNei tutorial della V1Oggi (letta-code e Agent SDK)
Installazionepip install e Docker sul repositorynpm install -g @letta-ai/letta-code, oppure uv tool install letta
Serverserver API REST da avviareApp Server, letta server --backend local
Programmazioneclient REST (anche Python, letta-client)Agent SDK in TypeScript, @letta-ai/letta-agent-sdk
Dove sta la memoriablocchi e archivio nel database del serverfile Markdown in un repository git dell'agente (MemFS)

Leggi la tabella come un avviso, non come un giudizio: se un tutorial ti fa scrivere LocalClient, lanciare letta db init o costruire un'immagine Docker dal repository, sta descrivendo il server ritirato. La fonte da seguire è la documentazione attuale, docs.letta.com. C'è anche un default da conoscere: il README di Letta Code dice che Letta Cloud è il predefinito, e che al primo avvio scegli se accedere o procedere in locale. Chi tiene i dati in casa deve scegliere il locale in modo esplicito, con letta backend local o --backend local.

Dove sta la memoria adesso: MemFS e dreaming

In Letta Code la memoria è un insieme di file Markdown con un'intestazione YAML, dentro un repository git che appartiene all'agente. Il nome del file è l'etichetta del blocco: la memoria persona diventa persona.md. La documentazione chiama questo livello MemFS (anche «context repository») e spiega la regola che sostituisce il tetto di caratteri della V1: i file alla radice entrano nel prompt a ogni turno, le directory con un proprio MEMORY.md restano fuori finché l'agente non decide di leggerle.

Struttura di una memoria, da docs.letta.com/concepts/memfs
$MEMORY_DIR/
├── MEMORY.md
├── persona.md
├── human.md
├── reference/
│   ├── MEMORY.md
│   └── project-notes.md
└── skills/
    └── my-skill/
        └── SKILL.md

Il mapping con il modello didattico è diretto: persona.md e human.md corrispondono ai blocchi nel prompt, la directory reference/ all'archivio, il suo MEMORY.md a un indice che indica dove guardare. Due conseguenze pratiche. Primo, MemFS non include un indice semantico o vettoriale: la documentazione dice che gli agenti cercano con i normali strumenti di ricerca e lettura sui file, e che la ricerca semantica richiede un mod separato che a sua volta dipende da QMD. Secondo, ogni modifica è un commit: hai la storia, e puoi tornare indietro.

Il dreaming è la parte nuova rispetto al paper. Sono sotto-agenti in background che rileggono le conversazioni recenti, consolidano ciò che vale e aggiornano la memoria senza interrompere il lavoro. Si attivano dopo un numero di passi o quando il contesto viene compattato. Un'opzione fa rivedere le proposte all'agente stesso in una seconda conversazione: la documentazione avverte che usa più token del modello e non chiede la tua approvazione.

Un agente con l'Agent SDK (schema da adattare, compilato ma non eseguito)

Il listato seguente è l'esempio della documentazione adattato al caso di Alice. L'ho compilato con tsc --strict contro @letta-ai/letta-agent-sdk 0.8.86, la versione corrente sul registro npm il 13 novembre 2026. Non l'ho eseguito, perché richiede un App Server in ascolto e un provider di modelli collegato: è uno schema da adattare. Il compilatore è comunque un controllo vero: scrivendo trigger: "step-conteggio" al posto di "step-count" rifiuta il tipo, e la correzione si vede prima dell'esecuzione.

Agent SDK di Letta: agente con persona, utente e dreaming
import { LettaAgentClient } from "@letta-ai/letta-agent-sdk";

const client = new LettaAgentClient({
  backend: "remote",
  url: process.env.LETTA_APP_SERVER_URL ?? "http://127.0.0.1:4500",
  authToken: process.env.LETTA_APP_SERVER_TOKEN,
});

const agentId = await client.createAgent({
  persona: "Sei un assistente di ricerca. Annota ciò che impari sull'utente.",
  human: "Utente: Alice, ingegnera software, preferisce risposte concise.",
  dreaming: { trigger: "step-count", behavior: "auto-launch", stepCount: 25 },
});

await using session = client.createSession(agentId, { cwd: process.cwd() });
await session.send("Quale era il mio ruolo?");
for await (const message of session.stream()) {
  if (message.type === "assistant") console.log(message.content);
}

persona e human sono scorciatoie che impostano le due memorie di base; chi vuole il controllo completo passa invece un array memory di oggetti label e value, e ogni voce diventa un file. Per dreaming la documentazione elenca trigger ("off", "step-count", "compaction-event") e behavior ("reminder" o "auto-launch"), che si può fissare solo alla creazione. La pagina non dichiara il valore predefinito di trigger: per saperlo non indovinare, leggi il messaggio init della sessione, che riporta le impostazioni effettive.

Il backend "remote" si collega a un App Server che gestisci tu, con url e un authToken letto dall'ambiente; la guida all'avvio dell'App Server precisa che per un indirizzo diverso dal loopback l'autenticazione WebSocket va configurata (per esempio con --ws-auth capability-token e un file con il token). Con "local" l'SDK avvia l'App Server come sottoprocesso sulla stessa macchina. await using chiude la sessione da solo; per questo il tsconfig di prova include la libreria ESNext.Disposable. Il ciclo for await riceve i messaggi in streaming e qui stampa solo quelli dell'assistente.

Self-hosting: che cosa resta tuo e che cosa no

La pagina «Self-hosting» della documentazione distingue due forme: il runtime locale, in cui la CLI esegue gli agenti nel suo processo senza bisogno di un account Letta, e l'App Server, che ospita gli agenti su una macchina sempre accesa e li espone all'SDK. I comandi sono pochi e li riporto come li scrive la documentazione, senza averli eseguiti: avviarli significa aprire una porta e collegare un provider.

Runtime locale con Ollama e App Server (comandi dalla documentazione, non eseguiti)
npm install -g @letta-ai/letta-code
letta --backend local connect ollama
letta server --backend local --listen ws://127.0.0.1:4500

La prima riga installa la CLI (serve Node.js 22.19 o successivo). La seconda collega un Ollama in ascolto sulla stessa macchina come provider di modelli, ed è la scelta che tiene anche l'inferenza in locale. La terza avvia l'App Server legato a 127.0.0.1: ascolta soltanto sulla macchina stessa, e per un indirizzo diverso dal loopback la documentazione chiede di configurare l'autenticazione (e mettere TLS davanti è buona prassi, non un requisito che ho verificato). La documentazione ricorda che la scelta del modello è separata: se colleghi un provider remoto, i prompt vanno a quel provider.

Le avvertenze della stessa pagina, tradotte in obblighi per chi gestisce il servizio:

  • gli strumenti integrati girano dove gira l'agente, quindi sulla macchina dell'App Server: anche i permessi di file e comandi sono quelli di quella macchina;
  • gli agenti self-hosted non sono raggiungibili da chat.letta.com;
  • non hanno un backup automatico: copiare il repository git della memoria è compito tuo.

Il primo punto è il più delicato: un agente che esegue comandi sulla tua macchina ha i permessi del suo processo, e va trattato come ogni servizio con accesso alla shell, con un utente dedicato e senza privilegi. Il terzo è quello che si dimentica: in locale la memoria dell'agente è un repository su disco, quindi il backup è quello di una cartella, e va programmato prima del primo giorno di uso.

Quando la memoria persistente fa danni

Una memoria che dura è un archivio di errori che durano. Se l'agente scrive un fatto sbagliato, o un testo preso da un documento ostile, quel fatto rientra nel prompt di ogni conversazione futura: è lo stesso problema dell'iniezione di prompt, ma con effetto ritardato. Questo ragionamento è mio, non una misura: la difesa è trattare i file di memoria come input non fidato, rileggerli a campione e limitare gli strumenti che l'agente può usare dopo averli letti.

Il versionamento ha un lato meno ovvio. Poiché ogni modifica è un commit, cancellare un dato personale dal file non lo cancella dalla storia: se devi onorare una richiesta di cancellazione, devi riscrivere la storia del repository, o non mettere affatto in memoria ciò che non potresti più togliere. Anche i costi crescono in modo silenzioso, perché i file alla radice entrano in ogni prompt; la documentazione offre il comando /doctor (dal CLI) proprio per controllare duplicati e uso di token nel prompt di sistema.

C'è infine il rischio di dipendenza, e Letta lo mostra bene: l'API V1 su cui poggiavano i tutorial è stata ritirata. Se costruisci un prodotto, tieni l'SDK dietro una tua interfaccia sottile, fissa la versione (l'SDK è alla 0.8.86, sotto la 1.0: aspettati cambiamenti) e leggi il changelog prima di aggiornare. Un agente con memoria è la scelta giusta quando l'utente torna e deve essere riconosciuto; è sovradimensionato per una richiesta singola e senza storia.

Che cosa sai fare adesso

Sai spiegare perché un agente ha bisogno di una gerarchia di memoria e che cosa costa ciascun livello, e hai un modello eseguibile per ragionarci sopra. Sai riconoscere un tutorial costruito sul server V1 ritirato, scegliere tra cloud e locale prima del primo avvio e scrivere un agente con l'Agent SDK che il compilatore ha già controllato. Nel prossimo articolo la stessa domanda, che cosa ricorda l'agente e dove vive lo stato, riceve la risposta di un framework TypeScript; il confronto tra i tre orchestratori e l'analisi dei costi vengono dopo, e l'articolo sul debugging e le tracce chiude la serie con il modo di vedere che cosa fa davvero un agente.

Domande frequenti

Letta è ancora open source?

Sì: il repository letta-ai/letta e letta-ai/letta-code sono pubblicati con licenza Apache-2.0 secondo l'API di GitHub, e anche l'Agent SDK su npm dichiara Apache-2.0. Letta Cloud, invece, è un servizio ospitato e non un software da scaricare, ed è il predefinito della CLI.

Posso usare Letta senza account e senza cloud?

Sì, con il backend locale: la documentazione di self-hosting dice che con il runtime locale lo stato dell'agente (messaggi, memoria, collegamenti ai provider) resta sul dispositivo e non serve un account Letta. Se colleghi un provider di modelli remoto, però, i prompt arrivano a quel provider.

Letta e MemGPT sono la stessa cosa?

MemGPT è il nome del progetto di ricerca e del paper del 2023; Letta è il nome attuale del progetto e dell'azienda, e il README lo indica come «f.k.a. MemGPT». Il pacchetto PyPI pymemgpt si ferma alla 0.3.25 del settembre 2024, mentre letta è aggiornato a ottobre 2026.

Fonti

Le cifre di versione (letta 0.34.12, @letta-ai/letta-code 0.34.56, @letta-ai/letta-agent-sdk 0.8.86) vengono dai registri PyPI e npm, interrogati il 2026-11-13 con npm view e con l'API JSON di PyPI. Il modello in Python è stato eseguito con python3 -I due volte, con la stessa uscita; il listato TypeScript è stato compilato con tsc in modalità strict ed è uno schema da adattare: nessun server è stato avviato e nessun modello è stato chiamato.

Prova Questi Strumenti

Strumenti gratuiti correlati a questo argomento.

Commenti

Caricamento commenti...

Accedi per commentare

Articoli e strumenti nuovi anche su Telegram

Il canale Telegram segnala gli articoli e gli strumenti nuovi del sito.

Ti è piaciuto questo articolo?

Esplora altri contenuti sul blog o scopri i miei progetti