Sincronizza la tua cartella con ChatGPT: la storia dietro `openai-folder-sync`

created: venerdì, ago 29, 2025

Tempo fa mi capitava spesso lo stesso problema: avevo un sacco di appunti, specifiche e documenti markdown sul mio portatile, ma quando aprivo ChatGPT e gli facevo domande su quei contenuti, il modello ovviamente non sapeva che esistessero. Copiare e incollare i file era noioso; caricarli manualmente uno per uno non era molto meglio. Così ho costruito un piccolo CLI che fa la parte noiosa per me: openai-folder-sync, uno strumento da riga di comando che sincronizza una directory locale in un OpenAI Vector Store, in modo che quei file diventino contesto ricercabile per ChatGPT.

Perché uno store vettoriale?

La ricerca di file di OpenAI è costruita attorno a uno store vettoriale. Aggiungi file a uno store, vengono processati in embedding, e gli assistant (o ChatGPT tramite strumenti collegati) possono recuperare e ancorare le risposte usando quei file. È un modello pulito, ma presuppone che ti ricorderai di caricare e mantenere il tuo insieme di file. Un passaggio di sincronizzazione — che rispecchia una cartella a cui tieni già — è più vicino a come lavoriamo giorno per giorno.

Cosa fa lo strumento

openai-folder-sync scansiona una directory sul tuo computer, filtra i file per estensione e li invia a uno store vettoriale esistente. Puoi eseguirlo una volta per popolare uno store, oppure aggiungerlo alla tua routine (es. un cron job) per mantenere aggiornata la tua base di conoscenza. C’è anche un’opzione per incorporare i metadati git (branch e commit) nel contenuto caricato, così quando ChatGPT cita qualcosa, sai esattamente da quale versione proviene.

Rispecchia una cartella locale in un Vector Store
Supporta il filtro per estensioni (es. md,txt,pdf)
Provenienza git opzionale (--git-info)
Può essere usato in script o eseguito ad-hoc

Repo: https://github.com/JensWalter/openai-folder-sync

Installazione

È scritto in Rust e si installa tramite Cargo:

cargo install --git https://github.com/JensWalter/openai-folder-sync.git

Cargo compila e piazza il binario openai-folder-sync nella tua PATH.

Uso

Ti servirà una chiave API OpenAI e un ID di vector store esistente (assomiglia a vs_…). Poi punta il CLI alla tua cartella:

openai-folder-sync \
  --vector-store 'vs_ABCDEFGHIJK' \
  --local-dir '/Users/jens/tmp/wiki/content' \
  --extensions md

Preferisci eseguirlo tramite Cargo durante lo sviluppo?

cargo run -- \
  --vector-store 'vs_ABCDEFGHIJK' \
  --local-dir '/Users/jens/tmp/wiki/content' \
  --extensions md

La maggior parte delle opzioni può anche essere impostata tramite variabili d’ambiente:

export OPENAI_API_KEY=sk-...
export VECTOR_STORE=vs_ABCDEFGHIJK
export LOCAL_DIR=/Users/jens/tmp/wiki/content
export EXTENSIONS=md,txt,pdf
export GIT_INFO=true

openai-folder-sync

Opzioni comuni
  --vector-store / VECTOR_STORE – ID dello store di destinazione
  --local-dir / LOCAL_DIR – cartella da sincronizzare
  --extensions / EXTENSIONS – lista separata da virgola
  --git-info / GIT_INFO – includi metadati git (true|false)
  --help – mostra tutte le opzioni

Come si integra con ChatGPT

Una volta che i file sono in uno store vettoriale, ChatGPT (o le tue app API Assistants) può recuperare spezzoni rilevanti di quei file mentre risponde alle tue domande. Questo significa che puoi chiedere cose come “Cosa diceva la proposta sulla timeline della migrazione?” e il modello estrarrà il contesto rilevante dai tuoi documenti sincronizzati — niente copia-incolla necessario. La tua cartella diventa effettivamente una base di conoscenza viva.

Suggerimenti e avvertenze

Scegli le estensioni con criterio. Inizia con i formati che usi davvero — md, txt, magari pdf. Questo mantiene le elaborazioni rapide e il recupero focalizzato.
Crea prima lo store vettoriale. Lo strumento si aspetta un ID di store; creane uno via API o dashboard, poi passa quell’ID al CLI.
Usa le informazioni git per la provenienza. Se sincronizzi da un repository, abilitare --git-info tagga il testo caricato con i metadati dei commit, rendendo le risposte più facili da verificare e tracciare.
Escludi il rumore. Considera di tenere artefatti di build, node_modules o file temporanei fuori dalla cartella di sync, o aggiungili a .gitignore se fai affidamento sui metadati git.

Flusso di lavoro di esempio

Crea uno store vettoriale per ogni dominio di conoscenza (es. “Company Wiki”, “Research Notes”).
Punta openai-folder-sync alla cartella locale corrispondente.
Eseguine la sincronizzazione come parte della tua routine di scrittura (per me: dopo aver pushato su main).
Esegui lo strumento come parte della tua routine (per me: dopo il push su main).
Fai domande a ChatGPT e lascia che il retrieval si occupi del lavoro pesante.

Roadmap

Al momento non ho ulteriori piani per questo strumento. Se pensi che manchi qualcosa, apri pure un issue o una PR.

⸻

Se vuoi provare, il repository include dettagli di installazione e uso oltre all’output di help. L’ho creato per semplificare il mio flusso di lavoro; se ti risparmia qualche maratona di copia-incolla e aiuta ChatGPT a rispondere dai tuoi documenti reali, è già un successo. Buona sincronizzazione!