Dai ai tuoi agenti di codifica una memoria che possiedi veramente

Il problema della memoria negli agenti di codifica

Chi lavora con agenti di codifica sa bene un problema ricorrente: ogni volta che si avvia un nuovo agente su una macchina diversa, si parte da zero. Il ragionamento dalla "scorsa martedì" scompare quando la sessione termina. Ogni nuovo agente, su ogni nuovo host, inizia come uno straniero nel vostro progetto, senza memoria di cosa sia stato deciso in precedenza, quale approccio sia stato provato senza successo, o perché una particolare soluzione sia stata scartata.

Questo fenomeno è stato affrontato in un articolo precedente intitolato "Software Forgets: Agent Traces Are the Memory", che ha mosso un'osservazione cruciale: gli agenti di codifica già producono il registro che andiamo perdendo. Mentre cercano una codebase, provano approcci diversi, incontrano errori, leggono documentazione e cambiano direzione, lasciano dietro di sé un resoconto denso che non riguarda solo cosa è cambiato, ma soprattutto perché.

Tuttavia, la diagnosi è corretta solo a metà: le tracce sono solo memoria potenziale. I log di sessione di un agente rimangono semplicemente un archivio. Non è possibile usare grep per rispondere a domande come "perché abbiamo abbandonato il parser in streaming?" attraverso diecimila turni di conversazione. Per consentire a un agente di utilizzare effettivamente quelle tracce durante il lavoro, è necessario indicizzazione, recupero, ranking e tracciamento preciso della provenienza. È qui che entra in gioco Funes.

Cosa è Funes e come funziona

Funes è uno strato di memoria durevole per i vostri agenti (Claude Code, Codex, pi e Hermes). È costruito dalle sessioni già presenti sulla vostra macchina e funziona localmente, diventando parte del flusso di lavoro normale dell'agente con un singolo comando. Quando lo desiderate, può anche trasferirsi a un dataset Hugging Face che possedete, privato per impostazione predefinita.

Funes è un singolo binario. Il suo backend di inferenza predefinito non ha dipendenze di runtime ML, e l'embedding e il reranking avvengono sulla vostra macchina. L'installazione è straordinariamente semplice: con un unico comando `add`, il sistema costruisce il primo indice, fornisce all'agente gli strumenti `recall` e `get`, e installa l'automazione che indicizza ogni turno completato.

Il processo di indicizzazione incrementale

L'indicizzazione è incrementale: le nuove esecuzioni aggiungono nuovi turni anziché incorporare di nuovo l'intera cronologia. I contenuti più vecchi e più profondi possono essere completati in passaggi limitati. Una volta che Funes è stato aggiunto, il ricordo avviene all'interno della conversazione. L'agente raggiunge la sua memoria autonomamente e nomina la sessione dietro la sua risposta.

Lo strumento `recall` restituisce il testo originale, non un riassunto, e mostra esattamente da dove proviene (l'agente, il timestamp, la sessione e il turno). Ogni risultato include un comando `get` che apre il turno completo e il suo contesto circostante.

L'architettura tecnica di Funes

Sotto il cofano, una pipeline deterministica analizza ogni traccia supportata nella stessa forma turno-blocco, la divide in chunk, la incorpora con un modello locale fisso, e la scrive in un dataset locale Lance. Una query combina ricerca vettoriale e BM25, fonde i loro ranking, riclassifica i candidati con un cross-encoder, riappesa in base alla recency, e allega chunk adiacenti.

Questo design fornisce a Funes tre proprietà importanti:

• Risolve il problema dell'agente come straniero su una singola macchina: La memoria locale funziona perfettamente per chi lavora su un unico dispositivo.
• Funziona anche su più macchine: La memoria diventa ancora più utile quando il prossimo agente è in esecuzione da qualche altra parte.
• Mantiene il controllo e la privacy: La memoria segue il vostro lavoro senza dipendere da servizi esterni.

Memoria distribuita e sincronizzazione cross-device

Per rendere una memoria seguire il vostro lavoro da una macchina all'altra, si associa una memoria quando si aggiunge Funes a un agente. Questo comando pubblica la vostra memoria attuale su Hugging Face. Funes mantiene quindi la sua attualità, indicizzando ogni turno localmente e pubblicando ai confini della sessione. L'agente richiama da essa durante tutto il lavoro. Eseguendo lo stesso comando su un'altra macchina, la memoria vi segue.

Sotto il cofano, la memoria locale è un dataset Lance, e la memoria condivisa è un dataset Hugging Face (privato per impostazione predefinita) che voi possedete. Prima che qualcosa raggiunga l'Hub, le credenziali sono già state rimosse durante l'indicizzazione. La pubblicazione quindi esegue nuovamente la scansione di ogni chunk e trattiene qualsiasi cosa che sembri ancora un segreto. Lo scanner dietro questo processo è documentato in SECURITY.md, incluso cosa copre e cosa no.

Quando un agente legge una memoria remota, Funes memorizza nella cache i file del dataset localmente, così le query calde tornano alla velocità locale. L'Hub fornisce la proprietà, il controllo dell'accesso, il versioning e la distribuzione che già fornisce per altri dataset. La vostra memoria non diventa un account in un servizio di memoria separato, e non lo prendete in affitto attraverso un'API.

Interfacce utente: recall e ask

`recall` è modellato per gli agenti. Quando desiderate porre una domanda a una memoria voi stessi, usate `ask`. Legge la vostra memoria locale per impostazione predefinita, ma potete anche indicarla a una memoria condivisa.

Gli sviluppatori hanno pubblicato una memoria dello sviluppo di Funes stesso, così potete chiedere perché Funes funziona nel modo in cui funziona senza creare una memoria vostra. `funes ask` è il fratello di sola lettura e una singola domanda di `funes add`. Richiama i passaggi, li consegna a un agente di codifica e restituisce una risposta fondata che nomina le sue fonti. Non installa un'integrazione né modifica la configurazione persistente dell'agente.

Un elemento importante: una mancanza di recupero non viene coperta. Se i passaggi non supportano una risposta, l'agente lo dice chiaramente. Potete riformulare la domanda o aggiungere Funes all'agente in modo che possa cercare la memoria iterativamente durante il lavoro normale.

Memoria condivisa e interoperabilità tra agenti

Una memoria condivisa non è legata all'agente o al modello che l'ha creata. Potete iniziare un compito in Claude Code, continuarlo in Codex la prossima settimana, e il secondo agente può richiamare il ragionamento del primo agente. Usate pi con un modello locale o uno servito attraverso il router Hugging Face, quindi tornate a Claude. Claude prende una decisione; un hook l'indicizza; Codex la richiama in un'altra sessione.

Gli hit più vecchi nella demo sono registrazioni precedenti dello stesso esperimento: una memoria di sola aggiunta ha ricordato anche le prove. Questo rappresenta un paradigma completamente nuovo nel modo in cui gli agenti possono collaborare e costruire sui progressi reciproci nel tempo.

Memoria aperta e scopribilità

Le memorie pubblicate contengono una scheda dataset e il tag Funes, rendendole riconoscibili e scopribili sull'Hub. L'Hub ospita già pesi aperti e dataset. Funes aggiunge memoria di lavoro aperta. Contiene le decisioni, gli approcci falliti e il ragionamento dietro un progetto, interrogabile da un altro agente e tracciabile alle sessioni che le hanno prodotte.

Questo crea un ecosistema completamente nuovo dove il "come" e il "perché" di un progetto di codifica rimangono disponibili e ricercabili, non sepolti in una storia di chat dimenticata.

Prestazioni e confronto con altri approcci

Un'indagine lunga gonfia una sessione fino al punto che ogni turno costa più da mantenere in contesto che da fare il lavoro. Le risposte abituali sono lasciar compattare all'agente e continuare, oppure scrivere un handoff e ricominciare da capo. Recall è una terza opzione, e gli sviluppatori l'hanno misurata contro le altre due nel benchmark "handoff-vs-recall".

Il benchmark testa due compiti la cui risposta non può essere ricostruita senza la conoscenza precedente della sessione. La compattazione è quello che la maggior parte degli agenti fa per impostazione predefinita, ed era l'unica delle tre il cui risultato si divideva: arrivava su un compito e non arrivava mai sull'altro. Dove falliva, il suo riassunto aveva appiattito i risultati che importavano. Recall restituisce i passaggi stessi, così un risultato non deve sopravvivere al riassunto.

Recall era la più economica delle tre su entrambi i compiti, 8 volte più economica di un handoff scritto su uno e 4 volte sull'altro. Il segmento più leggero di ogni barra è l'addebito una tantum per la preparazione del canale, l'handoff o la compattazione, pagato prima che la prima domanda venga posta e contato una volta. Una croce segna un canale che non arriva mai, e quindi non ha costo per il successo.

Valutazione empirica di Funes

Gli sviluppatori hanno eseguito Funes 1.3.0 su una macchina con 19.195 sessioni di agenti di codifica già su disco (LongMemEval inserito nei veri layout ~/.claude e ~/.codex), 100 domande la cui risposta si trova esattamente in una sessione, valutate dal fatto che quella sessione torni.

L'indice completo ha richiesto 2 ore e 3 minuti su un laptop M4 pro (308k chunk), con 6.3 secondi per query. Con i parametri predefiniti: hit@1 9/100, hit@5 39, found@50 71. Con --half-life 0: 19/46/71 — la mezza vita di 30 giorni dimezza il ranking 1 sulla cronologia più vecchia di un mese, che è la maggior parte di ciò che si trova su un disco reale; vale la pena menzionarlo nella documentazione. Una volta spenta la recency, lo stack vettore+rerank è chiaramente il miglior ranker nella tabella al rank cinque. Il primo passaggio documentato di un minuto lascia 218 delle 19k sessioni indicizzate (0/100 risposte), quindi il framing "circa un minuto" è davvero "circa un minuto fino all'inizio del lavoro di embedding".

Per il confronto sullo stesso corpus, deja-vu (BM25 semplice su file di 24 agenti) indicizza in 29 secondi e risponde in 24ms a hit@1 18/100, hit@5 35. Lo strumento dimostra come Funes brilli quando le informazioni sono effettivamente difficili da trovare. LongMemEval non ha davvero bisogno della ricerca semantica: BM25 già fornisce lo stesso rapporto, quindi per questo caso d'uso è praticamente previsto che non valga la pena pagare il costo della valutazione degli embedding (questo costo extra che vedete nel tempo di indicizzazione e richiamo).

Caratteristiche di sicurezza e privacy

La sicurezza è integrata nel design di Funes. Prima che qualcosa raggiunga l'Hub, le credenziali sono già state rimosse durante l'indicizzazione. La pubblicazione successiva esegue nuovamente la scansione di ogni chunk e trattiene qualsiasi cosa che sembri ancora un segreto. Lo scanner è documentato completamente in SECURITY.md, incluso ciò che copre e ciò che non copre.

Questo approccio multi-strato garantisce che i vostri dati sensibili non vengano accidentalmente esposti, mentre consente comunque la sincronizzazione utile della memoria tra dispositivi e agenti.

Come iniziare con Funes

Funes vive su github.com/huggingface/funes, un comando lontano dal trasformare il record che i vostri agenti hanno già scritto in una memoria che il prossimo agente può leggere, su qualunque macchina vi troviate.

Funes inventa poco di tutto questo. Si basa su modelli di embedding open-source abbastanza buoni per funzionare localmente, sui dataset di sola aggiunta di Lance con scritti incrementali economici, e sulla memorizzazione nella cache e sulla deduplicazione del contenuto dell'Hub per i dataset. Il lavoro è nel farli rientrare in una memoria che un agente può effettivamente usare.

Funes è anche open source. Potete aprire un issue per qualsiasi cosa, da un intoppo di installazione a un ricordo che ha mancato, o a un agente che vorreste fosse supportato.

Conclusione: ripensare la memoria degli agenti

L'intuizione di Jorge Luis Borges in "Funes il memorioso" — "pensare è dimenticare le differenze, generalizzare, fare astrazioni" — cattura un aspetto importante del problema che Funes risolve. Mentre la compattazione e il riassunto sono il modo predefinito in cui gli agenti gestiscono il contesto lungo, il ricordo degli specifici passaggi originali, delle prove fallite e del ragionamento preciso dietro le decisioni spesso è più prezioso.

Funes trasforma il record che gli agenti producono già — le tracce della loro ricerca, dei loro errori e delle loro decisioni — in una memoria reale che persistono tra le sessioni e le macchine. Non è semplicemente un archivio di log. È un sistema