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

created: venerdì, ago 29, 2025

Tempo fa mi ritrovavo spesso con lo stesso problema: avevo un sacco di note, specifiche e documenti markdown sul mio portatile, ma quando aprivo ChatGPT e facevo domande su di essi, ovviamente il modello non sapeva che esistessero. Copiare e incollare i file era tedioso; caricarli manualmente uno per uno non era molto meglio. Così ho creato un piccolo CLI che fa il lavoro noioso per me: openai-folder-sync, uno strumento da linea di comando che sincronizza una directory locale con un OpenAI Vector Store, così quei file diventano contesto ricercabile per ChatGPT.

Why a vector store?

La ricerca file di OpenAI è costruita attorno a un vector store. Aggiungi file a uno store, questi vengono trasformati in embeddings, e gli assistenti (o ChatGPT tramite strumenti connessi) possono recuperare e basare le risposte su quei file. È un modello pulito, ma presuppone che tu ricordi di caricare e mantenere il tuo set di file. Un passaggio di sincronizzazione — che riflette una cartella a cui tieni già — è più vicino a come lavoriamo giorno per giorno.

What the tool does

openai-folder-sync scansiona una directory sulla tua macchina, filtra i file per estensione e li invia a un vector store esistente. Puoi eseguirlo una volta per popolare uno store, o aggiungerlo alla tua routine (es. un job cron) 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.

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

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

Installation

È scritto in Rust e si installa tramite Cargo:

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

Cargo compilerà e posizionerà il binario openai-folder-sync nel tuo PATH.

Usage

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ò essere impostata anche 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

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

How this fits with ChatGPT

Una volta che i file sono in un vector store, ChatGPT (o le tue app Assistants API) possono recuperare estratti rilevanti da quei file mentre rispondono alle tue domande. Questo significa che puoi chiedere ad esempio “Cosa diceva la proposta sulla tempistica della migrazione?” e il modello tirerà fuori il contesto rilevante dai tuoi documenti sincronizzati — niente copia-incolla richiesto. La tua cartella diventa effettivamente una base di conoscenza vivente.

Tips & gotchas

Scegli le estensioni con attenzione. Parti dai formati che usi realmente — md, txt, magari pdf. Questo mantiene la elaborazione veloce e il recupero mirato.
Crea prima il vector store. Lo strumento si aspetta un ID store; impostane uno tramite API o dashboard, poi passalo al CLI.
Usa le info git per la provenienza. Se sincronizzi da un repo, abilitare –git-info tagga il testo caricato con metadati di commit, facilitando fiducia e tracciabilità delle risposte.
Escludi il rumore. Considera di tenere artefatti di build, node_modules o file temporanei fuori dalla tua cartella di sincronizzazione, o aggiungili a .gitignore se ti affidi ai metadati git.

Example workflow

Crea uno vector store 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 il push su main).
Fai domande a ChatGPT e lascia che il recupero faccia il lavoro pesante.

Roadmap

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

⸻

Se vuoi provarlo, il repository include dettagli di installazione, uso e output di aiuto. L’ho creato per semplificare la mia routine; se ti salva da qualche maratona di copia-incolla e aiuta ChatGPT a rispondere dai tuoi documenti reali, è un successo. Buona sincronizzazione!