[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M74EYP9J7EV4CW70TAPHYA2K":3,"skill-same:01M74EYP9J7EV4CW70TAPHYA2K":64},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":42,"commitSha":43,"skillDirectory":44,"forksCount":14,"repositoryHtmlUrl":45,"repositoryHomepageUrl":6,"ownerHtmlUrl":46,"ownerBlogUrl":47,"ownerDescription":48,"updatedAt":49,"install":50,"resources":63},"01M74EYP9J7EV4CW70TAPHYA2K","qmd",null,"Search personal knowledge bases, notes, docs, and meeting transcripts locally using qmd — a hybrid retrieval engine with BM25, vector search, and LLM reranking. Supports CLI and MCP integration.","aniruddhaadak80\u002Fherclew","aniruddhaadak80","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F127435065?v=4","01M74EJ1XW3EF2EYN26PFN1TG8","ANIRUDDHA ADAK","01M74EJ1YFT2GM6APEHR1CTTVF",0,"MIT","https:\u002F\u002Fgithub.com\u002Faniruddhaadak80\u002Fherclew\u002Fblob\u002Fmain\u002Fcore-agent\u002Foptional-skills\u002Fresearch\u002Fqmd\u002FSKILL.md",[],[],"2026-11-11 15:11:14",false,"---\nname: qmd\ndescription: Search personal knowledge bases, notes, docs, and meeting transcripts locally using qmd — a hybrid retrieval engine with BM25, vector search, and LLM reranking. Supports CLI and MCP integration.\nversion: 1.0.0\nauthor: Hermes Agent + Teknium\nlicense: MIT\nplatforms: [macos, linux]\nmetadata:\n  hermes:\n    tags: [Search, Knowledge-Base, RAG, Notes, MCP, Local-AI]\n    related_skills: [obsidian, native-mcp, arxiv]\n---\n\n# QMD — Query Markup Documents\n\nLocal, on-device search engine for personal knowledge bases. Indexes markdown\nnotes, meeting transcripts, documentation, and any text-based files, then\nprovides hybrid search combining keyword matching, semantic understanding, and\nLLM-powered reranking — all running locally with no cloud dependencies.\n\nCreated by [Tobi Lütke](https:\u002F\u002Fgithub.com\u002Ftobi\u002Fqmd). MIT licensed.\n\n## When to Use\n\n- User asks to search their notes, docs, knowledge base, or meeting transcripts\n- User wants to find something across a large collection of markdown\u002Ftext files\n- User wants semantic search (\"find notes about X concept\") not just keyword grep\n- User has already set up qmd collections and wants to query them\n- User asks to set up a local knowledge base or document search system\n- Keywords: \"search my notes\", \"find in my docs\", \"knowledge base\", \"qmd\"\n\n## Prerequisites\n\n### Node.js >= 22 (required)\n\n```bash\n# Check version\nnode --version  # must be >= 22\n\n# macOS — install or upgrade via Homebrew\nbrew install node@22\n\n# Linux — use NodeSource or nvm\ncurl -fsSL https:\u002F\u002Fdeb.nodesource.com\u002Fsetup_22.x | sudo -E bash -\nsudo apt-get install -y nodejs\n# or with nvm:\nnvm install 22 && nvm use 22\n```\n\n### SQLite with Extension Support (macOS only)\n\nmacOS system SQLite lacks extension loading. Install via Homebrew:\n\n```bash\nbrew install sqlite\n```\n\n### Install qmd\n\n```bash\nnpm install -g @tobilu\u002Fqmd\n# or with Bun:\nbun install -g @tobilu\u002Fqmd\n```\n\nFirst run auto-downloads 3 local GGUF models (~2GB total):\n\n| Model | Purpose | Size |\n|-------|---------|------|\n| embeddinggemma-300M-Q8_0 | Vector embeddings | ~300MB |\n| qwen3-reranker-0.6b-q8_0 | Result reranking | ~640MB |\n| qmd-query-expansion-1.7B | Query expansion | ~1.1GB |\n\n### Verify Installation\n\n```bash\nqmd --version\nqmd status\n```\n\n## Quick Reference\n\n| Command | What It Does | Speed |\n|---------|-------------|-------|\n| `qmd search \"query\"` | BM25 keyword search (no models) | ~0.2s |\n| `qmd vsearch \"query\"` | Semantic vector search (1 model) | ~3s |\n| `qmd query \"query\"` | Hybrid + reranking (all 3 models) | ~2-3s warm, ~19s cold |\n| `qmd get \u003Cdocid>` | Retrieve full document content | instant |\n| `qmd multi-get \"glob\"` | Retrieve multiple files | instant |\n| `qmd collection add \u003Cpath> --name \u003Cn>` | Add a directory as a collection | instant |\n| `qmd context add \u003Cpath> \"description\"` | Add context metadata to improve retrieval | instant |\n| `qmd embed` | Generate\u002Fupdate vector embeddings | varies |\n| `qmd status` | Show index health and collection info | instant |\n| `qmd mcp` | Start MCP server (stdio) | persistent |\n| `qmd mcp --http --daemon` | Start MCP server (HTTP, warm models) | persistent |\n\n## Setup Workflow\n\n### 1. Add Collections\n\nPoint qmd at directories containing your documents:\n\n```bash\n# Add a notes directory\nqmd collection add ~\u002Fnotes --name notes\n\n# Add project docs\nqmd collection add ~\u002Fprojects\u002Fmyproject\u002Fdocs --name project-docs\n\n# Add meeting transcripts\nqmd collection add ~\u002Fmeetings --name meetings\n\n# List all collections\nqmd collection list\n```\n\n### 2. Add Context Descriptions\n\nContext metadata helps the search engine understand what each collection\ncontains. This significantly improves retrieval quality:\n\n```bash\nqmd context add qmd:\u002F\u002Fnotes \"Personal notes, ideas, and journal entries\"\nqmd context add qmd:\u002F\u002Fproject-docs \"Technical documentation for the main project\"\nqmd context add qmd:\u002F\u002Fmeetings \"Meeting transcripts and action items from team syncs\"\n```\n\n### 3. Generate Embeddings\n\n```bash\nqmd embed\n```\n\nThis processes all documents in all collections and generates vector\nembeddings. Re-run after adding new documents or collections.\n\n### 4. Verify\n\n```bash\nqmd status   # shows index health, collection stats, model info\n```\n\n## Search Patterns\n\n### Fast Keyword Search (BM25)\n\nBest for: exact terms, code identifiers, names, known phrases.\nNo models loaded — near-instant results.\n\n```bash\nqmd search \"authentication middleware\"\nqmd search \"handleError async\"\n```\n\n### Semantic Vector Search\n\nBest for: natural language questions, conceptual queries.\nLoads embedding model (~3s first query).\n\n```bash\nqmd vsearch \"how does the rate limiter handle burst traffic\"\nqmd vsearch \"ideas for improving onboarding flow\"\n```\n\n### Hybrid Search with Reranking (Best Quality)\n\nBest for: important queries where quality matters most.\nUses all 3 models — query expansion, parallel BM25+vector, reranking.\n\n```bash\nqmd query \"what decisions were made about the database migration\"\n```\n\n### Structured Multi-Mode Queries\n\nCombine different search types in a single query for precision:\n\n```bash\n# BM25 for exact term + vector for concept\nqmd query $'lex: rate limiter\\nvec: how does throttling work under load'\n\n# With query expansion\nqmd query $'expand: database migration plan\\nlex: \"schema change\"'\n```\n\n### Query Syntax (lex\u002FBM25 mode)\n\n| Syntax | Effect | Example |\n|--------|--------|---------|\n| `term` | Prefix match | `perf` matches \"performance\" |\n| `\"phrase\"` | Exact phrase | `\"rate limiter\"` |\n| `-term` | Exclude term | `performance -sports` |\n\n### HyDE (Hypothetical Document Embeddings)\n\nFor complex topics, write what you expect the answer to look like:\n\n```bash\nqmd query $'hyde: The migration plan involves three phases. First, we add the new columns without dropping the old ones. Then we backfill data. Finally we cut over and remove legacy columns.'\n```\n\n### Scoping to Collections\n\n```bash\nqmd search \"query\" --collection notes\nqmd query \"query\" --collection project-docs\n```\n\n### Output Formats\n\n```bash\nqmd search \"query\" --json        # JSON output (best for parsing)\nqmd search \"query\" --limit 5     # Limit results\nqmd get \"#abc123\"                # Get by document ID\nqmd get \"path\u002Fto\u002Ffile.md\"       # Get by file path\nqmd get \"file.md:50\" -l 100     # Get specific line range\nqmd multi-get \"journals\u002F*.md\" --json  # Batch retrieve by glob\n```\n\n## MCP Integration (Recommended)\n\nqmd exposes an MCP server that provides search tools directly to\nHermes Agent via the native MCP client. This is the preferred\nintegration — once configured, the agent gets qmd tools automatically\nwithout needing to load this skill.\n\n### Option A: Stdio Mode (Simple)\n\nAdd to `~\u002F.hermes\u002Fconfig.yaml`:\n\n```yaml\nmcp_servers:\n  qmd:\n    command: \"qmd\"\n    args: [\"mcp\"]\n    timeout: 30\n    connect_timeout: 45\n```\n\nThis registers tools: `mcp_qmd_search`, `mcp_qmd_vsearch`,\n`mcp_qmd_deep_search`, `mcp_qmd_get`, `mcp_qmd_status`.\n\n**Tradeoff:** Models load on first search call (~19s cold start),\nthen stay warm for the session. Acceptable for occasional use.\n\n### Option B: HTTP Daemon Mode (Fast, Recommended for Heavy Use)\n\nStart the qmd daemon separately — it keeps models warm in memory:\n\n```bash\n# Start daemon (persists across agent restarts)\nqmd mcp --http --daemon\n\n# Runs on http:\u002F\u002Flocalhost:8181 by default\n```\n\nThen configure Hermes Agent to connect via HTTP:\n\n```yaml\nmcp_servers:\n  qmd:\n    url: \"http:\u002F\u002Flocalhost:8181\u002Fmcp\"\n    timeout: 30\n```\n\n**Tradeoff:** Uses ~2GB RAM while running, but every query is fast\n(~2-3s). Best for users who search frequently.\n\n### Keeping the Daemon Running\n\n#### macOS (launchd)\n\n```bash\ncat > ~\u002FLibrary\u002FLaunchAgents\u002Fcom.qmd.daemon.plist \u003C\u003C 'EOF'\n\u003C?xml version=\"1.0\" encoding=\"UTF-8\"?>\n\u003C!DOCTYPE plist PUBLIC \"-\u002F\u002FApple\u002F\u002FDTD PLIST 1.0\u002F\u002FEN\"\n  \"http:\u002F\u002Fwww.apple.com\u002FDTDs\u002FPropertyList-1.0.dtd\">\n\u003Cplist version=\"1.0\">\n\u003Cdict>\n  \u003Ckey>Label\u003C\u002Fkey>\n  \u003Cstring>com.qmd.daemon\u003C\u002Fstring>\n  \u003Ckey>ProgramArguments\u003C\u002Fkey>\n  \u003Carray>\n    \u003Cstring>qmd\u003C\u002Fstring>\n    \u003Cstring>mcp\u003C\u002Fstring>\n    \u003Cstring>--http\u003C\u002Fstring>\n    \u003Cstring>--daemon\u003C\u002Fstring>\n  \u003C\u002Farray>\n  \u003Ckey>RunAtLoad\u003C\u002Fkey>\n  \u003Ctrue\u002F>\n  \u003Ckey>KeepAlive\u003C\u002Fkey>\n  \u003Ctrue\u002F>\n  \u003Ckey>StandardOutPath\u003C\u002Fkey>\n  \u003Cstring>\u002Ftmp\u002Fqmd-daemon.log\u003C\u002Fstring>\n  \u003Ckey>StandardErrorPath\u003C\u002Fkey>\n  \u003Cstring>\u002Ftmp\u002Fqmd-daemon.log\u003C\u002Fstring>\n\u003C\u002Fdict>\n\u003C\u002Fplist>\nEOF\n\nlaunchctl load ~\u002FLibrary\u002FLaunchAgents\u002Fcom.qmd.daemon.plist\n```\n\n#### Linux (systemd user service)\n\n```bash\nmkdir -p ~\u002F.config\u002Fsystemd\u002Fuser\n\ncat > ~\u002F.config\u002Fsystemd\u002Fuser\u002Fqmd-daemon.service \u003C\u003C 'EOF'\n[Unit]\nDescription=QMD MCP Daemon\nAfter=network.target\n\n[Service]\nExecStart=qmd mcp --http --daemon\nRestart=on-failure\nRestartSec=10\nEnvironment=PATH=\u002Fusr\u002Flocal\u002Fbin:\u002Fusr\u002Fbin:\u002Fbin\n\n[Install]\nWantedBy=default.target\nEOF\n\nsystemctl --user daemon-reload\nsystemctl --user enable --now qmd-daemon\nsystemctl --user status qmd-daemon\n```\n\n### MCP Tools Reference\n\nOnce connected, these tools are available as `mcp_qmd_*`:\n\n| MCP Tool | Maps To | Description |\n|----------|---------|-------------|\n| `mcp_qmd_search` | `qmd search` | BM25 keyword search |\n| `mcp_qmd_vsearch` | `qmd vsearch` | Semantic vector search |\n| `mcp_qmd_deep_search` | `qmd query` | Hybrid search + reranking |\n| `mcp_qmd_get` | `qmd get` | Retrieve document by ID or path |\n| `mcp_qmd_status` | `qmd status` | Index health and stats |\n\nThe MCP tools accept structured JSON queries for multi-mode search:\n\n```json\n{\n  \"searches\": [\n    {\"type\": \"lex\", \"query\": \"authentication middleware\"},\n    {\"type\": \"vec\", \"query\": \"how user login is verified\"}\n  ],\n  \"collections\": [\"project-docs\"],\n  \"limit\": 10\n}\n```\n\n## CLI Usage (Without MCP)\n\nWhen MCP is not configured, use qmd directly via terminal:\n\n```\nterminal(command=\"qmd query 'what was decided about the API redesign' --json\", timeout=30)\n```\n\nFor setup and management tasks, always use terminal:\n\n```\nterminal(command=\"qmd collection add ~\u002FDocuments\u002Fnotes --name notes\")\nterminal(command=\"qmd context add qmd:\u002F\u002Fnotes 'Personal research notes and ideas'\")\nterminal(command=\"qmd embed\")\nterminal(command=\"qmd status\")\n```\n\n## How the Search Pipeline Works\n\nUnderstanding the internals helps choose the right search mode:\n\n1. **Query Expansion** — A fine-tuned 1.7B model generates 2 alternative\n   queries. The original gets 2x weight in fusion.\n2. **Parallel Retrieval** — BM25 (SQLite FTS5) and vector search run\n   simultaneously across all query variants.\n3. **RRF Fusion** — Reciprocal Rank Fusion (k=60) merges results.\n   Top-rank bonus: #1 gets +0.05, #2-3 get +0.02.\n4. **LLM Reranking** — qwen3-reranker scores top 30 candidates (0.0-1.0).\n5. **Position-Aware Blending** — Ranks 1-3: 75% retrieval \u002F 25% reranker.\n   Ranks 4-10: 60\u002F40. Ranks 11+: 40\u002F60 (trusts reranker more for long tail).\n\n**Smart Chunking:** Documents are split at natural break points (headings,\ncode blocks, blank lines) targeting ~900 tokens with 15% overlap. Code\nblocks are never split mid-block.\n\n## Best Practices\n\n1. **Always add context descriptions** — `qmd context add` dramatically\n   improves retrieval accuracy. Describe what each collection contains.\n2. **Re-embed after adding documents** — `qmd embed` must be re-run when\n   new files are added to collections.\n3. **Use `qmd search` for speed** — when you need fast keyword lookup\n   (code identifiers, exact names), BM25 is instant and needs no models.\n4. **Use `qmd query` for quality** — when the question is conceptual or\n   the user needs the best possible results, use hybrid search.\n5. **Prefer MCP integration** — once configured, the agent gets native\n   tools without needing to load this skill each time.\n6. **Daemon mode for frequent users** — if the user searches their\n   knowledge base regularly, recommend the HTTP daemon setup.\n7. **First query in structured search gets 2x weight** — put the most\n   important\u002Fcertain query first when combining lex and vec.\n\n## Troubleshooting\n\n### \"Models downloading on first run\"\nNormal — qmd auto-downloads ~2GB of GGUF models on first use.\nThis is a one-time operation.\n\n### Cold start latency (~19s)\nThis happens when models aren't loaded in memory. Solutions:\n- Use HTTP daemon mode (`qmd mcp --http --daemon`) to keep warm\n- Use `qmd search` (BM25 only) when models aren't needed\n- MCP stdio mode loads models on first search, stays warm for session\n\n### macOS: \"unable to load extension\"\nInstall Homebrew SQLite: `brew install sqlite`\nThen ensure it's on PATH before system SQLite.\n\n### \"No collections found\"\nRun `qmd collection add \u003Cpath> --name \u003Cname>` to add directories,\nthen `qmd embed` to index them.\n\n### Embedding model override (CJK\u002Fmultilingual)\nSet `QMD_EMBED_MODEL` environment variable for non-English content:\n```bash\nexport QMD_EMBED_MODEL=\"your-multilingual-model\"\n```\n\n## Data Storage\n\n- **Index & vectors:** `~\u002F.cache\u002Fqmd\u002Findex.sqlite`\n- **Models:** Auto-downloaded to local cache on first run\n- **No cloud dependencies** — everything runs locally\n\n## References\n\n- [GitHub: tobi\u002Fqmd](https:\u002F\u002Fgithub.com\u002Ftobi\u002Fqmd)\n- [QMD Changelog](https:\u002F\u002Fgithub.com\u002Ftobi\u002Fqmd\u002Fblob\u002Fmain\u002FCHANGELOG.md)\n","# QMD — Query Markup Documents\n\nLocal, on-device search engine for personal knowledge bases. Indexes markdown\nnotes, meeting transcripts, documentation, and any text-based files, then\nprovides hybrid search combining keyword matching, semantic understanding, and\nLLM-powered reranking — all running locally with no cloud dependencies.\n\nCreated by [Tobi Lütke](https:\u002F\u002Fgithub.com\u002Ftobi\u002Fqmd). MIT licensed.\n\n## When to Use\n\n- User asks to search their notes, docs, knowledge base, or meeting transcripts\n- User wants to find something across a large collection of markdown\u002Ftext files\n- User wants semantic search (\"find notes about X concept\") not just keyword grep\n- User has already set up qmd collections and wants to query them\n- User asks to set up a local knowledge base or document search system\n- Keywords: \"search my notes\", \"find in my docs\", \"knowledge base\", \"qmd\"\n\n## Prerequisites\n\n### Node.js >= 22 (required)\n\n```bash\n# Check version\nnode --version  # must be >= 22\n\n# macOS — install or upgrade via Homebrew\nbrew install node@22\n\n# Linux — use NodeSource or nvm\ncurl -fsSL https:\u002F\u002Fdeb.nodesource.com\u002Fsetup_22.x | sudo -E bash -\nsudo apt-get install -y nodejs\n# or with nvm:\nnvm install 22 && nvm use 22\n```\n\n### SQLite with Extension Support (macOS only)\n\nmacOS system SQLite lacks extension loading. Install via Homebrew:\n\n```bash\nbrew install sqlite\n```\n\n### Install qmd\n\n```bash\nnpm install -g @tobilu\u002Fqmd\n# or with Bun:\nbun install -g @tobilu\u002Fqmd\n```\n\nFirst run auto-downloads 3 local GGUF models (~2GB total):\n\n| Model | Purpose | Size |\n|-------|---------|------|\n| embeddinggemma-300M-Q8_0 | Vector embeddings | ~300MB |\n| qwen3-reranker-0.6b-q8_0 | Result reranking | ~640MB |\n| qmd-query-expansion-1.7B | Query expansion | ~1.1GB |\n\n### Verify Installation\n\n```bash\nqmd --version\nqmd status\n```\n\n## Quick Reference\n\n| Command | What It Does | Speed |\n|---------|-------------|-------|\n| `qmd search \"query\"` | BM25 keyword search (no models) | ~0.2s |\n| `qmd vsearch \"query\"` | Semantic vector search (1 model) | ~3s |\n| `qmd query \"query\"` | Hybrid + reranking (all 3 models) | ~2-3s warm, ~19s cold |\n| `qmd get \u003Cdocid>` | Retrieve full document content | instant |\n| `qmd multi-get \"glob\"` | Retrieve multiple files | instant |\n| `qmd collection add \u003Cpath> --name \u003Cn>` | Add a directory as a collection | instant |\n| `qmd context add \u003Cpath> \"description\"` | Add context metadata to improve retrieval | instant |\n| `qmd embed` | Generate\u002Fupdate vector embeddings | varies |\n| `qmd status` | Show index health and collection info | instant |\n| `qmd mcp` | Start MCP server (stdio) | persistent |\n| `qmd mcp --http --daemon` | Start MCP server (HTTP, warm models) | persistent |\n\n## Setup Workflow\n\n### 1. Add Collections\n\nPoint qmd at directories containing your documents:\n\n```bash\n# Add a notes directory\nqmd collection add ~\u002Fnotes --name notes\n\n# Add project docs\nqmd collection add ~\u002Fprojects\u002Fmyproject\u002Fdocs --name project-docs\n\n# Add meeting transcripts\nqmd collection add ~\u002Fmeetings --name meetings\n\n# List all collections\nqmd collection list\n```\n\n### 2. Add Context Descriptions\n\nContext metadata helps the search engine understand what each collection\ncontains. This significantly improves retrieval quality:\n\n```bash\nqmd context add qmd:\u002F\u002Fnotes \"Personal notes, ideas, and journal entries\"\nqmd context add qmd:\u002F\u002Fproject-docs \"Technical documentation for the main project\"\nqmd context add qmd:\u002F\u002Fmeetings \"Meeting transcripts and action items from team syncs\"\n```\n\n### 3. Generate Embeddings\n\n```bash\nqmd embed\n```\n\nThis processes all documents in all collections and generates vector\nembeddings. Re-run after adding new documents or collections.\n\n### 4. Verify\n\n```bash\nqmd status   # shows index health, collection stats, model info\n```\n\n## Search Patterns\n\n### Fast Keyword Search (BM25)\n\nBest for: exact terms, code identifiers, names, known phrases.\nNo models loaded — near-instant results.\n\n```bash\nqmd search \"authentication middleware\"\nqmd search \"handleError async\"\n```\n\n### Semantic Vector Search\n\nBest for: natural language questions, conceptual queries.\nLoads embedding model (~3s first query).\n\n```bash\nqmd vsearch \"how does the rate limiter handle burst traffic\"\nqmd vsearch \"ideas for improving onboarding flow\"\n```\n\n### Hybrid Search with Reranking (Best Quality)\n\nBest for: important queries where quality matters most.\nUses all 3 models — query expansion, parallel BM25+vector, reranking.\n\n```bash\nqmd query \"what decisions were made about the database migration\"\n```\n\n### Structured Multi-Mode Queries\n\nCombine different search types in a single query for precision:\n\n```bash\n# BM25 for exact term + vector for concept\nqmd query $'lex: rate limiter\\nvec: how does throttling work under load'\n\n# With query expansion\nqmd query $'expand: database migration plan\\nlex: \"schema change\"'\n```\n\n### Query Syntax (lex\u002FBM25 mode)\n\n| Syntax | Effect | Example |\n|--------|--------|---------|\n| `term` | Prefix match | `perf` matches \"performance\" |\n| `\"phrase\"` | Exact phrase | `\"rate limiter\"` |\n| `-term` | Exclude term | `performance -sports` |\n\n### HyDE (Hypothetical Document Embeddings)\n\nFor complex topics, write what you expect the answer to look like:\n\n```bash\nqmd query $'hyde: The migration plan involves three phases. First, we add the new columns without dropping the old ones. Then we backfill data. Finally we cut over and remove legacy columns.'\n```\n\n### Scoping to Collections\n\n```bash\nqmd search \"query\" --collection notes\nqmd query \"query\" --collection project-docs\n```\n\n### Output Formats\n\n```bash\nqmd search \"query\" --json        # JSON output (best for parsing)\nqmd search \"query\" --limit 5     # Limit results\nqmd get \"#abc123\"                # Get by document ID\nqmd get \"path\u002Fto\u002Ffile.md\"       # Get by file path\nqmd get \"file.md:50\" -l 100     # Get specific line range\nqmd multi-get \"journals\u002F*.md\" --json  # Batch retrieve by glob\n```\n\n## MCP Integration (Recommended)\n\nqmd exposes an MCP server that provides search tools directly to\nHermes Agent via the native MCP client. This is the preferred\nintegration — once configured, the agent gets qmd tools automatically\nwithout needing to load this skill.\n\n### Option A: Stdio Mode (Simple)\n\nAdd to `~\u002F.hermes\u002Fconfig.yaml`:\n\n```yaml\nmcp_servers:\n  qmd:\n    command: \"qmd\"\n    args: [\"mcp\"]\n    timeout: 30\n    connect_timeout: 45\n```\n\nThis registers tools: `mcp_qmd_search`, `mcp_qmd_vsearch`,\n`mcp_qmd_deep_search`, `mcp_qmd_get`, `mcp_qmd_status`.\n\n**Tradeoff:** Models load on first search call (~19s cold start),\nthen stay warm for the session. Acceptable for occasional use.\n\n### Option B: HTTP Daemon Mode (Fast, Recommended for Heavy Use)\n\nStart the qmd daemon separately — it keeps models warm in memory:\n\n```bash\n# Start daemon (persists across agent restarts)\nqmd mcp --http --daemon\n\n# Runs on http:\u002F\u002Flocalhost:8181 by default\n```\n\nThen configure Hermes Agent to connect via HTTP:\n\n```yaml\nmcp_servers:\n  qmd:\n    url: \"http:\u002F\u002Flocalhost:8181\u002Fmcp\"\n    timeout: 30\n```\n\n**Tradeoff:** Uses ~2GB RAM while running, but every query is fast\n(~2-3s). Best for users who search frequently.\n\n### Keeping the Daemon Running\n\n#### macOS (launchd)\n\n```bash\ncat > ~\u002FLibrary\u002FLaunchAgents\u002Fcom.qmd.daemon.plist \u003C\u003C 'EOF'\n\u003C?xml version=\"1.0\" encoding=\"UTF-8\"?>\n\u003C!DOCTYPE plist PUBLIC \"-\u002F\u002FApple\u002F\u002FDTD PLIST 1.0\u002F\u002FEN\"\n  \"http:\u002F\u002Fwww.apple.com\u002FDTDs\u002FPropertyList-1.0.dtd\">\n\u003Cplist version=\"1.0\">\n\u003Cdict>\n  \u003Ckey>Label\u003C\u002Fkey>\n  \u003Cstring>com.qmd.daemon\u003C\u002Fstring>\n  \u003Ckey>ProgramArguments\u003C\u002Fkey>\n  \u003Carray>\n    \u003Cstring>qmd\u003C\u002Fstring>\n    \u003Cstring>mcp\u003C\u002Fstring>\n    \u003Cstring>--http\u003C\u002Fstring>\n    \u003Cstring>--daemon\u003C\u002Fstring>\n  \u003C\u002Farray>\n  \u003Ckey>RunAtLoad\u003C\u002Fkey>\n  \u003Ctrue\u002F>\n  \u003Ckey>KeepAlive\u003C\u002Fkey>\n  \u003Ctrue\u002F>\n  \u003Ckey>StandardOutPath\u003C\u002Fkey>\n  \u003Cstring>\u002Ftmp\u002Fqmd-daemon.log\u003C\u002Fstring>\n  \u003Ckey>StandardErrorPath\u003C\u002Fkey>\n  \u003Cstring>\u002Ftmp\u002Fqmd-daemon.log\u003C\u002Fstring>\n\u003C\u002Fdict>\n\u003C\u002Fplist>\nEOF\n\nlaunchctl load ~\u002FLibrary\u002FLaunchAgents\u002Fcom.qmd.daemon.plist\n```\n\n#### Linux (systemd user service)\n\n```bash\nmkdir -p ~\u002F.config\u002Fsystemd\u002Fuser\n\ncat > ~\u002F.config\u002Fsystemd\u002Fuser\u002Fqmd-daemon.service \u003C\u003C 'EOF'\n[Unit]\nDescription=QMD MCP Daemon\nAfter=network.target\n\n[Service]\nExecStart=qmd mcp --http --daemon\nRestart=on-failure\nRestartSec=10\nEnvironment=PATH=\u002Fusr\u002Flocal\u002Fbin:\u002Fusr\u002Fbin:\u002Fbin\n\n[Install]\nWantedBy=default.target\nEOF\n\nsystemctl --user daemon-reload\nsystemctl --user enable --now qmd-daemon\nsystemctl --user status qmd-daemon\n```\n\n### MCP Tools Reference\n\nOnce connected, these tools are available as `mcp_qmd_*`:\n\n| MCP Tool | Maps To | Description |\n|----------|---------|-------------|\n| `mcp_qmd_search` | `qmd search` | BM25 keyword search |\n| `mcp_qmd_vsearch` | `qmd vsearch` | Semantic vector search |\n| `mcp_qmd_deep_search` | `qmd query` | Hybrid search + reranking |\n| `mcp_qmd_get` | `qmd get` | Retrieve document by ID or path |\n| `mcp_qmd_status` | `qmd status` | Index health and stats |\n\nThe MCP tools accept structured JSON queries for multi-mode search:\n\n```json\n{\n  \"searches\": [\n    {\"type\": \"lex\", \"query\": \"authentication middleware\"},\n    {\"type\": \"vec\", \"query\": \"how user login is verified\"}\n  ],\n  \"collections\": [\"project-docs\"],\n  \"limit\": 10\n}\n```\n\n## CLI Usage (Without MCP)\n\nWhen MCP is not configured, use qmd directly via terminal:\n\n```\nterminal(command=\"qmd query 'what was decided about the API redesign' --json\", timeout=30)\n```\n\nFor setup and management tasks, always use terminal:\n\n```\nterminal(command=\"qmd collection add ~\u002FDocuments\u002Fnotes --name notes\")\nterminal(command=\"qmd context add qmd:\u002F\u002Fnotes 'Personal research notes and ideas'\")\nterminal(command=\"qmd embed\")\nterminal(command=\"qmd status\")\n```\n\n## How the Search Pipeline Works\n\nUnderstanding the internals helps choose the right search mode:\n\n1. **Query Expansion** — A fine-tuned 1.7B model generates 2 alternative\n   queries. The original gets 2x weight in fusion.\n2. **Parallel Retrieval** — BM25 (SQLite FTS5) and vector search run\n   simultaneously across all query variants.\n3. **RRF Fusion** — Reciprocal Rank Fusion (k=60) merges results.\n   Top-rank bonus: #1 gets +0.05, #2-3 get +0.02.\n4. **LLM Reranking** — qwen3-reranker scores top 30 candidates (0.0-1.0).\n5. **Position-Aware Blending** — Ranks 1-3: 75% retrieval \u002F 25% reranker.\n   Ranks 4-10: 60\u002F40. Ranks 11+: 40\u002F60 (trusts reranker more for long tail).\n\n**Smart Chunking:** Documents are split at natural break points (headings,\ncode blocks, blank lines) targeting ~900 tokens with 15% overlap. Code\nblocks are never split mid-block.\n\n## Best Practices\n\n1. **Always add context descriptions** — `qmd context add` dramatically\n   improves retrieval accuracy. Describe what each collection contains.\n2. **Re-embed after adding documents** — `qmd embed` must be re-run when\n   new files are added to collections.\n3. **Use `qmd search` for speed** — when you need fast keyword lookup\n   (code identifiers, exact names), BM25 is instant and needs no models.\n4. **Use `qmd query` for quality** — when the question is conceptual or\n   the user needs the best possible results, use hybrid search.\n5. **Prefer MCP integration** — once configured, the agent gets native\n   tools without needing to load this skill each time.\n6. **Daemon mode for frequent users** — if the user searches their\n   knowledge base regularly, recommend the HTTP daemon setup.\n7. **First query in structured search gets 2x weight** — put the most\n   important\u002Fcertain query first when combining lex and vec.\n\n## Troubleshooting\n\n### \"Models downloading on first run\"\nNormal — qmd auto-downloads ~2GB of GGUF models on first use.\nThis is a one-time operation.\n\n### Cold start latency (~19s)\nThis happens when models aren't loaded in memory. Solutions:\n- Use HTTP daemon mode (`qmd mcp --http --daemon`) to keep warm\n- Use `qmd search` (BM25 only) when models aren't needed\n- MCP stdio mode loads models on first search, stays warm for session\n\n### macOS: \"unable to load extension\"\nInstall Homebrew SQLite: `brew install sqlite`\nThen ensure it's on PATH before system SQLite.\n\n### \"No collections found\"\nRun `qmd collection add \u003Cpath> --name \u003Cname>` to add directories,\nthen `qmd embed` to index them.\n\n### Embedding model override (CJK\u002Fmultilingual)\nSet `QMD_EMBED_MODEL` environment variable for non-English content:\n```bash\nexport QMD_EMBED_MODEL=\"your-multilingual-model\"\n```\n\n## Data Storage\n\n- **Index & vectors:** `~\u002F.cache\u002Fqmd\u002Findex.sqlite`\n- **Models:** Auto-downloaded to local cache on first run\n- **No cloud dependencies** — everything runs locally\n\n## References\n\n- [GitHub: tobi\u002Fqmd](https:\u002F\u002Fgithub.com\u002Ftobi\u002Fqmd)\n- [QMD Changelog](https:\u002F\u002Fgithub.com\u002Ftobi\u002Fqmd\u002Fblob\u002Fmain\u002FCHANGELOG.md)\n",{"name":5,"author":24,"license":15,"version":25,"metadata":26,"platforms":39,"description":7},"Hermes Agent + Teknium","1.0.0",{"hermes":27},{"tags":28,"related_skills":35},[29,30,31,32,33,34],"Search","Knowledge-Base","RAG","Notes","MCP","Local-AI",[36,37,38],"obsidian","native-mcp","arxiv",[40,41],"macos","linux","main","ff3476b880e3f7eddb4ffe2b62141766402e972b","core-agent\u002Foptional-skills\u002Fresearch\u002Fqmd","https:\u002F\u002Fgithub.com\u002Faniruddhaadak80\u002Fherclew","https:\u002F\u002Fgithub.com\u002Faniruddhaadak80","https:\u002F\u002Faniruddha-adak.vercel.app","I build agentic harnesses and production-grade agent skills. \r\n\r\nContributor :) @genspark-ai @CopilotKit @openclaw @NousResearch  @synthetic-sciences @PriorLabs","2026-11-14 20:45:37",{"source":8,"skillName":5,"commands":51,"prompt":61,"zipAvailable":62},[52,55,58],{"tool":53,"command":54},"npx","npx skills add aniruddhaadak80\u002Fherclew --skill qmd",{"tool":56,"command":57},"bunx","bunx skills add aniruddhaadak80\u002Fherclew --skill qmd",{"tool":59,"command":60},"pnpm","pnpm dlx skills add aniruddhaadak80\u002Fherclew --skill qmd","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Faniruddhaadak80\u002Fherclew\u002Fblob\u002Fmain\u002Fcore-agent\u002Foptional-skills\u002Fresearch\u002Fqmd\u002FSKILL.md",true,[],[65,74,82,89,96,103],{"skillNo":66,"name":67,"nameZh":6,"description":68,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":69,"licenseFileUrl":70,"sourceHtmlUrl":71,"categories":72,"keywords":73,"publishedAt":19},"01M74FJW4M7QZ5KZHYH1W3SYET","skill-creator","Create, edit, audit, tidy, validate, or restructure AgentSkills and SKILL.md files.","Apache-2.0","https:\u002F\u002Fgithub.com\u002Faniruddhaadak80\u002Fherclew\u002Fblob\u002Fmain\u002Fgateway-node\u002Fskills\u002Fsoftware-development\u002Fskill-creator\u002Flicense.txt","https:\u002F\u002Fgithub.com\u002Faniruddhaadak80\u002Fherclew\u002Fblob\u002Fmain\u002Fgateway-node\u002Fskills\u002Fsoftware-development\u002Fskill-creator\u002FSKILL.md",[],[],{"skillNo":75,"name":76,"nameZh":6,"description":77,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":78,"sourceHtmlUrl":79,"categories":80,"keywords":81,"publishedAt":19},"01M74FDY7EK673NW905BRFR3ZD","prose","OpenProse VM skill pack. Activate on any `prose` command, .prose files, or OpenProse mentions; orchestrates multi-agent workflows.","https:\u002F\u002Fgithub.com\u002Faniruddhaadak80\u002Fherclew\u002Fblob\u002Fmain\u002Fgateway-node\u002Fextensions\u002Fopen-prose\u002Fskills\u002Fprose\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Faniruddhaadak80\u002Fherclew\u002Fblob\u002Fmain\u002Fgateway-node\u002Fextensions\u002Fopen-prose\u002Fskills\u002Fprose\u002FSKILL.md",[],[],{"skillNo":83,"name":84,"nameZh":6,"description":85,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":86,"categories":87,"keywords":88,"publishedAt":19},"01M74FAMG647DMCPE12FZE3PKF","writing-plans","Write implementation plans: bite-sized tasks, paths, code.","https:\u002F\u002Fgithub.com\u002Faniruddhaadak80\u002Fherclew\u002Fblob\u002Fmain\u002Fcore-agent\u002Fskills\u002Fsoftware-development\u002Fwriting-plans\u002FSKILL.md",[],[],{"skillNo":90,"name":91,"nameZh":6,"description":92,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":93,"categories":94,"keywords":95,"publishedAt":19},"01M74FAHVK9XY77HSP589QYQYB","test-driven-development","TDD: enforce RED-GREEN-REFACTOR, tests before code.","https:\u002F\u002Fgithub.com\u002Faniruddhaadak80\u002Fherclew\u002Fblob\u002Fmain\u002Fcore-agent\u002Fskills\u002Fsoftware-development\u002Ftest-driven-development\u002FSKILL.md",[],[],{"skillNo":97,"name":98,"nameZh":6,"description":99,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":100,"categories":101,"keywords":102,"publishedAt":19},"01M74FAECYXZ2DQXQSQ44FHZJZ","systematic-debugging","4-phase root cause debugging: understand bugs before fixing.","https:\u002F\u002Fgithub.com\u002Faniruddhaadak80\u002Fherclew\u002Fblob\u002Fmain\u002Fcore-agent\u002Fskills\u002Fsoftware-development\u002Fsystematic-debugging\u002FSKILL.md",[],[],{"skillNo":104,"name":105,"nameZh":6,"description":106,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":107,"categories":108,"keywords":109,"publishedAt":19},"01M74FABCBB1Z2Y5F67699RPX6","subagent-driven-development","Execute plans via delegate_task subagents (2-stage review).","https:\u002F\u002Fgithub.com\u002Faniruddhaadak80\u002Fherclew\u002Fblob\u002Fmain\u002Fcore-agent\u002Fskills\u002Fsoftware-development\u002Fsubagent-driven-development\u002FSKILL.md",[],[]]