# Perché ho dato agli agenti un filesystem invece di un'altra API > Un flusso concreto di RAGFS mostra perché ho messo operazioni file, risultati e undo in un mount FUSE su Linux. Published: 2026-09-25 Canonical: https://gianlucamazza.it/it/blog/agent-filesystem Tags: FUSE, RAG, Rust, Linux ## Perché conta Un agente che lavora in una directory sa già elencare, leggere e scrivere percorsi. Dargli un'API separata per gestire gli stessi file introduce una seconda interfaccia. Volevo che anche il risultato di un'operazione, compresa la via per invertirla, fosse disponibile nel filesystem. [RAGFS](https://github.com/Venere-Labs/ragfs) è la mia implementazione FUSE per Linux. Monta una directory indicizzata ed espone una directory virtuale di controllo, `.ragfs`. I file sottostanti restano nella directory sorgente. La [scheda ragfs](/it/progetti#ragfs) indica il repository e la documentazione. ## Un'operazione, dalla richiesta all'undo Supponiamo che un agente decida di eliminare `docs/old.md`. Il quick start del README avvia il mount in foreground: ```plaintext mkdir ~/ragfs-mount ragfs mount ~/Documents ~/ragfs-mount --foreground ``` L'esempio di cancellazione usa poi quel mount. Scrive un percorso relativo nel file di controllo e legge il risultato JSON: ```plaintext echo "docs/old.md" > ~/ragfs-mount/.ragfs/.ops/.delete cat ~/ragfs-mount/.ragfs/.ops/.result ``` La cancellazione sposta il file nel cestino. Il risultato contiene un `undo_id`. L'agente può conservarlo e scriverlo nel file di sicurezza per invertire l'operazione: ```plaintext echo "" > ~/ragfs-mount/.ragfs/.safety/.undo ``` Il punto è la sequenza visibile: richiesta, lettura del risultato, conservazione dell'identificatore di undo e inversione se serve. È un contratto d'interfaccia, non la prova che un agente scelga sempre bene cosa cancellare. Devo comunque rivedere ciò che intende rimuovere. ## Perché la ricerca sta sullo stesso mount Lo stesso mount permette di cercare nella directory. RAGFS estrae il testo, lo divide in chunk, esegue `thenlper/gte-small` in locale tramite Candle e salva i vettori in LanceDB. Il modello viene scaricato al primo utilizzo. Le query di embedding successive usano quel modello locale e non chiamano un'API esterna di embedding. L'indice LanceDB resta fuori dalla directory sorgente. Il percorso di ricerca sta sul mount, accanto ai file. È un indice pratico, con limiti. Il chunking del codice riconosce firme di funzioni e classi con pattern. Il README descrive quella divisione come regex sulle firme, non come un AST tree-sitter. La ricerca cosine resta una scansione esatta finché non viene costruito un indice IVF-PQ. Il README colloca quella soglia da 256 chunk in su. Le ricerche L2 e Dot restano esatte. Non ho pubblicato benchmark sulla qualità del retrieval o sulla scala di questa configurazione, quindi non presento queste scelte implementative come prova di risposte migliori. ## Cosa non delegherei ancora Il README segna come stabili la CLI, il mount FUSE, le operazioni per agenti sotto `.ops/` e il livello di sicurezza sotto `.safety/`. Organize, dedupe e cleanup sono in beta: propongono un piano che richiede approvazione prima dell'esecuzione. Anche i binding Python e il server MCP sono in beta. L'interfaccia a file non elimina questo confine di approvazione. FUSE oggi funziona su Linux. Il [README del repository](https://github.com/Venere-Labs/ragfs#feature-status) indica lo stato di ogni funzione, i requisiti di installazione e gli estrattori supportati. Lo verificherei prima di adottare RAGFS per un nuovo corpus: questo articolo spiega una scelta d'interfaccia, non garantisce la maturità del prodotto. ## Dove entra il retrieval L'ordine di diagnosi che uso quando una pipeline RAG funziona male sta in [RAG in produzione](/it/blog/rag-systems-production): misurare, poi esaminare chunking e ranking prima di cambiare modello di embedding. RAGFS dà all'agente un modo per lavorare sul corpus. Non dimostra che i risultati del retrieval siano buoni senza una valutazione. ## FAQ ### Come posso annullare una cancellazione eseguita dall'agente? Scrivo il percorso relativo nel file `.ragfs/.ops/.delete` e leggo il risultato JSON da `.ragfs/.ops/.result`. La cancellazione sposta il file nel cestino e restituisce un `undo_id`; per invertirla, scrivo quell'identificatore in `.ragfs/.safety/.undo`. ### La ricerca RAGFS invia embedding a un'API esterna? No. Estraggo il testo, lo divido in chunk ed eseguo `thenlper/gte-small` localmente tramite Candle. Il modello viene scaricato al primo utilizzo e le query successive usano quel modello locale; i vettori sono salvati in LanceDB fuori dalla directory sorgente. ### Quali limiti ha il chunking e la ricerca in RAGFS? Uso il pattern matching per le firme di funzioni e classi nel codice, non un AST tree-sitter. La ricerca cosine è una scansione esatta finché non viene costruito un indice IVF-PQ; il README indica che costruisce un indice IVF-PQ da 256 chunk in su. Non ho pubblicato benchmark sulla qualità del retrieval o sulla scala. ### Quali funzioni richiedono ancora approvazione? Organize, dedupe e cleanup sono in beta e propongono un piano che richiede approvazione prima dell'esecuzione. Anche i binding Python e il server MCP sono in beta. L'interfaccia a file non rimuove questo confine di approvazione. ### Su quali sistemi funziona oggi il mount FUSE? Oggi FUSE funziona su Linux. Prima di adottarlo per un nuovo corpus, verificherei nel README del repository lo stato delle funzioni, i requisiti di installazione e gli estrattori supportati, perché questa scelta d'interfaccia non garantisce la maturità del prodotto.