Perché ho dato agli agenti un filesystem invece di un'altra API

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 è 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 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:

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:

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:

echo "<undo_id>" > ~/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 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: 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.