====== QMD ======

[[https://github.com/tobi/qmd|QMD]] je lokální search engine pro markdownové dokumenty, poznámky, meeting notes a knowledge base. Podle README kombinuje BM25 fulltext, vektorové vyhledávání a LLM re-ranking, přitom běží on-device nad lokálními soubory. Dobře zapadá například jako doplněk k [[ai:zapisy-a-workflow:inspirace-a-strategie:karpathy-llm-wiki-prubezne-budovana-znalostni-baze|patternu LLM Wiki]], kde může sloužit jako vyhledávací vrstva nad rostoucí wiki.

===== Co to je =====

QMD není samotná knowledge base ani agent memory platforma. Je to nástroj pro indexaci a prohledávání dokumentů, které už někde máš – typicky markdown, dokumentaci, zápisky nebo interní wiki. Hlavní hodnota je v tom, že nad těmito soubory umí dělat jak rychlé keyword search, tak i sémantické hledání a následný re-ranking výsledků.

README ho popisuje jako „Query Markup Documents“ a cílí hlavně na agentic workflows, kde agent potřebuje rychle:

  * najít relevantní soubory
  * získat jejich cestu nebo docid
  * stáhnout konkrétní dokument
  * omezit hledání jen na vybranou kolekci

===== Jak funguje =====

Podle dokumentace používá QMD hybridní pipeline:

  * **BM25 / FTS5** pro klasické fulltextové hledání
  * **vector search** pro sémantickou podobnost
  * **query expansion** pro rozšíření dotazu
  * **LLM re-ranking** pro přesnější finální pořadí výsledků

V README je architektura popsaná jako kombinace více retrieval kroků, které se spojují přes RRF (Reciprocal Rank Fusion) a následně se přerovnají pomocí lokálního rerankeru. Prakticky je důležité hlavně to, že nejde jen o jednoduché grepování souborů.

===== Co umí =====

QMD umí pracovat jak přes CLI, tak přes MCP server. V praxi nabízí hlavně:

  * správu kolekcí nad adresáři se soubory
  * indexaci markdownu a dalších textových zdrojů
  * ukládání kontextu k adresářům a cestám
  * vyhledávání v režimech ''search'', ''vsearch'' a ''query''
  * načítání jednoho nebo více dokumentů přes ''get'' a ''multi-get''
  * JSON nebo file-oriented výstup vhodný pro agenty
  * MCP server pro přímé napojení do LLM klientů

Pro větší bázi je důležité i to, že QMD nevrací jen seznam výsledků, ale umí dodat i snippet, skóre, docid a kontext. Agent tak může udělat dvoukrokový workflow: nejdřív hledat, potom stáhnout konkrétní dokumenty.

===== Lokální běh a modely =====

QMD běží lokálně a podle README využívá ''node-llama-cpp'' a GGUF modely pro embeddingy, reranking a query expansion. To je důležitý rozdíl oproti cloudovým službám – obsah dokumentů nemusí odcházet mimo lokální stroj.

README uvádí tři hlavní lokální modelové role:

  * embedding model
  * reranker
  * model pro query expansion

Výhodou je soukromí a přímý běh nad lokálními soubory. Nevýhodou jsou vyšší nároky na lokální prostředí a nutnost počítat s tím, že pokročilejší kvalita retrievalu něco stojí i výpočetně.

===== K čemu je to dobré =====

QMD dává smysl hlavně v těchto situacích:

  * máš větší markdownovou knowledge base
  * agent nad ní potřebuje opakovaně hledat
  * nechceš pokaždé ručně procházet index nebo adresáře
  * chceš lokální, souborově orientovaný search bez nutnosti stavět vlastní retrieval stack
  * potřebuješ rychle připojit vyhledávání do Claude Code, MCP klienta nebo jiného agentního workflow

Typický use-case je právě větší osobní nebo týmová wiki, kde samotná struktura souborů a ruční index přestávají stačit, ale pořád chceš zůstat u lokálního markdownového workflow.

===== Jak se liší od LLM Wiki =====

Tady je dobré rozlišit pattern a nástroj.

[[ai:zapisy-a-workflow:inspirace-a-strategie:karpathy-llm-wiki-prubezne-budovana-znalostni-baze|LLM Wiki]] je způsob práce s knowledge base. Řeší, jak se zdroje průběžně kompilují do wiki, jak vznikají syntézy, jak se udržují vztahy mezi stránkami a jak se dělá linting.

QMD oproti tomu řeší hlavně retrieval nad již existujícími soubory. Jinými slovy:

  * **LLM Wiki** = pattern pro průběžně udržovanou znalostní vrstvu
  * **QMD** = search vrstva nad markdownem a dokumenty

Nejsou to konkurenti. QMD může být praktický stavební blok uvnitř workflow LLM Wiki.

===== Základní použití =====

README uvádí například tento rychlý start:

<code bash>
# instalace
npm install -g @tobilu/qmd

# přidání kolekce
qmd collection add ~/notes --name notes

# vytvoření embeddingů
qmd embed

# fulltext search
qmd search "project timeline"

# semantické vyhledávání
qmd vsearch "how to deploy"

# hybridní query
qmd query "quarterly planning process"
</code>

Pokud se má QMD používat přímo z agenta, dává smysl i MCP server:

<code bash>
qmd mcp
</code>

README uvádí také HTTP variantu MCP serveru pro sdílený běh bez opakovaného načítání modelů.

===== Na co dát pozor =====

  * QMD není náhrada za kvalitní strukturu knowledge base
  * výsledky budou jen tak dobré, jak dobré jsou indexované dokumenty a kontext
  * lokální modely zvyšují nároky na runtime prostředí
  * hybridní retrieval je užitečný, ale pořád neřeší sám o sobě syntézu, konsolidaci a údržbu wiki

Jinými slovy: QMD dobře řeší hledání, ale neřeší za tebe znalostní architekturu.

===== Kdy ho zvažovat =====

QMD má smysl zvažovat ve chvíli, kdy už máš větší množství markdownu a agent nad ním dělá opakované dotazy. Pokud máš jen malou sadu souborů, může stačit obyčejný filesystem a jednoduché fulltextové nástroje. Jakmile ale knowledge base roste, QMD dává smysl jako hotová lokální retrieval vrstva.

===== Zdroje =====

  * [[https://github.com/tobi/qmd|tobi/qmd – GitHub]]
  * [[https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f|Karpathy – LLM Wiki gist]]
  * [[https://www.marigold.cz/item/karpathy-llm-knowledgebase/|Marigold.cz – Karpathy přišel na to, jak používat AI jinak. A má pravdu.]]