tobi/qmd

mini cli search engine for your docs, knowledge bases, meeting notes, whatever. Tracking current sota approaches while being all local

QMD – Query Markdown Documents

它是什么

一款本地、设备端搜索工具，适用于 Markdown 风格的笔记、转录文本、文档及其他知识库。
结合三种检索方法：
1. BM25 全文（关键词）搜索。
2. 向量语义搜索，使用嵌入。
3. LLM 重排序（通过 node-llama-cpp 和 GGUF 模型）提升相关性。
所有组件均在本地运行；无需外部 API 调用。

关键概念

类型化子查询 – 您可以明确请求词法（lex）搜索、向量（vec）搜索或 HyDE（假设文档）扩展。系统使用倒数排名融合（RRF）融合结果，并可选地使用 LLM 进行重排序。
上下文 – 您附加到集合的层次化元数据（例如，“个人笔记和想法”）。上下文字符串随结果返回，帮助下游代理做出更好的决策。
MCP 服务器 – 一个轻量级模型上下文协议服务器（stdio 或 HTTP），允许其他工具（Claude Desktop、自定义代理）以编程方式调用 QMD。

快速开始（CLI）

# 全局安装（Node 或 Bun）
npm install -g @tobilu/qmd   # 或 bun install -g @tobilu/qmd

# 添加集合（Markdown 文件文件夹）
qmd collection add ~/notes      --name notes
qmd collection add ~/Documents/meetings --name meetings
qmd collection add ~/work/docs  --name docs

# 为每个集合添加人类可读的上下文（可选但推荐）
qmd context add qmd://notes "个人笔记和想法"
qmd context add qmd://meetings "会议转录和笔记"
qmd context add qmd://docs "工作文档"

# 为向量后端生成嵌入
qmd embed

# 搜索示例
qmd search "项目时间线"               # 快速 BM25 关键词搜索
qmd vsearch "如何部署"                # 纯语义搜索
qmd query "季度规划流程"      # 混合（BM25+向量）+ LLM 重排序

# 检索文件
qmd get "meetings/2024-01-15.md"
qmd get "#abc123"                         # 按内部文档 ID
qmd multi-get "journals/2025-05*.md"        # 通配符模式

代理友好输出

--json 返回结构化数据（文件 URI、分数、片段）。
--files 添加绝对文件路径，对于需要打开源文件的代理很有用。

MCP 服务器（编程访问）

运行 qmd mcp --http 启动持久 HTTP 服务器（默认 localhost:8181）。
端点：
- POST /mcp – 完整的 MCP 流协议。
- POST /query（别名 /search）– 与 CLI query 工具相同的参数，返回 JSON，包含 file 字段，如 qmd://collection/path。
- POST /metadata – 发现可用的元数据键/值。
- GET /health – 存活检查。
安全性：默认仅接受回环来源；您可以通过 QMD_ALLOWED_ORIGINS 或 QMD_ALLOWED_HOSTS 放宽此限制。
服务器在请求之间将 LLM 模型保留在 VRAM 中；嵌入上下文在 5 分钟不活动后清除。

SDK / 库使用（Node/Bun）

npm install @tobilu/qmd

import { createStore } from '@tobilu/qmd'

const store = await createStore({
  dbPath: './my-index.sqlite',
  config: {
    collections: {
      docs: { path: '/path/to/docs', pattern: '**/*.md' },
      notes: { path: '/path/to/notes' },
    },
  },
})

// 简单混合搜索（自动扩展 + RRF + LLM 重排序）
const results = await store.search({ query: 'authentication flow' })
console.log(results.map(r => `${r.title} (${(r.score*100).toFixed(0)}%)`))

await store.close()

SDK 镜像 CLI 功能：

search、searchLex、searchVector 用于三种检索模式。
get、multiGet 用于文档检索。
集合管理（addCollection、listCollections 等）。
上下文处理（addContext、listContexts）。
索引（update）和嵌入（embed）。
所有公共对象的丰富 TypeScript 类型定义。

何时使用 QMD？

个人知识库 – 保持所有 Markdown 笔记可搜索，无需将数据发送到云端。
代理工作流 – LLM 代理（例如 Claude、Auto-GPT）可以调用 MCP 服务器实时获取相关片段或整个文档。
混合检索 – 您需要精确关键词匹配和语义相似性，并可选择 LLM 重排序以获得高质量结果。
自托管环境 – 任何需要数据隐私或离线操作的情况。

摘要

QMD 是一款本地运行的混合搜索工具，适用于基于 Markdown 的知识集合。它融合了 BM25、向量相似性和 LLM 重排序，提供 CLI、用于代理的 HTTP/MCP 服务器，以及用于嵌入到您自己的应用中的完整 TypeScript SDK。