AIREITERPuò bastare un’ora per ricostruire perché è stato modificato un parser, salvo poi perdere tutto quel ragionamento quando il task successivo parte con un altro agente. Funes indicizza localmente le sessioni degli agenti, restituisce le prove originali con la relativa provenienza e permette di condividere la stessa memoria tra Claude Code, Codex, pi e Hermes. Il limite da tenere presente è uno solo, ma importante: Funes recupera la cronologia; spetta comunque all’agente decidere se una vecchia scelta sia ancora applicabile.
Questa guida mostra una configurazione pratica Claude Code → Codex, l’uso della memoria solo locale, la sincronizzazione opzionale con Hugging Face, il collegamento a client MCP generici e i controlli necessari per mantenere affidabile la cronologia recuperata.
Definisci il perimetro della memoria prima di installare
Se stai valutando Funes o lavori con repository sensibili, parti dalla memoria locale. Collega un dataset Hugging Face solo quando ti serve ritrovare la stessa cronologia su un’altra macchina o condividerla con un team.
| Modalità | Dove viene salvata | Primo utilizzo ideale | Attenzione principale |
|---|---|---|---|
local | Dataset Lance locale | Un solo sviluppatore e una sola macchina | La memoria non segue automaticamente l’utente su un altro host |
<org>/<repo> | Dati Lance locali più un repository Dataset su Hugging Face | Passare da un agente o da una macchina all’altra | Le tracce delle sessioni possono contenere codice, prompt, percorsi o credenziali sensibili |
La policy di sicurezza di Funes specifica che parsing, suddivisione in chunk, embedding e reranking avvengono localmente per impostazione predefinita. I dati escono dalla macchina tramite funes push oppure attraverso un’integrazione con memoria condivisa che pubblica i dati alla fine della sessione. Una memoria collegata a Hub è un repository di dataset: controllane quindi la visibilità prima del primo push.
Per il primo test, usa local. Potrai modificare in seguito il collegamento eseguendo di nuovo funes add <agent> <memory>.
Installa Funes e crea il primo indice
Il repository ufficiale di Funes mette a disposizione uno script shell che rileva la piattaforma, scarica un binario associato a un tag, verifica il checksum della release e colloca l’eseguibile nel PATH, per impostazione predefinita in ~/.local/bin:
curl -fsSL https://huggingface.co/buckets/huggingface/funes/resolve/install.sh | shSe funes non viene trovato subito, apri una nuova shell e verifica l’installazione:
funes statusIl repository elenca binari associati a tag per Linux x86_64, Linux aarch64 e macOS Apple Silicon. Se la tua piattaforma non è tra quelle indicate, segui le istruzioni del progetto per la compilazione dai sorgenti invece di dare per scontato che lo script includa anche il tuo sistema.
Il bootstrap in cinque minuti
Esegui il comando nella directory in cui sono già presenti le sessioni dell’agente che vuoi conservare:
funes add claudeCon Claude Code, il comando può creare il primo indice, registrare gli strumenti di lettura, installare l’automazione d’integrazione e continuare a indicizzare i turni completati. Dopo la conferma, il primo passaggio è orientato al testo e la documentazione indica una durata di circa un minuto. Prima vengono analizzati prosa e ragionamento, mentre gli output voluminosi degli strumenti vengono lasciati in secondo piano. (Documentazione di configurazione di Funes)
Controlla quindi lo stato:
funes statusSe devi creare o aggiornare manualmente l’indice delle sessioni Claude, usa:
funes index --harness claudeSenza specificare un percorso, funes index può cercare le posizioni standard delle sessioni di Claude, Codex, pi e Hermes, tra cui ~/.claude/projects e ~/.codex/sessions. Con --harness claude, la scansione viene limitata a Claude Code. La guida all’indicizzazione documenta inoltre un budget di circa 60 secondi, orientato al testo, per gli aggiornamenti senza percorso; le sessioni più vecchie e i risultati molto grandi degli strumenti potrebbero richiedere passaggi successivi.
L’indicizzazione di Funes è incrementale: rieseguendola, i chunk già scritti non vengono sottoposti di nuovo a embedding. I percorsi espliciti dei transcript e i repository di tracce su Hub vengono invece indicizzati interamente, senza applicare il budget previsto per le scansioni senza percorso. (Dettagli sull’indicizzazione)
Collega Funes a Claude Code
Per usare una memoria locale con Claude Code, esegui:
funes add claude local
funes statusPuoi omettere local, perché è il valore predefinito. Se nel terminale è disponibile un token HF, Funes potrebbe proporti di configurare un repository di proprietà dell’utente, <user>/funes-memory; per un test solo locale, rifiuta la proposta.
L’integrazione con Claude utilizza un plugin basato esclusivamente sugli hook e una registrazione MCP separata. Funes non modifica il file settings.json di Claude Code: l’automazione indicizza i turni completati, mentre la configurazione della memoria condivisa aggiunge la pubblicazione alla fine delle sessioni. (Comportamento dell’automazione)
Apri Claude Code e verifica una decisione storica nota, invece di considerare riuscita la configurazione solo perché l’installazione è andata a buon fine:
Find the previous decision about the streaming parser. Use Funes recall if the repository history does not explain it, and cite the session you used.Un buon risultato deve rimandare a un passaggio precedente, indicare la sessione di provenienza e distinguere un vecchio esperimento dallo stato attuale del repository.
Per disattivare l’integrazione senza eliminare i dati salvati, esegui:
funes remove claudeLa documentazione sulla rimozione specifica che il comando elimina il collegamento di Funes, ma conserva la memoria locale, i transcript originali, le cache e la memoria pubblicata.
Collega la stessa memoria a Codex
Quando Claude Code funziona correttamente, aggiungi Codex alla stessa memoria locale:
funes add codex local
funes statusPer usare una memoria condivisa basata su Hub, indica lo stesso identificativo di repository per entrambi gli agenti:
funes add claude <org>/<repo>
funes add codex <org>/<repo>Codex prevede un passaggio di autorizzazione facile da trascurare. Funes scrive i propri hook in ~/.codex/hooks.json; dentro Codex, esegui /hooks, controlla le voci di Funes e autorizzale. Finché gli hook non vengono considerati affidabili, Codex li ignora: di conseguenza i nuovi turni non vengono indicizzati e nessuna memoria viene pubblicata. Il flusso documentato per il collegamento della memoria richiede Codex 0.151.0. (Requisiti dell’automazione di Codex)
Prova davvero il passaggio di consegne tra agenti
Scegli una decisione distintiva presente in una sessione ma non nell’altra:
- In Claude Code, trova la decisione sul parser e annota un termine caratteristico della discussione.
- Chiudi la sessione, così l’indicizzazione e l’automazione di fine sessione possono essere eseguite.
- In Codex, chiedi informazioni su quel termine e domandagli di recuperare il ragionamento precedente.
- Verifica che la risposta indichi Claude come harness di origine e rimandi alla sessione o al turno originale.
Puoi controllare direttamente le prove dal terminale:
funes recall "why did we switch away from the streaming parser"recall restituisce passaggi classificati per rilevanza, non un riassunto generato. Ogni risultato include le informazioni sulla fonte e un comando get generato automaticamente; copialo quando ti serve recuperare i turni circostanti.
Se Codex non restituisce nulla, controlla la versione, lo stato di autorizzazione in /hooks, l’output di funes status e verifica se la sessione Claude è precedente all’integrazione. Poi riprova usando un termine distintivo della discussione originale.
Collega pi, Hermes o un altro client MCP
Oltre a Claude Code e Codex, Funes supporta direttamente pi e Hermes. Pi utilizza gli eventi delle estensioni; Hermes usa hook shell e la sua indicizzazione turno per turno è documentata come beta. (Dettagli sugli agenti supportati)
Per un client compatibile con MCP diverso da questi quattro, avvia Funes come server stdio locale:
{
"mcpServers": {
"funes": {
"command": "funes",
"args": ["mcp"]
}
}
}Per collegare il server a una memoria condivisa, aggiungi il repository dopo mcp:
{
"mcpServers": {
"funes": {
"command": "funes",
"args": ["mcp", "<org>/<repo>"]
}
}
}La documentazione MCP espone recall, get e status. funes mcp è in sola lettura: non indicizza le sessioni e non pubblica dati. Per queste operazioni usa funes index, funes push oppure un’integrazione supportata da funes add.
Una memoria specificata nella singola chiamata MCP ha la precedenza sul collegamento definito a livello di server. Se non ne viene indicata nessuna, Funes usa la memoria locale.
Usa recall senza rinunciare alle prove
Funes mette a disposizione tre flussi distinti:
| Comando | Output | Quando usarlo |
|---|---|---|
funes recall "…" | Passaggi originali ordinati per rilevanza e corredati dalla provenienza | Quando vuoi esaminare le prove |
funes get … | Il turno citato e il contesto circostante | Quando un risultato è pertinente ma incompleto |
funes ask <agent> "…" | Una singola risposta in linguaggio naturale, basata sulle fonti | Quando vuoi una risposta rapida da Claude o Codex senza installare un’integrazione |
Le impostazioni predefinite documentate di recall sono 8 risultati, un insieme candidato di 30 risultati sottoposto a reranking, un dimezzamento della rilevanza temporale ogni 30 giorni e 1 chunk adiacente. (Flag e valori predefiniti di recall)
Un ciclo di debug affidabile è questo:
- Esegui
funes recallusando l’errore, il nome del componente o la frase che descrive la decisione. - Segui il comando
getgenerato per recuperare il turno completo. - Confronta la decisione recuperata con il branch attuale.
- Applica la modifica o esegui l’esperimento.
- Esegui di nuovo recall usando il risultato ottenuto, così la sessione successiva potrà ritrovarlo.
funes ask è più limitato. Prima esegue il recupero, poi invia i passaggi selezionati e la domanda a Claude o Codex per ottenere una risposta. L’agente figlio non riceve strumenti, stdin o server MCP e non può riprovare il recupero se il primo abbinamento è scarso. Anche se il recupero avviene localmente, la domanda e i passaggi recuperati vengono inviati al provider configurato per l’agente selezionato. Per questo la documentazione di ask consiglia funes recall per i contenuti che non invieresti a quel provider.
Mantieni la memoria affidabile e sotto controllo
Funes conserva i passaggi originali e la loro provenienza, ma non può stabilire se ogni workaround storico sia ancora valido.
“Gli agenti di coding diventano molto meno imprevedibili quando la memoria è un’infrastruttura noiosa: indice locale, provenienza esatta, privata per impostazione predefinita.” — @TheArtemisHunts su X
Una checklist essenziale per la produzione
| Situazione | Controllo | Azione |
|---|---|---|
| Codex non recupera nulla | Autorizzazione degli hook e versione | Esegui /hooks, autorizza le voci di Funes e verifica che Codex sia 0.151.0 |
| Mancano le sessioni più vecchie | Ambito e livello dell’indicizzazione | Esegui funes index --harness claude oppure --harness codex; lascia che i passaggi successivi completino gli output voluminosi |
| Un push remoto viene bloccato | TruffleHog e ambito del token | Installa TruffleHog o imposta FUNES_TRUFFLEHOG; usa un token di scrittura a granularità fine solo sulle macchine che eseguono il push |
| Un risultato contiene un segreto | Stato della pulizia locale | Esegui funes scrub, poi ripeti il push; i transcript originali non vengono modificati |
| Una memoria remota è condivisa | Visibilità e affidabilità dei contenuti | Mantieni il dataset privato, a meno che la condivisione pubblica non sia intenzionale, e tratta il testo recuperato da terze parti come input non affidabile per l’agente |
| L’ultima sessione non è su Hub | Tempistica della pubblicazione | Esegui funes push <org>/<repo> prima di dismettere la macchina |
Funes oscura le credenziali durante l’indicizzazione ed esegue una scansione TruffleHog fail-closed prima della pubblicazione. La documentazione sul push specifica che l’assenza dello scanner blocca la pubblicazione; se una credenziale attiva arriva in un dataset remoto, ruotala immediatamente, perché ripulire un commit successivo non può cancellare la cronologia del repository.
Usa token Hugging Face con il minimo privilegio necessario: ambito di scrittura sulle macchine che pubblicano e sola lettura per i membri del team o gli host che devono solo eseguire recall. Due macchine che pubblicano sulla stessa memoria remota possono inoltre entrare in conflitto; la documentazione sull’automazione non garantisce la serializzazione tra macchine diverse.
La scelta più pratica
Parti da uno di questi scenari, invece di installare tutte le integrazioni contemporaneamente:
| Flusso di lavoro | Configurazione consigliata | Motivo |
|---|---|---|
| Un solo sviluppatore che valuta la memoria persistente | funes add claude local | Minore rischio di condivisione dei dati e rollback più semplice |
| Claude Code per la pianificazione, Codex per l’implementazione o la revisione | Collega entrambi alla stessa memoria local | Conserva il ragionamento tra gli agenti sullo stesso host |
| Agenti su più macchine | Collega entrambi alla stessa memoria privata <org>/<repo> | Permette alla memoria di seguire lo sviluppatore tramite il dataset Hub |
| Cronologia di progetto condivisa dal team | Dataset privato più token di sola lettura per chi consulta | Separa l’autorità di pubblicazione dall’accesso in lettura |
| Agente MCP non supportato direttamente | funes mcp [memory] | Aggiunge l’accesso in lettura lasciando esplicita l’indicizzazione |
| Materiale sorgente sensibile | Memoria locale più recall | Evita la pubblicazione remota e l’invio una tantum al provider |
FAQ sulla memoria per agenti di coding Funes
Funes è un sistema locale?
Per impostazione predefinita, Funes elabora e conserva la memoria localmente. È local-first, non automaticamente solo locale: il push, gli hook per la memoria condivisa e ask possono inviare dati fuori dal processo locale.
Funes funziona con Claude Code e Codex?
Sì. funes add supporta Claude Code e Codex, oltre a pi e Hermes. Il collegamento della memoria a Codex richiede la versione 0.151.0 e hook autorizzati.
Funes indicizza automaticamente le sessioni?
Dopo funes add, le integrazioni supportate installano l’automazione per l’indicizzazione turno per turno. Il bootstrap iniziale è soggetto a un limite, quindi le sessioni più vecchie e gli output voluminosi degli strumenti potrebbero richiedere passaggi successivi.
Come condivido la stessa memoria tra Claude Code e Codex?
Usa lo stesso argomento <org>/<repo> sia per funes add claude sia per funes add codex. Funes mantiene localmente l’indice di lavoro e pubblica il dataset condiviso alla fine delle sessioni.
Cosa succede se Funes recupera una decisione superata?
Esaminala con funes recall, approfondiscila usando il comando get generato e confrontala con il branch attuale prima di agire. Se il primo recupero non è corretto, riformula la query.
funes ask mantiene i dati sulla mia macchina?
Il recupero e il reranking sono locali, ma ask invia la domanda e i passaggi recuperati al provider Claude o Codex configurato. Per le prove sensibili, usa recall.
Posso rimuovere Funes senza eliminare la memoria?
Sì. funes remove claude, funes remove codex, funes remove pi e funes remove hermes rimuovono il collegamento all’integrazione, conservando la memoria indicizzata e i transcript originali.