qmd

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

qmd - Quick Markdown Search

qmd - 快速Markdown搜索

Local search engine for Markdown notes, docs, and knowledge bases. Index once, search fast.

一款面向Markdown笔记、文档和知识库的本地搜索引擎。一次索引，快速搜索。

When to use (trigger phrases)

使用场景（触发语）

"search my notes / docs / knowledge base"
"find related notes"
"retrieve a markdown document from my collection"
"search local markdown files"

"搜索我的笔记 / 文档 / 知识库"
"查找相关笔记"
"从我的集合中检索Markdown文档"
"搜索本地Markdown文件"

Default behavior (important)

默认行为（重要）

Prefer
```
qmd search
```
(BM25). It's typically instant and should be the default.
Use
```
qmd vsearch
```
only when keyword search fails and you need semantic similarity (can be very slow on a cold start).
Avoid
```
qmd query
```
unless the user explicitly wants the highest quality hybrid results and can tolerate long runtimes/timeouts.

优先使用
```
qmd search
```
（BM25算法）。该模式通常能瞬间出结果，应作为默认选择。
仅当关键词搜索失败，且你需要语义相似度搜索时，才使用
```
qmd vsearch
```
（冷启动时可能非常缓慢）。
除非用户明确要求最高质量的混合搜索结果，且能容忍较长运行时间/超时，否则避免使用
```
qmd query
```
。

Prerequisites

前置要求

Bun >= 1.0.0
macOS:
```
brew install sqlite
```
(SQLite extensions)
Ensure PATH includes:
```
$HOME/.bun/bin
```

Install Bun (macOS):

brew install oven-sh/bun/bun

Bun >= 1.0.0
macOS:
```
brew install sqlite
```
（SQLite扩展）
确保PATH包含：
```
$HOME/.bun/bin
```

安装Bun（macOS）：

brew install oven-sh/bun/bun

Install

安装

bun install -g https://github.com/tobi/qmd

bun install -g https://github.com/tobi/qmd

Setup

配置

bash

qmd collection add /path/to/notes --name notes --mask "**/*.md"
qmd context add qmd://notes "Description of this collection"  # optional
qmd embed  # one-time to enable vector + hybrid search

bash

qmd collection add /path/to/notes --name notes --mask "**/*.md"
qmd context add qmd://notes "该集合的描述"  # 可选
qmd embed  # 仅需执行一次，用于启用向量+混合搜索

What it indexes

索引范围

Intended for Markdown collections (commonly
```
**/*.md
```
).
In our testing, "messy" Markdown is fine: chunking is content-based (roughly a few hundred tokens per chunk), not strict heading/structure based.
Not a replacement for code search; use code search tools for repositories/source trees.

专为Markdown集合设计（通常匹配
```
**/*.md
```
）。
测试表明，“不规范”的Markdown文件也能正常处理：分块基于内容（大致每块几百个tokens），而非严格基于标题/结构。
不能替代代码搜索工具；如需搜索代码仓库/源码树，请使用专门的代码搜索工具。

Search modes

搜索模式

```
qmd search
```
(default): fast keyword match (BM25)
```
qmd vsearch
```
(last resort): semantic similarity (vector). Often slow due to local LLM work before the vector lookup.
```
qmd query
```
(generally skip): hybrid search + LLM reranking. Often slower than
```
vsearch
```
and may timeout.

```
qmd search
```
（默认）：快速关键词匹配（BM25算法）
```
qmd vsearch
```
（最后选择）：语义相似度（向量）搜索。由于本地LLM运算，在向量查找前通常速度较慢。
```
qmd query
```
（通常跳过）：混合搜索+LLM重排序。通常比
```
vsearch
```
更慢，且可能超时。

Performance notes

性能说明

```
qmd search
```
is typically instant.
```
qmd vsearch
```
can be ~1 minute on some machines because query expansion may load a local model (e.g., Qwen3-1.7B) into memory per run; the vector lookup itself is usually fast.
```
qmd query
```
adds LLM reranking on top of
```
vsearch
```
, so it can be even slower and less reliable for interactive use.
If you need repeated semantic searches, consider keeping the process/model warm (e.g., a long-lived qmd/MCP server mode if available in your setup) rather than invoking a cold-start LLM each time.

```
qmd search
```
通常能瞬间出结果。
```
qmd vsearch
```
在部分机器上可能耗时约1分钟，因为查询扩展可能需要将本地模型（如Qwen3-1.7B）加载到内存中；向量查找本身通常很快。
```
qmd query
```
在
```
vsearch
```
基础上增加了LLM重排序，因此速度更慢，交互式使用时可靠性更低。
如需重复进行语义搜索，建议保持进程/模型处于预热状态（例如，若你的环境支持，可使用长期运行的qmd/MCP服务器模式），而非每次都启动冷LLM。

Common commands

常用命令

bash

qmd search "query"             # default
qmd vsearch "query"
qmd query "query"
qmd search "query" -c notes     # Search specific collection
qmd search "query" -n 10        # More results
qmd search "query" --json       # JSON output
qmd search "query" --all --files --min-score 0.3

bash

qmd search "query"             # 默认模式
qmd vsearch "query"
qmd query "query"
qmd search "query" -c notes     # 搜索指定集合
qmd search "query" -n 10        # 显示更多结果
qmd search "query" --json       # JSON格式输出
qmd search "query" --all --files --min-score 0.3

Useful options

实用选项

```
-n <num>
```
: number of results
```
-c, --collection <name>
```
: restrict to a collection
```
--all --min-score <num>
```
: return all matches above a threshold
```
--json
```
/
```
--files
```
: agent-friendly output formats
```
--full
```
: return full document content

```
-n <num>
```
：结果数量
```
-c, --collection <name>
```
：限定搜索指定集合
```
--all --min-score <num>
```
：返回所有高于阈值的匹配结果
```
--json
```
/
```
--files
```
：适用于Agent的输出格式
```
--full
```
：返回完整文档内容

Retrieve

文档检索

bash

qmd get "path/to/file.md"       # Full document
qmd get "#docid"                # By ID from search results
qmd multi-get "journals/2025-05*.md"
qmd multi-get "doc1.md, doc2.md, #abc123" --json

bash

qmd get "path/to/file.md"       # 获取完整文档
qmd get "#docid"                # 通过搜索结果中的ID获取
qmd multi-get "journals/2025-05*.md"
qmd multi-get "doc1.md, doc2.md, #abc123" --json

Maintenance

维护

bash

qmd status                      # Index health
qmd update                      # Re-index changed files
qmd embed                       # Update embeddings

bash

qmd status                      # 索引健康状态
qmd update                      # 重新索引已修改的文件
qmd embed                       # 更新嵌入向量

Keeping the index fresh

保持索引更新

Automate indexing so results stay current as you add/edit notes.

For keyword search (
```
qmd search
```
),
```
qmd update
```
is usually enough (fast).
If you rely on semantic/hybrid search (
```
vsearch
```
/
```
query
```
), you may also want
```
qmd embed
```
, but it can be slow.

Example schedules (cron):

bash

undefined

自动执行索引，确保在添加/编辑笔记时结果保持最新。

对于关键词搜索（
```
qmd search
```
），
```
qmd update
```
通常足够（速度快）。
若依赖语义/混合搜索（
```
vsearch
```
/
```
query
```
），你可能还需要执行
```
qmd embed
```
，但该操作速度较慢。

示例定时任务（cron）：

bash

undefined

Hourly incremental updates (keeps BM25 fresh):

每小时增量更新（保持BM25索引最新）：

0 * * * * export PATH="$HOME/.bun/bin:$PATH" && qmd update

Optional: nightly embedding refresh (can be slow):

可选：每晚更新嵌入向量（可能速度较慢）：

0 5 * * * export PATH="$HOME/.bun/bin:$PATH" && qmd embed


If your Clawdbot/agent environment supports a built-in scheduler, you can run the same commands there instead of system cron.

0 5 * * * export PATH="$HOME/.bun/bin:$PATH" && qmd embed


如果你的Clawdbot/Agent环境支持内置调度器，你可以在该环境中运行相同的命令，而非使用系统cron。

Models and cache

模型与缓存

Uses local GGUF models; first run auto-downloads them.
Default cache:
```
~/.cache/qmd/models/
```
(override with
```
XDG_CACHE_HOME
```
).

使用本地GGUF模型；首次运行时会自动下载。
默认缓存路径：
```
~/.cache/qmd/models/
```
（可通过
```
XDG_CACHE_HOME
```
覆盖）。

Relationship to Clawdbot memory search

与Clawdbot内存搜索的区别

```
qmd
```
searches your local files (notes/docs) that you explicitly index into collections.
Clawdbot's
```
memory_search
```
searches agent memory (saved facts/context from prior interactions).
Use both:
```
memory_search
```
for "what did we decide/learn before?",
```
qmd
```
for "what's in my notes/docs on disk?".

```
qmd
```
搜索的是你本地的文件（笔记/文档），这些文件需要你显式索引到集合中。
Clawdbot的
```
memory_search
```
搜索的是Agent内存（来自之前交互的已保存事实/上下文）。
两者可配合使用：
```
memory_search
```
用于查找“我们之前决定/了解到什么？”，
```
qmd
```
用于查找“我磁盘上的笔记/文档中有什么内容？”。