Gsd Qdrant Knowledge
CLI per setup automatico GSD + Qdrant in qualsiasi progetto Node.js
Ask AI about Gsd Qdrant Knowledge
Powered by Claude Β· Grounded in docs
I know everything about Gsd Qdrant Knowledge. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
gsd-qdrant-knowledge
Knowledge base semantica cross-project per AI coding agents.
Un agent che reinventa la ruota ogni volta che cambia progetto? Non piΓΉ. Questo tool indicizza automaticamente .gsd/ e codice sorgente in una collection Qdrant unificata, poi fa retrieving di contesto rilevante da altri progetti β con scoring intelligente che premia contenuti riutilizzabili e cross-project.
E non serve mai ricordare di cercarlo. L'hook inietta contesto rilevante prima di ogni risposta, automaticamente. Zero query manuali. E zero tokens sprecati a reinventare soluzioni che esistono giΓ .
Come funziona
ββββββββββββββββ sync βββββββββββββββ
β .gsd/*.md β βββββββββββΊ β β
β codice src β post-commit β Qdrant β
β (tutti i β β gsd_memory β
β progetti) β βββββββββββββ β collection β
ββββββββββββββββ auto-retrieve βββββββββββββββ
β
βΌ
Risultati con relevance_score
(0.92 β 0.99 per match forti)
- Sync automatico β dopo ogni commit locale,
.gsd/e il codice vengono indicizzati ingsd_memory, una collection condivisa tra tutti i progetti - Codice analizzato in profonditΓ β estrazione di signatures, JSDoc, commenti, GSD IDs, link bidirezionali con la documentazione
- Ricerca boostata β vector cosine + lexical TF-lite + boosting per contenuti riutilizzabili e cross-project
- Auto-retrieve hook β inietta contesto rilevante prima di ogni risposta, senza che l'agent debba ricordarsi di cercarlo
Auto-retrieve: il contesto arriva da solo
Nessun altro tool inietta automaticamente contesto cross-project nel flusso dell'agent.
L'hook intercetta ogni richiesta utente, chiama auto_retrieve() nel server MCP, filtra per soglia di rilevanza e inietta il contesto nel payload. L'agent vede solo il risultato β zero overhead.
Risparmio tokens
| Cosa | Senza hook | Con hook |
|---|---|---|
| Chi chiama il tool | L'agent (via KNOWLEDGE.md) | L'hook (trasparente) |
| Tokens nel prompt | Input tool call + output risultati | Solo la richiesta dell'utente |
| Reasoning | L'agent ragiona al buio su cosa esiste | L'agent vede subito il contesto disponibile |
| Fiducia | A volte ricorda di cercare, a volte no | Contesto sempre consistente |
Un'agent senza contesto cross-project tende a riscrivere pattern che esistono giΓ . Ogni riga di codice riscritta da zero Γ¨ un token sprecato.
Features
| Feature | Dettaglio |
|---|---|
| β‘ Auto-retrieve hook | β Unique β Iniezione automatica di contesto prima di ogni risposta. Zero query manuali, zero tokens sprecati a reinventare |
| π Cross-project retrieval | Collection unificata gsd_memory con embedding bge-m3-1024 multilingue β tutti i progetti condividono la stessa knowledge base |
| π Flat search + re-ranking | Flat search(LIMIT=30) β lexical rescue pre-threshold β threshold filter(β₯0.78 CLI / β₯0.70 MCP) β recency/path matching β token truncation; piΓΉ candidati per il re-ranker, soglie abbassate |
| π Re-ranking avanzato | Recency boost +0.05 (file <30gg), path matching +0.15, symbol boost Γ1.5, source path overlap fino a +0.20 β flat search LIMIT=30 con soglie 0.78/0.55 CLI e 0.70/0.48 MCP |
| π DocβCode linking | β
Unique β ogni snippet ha relatedDocPaths e relatedDocIds: il codice sa quali docs gli appartengono, e i docs sanno quali code file citano. Retrieval contestuale bidirezionale |
| π» Smart code indexing | bge-m3-1024 con path-first (prima linea = percorso file) e weighted header SIGNATURES:/EXPORTS:/IMPORTS: β il codice Γ¨ indicizzato come lo leggono gli agent |
| π Auto-sync | Hook post-commit sincronizza automaticamente. Health check su Qdrant prima di ogni sync. Zero configurazione manuale |
| β‘ Zero config | Un comando: gsd-qdrant-knowledge. Bootstrap, collection, MCP registration, hook β tutto automatico |
Scoring (bge-m3 + flat search + re-ranking)
| Range | Significato |
|---|---|
| 0.95 β 1.0 | Match eccellente β vettoriale forte + recency/path/symbol boost |
| 0.85 β 0.94 | Match forte β buon embedding, boosting applicato |
| 0.78 β 0.94 | Rilevante CLI / β₯0.70 MCP β contesto utile (soglia primaria SCORE_THRESHOLD) |
| 0.55 β 0.77 | Fallback CLI / β₯0.48 MCP β risultati deboli ma potenzialmente utili |
| < 0.48 | Ignorato (sotto entrambe le soglie fallback) |
Il re-ranking applica:
- +0.05 recency boost per file modificati negli ultimi 30 giorni
- +0.15 path matching quando parole della query corrispondono al percorso sorgente
- Symbol boost Γ1.5 (β+0.2) su match con
symbolNamesnel payload - Source path overlap fino a +0.20 β il basename del file (
ProjectCard.jsx) viene tokenizzato e confrontato con i token della query
Soglie: flat search restituisce fino a LIMIT=30 candidati, filtra per SCORE_THRESHOLD (CLI 0.78 / MCP 0.70), fallback a FALLBACK_THRESHOLD (CLI 0.55 / MCP 0.48) se troppo pochi risultati. Il re-ranking fa il lavoro di filtraggio finale.
Pipeline di retrieval (dettaglio)
flat search(LIMIT=30, bge-m3-1024)
β lexical rescue pre-threshold (+symbol match Γ1.5, +source overlap fino a 0.12)
β threshold filter(β₯0.78 CLI / β₯0.70 MCP)
β fallback se <2 risultati (β₯0.55 CLI / β₯0.48 MCP)
β sortChunksByPosition() (ordinamento per startLine)
β sibling file expansion (.css β .jsx stesso stem)
β re-ranking(recency + path match + symbol boost Γ1.5 + source overlap fino a 0.20)
β token estimation/truncation(4000 max, 500 char per risultato)
Il lexical rescue pre-threshold Γ¨ il passo chiave che permette ai file con nomi significativi (ProjectCard.jsx, AuthMiddleware.ts) di sopravvivere al cutoff anche quando l'embedding semantico da solo non basta. Senza questo step, un punteggio vettoriale borderline (es. 0.41) veniva eliminato prima che il re-ranking potesse applicare i boost lessicali.
Esempio di output
=== CONTESTO DA MEMORIA CROSS-PROJECT ===
Task: "implementare autenticazione JWT"
Trovati 3 risultati rilevanti:
β’ [doc] Authentication middleware pattern
Score: 0.967 | Source: auth-middleware/DECISIONS.md
Match type: semantic
β’ [code] JWT auth module with refresh tokens
Score: 0.942 | Source: payment-service/src/auth/jwt.js
Match type: semantic
relatedDocPaths: [auth-middleware/DECISIONS.md]
β’ [doc] Security decisions and patterns
Score: 0.918 | Source: api-gateway/DECISIONS.md
Match type: semantic
Architettura (bge-m3 + flat search)
gsd_memory (single Qdrant collection, bge-m3-1024 vectors)
βββ type: doc β .gsd/*.md (STATE.md escluso)
βββ type: code β src/**/*.js,ts,py,go,...
βββ signatures, comments, exports, imports
βββ relatedDocPaths β docs collegati (GSD IDs matching)
Pipeline di retrieval: flat search(LIMIT=30) β lexical rescue pre-threshold β threshold filter(β₯0.78 CLI / β₯0.70 MCP) β fallback se <2 risultati (β₯0.55 CLI / β₯0.48 MCP) β sortChunksByPosition() β sibling expansion β re-ranking(recency + path match + symbol boost Γ1.5 + source overlap fino a 0.20) β token estimation/truncation
Link bidirezionale docs β code: durante l'indicizzazione, il tool estrae i GSD IDs (M001, S02, T03β¦) da ogni file. Se uno snippet di codice cita M003/S01/ e un doc contiene gli stessi IDs, il link viene creato automaticamente.
Sibling expansion: quando una query trova ProjectCard.jsx, il sistema cerca anche ProjectCard.css, ProjectCard.test.js nello stesso path β lo stem del file funziona da chiave per recuperare tutti i file correlati senza bisogno che la query li menzioni esplicitamente.
- GSD = source of truth β i file
.gsd/del progetto corrente restano gestiti localmente - Qdrant = enhancer β memoria condivisa tra progetti, non sostituzione del contesto locale
- Nessuna scrittura dentro
.gsd/β il tool rispetta i flussi nativi di GSD
CLI
gsd-qdrant-knowledge # Bootstrap completo
gsd-qdrant-knowledge context "query" # Query manuale
gsd-qdrant-knowledge uninstall # Rimuove gli artifact
Installazione completa: GSD-QDRANT-SETUP.md
Integrazione
Il tool espone un MCP server (gsd-qdrant-mcp) con lo strumento auto_retrieve. Attualmente integrato con GSD/pi tramite hook before_provider_request, l'architettura Γ¨ agnostica e puΓ² essere adattata ad altri agent.
Durante il bootstrap, il progetto registra automaticamente il server in .mcp.json β nessuna configurazione manuale richiesta.
Link utili: Setup completo Β· Changelog
