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

Daniil Fedorov

февраля 19, 2026

Обновлено февраля 19, 2026

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

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

~/.cache/qmd/models/

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

Установка

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

npm install -g @tobilu/qmd

# или

bun install -g @tobilu/qmd

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

npx @tobilu/qmd ...

bunx @tobilu/qmd ...

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

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

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

qmd collection add ~/notes --name notes

qmd collection add ~/Documents/meetings --name meetings

qmd collection add ~/work/docs --name docs

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

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

qmd context add qmd://notes "Личные заметки и идеи"

qmd context add qmd://meetings "Транскрипты и заметки встреч"

qmd context add qmd://docs "Рабочая документация"

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

cd ~/notes

qmd context add "Личные заметки и идеи"

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

qmd embed

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

qmd embed -f

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

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

qmd search

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

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

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

Примеры

qmd search "project timeline"

qmd vsearch "как задеплоить сервис"

qmd query "процесс квартального планирования"

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

qmd search "API" -c notes

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

-n

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

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

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

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

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

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

qmd query "error handling" --all --files --min-score 0.4

qmd search "authentication" --json -n 10

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

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

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

qmd get "meetings/2024-01-15.md"

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

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

qmd get "#abc123"

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

qmd get notes/meeting.md:50 -l 100

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

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

qmd multi-get "journals/2025-05*.md"

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

qmd multi-get "doc1.md, doc2.md, #abc123"

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

qmd multi-get "docs/*.md" --max-bytes 20480

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

Коллекции

# добавить коллекцию из текущей директории

qmd collection add . --name myproject
# добавить коллекцию с маской (например, только .md)

qmd collection add ~/Documents/notes --name notes --mask "**/*.md"
# список коллекций

qmd collection list
# удалить/переименовать

qmd collection remove myproject

qmd collection rename myproject my-project

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

qmd status

qmd update

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

qmd update --pull

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

qmd cleanup

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

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

~/.cache/qmd/index.sqlite

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

XDG_CACHE_HOME

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

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

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

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

Пример для Claude Desktop

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

qmd mcp

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



{

"mcpServers": {

"qmd": {

"command": "qmd",

"args": ["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

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