Il tuo prossimo coding agent non dovrebbe partire da zero

La cosa più costosa quando cambi coding agent non è l'abbonamento. È l'ora che passi a spiegare di nuovo il progetto.

Quali file contano, quale approccio ha già fallito, perché i test sono strutturati così, cosa sta facendo il branch a metà. Claude Code non ne sa niente. Nemmeno Codex, Cursor o Gemini CLI. Ognuno parte con una context window vuota e una cortese disponibilità ad aiutare.

ai-memory è un binario Rust che prova a risolvere questo, e le sue scelte di design sono più interessanti della lista di feature.

Una memoria, tanti harness

La promessa è che una ventina abbondante di harness per agenti — Claude Code, Codex, Cursor, Gemini CLI, OpenCode, Grok, Devin, Kimi, Kiro e gli altri — leggano da un unico archivio di memoria condiviso. Lavori in uno, ti fermi a metà task, ne apri un altro nella stessa directory, e quello riprende da dove aveva lasciato il primo.

Il meccanismo è un handoff tipizzato. Non un riassunto che l'agente genera sperando che sia accurato, ma un record esplicito con un owner che può essere preso in carico una sola volta. È proprio quel vincolo la parte utile: due agenti non possono credere entrambi di stare continuando il lavoro, e un handoff abbandonato resta visibile invece di perdersi in silenzio.

C'è anche un livello che attraversa i progetti. Le tue preferenze di lavoro — package manager, come è organizzata la suite di test, come ti piace strutturare i moduli — ti seguono nei nuovi repository, così un checkout fresco non riparte da zero su quelle cose che valgono ovunque.

Markdown come fonte di verità

Ecco la decisione di design su cui vale la pena discutere.

I sistemi di memoria per gli agenti di solito significano embedding. Spezzetti la cronologia, la embeddi, la metti in un vector database, recuperi per similarità. Funziona, e ha tre problemi: non puoi leggerla, non puoi farne il diff, e il retrieval è così opaco che quando restituisce la cosa sbagliata non hai idea del perché.

ai-memory inverte tutto questo. La fonte di verità è un normale wiki Markdown, versionato con git. L'indice SQLite — full-text search, entità, embedding — è derivato e ricostruibile. Cancella il database e non perdi niente.

Quella singola scelta vale molto. Puoi fare grep sul wiki. Puoi aprirlo in Obsidian. Puoi correggere a mano una voce sbagliata. Puoi sincronizzarlo con rsync. Puoi leggere un diff e vedere che la comprensione dell'architettura da parte dell'agente è cambiata martedì. E non c'è nessun vector store in cui restare bloccati.

Significa anche che la memoria è verificabile in un modo che per i team conta. «Perché l'agente pensa che usiamo pnpm» è una domanda la cui risposta è un file.

Invecchiare senza cancellare

Il progetto descrive un sistema di invecchiamento della memoria: decadimento a livelli, ritenzione pesata sugli accessi, deduplicazione e segnalazione delle contraddizioni. Le note che non vengono usate scendono di priorità senza sparire, e le voci in conflitto vengono marcate invece di essere sovrascritte in silenzio.

Il dettaglio importante è che niente viene cancellato in modo definitivo. Le pagine vecchie restano in git e un comando di restore le riporta indietro. Visto quanto spesso la nota «obsoleta» di un agente si rivela l'unica traccia del perché è stata presa una decisione, è il default giusto.

C'è una funzione opzionale chiamata dreaming, che usa un LLM per riscrivere cluster di note fredde durante i tempi morti. È disattivata di default, e il README dice esplicitamente che non cancella mai il materiale di partenza. Default-off è la scelta corretta per qualsiasi cosa riscriva le tue note con un modello.

Il setup è davvero breve

Due comandi su Linux o macOS: un installer da curl a shell che verifica un checksum SHA-256, poi ai-memory setup, che crea la directory dei dati, avvia un servizio a livello utente e collega gli agenti che rileva. C'è l'equivalente PowerShell per Windows, più AUR, RPM, Nix, Docker e le voci nel marketplace dei plugin per Claude Code e Codex.

L'uso quotidiano ruota attorno a un wrapper: ai-memory run claude invece di claude. Al primo avvio installa gli hook e l'MCP server giusti e limita la sessione al progetto corrente. Da lì, ai-memory continue riprende l'ultimo checkout gestito, e resume --search auth sceglie per nome tra i tuoi workflow.

C'è un comando bootstrap che importa la cronologia esistente del progetto in un solo passaggio: è la differenza tra uno strumento che adotti e uno che continui a dire che prima o poi adotterai.

Le parti scomode

La cattura silenziosa tramite gli hook del ciclo di vita significa che il sistema registra prompt, chiamate agli strumenti e confini di sessione mentre lavori. È l'unico modo perché questo funzioni — non ti metterai a tenere un diario a mano — ma vale la pena dirlo chiaro. Un registro di ogni prompt che hai scritto su un codice di un cliente è materiale sensibile, e adesso sta in una directory versionata con git.

Le mitigazioni sono ragionevoli: di default ascolta solo su loopback, e il setup genera un bearer token scritto in un file leggibile solo dall'owner, non nella config del tuo agente. Però la quickstart di Docker gira senza autenticazione, e il README lo segnala come solo per uso locale. Se esponi quella porta senza un reverse proxy TLS, hai pubblicato la tua cronologia di lavoro.

La parte team è più matura di quanto mi aspettassi per un progetto così giovane: server condiviso, condivisione per progetto, handoff privati, auth multiutente, attribuzione e audit log, tutto fuori dal piano a pagamento. È quel set di feature a decidere se questo sopravvive al contatto con un'organizzazione di engineering vera.

Se non vuoi gestire un server

Obiezione legittima: «il mio server» è una frase che perde metà del pubblico all'istante.

Non deve per forza essere un server. Il comando di setup avvia un servizio a livello utente sulla stessa macchina, legato al loopback, e quella è la strada predefinita: niente homelab, niente VPS, niente DNS. Le funzioni cross-machine e per i team contano solo quando le vuoi, e sono separabili dal loop principale.

C'è anche una menu bar app per macOS costruita dal repo, e una vista web in sola lettura se preferisci sfogliare il wiki nel browser invece che nell'editor. La via Docker esiste soprattutto per chi ragiona già in container.

Quindi la scala di adozione onesta è: installalo sul portatile, lascia che catturi un progetto e guarda se il wiki che produce è una cosa che leggeresti davvero. Se lo è, il resto viene da sé. Se il wiki è rumore, nessuna feature per i team lo salverà.

Perché conta più di quanto sembri

Il mercato degli agenti oggi è organizzato attorno ai vendor, e i vendor non hanno alcun interesse a renderti facile andartene. Il tuo contesto è il lock-in. È per questo che il costo di cambiare sembra più alto di quanto suggerisca il prezzo dell'abbonamento.

Uno strumento che sta sotto a tutti loro e tiene la memoria in un formato che possiedi è un piccolo atto di standardizzazione dal lato utente. Che poi vinca proprio ai-memory è quasi irrilevante: la forma della soluzione — testo semplice portabile con un indice ricostruibile — è ovviamente quella giusta, ed è la forma con cui prima o poi dovrà competere ogni feature di memoria proprietaria.

Inoltre è un singolo binario e non serve nessuna API key per il loop principale. Cosa rara in una categoria dove «memoria» di solito significa «un altro abbonamento».