52 - Qdrant and vector databases for agent context

This addendum answers the follow-up question: does a vector database like Qdrant add meaningful token-usage value on top of the planned fff + codedb code-intelligence stack?

TL;DR

• Qdrant is not a replacement for fff or codedb. fff finds files, paths, and text quickly; codedb answers code-structure questions; Qdrant stores vectors and retrieves semantically similar chunks or memories.
• A vector DB can save tokens only through retrieval selectivity. It saves when it finds 3-5 compact, relevant snippets that prevent reading many files or docs. It loses when it adds embedding cost, stale chunks, MCP schema overhead, and extra retrieved text on top of normal search.
• The dossier already covered the category, but not Qdrant specifically. File 14 called semantic/RAG repo indexing the largest evidence gap; file 19 rejected semantic response caching for coding agents; file 51 compared purpose-built code context engines. This file adds Qdrant as a backend choice.
• Best current recommendation: do not add raw Qdrant as a default third tool. Pilot it only as an optional semantic-memory/RAG arm against fff + codedb.
• If a vector layer is needed, prefer a code-aware layer first. Code Context Engine or Claude Context already include chunking, hybrid retrieval, compression, and agent wiring. Qdrant is the lower-level backend you choose when you want to build or control that layer yourself.

Is Qdrant already covered?

Partially.

So Qdrant is not missing as a concept, but it was missing as a concrete candidate for the current fff + codedb plan.

What Qdrant actually provides

Qdrant is a Rust vector database and vector search engine. The upstream README positions it as a production service for storing vectors plus payloads and then searching by vector similarity. The relevant capabilities for AI-agent context are:

• dense vector search for semantic similarity;
• sparse vector search for keyword/full-text-style retrieval;
• multivector search for late-interaction models such as ColBERT;
• JSON payload filtering, including keyword, numeric, geo, and boolean clauses;
• hybrid queries that fuse dense and sparse search with RRF or DBSF;
• quantization and on-disk storage to reduce memory pressure;
• distributed deployment for scale;
• an official MCP server with qdrant-store and qdrant-find;
• local or server deployment, including QDRANT_LOCAL_PATH in the MCP server.

That is infrastructure. It does not automatically provide:

• AST-aware code chunking;
• symbol/caller/dependency graphs;
• file outlines;
• edit-safe code spans;
• index freshness tied to git edits;
• token-optimized snippet compression;
• source-of-truth verification before patching.

Those must come from a layer above Qdrant, such as Code Context Engine, Claude Context, a custom indexer, or a future jackin' role extension.

Qdrant vs the tools already considered

Vector database comparison for this purpose

The question is not "which vector DB is best in abstract?" It is "which backend would make sense for AI coding agents trying to spend fewer tokens?"

Verdict: if the project wants a raw vector DB backend, Qdrant is the best fit among open-source options for a jackin' role pilot. But the best solution for token usage is probably not raw Qdrant; it is a code-aware retrieval layer that may use Qdrant underneath.

Benchmark evidence: does anyone prove they beat Qdrant?

No public source found proves that any raw vector database is significantly better than Qdrant for jackin's actual metric: fewer total tokens per solved coding-agent task on top of fff + codedb. The available evidence measures database performance, retrieval quality, or code-context-tool compression, not the full agent loop.

Independent algorithm benchmarks (ANN-Benchmarks, big-ann/NeurIPS) reinforce this: they rank algorithms, not products, and crown no consumer database; Qdrant sits on the recall-vs-latency Pareto frontier, and the vendor benchmarks mutually contradict each other — each wins the axis it chose (usually throughput) while the same data shows Qdrant winning tail latency, which is itself proof there is no decisive winner.

So the verified answer is:

• Better raw vector DB for high-scale managed throughput/cost: possibly Milvus/Zilliz, and possibly Turbopuffer or Pinecone depending on cloud workload.
• Better raw vector DB for embedded/local library ergonomics: possibly LanceDB or Chroma.
• Better search platform for production hybrid ranking: possibly Vespa.
• Better solution for coding-agent token savings: not a raw DB; benchmark Code Context Engine or Claude Context as code-aware layers.
• Better default for jackin' right now: no vector DB by default. Keep fff + codedb; add a vector layer only as an opt-in semantic-memory/RAG arm.

Where Qdrant would add value

Qdrant makes sense when the agent needs semantic recall that fff and codedb do not naturally cover:

• "Find code similar to this behavior, even if names differ."
• "Find examples of how we use this third-party library."
• "Find the design decision we made last week."
• "Find the docs snippet that explains this config."
• "Find prior implementation patterns across many repos."
• "Retrieve accepted code snippets only, then keep generated code consistent."

The Qdrant MCP blog uses exactly this shape: a semantic memory layer stores code snippets, documentation, and implementation details, then qdrant-find retrieves relevant context before the assistant generates code. That can improve relevance and avoid reading irrelevant documentation.

Why the docs corpus is the good case

This distinction matters enough to preserve in the research because otherwise the recommendation is easy to misread as "vector search never helps." The more precise claim is: vector search is a weak default for exact code navigation, but a plausible speedup for semantic documentation and decision recall.

The current repo is large enough for that distinction to matter. A local count on 2026-06-13 found:

rg --files docs token-optimization | wc -l                => 383 files
rg --files docs token-optimization | rg '\.(md|mdx)$' | wc -l => 234 Markdown/MDX files

That is ≈900k–1M tokens of prose (estimate) — far too large to load wholesale — a substantial human-language surface: user docs, reference pages, error pages, topic rules, research files, and decision-like conclusions. For questions such as "where do we document the TUI modal rule?", "what is the host-write policy?", or "what did we conclude about Qdrant versus codedb?", the agent may not know the exact file name or wording. A bounded hybrid vector index can cut the search path from repeated rg attempts plus several file reads to a small set of path:line snippets.

This is mostly a wall-clock and tool-loop speedup claim, not automatically a token-savings claim. It becomes a token-saving claim only when the retrieval layer returns compact pointers and snippets:

good: 3-5 path:line hits + short excerpts + normal file-read verification
bad: 10-20 large chunks pasted into the prompt before every task

The recommended policy is therefore:

• use vector or hybrid search for docs, examples, decisions, tickets, logs, and architecture memory when exact keywords are uncertain;
• prefer hybrid retrieval, not pure vector: BM25/keyword + vector + metadata filters, because commands, config keys, error codes, and product terms are often literal;
• cap output to 3-5 compact results and require native file reads before citing or editing;
• do not route exact path, symbol, caller, dependency, or patching questions through the vector index.

This makes the vector layer useful as a documentation accelerator without promoting it to the primary code-navigation layer.

Where Qdrant does not add value

Qdrant should not be used when a precise code tool already answers the question:

• "Where is this function defined?" Use rust-analyzer/Serena/codedb.
• "Who calls this function?" Use codedb or an LSP/reference tool.
• "Which files mention this string?" Use fff or rg.
• "What is the outline of this file?" Use codedb.
• "Patch this function." Use native file-edit tools after exact span lookup.

For these tasks, Qdrant adds a semantic approximation layer where an exact structural or lexical tool is cheaper and safer.

Token economics

Qdrant never saves tokens merely by existing. It saves tokens only if:

tokens avoided by fewer file/doc reads
  > retrieved snippets
  + embedding/indexing cost
  + MCP schema/tool overhead
  + stale-index recovery
  + extra verification reads

Expected positive cases:

• large docs or examples where semantic query returns a few snippets instead of reading many files;
• repeated architecture/design recall across sessions;
• code pattern discovery when names are unknown;
• multi-repo or cross-project memory where grep in one checkout is insufficient.

Expected negative or neutral cases:

• normal single-repo Rust edits where fff + codedb + rust-analyzer already find the exact path/symbol quickly;
• active editing where vector chunks go stale;
• broad semantic queries that return big chunks;
• agent instructions that say "always search Qdrant" before every code change;
• whole-response semantic caching, which file 19 already killed for coding agents.

Recommended jackin' setup if piloted

Do not add Qdrant to every role. Add a separate opt-in vector-context pilot for the-architect or a research role.

Minimum safe shape:

rust-analyzer + ast-grep
+ codedb
+ fff
+ optional qdrant-find only for semantic docs/examples/decisions

Implementation constraints:

• Run Qdrant and the MCP server inside the role container, not on the host.
• Keep jackin-owned state under /jackin/state/qdrant/ or a role-owned equivalent, not /tmp, /var, or the operator's home.
• Register MCP in the container's user scope only.
• Start read-only: expose qdrant-find; disable or strictly gate qdrant-store until storage policy is clear.
• Store pointers first: path, line_start, line_end, commit, symbol, kind, and a short snippet. Avoid returning large chunks by default.
• Limit results to 3-5 unless the agent explicitly asks for more.
• Include a freshness check: project root, indexed commit/hash, changed-file status, and last-index time.
• Use hybrid retrieval if available: dense vector + sparse/keyword + metadata filters. Pure vector search is too fuzzy for code.
• Require the agent to verify with native file reads before editing.

Example Claude Code registration, adapted from Qdrant's MCP docs:

claude mcp add qdrant-code-search \
  -e QDRANT_URL="http://localhost:6333" \
  -e COLLECTION_NAME="code-repository" \
  -e EMBEDDING_MODEL="sentence-transformers/all-MiniLM-L6-v2" \
  -e TOOL_FIND_DESCRIPTION="Use for semantic search over approved docs, examples, prior decisions, and code patterns when exact path/symbol names are unknown. Return compact path:line pointers and snippets; verify with native reads before editing." \
  -e TOOL_STORE_DESCRIPTION="Store only operator-approved snippets or accepted implementation decisions with metadata. Do not store generated code automatically." \
  -- uvx mcp-server-qdrant

For a jackin' role, prefer the same command inside a setup hook and point Qdrant storage at role/container state. Do not run the upstream registration against the operator's host config without explicit opt-in.

Best-solution ranking after adding Qdrant

Validation protocol

Add Qdrant only if it beats the current plan in a realistic harness.

Arms:

Task set:

• 10 exact code-navigation tasks, where vector search should not help;
• 10 semantic "find similar pattern" tasks, where vector search might help;
• 10 docs/examples/API usage tasks, where vector search should help;
• 5 stale-index/edit-after-retrieval tasks;
• 5 multi-repo or cross-session decision recall tasks, if available.

Metrics:

• solved task rate;
• correct target file top-1 and top-5;
• total input/output/cache tokens per solved task;
• tool calls and tool-result tokens;
• number of verification reads after retrieval;
• index build time and incremental update time;
• embedding/model cost;
• stale or misleading retrieval incidents;
• host/container state written.

Acceptance:

Adopt Qdrant only if:
  solved_task_rate >= planned stack
  total tokens per solved task <= planned stack by at least 20%
  stale/misleading retrieval incidents do not increase
  host writes are zero unless explicitly opted in
  exact symbol tasks still use codedb/LSP, not Qdrant

If Qdrant wins only on docs/examples/decisions, keep it scoped there. Do not promote it to general code search.

Bottom line

Qdrant is a good vector database and a credible backend for semantic memory/RAG. It should not replace fff or codedb, and it should not be added as a default third tool merely because vector databases are popular.

For jackin', the practical recommendation is:

Default code role:
  rust-analyzer + ast-grep + codedb + fff

Optional semantic-memory pilot:
  add Qdrant only for docs/examples/decisions/pattern recall

Token-saving benchmark:
  compare Qdrant against Code Context Engine and Claude Context

If the pilot proves a 20%+ token reduction per solved task over fff + codedb with equal quality, Qdrant becomes a useful optional role component. Until then, it is a backend candidate, not part of the default stack.

Source ledger

• Qdrant repository and README: https://github.com/qdrant/qdrant
• Qdrant MCP server: https://github.com/qdrant/mcp-server-qdrant
• Qdrant hybrid queries: https://qdrant.tech/documentation/search/hybrid-queries/
• Qdrant MCP coding-agent article: https://qdrant.tech/blog/webinar-vibe-coding-rag/
• Qdrant vector search benchmarks: https://qdrant.tech/benchmarks/
• VectorDBBench repository: https://github.com/zilliztech/VectorDBBench
• VectorDBBench leaderboard: https://zilliz.com/vdbbench-leaderboard
• RAGPerf paper: https://arxiv.org/abs/2603.10765
• 2026 HPC vector DB scaling paper: https://arxiv.org/html/2606.08950v1
• Code Context Engine: https://github.com/elara-labs/code-context-engine
• Claude Context: https://github.com/zilliztech/claude-context
• Milvus overview: https://milvus.io/docs/overview.md
• Weaviate documentation: https://docs.weaviate.io/weaviate
• Chroma documentation: https://docs.trychroma.com/docs/overview/introduction
• LanceDB documentation: https://lancedb.github.io/lancedb/
• Vespa vector database overview: https://vespa.ai/vector-database/
• Turbopuffer documentation: https://turbopuffer.com/docs/index
• Pinecone vector database explainer: https://www.pinecone.io/learn/vector-database/
• pgvector repository: https://github.com/pgvector/pgvector
• Existing semantic/RAG discussion: token-optimization/14-retrieval-memory-and-state.md
• Existing semantic-cache discussion: token-optimization/19-infrastructure-level.md
• Existing code-intelligence comparison: token-optimization/51-code-intelligence-tools.md