Skip to content

QMD Semantic Document Search

Role & Purpose

QMD provides fast, local hybrid search (BM25 keyword full-text + vector embeddings + LLM reranking) over the curated markdown knowledge corpus in BluCity-Docs.

========================================================================================
ENGINE                 CAPABILITY                  FUNCTION
========================================================================================
Lexical (BM25)         Exact symbol/error lookup   Finds specific rule IDs (e.g. STD-AUTH-001)
Vector (Embeddings)    Semantic concept search     Finds architecture and governance intent
LLM Reranking (RRF)    Contextual ordering         Ranks high-signal policy guidelines first
========================================================================================

Operating Invariants for QMD

  1. One Canonical Corpus (blueflyio/blu/blucity-docs):
  2. QMD indexes local checkouts of BluCity-Docs.
  3. QMD index caches (~/.cache/qmd/index.sqlite) are derived runtime artifacts; they are NOT document stores.
  4. Doctrine Mutation Workflow:
  5. If a QMD search reveals an outdated or conflicting standard, the agent MUST NOT patch the QMD cache.
  6. The fix is: worktree → author update in BluCity-Docs → commit → MR to release/v0.1.x.
  7. Workspace Integration:
  8. In GitLab Workspaces on Oracle K3s, QMD is accessed via shared read-only corpus mounts or pre-indexed artifact synchronization.

Relationship to other context sources

QMD is DERIVED/NON-AUTHORITATIVE — see README.md §3. It indexes BluCity-Docs for fast retrieval; BluCity-Docs source (read live via the GitLab API, or the working copy) is always the authority when a search hit is consequential. QMD has been independently observed stale (orphaned embedding chunks) — see the "Absence proven by a single mechanism is not absence" entry in the Failure Signature Catalog.