Back to Details

qmd

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

QMD - Quick Markdown Search

QMD - 快速Markdown搜索工具

Local search engine for markdown content.
用于Markdown内容的本地搜索引擎。

Status

状态

!
qmd status 2>/dev/null || echo "Not installed: npm install -g @tobilu/qmd"
!
qmd status 2>/dev/null || echo "Not installed: npm install -g @tobilu/qmd"

MCP: 
query

MCP: 
query

json
{
  "searches": [
    { "type": "lex", "query": "CAP theorem consistency" },
    { "type": "vec", "query": "tradeoff between consistency and availability" }
  ],
  "collections": ["docs"],
  "limit": 10
}
json
{
  "searches": [
    { "type": "lex", "query": "CAP theorem consistency" },
    { "type": "vec", "query": "tradeoff between consistency and availability" }
  ],
  "collections": ["docs"],
  "limit": 10
}

Query Types

查询类型

TypeMethodInput
lex
BM25Keywords — exact terms, names, code
vec
VectorQuestion — natural language
hyde
VectorAnswer — hypothetical result (50-100 words)
类型方法输入
lex
BM25关键词 — 精确术语、名称、代码
vec
向量问题 — 自然语言
hyde
向量答案 — 假设性结果（50-100字）

Writing Good Queries

如何写出高质量的查询语句

lex (keyword)
  • 2-5 terms, no filler words
  • Exact phrase: 
    "connection pool"
    (quoted)
  • Exclude terms: 
    performance -sports
    (minus prefix)
  • Code identifiers work: 
    handleError async
vec (semantic)
  • Full natural language question
  • Be specific: 
    "how does the rate limiter handle burst traffic"
  • Include context: 
    "in the payment service, how are refunds processed"
hyde (hypothetical document)
  • Write 50-100 words of what the answer looks like
  • Use the vocabulary you expect in the result
expand (auto-expand)
  • Use a single-line query (implicit) or 
    expand: question
    on its own line
  • Lets the local LLM generate lex/vec/hyde variations
  • Do not mix 
    expand:
    with other typed lines — it's either a standalone expand query or a full query document
lex (关键词)
  • 2-5个术语，无填充词
  • 精确短语：
    "connection pool"
    （加引号）
  • 排除术语：
    performance -sports
    （加前缀减号）
  • 支持代码标识符：
    handleError async
vec (语义)
  • 完整的自然语言问题
  • 尽量具体：
    "how does the rate limiter handle burst traffic"
  • 包含上下文：
    "in the payment service, how are refunds processed"
hyde (假设文档)
  • 撰写50-100字描述你期望的答案内容
  • 使用你认为结果中会出现的词汇
expand (自动扩展)
  • 使用单行查询（隐式）或单独一行写
    expand: 问题
  • 让本地LLM生成lex/vec/hyde的变体查询
  • 不要将
    expand:
    和其他类型的行混合使用 — 要么是独立的expand查询，要么是完整的查询文档

Intent (Disambiguation)

意图（消歧）

When a query term is ambiguous, add 
intent
to steer results:
json
{
  "searches": [
    { "type": "lex", "query": "performance" }
  ],
  "intent": "web page load times and Core Web Vitals"
}
Intent affects expansion, reranking, chunk selection, and snippet extraction. It does not search on its own — it's a steering signal that disambiguates queries like "performance" (web-perf vs team health vs fitness).
当查询术语存在歧义时，添加
intent
来引导结果：
json
{
  "searches": [
    { "type": "lex", "query": "performance" }
  ],
  "intent": "web page load times and Core Web Vitals"
}
意图会影响查询扩展、重排序、片段选择和摘要提取。它本身不会执行搜索 — 它是一个引导信号，用于消除类似“performance”这类查询的歧义（是网页性能、团队健康还是健身相关）。

Combining Types

查询类型组合

GoalApproach
Know exact terms
lex
only
Don't know vocabularyUse a single-line query (implicit 
expand:
) or 
vec
Best recall
lex
+ 
vec
Complex topic
lex
+ 
vec
+ 
hyde
Ambiguous queryAdd 
intent
to any combination above
First query gets 2x weight in fusion — put your best guess first.
目标方案
知道精确术语仅用
lex
不清楚相关词汇使用单行查询（隐式
expand:
）或
vec
最高召回率
lex
+ 
vec
复杂主题
lex
+ 
vec
+ 
hyde
歧义查询在以上任意组合中添加
intent
第一个查询在融合时权重翻倍 — 把你认为最可能的查询放在最前面。

Lex Query Syntax

Lex查询语法

SyntaxMeaningExample
term
Prefix match
perf
matches "performance"
"phrase"
Exact phrase
"rate limiter"
-term
Exclude
performance -sports
Note: 
-term
only works in lex queries, not vec/hyde.
语法含义示例
term
前缀匹配
perf
匹配 "performance"
"phrase"
精确短语匹配
"rate limiter"
-term
排除该术语
performance -sports
注意：
-term
仅在lex查询中生效，vec/hyde查询不支持。

Collection Filtering

集合过滤

json
{ "collections": ["docs"] }              // Single
{ "collections": ["docs", "notes"] }     // Multiple (OR)
Omit to search all collections.
json
{ "collections": ["docs"] }              // 单个集合
{ "collections": ["docs", "notes"] }     // 多个集合（OR逻辑）
省略该字段则搜索所有集合。

Other MCP Tools

其他MCP工具

ToolUse
get
Retrieve doc by path or 
#docid
multi_get
Retrieve multiple by glob/list
status
Collections and health
工具用途
get
通过路径或
#docid
获取文档
multi_get
通过通配符/列表获取多个文档
status
查看集合和服务健康状态

CLI

CLI

bash
qmd query "question"              # Auto-expand + rerank
qmd query $'lex: X\nvec: Y'       # Structured
qmd query $'expand: question'     # Explicit expand
qmd query --json --explain "q"    # Show score traces (RRF + rerank blend)
qmd search "keywords"             # BM25 only (no LLM)
qmd get "#abc123"                 # By docid
qmd multi-get "journals/2026-*.md" -l 40  # Batch pull snippets by glob
qmd multi-get notes/foo.md,notes/bar.md   # Comma-separated list, preserves order
bash
qmd query "question"              # 自动扩展 + 重排序
qmd query $'lex: X\nvec: Y'       # 结构化查询
qmd query $'expand: question'     # 显式扩展
qmd query --json --explain "q"    # 显示得分追踪（RRF + 重排序混合）
qmd search "keywords"             # 仅BM25搜索（无LLM参与）
qmd get "#abc123"                 # 通过docid获取
qmd multi-get "journals/2026-*.md" -l 40  # 按通配符批量拉取片段
qmd multi-get notes/foo.md,notes/bar.md   # 逗号分隔列表，保留顺序

HTTP API

HTTP API

bash
curl -X POST http://localhost:8181/query \
  -H "Content-Type: application/json" \
  -d '{"searches": [{"type": "lex", "query": "test"}]}'
bash
curl -X POST http://localhost:8181/query \
  -H "Content-Type: application/json" \
  -d '{"searches": [{"type": "lex", "query": "test"}]}'

Setup

安装配置

bash
npm install -g @tobilu/qmd
qmd collection add ~/notes --name notes
qmd embed
bash
npm install -g @tobilu/qmd
qmd collection add ~/notes --name notes
qmd embed