Qmd

Поиск по личным базам знаний, заметкам, документам и стенограммам встреч локально с помощью qmd — гибридного поискового движка с BM25, векторным поиском и переранжированием через LLM. Поддерживает интеграцию через CLI и MCP.

Метаданные навыка


Источник	Опционально — установка: `vibeos skills install official/research/qmd`
Путь	`optional-skills/research/qmd`
Версия	`1.0.0`
Автор	VibeOS + Teknium
Лицензия	MIT
Платформы	macos, linux
Теги	`Search`, `Knowledge-Base`, `RAG`, `Notes`, `MCP`, `Local-AI`
Связанные навыки	`obsidian`, `native-mcp`, `arxiv`

Справочно: полный SKILL.md

к сведению

Ниже приведено полное определение навыка, которое VibeOS загружает при его активации. Агент видит эти инструкции, когда навык активен.

QMD — Query Markup Documents

Локальный поисковый движок для персональных баз знаний. Индексирует заметки в Markdown, стенограммы встреч, документацию и любые текстовые файлы, предоставляя гибридный поиск, сочетающий точное совпадение ключевых слов, семантическое понимание и переранжирование на основе LLM — всё работает локально, без облачных зависимостей.

Создано Тоби Лютке. Лицензия MIT.

Когда использовать

Пользователь просит найти что-то в заметках, документах, базе знаний или стенограммах встреч
Пользователь хочет найти информацию в большой коллекции Markdown/текстовых файлов
Пользователю нужен семантический поиск («найди заметки о концепции X»), а не просто grep по ключевым словам
Пользователь уже настроил коллекции qmd и хочет выполнять по ним запросы
Пользователь просит настроить локальную базу знаний или систему поиска документов
Ключевые слова: «поиск в заметках», «найти в документах», «база знаний», «qmd»

Предварительные требования

Node.js >= 22 (обязательно)

# Проверка версии
node --version  # должно быть >= 22

# macOS — установка или обновление через Homebrew
brew install node@22

# Linux — используйте NodeSource или nvm
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs
# или с nvm:
nvm install 22 && nvm use 22

SQLite с поддержкой расширений (только macOS)

Системный SQLite на macOS не поддерживает загрузку расширений. Установите через Homebrew:

brew install sqlite

Установка qmd

npm install -g @tobilu/qmd
# или с Bun:
bun install -g @tobilu/qmd

При первом запуске автоматически загружаются 3 локальные GGUF-модели (~2 ГБ всего):

Модель	Назначение	Размер
embeddinggemma-300M-Q8_0	Векторные эмбеддинги	~300 МБ
qwen3-reranker-0.6b-q8_0	Переранжирование результатов	~640 МБ
qmd-query-expansion-1.7B	Расширение запросов	~1.1 ГБ

Проверка установки

qmd --version
qmd status

Краткая справка

Команда	Что делает	Скорость
`qmd search "запрос"`	Поиск по ключевым словам BM25 (без моделей)	~0.2 с
`qmd vsearch "запрос"`	Семантический векторный поиск (1 модель)	~3 с
`qmd query "запрос"`	Гибридный поиск + переранжирование (все 3 модели)	~2-3 с (горячий старт), ~19 с (холодный старт)
`qmd get <docid>`	Получить полное содержимое документа	мгновенно
`qmd multi-get "glob"`	Получить несколько файлов	мгновенно
`qmd collection add <путь> --name <имя>`	Добавить директорию как коллекцию	мгновенно
`qmd context add <путь> "описание"`	Добавить контекстные метаданные для улучшения поиска	мгновенно
`qmd embed`	Сгенерировать/обновить векторные эмбеддинги	зависит от объёма
`qmd status`	Показать состояние индекса и информацию о коллекциях	мгновенно
`qmd mcp`	Запустить MCP-сервер (stdio)	постоянно
`qmd mcp --http --daemon`	Запустить MCP-сервер (HTTP, с прогревом моделей)	постоянно

Процесс настройки

1. Добавление коллекций

Укажите qmd директории с вашими документами:

# Добавить директорию с заметками
qmd collection add ~/notes --name notes

# Добавить документацию проекта
qmd collection add ~/projects/myproject/docs --name project-docs

# Добавить стенограммы встреч
qmd collection add ~/meetings --name meetings

# Список всех коллекций
qmd collection list

2. Добавление контекстных описаний

Контекстные метаданные помогают поисковому движку понять, что содержит каждая коллекция. Это значительно улучшает качество поиска:

qmd context add qmd://notes "Личные заметки, идеи и дневниковые записи"
qmd context add qmd://project-docs "Техническая документация основного проекта"
qmd context add qmd://meetings "Стенограммы встреч и задачи из командных синхронизаций"

3. Генерация эмбеддингов

qmd embed

Это обрабатывает все документы во всех коллекциях и генерирует векторные эмбеддинги. Повторно запускайте после добавления новых документов или коллекций.

4. Проверка

qmd status   # показывает состояние индекса, статистику коллекций, информацию о моделях

Паттерны поиска

Быстрый поиск по ключевым словам (BM25)

Лучше всего подходит для: точных терминов, идентификаторов кода, имён, известных фраз. Модели не загружаются — результаты почти мгновенные.

qmd search "authentication middleware"
qmd search "handleError async"

Семантический векторный поиск

Лучше всего подходит для: вопросов на естественном языке, концептуальных запросов. Загружает модель эмбеддингов (~3 с на первый запрос).

qmd vsearch "как ограничитель скорости обрабатывает пиковый трафик"
qmd vsearch "идеи по улучшению процесса онбординга"

Гибридный поиск с переранжированием (наилучшее качество)

Лучше всего подходит для: важных запросов, где качество имеет первостепенное значение. Использует все 3 модели — расширение запроса, параллельный BM25+векторный поиск, переранжирование.

qmd query "какие решения были приняты по миграции базы данных"

Структурированные многомодовые запросы

Комбинируйте разные типы поиска в одном запросе для точности:

# BM25 для точного термина + векторный для концепции
qmd query $'lex: rate limiter\nvec: как работает троттлинг под нагрузкой'

# С расширением запроса
qmd query $'expand: план миграции базы данных\nlex: "изменение схемы"'

Синтаксис запросов (режим lex/BM25)

Синтаксис	Эффект	Пример
`термин`	Совпадение по префиксу	`perf` соответствует «performance»
`"фраза"`	Точная фраза	`"rate limiter"`
`-термин`	Исключить термин	`performance -sports`

HyDE (Гипотетические эмбеддинги документов)

Для сложных тем напишите, как, по вашему мнению, должен выглядеть ответ:

qmd query $'hyde: План миграции состоит из трех этапов. Сначала мы добавляем новые столбцы, не удаляя старые. Затем заполняем данные. Наконец, переключаемся и удаляем устаревшие столбцы.'

Ограничение по коллекциям

qmd search "запрос" --collection notes
qmd query "запрос" --collection project-docs

Форматы вывода

qmd search "запрос" --json        # Вывод в JSON (лучше всего для парсинга)
qmd search "запрос" --limit 5     # Ограничение результатов
qmd get "#abc123"                # Получить по ID документа
qmd get "path/to/file.md"       # Получить по пути к файлу
qmd get "file.md:50" -l 100     # Получить конкретный диапазон строк
qmd multi-get "journals/*.md" --json  # Пакетное получение по glob

Интеграция через MCP (рекомендуется)

qmd предоставляет MCP-сервер, который даёт инструменты поиска напрямую агенту VibeOS через встроенный MCP-клиент. Это предпочтительный способ интеграции — после настройки агент автоматически получает инструменты qmd без необходимости загружать этот навык.

Вариант A: Режим Stdio (простой)

Добавьте в ~/.vibeos/config.yaml:

mcp_servers:
  qmd:
    command: "qmd"
    args: ["mcp"]
    timeout: 30
    connect_timeout: 45

Это регистрирует инструменты: mcp_qmd_search, mcp_qmd_vsearch, mcp_qmd_deep_search, mcp_qmd_get, mcp_qmd_status.

Компромисс: Модели загружаются при первом поисковом запросе (~19 с холодный старт), затем остаются прогретыми в течение сессии. Приемлемо для нечастого использования.

Вариант B: Режим HTTP-демона (быстрый, рекомендуется для активного использования)

Запустите демон qmd отдельно — он держит модели прогретыми в памяти:

# Запуск демона (сохраняется между перезапусками агента)
qmd mcp --http --daemon

# По умолчанию работает на http://localhost:8181

Затем настройте VibeOS на подключение через HTTP:

mcp_servers:
  qmd:
    url: "http://localhost:8181/mcp"
    timeout: 30

Компромисс: Использует ~2 ГБ ОЗУ во время работы, но каждый запрос выполняется быстро (~2-3 с). Лучше всего подходит для пользователей, которые часто ищут.

Поддержание работы демона

macOS (launchd)

cat > ~/Library/LaunchAgents/com.qmd.daemon.plist << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.qmd.daemon</string>
  <key>ProgramArguments</key>
  <array>
    <string>qmd</string>
    <string>mcp</string>
    <string>--http</string>
    <string>--daemon</string>
  </array>
  <key>RunAtLoad</key>
  <true/>
  <key>KeepAlive</key>
  <true/>
  <key>StandardOutPath</key>
  <string>/tmp/qmd-daemon.log</string>
  <key>StandardErrorPath</key>
  <string>/tmp/qmd-daemon.log</string>
</dict>
</plist>
EOF

launchctl load ~/Library/LaunchAgents/com.qmd.daemon.plist

Linux (пользовательский сервис systemd)

mkdir -p ~/.config/systemd/user

cat > ~/.config/systemd/user/qmd-daemon.service << 'EOF'
[Unit]
Description=QMD MCP Daemon
After=network.target

[Service]
ExecStart=qmd mcp --http --daemon
Restart=on-failure
RestartSec=10
Environment=PATH=/usr/local/bin:/usr/bin:/bin

[Install]
WantedBy=default.target
EOF

systemctl --user daemon-reload
systemctl --user enable --now qmd-daemon
systemctl --user status qmd-daemon

Справочник по MCP-инструментам

После подключения доступны следующие инструменты как mcp_qmd_*:

MCP-инструмент	Соответствует	Описание
`mcp_qmd_search`	`qmd search`	Поиск по ключевым словам BM25
`mcp_qmd_vsearch`	`qmd vsearch`	Семантический векторный поиск
`mcp_qmd_deep_search`	`qmd query`	Гибридный поиск + переранжирование
`mcp_qmd_get`	`qmd get`	Получить документ по ID или пути
`mcp_qmd_status`	`qmd status`	Состояние индекса и статистика

MCP-инструменты принимают структурированные JSON-запросы для многомодового поиска:

{
  "searches": [
    {"type": "lex", "query": "authentication middleware"},
    {"type": "vec", "query": "как проверяется вход пользователя"}
  ],
  "collections": ["project-docs"],
  "limit": 10
}

Использование CLI (без MCP)

Если MCP не настроен, используйте qmd напрямую через терминал:

terminal(command="qmd query 'что было решено по редизайну API' --json", timeout=30)

Для задач настройки и управления всегда используйте терминал:

terminal(command="qmd collection add ~/Documents/notes --name notes")
terminal(command="qmd context add qmd://notes 'Личные исследовательские заметки и идеи'")
terminal(command="qmd embed")
terminal(command="qmd status")

Как работает конвейер поиска

Понимание внутреннего устройства помогает выбрать правильный режим поиска:

Расширение запроса — Тонко настроенная модель на 1.7B генерирует 2 альтернативных запроса. Исходный запрос получает вес x2 при слиянии.
Параллельный поиск — BM25 (SQLite FTS5) и векторный поиск выполняются одновременно для всех вариантов запроса.
RRF-слияние — Reciprocal Rank Fusion (k=60) объединяет результаты. Бонус за высокий ранг: #1 получает +0.05, #2-3 получают +0.02.
Переранжирование через LLM — qwen3-reranker оценивает топ-30 кандидатов (0.0-1.0).
Смешивание с учётом позиции — Ранги 1-3: 75% поиск / 25% переранжировщик. Ранги 4-10: 60/40. Ранги 11+: 40/60 (больше доверия переранжировщику для длинного хвоста).

Умная разбивка на чанки: Документы разбиваются по естественным границам (заголовки, блоки кода, пустые строки) с целевым размером ~900 токенов и 15% перекрытием. Блоки кода никогда не разбиваются внутри.

Лучшие практики

Всегда добавляйте контекстные описания — qmd context add значительно повышает точность поиска. Опишите, что содержит каждая коллекция.
Повторно создавайте эмбеддинги после добавления документов — qmd embed необходимо запускать заново при добавлении новых файлов в коллекции.
Используйте qmd search для скорости — когда нужен быстрый поиск по ключевым словам (идентификаторы кода, точные имена), BM25 работает мгновенно и не требует моделей.
Используйте qmd query для качества — когда вопрос концептуальный или пользователю нужны наилучшие результаты, используйте гибридный поиск.
Предпочитайте интеграцию через MCP — после настройки агент получает встроенные инструменты без необходимости каждый раз загружать этот навык.
Режим демона для частых пользователей — если пользователь регулярно ищет в своей базе знаний, рекомендуйте настройку HTTP-демона.
Первый запрос в структурированном поиске получает вес x2 — ставьте самый важный/точный запрос первым при комбинировании lex и vec.

Устранение неполадок

«Модели загружаются при первом запуске»

Нормально — qmd автоматически загружает ~2 ГБ GGUF-моделей при первом использовании. Это одноразовая операция.

Задержка холодного старта (~19 с)

Это происходит, когда модели не загружены в память. Решения:

Используйте режим HTTP-демона (qmd mcp --http --daemon) для поддержания прогретого состояния
Используйте qmd search (только BM25), когда модели не нужны
Режим MCP stdio загружает модели при первом поиске, остаётся прогретым в течение сессии

macOS: «unable to load extension»

Установите Homebrew SQLite: brew install sqlite Затем убедитесь, что он находится в PATH перед системным SQLite.

«No collections found»

Запустите qmd collection add <путь> --name <имя> для добавления директорий, затем qmd embed для их индексации.

Переопределение модели эмбеддингов (CJK/многоязычность)

Установите переменную окружения QMD_EMBED_MODEL для неанглийского контента:

export QMD_EMBED_MODEL="ваша-многоязычная-модель"

Хранение данных

Индекс и векторы: ~/.cache/qmd/index.sqlite
Модели: Автоматически загружаются в локальный кеш при первом запуске
Нет облачных зависимостей — всё работает локально

Метаданные навыка​

Справочно: полный SKILL.md​

QMD — Query Markup Documents

Когда использовать​

Предварительные требования​

Node.js >= 22 (обязательно)​

SQLite с поддержкой расширений (только macOS)​

Установка qmd​

Проверка установки​

Краткая справка​

Процесс настройки​

1. Добавление коллекций​

2. Добавление контекстных описаний​

3. Генерация эмбеддингов​

4. Проверка​

Паттерны поиска​

Быстрый поиск по ключевым словам (BM25)​

Семантический векторный поиск​

Гибридный поиск с переранжированием (наилучшее качество)​

Структурированные многомодовые запросы​

Синтаксис запросов (режим lex/BM25)​

HyDE (Гипотетические эмбеддинги документов)​

Ограничение по коллекциям​

Форматы вывода​

Интеграция через MCP (рекомендуется)​

Вариант A: Режим Stdio (простой)​

Вариант B: Режим HTTP-демона (быстрый, рекомендуется для активного использования)​

Поддержание работы демона​

macOS (launchd)​

Linux (пользовательский сервис systemd)​

Справочник по MCP-инструментам​

Использование CLI (без MCP)​

Как работает конвейер поиска​

Лучшие практики​

Устранение неполадок​

«Модели загружаются при первом запуске»​

Задержка холодного старта (~19 с)​

macOS: «unable to load extension»​

«No collections found»​

Переопределение модели эмбеддингов (CJK/многоязычность)​

Хранение данных​

Ссылки​