QMD: Personal Concept & Research Library
QMD (Quick Markdown Search) is a local semantic search engine tailored for your personal Markdown notes, conceptual gardens, and research archives. While code search finds exact lines of code, QMD retrieves the reusable principles, theoretical models, and architectural lessons you have accumulated over the years.
The Research Archivist Metaphor: Why QMD Exists
To understand why QMD is necessary, look at how different tools divide responsibility:
Basic Memoryis the sticky note on the monitor: It holds immediate project rules and red lines ("Do not touch production databases; keep this script small").zvec-grepis the code line locator: It points directly to line numbers in active code ("Where is the function calculating fees?").QMDis your personal research archivist: When facing a complex cross-project design challenge—such as "How did we separate quantitative research from production backtests?" or "What are the proven design patterns for offline sync?"—you do not want the AI to guess or re-invent the wheel from scratch.
The Problem: Stepping on the Same Rake Twice
Without a conceptual library:
- You spend months solving a tricky architectural problem in Project A.
- Six months later, you start Project B and face the exact same problem.
- Because the new AI session knows nothing about Project A's hard-won lessons, it suggests a naive approach, leading to the same mistakes and wasted effort.
QMD solves this by keeping your verified conceptual notes and research sources organized. You ask a question in everyday language, and QMD retrieves the relevant past concept note, grounding the AI in proven architectural patterns.
How QMD Operates
| Dimension | QMD (Concept Library) | zvec-grep (Code Radar) | Basic Memory (House Rules) |
|---|---|---|---|
| What It Stores | Architectural principles, theories, research notes | Source code functions, classes, file sections | Active project goals, hard red lines, vetoes |
| Search Target | Cross-project Markdown archives (knowledge/) | Active workspace repositories (.py, .ts, docs) | Single authoritative project note per task |
| Output Size | Full conceptual section (~1,000 words) | Exact file & line coordinates (~80 words) | Short constraints note (~1,500 words) |
| Primary Beneficiary | Strategic design choices and proven methodology | Direct code fixes and duplicate prevention | Keeping agents from running wild or over-engineering |
Essential Recipes (Daily Cheatsheet)
Run these commands in your terminal:
1. Smart Conceptual Query (Recommended)
Ask conceptual questions in natural language. QMD automatically expands synonyms and ranks the best notes:
qmd query "quantitative research production isolation" -c pkls-concepts
2. Fast Keyword Search (No AI Required)
Quickly find notes containing specific terms:
qmd search "FIFO execution" -c pkls-concepts
3. Retrieve and Read a Document
Display a clean, line-numbered view of a matched note:
qmd get qmd://pkls-concepts/quant/portfolio-lifecycle.md
Related Notes & Connected Systems
- The Bigger Picture: Agent Memory and Hierarchical Retrieval — Where QMD sits at Layer 1 (Domain Concept Garden) in the 4-tier cognitive hierarchy.
- Immediate Project Red Lines: Basic Memory — The high-level intent keeper that governs active project scope.
- Code Symbol Locator: zvec-grep (zg) — The low-level radar that pinpoints code lines once the architectural concept is clear.
Official Resources & References
- GitHub Repository: tobi/qmd
- NPM Package: @tobilu/qmd