QMD: локальный поиск по Markdown-заметкам и базе знаний (гайд 2026)

QMD: локальный поисковик по вашим заметкам и документации

QMD (Query Markup Documents) — on-device поисковый движок, который индексирует ваши markdown-заметки, расшифровки встреч, документацию и базы знаний, а затем позволяет искать по ним ключевыми словами или “человеческим” запросом.

Главная идея: не “скармливать” агенту весь контекст, а быстро находить релевантные куски локально и отдавать их в LLM по запросу — в том числе через удобные форматы вывода для agentic flows.

QMD делает гибридный поиск: BM25 (полнотекст), векторный семантический поиск и LLM-реранкинг — всё локально через node-llama-cpp и GGUF-модели.

Репозиторий: https://github.com/tobi/qmd

Требования

• Node.js >= 22
• Bun >= 1.0.0
• macOS: SQLite из Homebrew (для поддержки расширений)

Модели для семантики и качества (скачиваются автоматически)

QMD использует три локальные GGUF-модели (подтягиваются при первом использовании и кэшируются):

• Embedding-модель для векторов: ~300MB
• Реранкер: ~640MB
• Модель расширения запросов (query expansion): ~1.1GB

Кэш моделей обычно лежит в

.

Важно: первый запуск потребует интернета, чтобы скачать модели, дальше всё работает локально.

Установка

Установить можно глобально через npm или bun:

Можно запускать без установки (через npx/bunx):

Быстрый старт: индексируем заметки и начинаем искать

Идеология QMD — вы собираете всё в “коллекции” (папки/репозитории), добавляете контекст (что это за знания), затем генерируете эмбеддинги и ищете.

Добавьте коллекции

Добавьте контекст (важно для качества выдачи у агентов)

Контекст — это описание коллекции/подпапки, которое QMD возвращает вместе с совпадениями. Это сильно помогает LLM понять “что это за документы” и правильнее выбирать релевантные куски.

Можно добавлять контекст изнутри папки коллекции:

Сгенерируйте эмбеддинги для семантического поиска

Если нужно пересчитать всё заново:

Как искать: три режима

В QMD есть три режима поиска — выбирайте под задачу:

• qmd search

  — быстрый полнотекстовый BM25 (ключевые слова)

• qmd vsearch

  — семантический поиск по векторам (когда формулировки “не совпадают”)

• qmd query

  — “глубокий” гибрид: FTS + вектора + расширение запроса + реранкинг (максимальное качество)

Примеры

Поиск в конкретной коллекции

Полезные опции

• -n

  — количество результатов

• --all

  — вернуть все совпадения (лучше вместе с фильтром)

• --min-score

  — порог релевантности (чтобы отсечь шум)

• --json

  — структурированный вывод для скриптов/агентов

• --files

  — вывести список файлов, которые подходят под запрос

Пример “для агента”:

Как доставать документы целиком

После поиска обычно нужно быстро вытащить файл (или кусок файла) в контекст агента или в свою работу.

Получить документ по пути

Получить документ по docid

В результатах поиска QMD показывает docid (короткий хэш). Его можно использовать так:

Получить кусок файла по строкам

Достать несколько документов

По glob-шаблону:

Списком (включая docid):

Ограничить размер файлов (полезно для агентных пайплайнов):

Управление коллекциями и индексом

Коллекции

Обновление индекса

Если коллекции — это git-репозитории, можно обновлять с pull перед индексацией:

Очистка кэша и “осиротевших” данных:

Где хранятся данные

Индекс хранится в SQLite-файле (по умолчанию):

.
Можно переопределять базовую папку кэша через переменную окружения

.

Практический смысл: индекс легко бэкапить, переносить и держать раздельно (например, рабочий и личный).

MCP-интеграция для AI-агентов

QMD можно использовать просто как CLI (агент вызывает команды в терминале), но также есть MCP-сервер для более плотной интеграции.

QMD поднимает MCP и даёт инструменты вроде поиска (BM25/вектора/глубокий), получения документов и статуса индекса.

Пример для Claude Desktop

В конфиг добавляется MCP-сервер, который запускает

. Пример настроек:

Вывод

QMD — практичная “память” на вашей машине: вы индексируете заметки и документацию один раз, а дальше находите нужное быстрым полнотекстом, семантикой или гибридным глубоким поиском с реранкингом.
Это особенно полезно для agentic flows: QMD отдаёт результаты в структурированном виде и помогает агенту брать в контекст только действительно релевантные куски — без лишних токенов и без утечек данных наружу.

FAQ

• QMD — это облачный сервис?
  Нет. QMD работает on-device: индекс и модели находятся локально. Интернет нужен в основном на первом шаге (скачать модели), дальше поиск выполняется на вашей машине.
• Нужно ли обязательно делать эмбеддинги?
  Нет. Если вам достаточно ключевых слов, можно использовать только
  qmd search

  .
  Но для “человеческих” запросов и неочевидных формулировок семантика (

  vsearch

  ) и гибрид (

  query

  ) обычно заметно лучше.

• Чем
  search

  отличается от

  query

  ?

  search

  — быстрый BM25 по тексту (лучше для терминов, названий, точных совпадений).

  query

  — глубокий гибрид: сочетает полнотекст, вектора, расширение запроса и реранкинг (лучше качество, особенно для “как сделать…”).

• Можно ли разделить рабочий и личный индексы?
  Да. Можно использовать отдельный индекс (например, через отдельные профили/параметры запуска) и/или разнести кэши, чтобы не смешивать базы знаний.
• Как безопаснее использовать QMD с агентами?
  Используйте форматы
  --json

  и/или

  --files

  +

  --min-score

  , а затем подтягивайте документы точечно через

  qmd get

  или

  qmd multi-get

  .
  Так агент получает только то, что реально нужно, и меньше “мусора” попадает в контекст.

• Где посмотреть “здоровье” индекса?
  Команда
  qmd status

  покажет состояние индекса, коллекции и связанные контексты.