gDown per l'IA

Un assistente IA si aspetta tre cose da un database: capirne il modello, trovare ciò che cerca per significato oltre che per parole, e scrivere senza poter rompere nulla. gDown le ha tutte e tre, nello stesso motore e con gli stessi diritti di ogni altro client.

Server MCP

POST /mcp parla il Model Context Protocol: Claude o qualsiasi client MCP legge lo schema (JSON, Mermaid, Cypher, JSON Schema, GraphQL), esegue query di lettura, chiede il piano di una query senza eseguirla e scrive. Agisce con l'identità del proprio token o account, quindi con i suoi ruoli e privilegi; uno strumento che non può usare non compare nemmeno nell'elenco. Anche le query salvate (My APIs) sono strumenti.

Ricerca vettoriale

CREATE VECTOR INDEX su una proprietà di embedding, poi db.index.vector.queryNodes restituisce i k vicini più prossimi per similarità coseno o euclidea. Ricerca esatta fino a 2 000 vettori, poi un grafo HNSW approssimato (richiamo misurato di almeno 0,9) che segue gli aggiornamenti.

Ricerca full-text

CREATE FULLTEXT INDEX su più etichette e proprietà, con analizzatori (standard, simple, english, keyword...) e query per termini, +obbligatorio, -escluso, "frase esatta", prefisso*, fuzzy~ e proprietà:termine, ordinate per tf-idf.

Le due ricerche sono query come le altre, quindi si combinano con il grafo in una sola istruzione: si trovano i passaggi più vicini a una domanda per significato, si seguono le relazioni fino alla fonte, all'autore o al prodotto e si dà quel contesto all'assistente. È la base del recupero aumentato (RAG) su dati collegati.

Scrivere senza rompere nulla

  • A secco: una scrittura viene eseguita in una transazione annullata, e l'agente vede le modifiche che farebbe.
  • Diretta o per promozione: per impostazione predefinita la scrittura è applicata subito, entro i diritti dell'agente; in modalità « staged » diventa una proposta, conservata in un database replicato, che un revisore promuove o respinge.
  • Diritti propri: date all'agente un ruolo limitato ai database e alle etichette che gli servono, non il ruolo di scrittura integrato; così non raggiunge il database delle proposte.
  • Limiti e traccia: righe restituite, dimensione dell'istruzione e scritture al minuto sono limitate; le scritture compaiono nel registro di audit (protocollo mcp) e portano $_agent, $_at e $_source.

gDown AIM: memoria per il vostro assistente IA

gDown ricorda anche un progetto per Claude Code o qualsiasi client MCP: inviate i suoi file Markdown e i suoi commit, e l'assistente interroga la memoria con gli strumenti memory_*, entro un budget di token, con la fonte di ogni risposta.

  • Un pacchetto per repository: i file Markdown tracciati da Git e i commit degli ultimi giorni, inviati da uno script Python senza dipendenze (o con curl); gDown ne estrae fatti tipizzati (regole, decisioni, insidie, punti del piano, proprietà, rotte, limiti) e sostituisce lo stato precedente in modo atomico.
  • Recupero ibrido: concetti, testo completo e vettori; gli embedding sono calcolati da gDown stesso, nel proprio processo (modello integrato, predefinito) o tramite il vostro Ollama o la vostra API compatibile con OpenAI.
  • Cinque strumenti: memory_ask (una domanda, un repository, un budget), memory_context (ciò che si applica a un compito), memory_about (un concetto), memory_status e memory_note; ogni risposta cita la sua fonte (file e riga, commit o nota).
  • Un token API revocabile, legato a un account locale limitato a un database: l'assistente legge e può solo aggiungere note (memory_note è la sua unica scrittura); DROP API TOKEN gli toglie l'accesso subito.

Senza embedding (provider none, o un Ollama che non risponde) l'invio riesce e la ricerca è lessicale finché l'arretrato non è elaborato. Ollama (ollama pull bge-m3; su Linux deve ascoltare sull'interfaccia Docker) è facoltativo: il modello integrato non ne ha bisogno.

RAG: generazione aumentata dal recupero in gDown

gDown fa generazione aumentata dal recupero (RAG): trova i passaggi che rispondono a una domanda, per significato e per parole, insieme al grafo che li circonda, così che un modello linguistico risponda a partire dai vostri dati e li citi. gDown recupera; il modello che scrive la risposta è il vostro.

Per gli assistenti: gDown AIM

  • Acquisizione: i file Markdown e i commit di un repository diventano fatti tipizzati e frammenti di 1 000 caratteri con una sovrapposizione di 100.
  • Recupero ibrido: il grafo dei concetti, il testo completo e i vettori (prefiltrati per repository) sono combinati, poi ordinati e tagliati a un budget di token.
  • Ogni risposta cita la sua fonte (file e riga, commit o nota).
  • Servito dagli strumenti MCP memory_ask, memory_context, memory_about e memory_note; il modello proprio dell'assistente genera la risposta.

Per le vostre applicazioni

  • Un indice vettoriale su qualsiasi proprietà: ricerca esatta fino a 2 000 vettori, poi un grafo HNSW con un richiamo misurato di almeno 0,9.
  • Ricerca prefiltrata (etichette, valori di proprietà): i k risultati sono contati dopo il filtro.
  • La ricerca vettoriale, le query di grafo Cypher e il testo completo sono nello stesso database e nella stessa istruzione: trovare i passaggi più vicini, poi seguire le relazioni fino alla loro fonte.

Embedding: integrati o esterni

  • Integrati (predefinito, provider=onnx): il modello multilingual-e5-small, quantizzato int8, a 384 dimensioni, gira nel processo di gDown tramite ONNX Runtime. I file del modello sono fissati da SHA-256, scaricati una volta o letti da una cartella, e il modello viene scaricato dalla memoria quando è inattivo. Nessun testo lascia il server.
  • Esterni (provider=http): Ollama (consigliato bge-m3, 1 024 dimensioni) o un'API compatibile con OpenAI. Il token API è inviato solo a quell'API e mai registrato, e gli host che il provider può chiamare sono limitati a un elenco consentito (il loopback per impostazione predefinita).
  • Nessuno (provider=none): la ricerca usa solo il grafo e il testo completo.
  • Cambiare modello: i frammenti elaborati da un altro modello sono segnati come obsoleti e rielaborati su richiesta.

Qualità misurata

gDown AIM è stato valutato su tre insiemi di domande rispetto allo spazio di lavoro reale (32 repository), senza e con vettori (bge-m3 tramite Ollama). La tabella mostra il richiamo, la quota dei fatti attesi trovati, e la dimensione delle risposte. Questa tabella non include il modello ONNX integrato.

Richiamo e dimensione delle risposte in token. I vettori hanno cambiato il richiamo solo sull'insieme 3 (+11,1 punti) e accorciato le risposte degli insiemi 2 e 3.

Limiti: gli indici vettoriali e full-text risiedono in memoria e vengono ricostruiti all'apertura del database; nessun flusso dal server al client, nessun OAuth specifico di MCP (token o account, come le altre rotte); memoria: senza embedding (provider none, o un Ollama che non risponde) la ricerca è lessicale finché l'arretrato non è elaborato. Nessun benchmark della ricerca vettoriale né di MCP è ancora pubblicato: le cifre di questa pagina non li coprono.