gsd-qdrant-knowledge

Cross-project semantic knowledge base for AI coding agents.

An agent that reinvents the wheel every time it switches projects? Not anymore. This tool automatically indexes .gsd/ and source code into per-project Qdrant collections with TurboQuant support, then retrieves relevant context from other projects — with intelligent scoring that rewards reusable content and cross-project patterns.

And you never need to remember to search for it. The hook injects relevant context before every answer, automatically. Zero manual queries. Zero tokens wasted reinventing solutions that already exist.

---

How It Works

  ┌──────────────────┐
  │  .gsd/*.md       │
  │  source code     │  ──────────►
  │  (all projects)  │
  └──────────────────┘
            │
            │  sync / post-commit
            ▼
  ┌──────────────────┐
  │  Qdrant          │
  │  collection      │
  │  (per-project)   │
  └──────────────────┘
            │
            │  auto-retrieve
            ▼
  Results with relevance_score
  (0.92 — 0.99 for strong matches)

1. Auto-sync — after every local commit, .gsd/ and source code are indexed into the project's Qdrant collection
2. Deep code analysis — extraction of signatures, JSDoc, comments, GSD IDs, bidirectional links with documentation
3. Chunked docs — large .md files are split at headings (#, ##, ###) for precise semantic embedding, zero data loss
4. Boosted search — vector cosine + lexical TF-lite + boosting for reusable content and cross-project patterns
5. Auto-retrieve hook — injects relevant context before every answer, without the agent needing to remember to search

Auto-retrieve: context arrives on its own

No other tool automatically injects cross-project context into the agent's workflow.

The hook intercepts every user request, calls auto_retrieve() on the MCP server, filters by relevance threshold, and injects the context into the payload. The agent sees only the result — zero overhead.

Token savings

What	Without hook	With hook
Who calls the tool	The agent (via KNOWLEDGE.md)	The hook (transparent)
Tokens in prompt	Input tool call + output results	Only the user's request
Reasoning	The agent reasons blindly on what exists	The agent sees available context immediately
Reliability	Sometimes remembers to search, sometimes not	Context is always consistent

An agent without cross-project context tends to rewrite patterns that already exist. Every line of code rewritten from scratch is wasted tokens.

Features

Feature	Detail
🗜️ TurboQuant multi-bit	Qdrant 1.18+ with vector quantization: bits4 (8x), bits2 (16x), bits1_5 (24x), bits1 (32x) — 94% ANN recall (bits4), faster search (smaller vectors = more data in CPU cache)
⚡ Auto-retrieve hook	★ Unique — Automatic context injection before every answer. Zero manual queries, zero tokens wasted reinventing
🌐 Cross-project retrieval	Per-project collections with multilingual bge-m3-1024 embedding — all projects share the same knowledge base through cross-project search
🔍 Flat search + re-ranking	Flat search(LIMIT=30) → lexical rescue pre-threshold → composite score filtering(≥0.70 / ≥0.48) → recency/path matching → token truncation; more candidates for the re-ranker, unified thresholds
📊 Advanced re-ranking	Recency boost +0.05 (files <30 days), path matching +0.15, symbol boost ×1.5, source path overlap up to +0.20 — unified composite formula 0.6×sim + 0.15×recency + 0.05×importance + boosts across all 3 entry points
🔗 Doc↔Code linking	★ Unique — every snippet has relatedDocPaths and relatedDocIds: code knows which docs belong to it, and docs know which code files cite them. Bidirectional contextual retrieval
💻 Smart code indexing	bge-m3-1024 with path-first (first line = file path) and weighted header SIGNATURES:/EXPORTS:/IMPORTS: — code is indexed as agents read it
📄 Markdown chunking	Large .md files split at headings (6000 char chunks, 400 overlap) — each chunk is a separate Qdrant point with position metadata. Zero data loss.
🔄 Auto-sync	post-commit hook syncs automatically. Health check on Qdrant before every sync. Zero manual configuration
🎯 Multi-collection	.mcp.json as source of truth for COLLECTION_NAME, QDRANT_URL, QDRANT_QUANTIZATION, QDRANT_TURBO_BITS. Setup with --collection, --force, CLI flags for every command.

Scoring (bge-m3 + flat search + re-ranking)

Range	Meaning
0.95 – 1.0	Excellent match — strong vector + recency/path/symbol boost
0.85 – 0.94	Strong match — good embedding, boosting applied
0.70 – 0.84	Relevant — useful context (primary unified threshold)
0.48 – 0.69	Fallback — weak but potentially useful results
< 0.48	Ignored (below fallback threshold)

Unified composite formula (all 3 entry points):

score = 0.6 × similarity + 0.15 × recency + 0.05 × importance + boosts
clamped [0, 1]

The re-ranking applies:

• +0.05 recency boost for files modified in the last 30 days
• +0.15 path matching when query words match the source path
• Symbol boost ×1.5 (≈+0.2) on matches with symbolNames in payload
• Source path overlap up to +0.20 — the file basename (ProjectCard.jsx) is tokenized and compared with query tokens
• crossProjectBoost +0.06 for results from other projects

Unified thresholds: flat search returns up to LIMIT=30 candidates (CLI) / LIMIT=15 (MCP), filters by SCORE_THRESHOLD 0.70 (primary) / FALLBACK_THRESHOLD 0.48 (fallback). Re-ranking does the final filtering.

Retrieval pipeline (detail)

flat search(LIMIT=30 CLI / 15 MCP, bge-m3-1024)
    → lexical rescue pre-threshold (+symbol match ×1.5, +source overlap up to 0.12)
    → composite score filtering(≥0.70 primary / ≥0.48 fallback)
    → sortChunksByPosition() (ordering by startLine)
    → sibling file expansion (.css ↔ .jsx same stem)
    → re-ranking(composite: recency + path match + symbol boost ×1.5 + source overlap + crossProjectBoost)
    → token estimation/truncation(8000 max, 800 chars per result)

The lexical rescue pre-threshold is the key step that allows files with meaningful names (ProjectCard.jsx, AuthMiddleware.ts) to survive the cutoff even when the semantic embedding alone isn't enough. Without this step, a borderline vector score (e.g. 0.41) would be eliminated before re-ranking could apply lexical boosts.

CLI context output: In addition to standard retrieval, the context command produces a structured markdown table with detected technology patterns, expanded related concepts (two-phase search), and related documentation.

CLI output example

**Detected patterns:** React, TypeScript

| File | Description | Project | Technique |
|------|-----------|----------|---------|
| [src/auth/jwt.js](#src_auth_jwt_js) | JwtModule | payment-service | code/javascript |
| [lib/auth.ts](#lib_auth_ts) | type AuthConfig | api-gateway | code/typescript |

## Related elements

1. **authMiddleware** — export function authMiddleware(req, res, next)
   - Source: start/src/backend/utils/authMiddleware.js

2. **useAuth** — const useAuth = () =>
   - Source: start/src/contesti/useAuth.js

CLI

gsd-qdrant-knowledge setup                  # Setup project (minimal config + sync)
gsd-qdrant-knowledge sync                   # Manual synchronization
gsd-qdrant-knowledge context "query"        # Manual semantic search
gsd-qdrant-knowledge status                 # Show package version
gsd-qdrant-knowledge --version              # Show package version

Common flags

Flag	Default	Description
--collection	gsd_memory	Collection name
--qdrant-url	http://localhost:6333	Qdrant server URL
--turbo-bits	bits4	TQ bits: bits4, bits2, bits1_5, bits1
--quantization	turbo	turbo or none
--chunk-max	1500	Max chars per chunk (code)
--chunk-overlap	200	Chunk overlap (code)

Installation and configuration: SETUP.md

Integration

The tool exposes an MCP server (gsd-qdrant-mcp) with the auto_retrieve tool. It is already tested and working with GSD/pi and Claude Code, compatible with all agents following the same MCP pattern (Stdio + .mcp.json).

During setup, the project automatically registers the server in .mcp.json — no manual configuration required.

---

Useful links: Full setup · Changelog