Qmd

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

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


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

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

инфо

Ниже — полное определение навыка, которое Hermes загружает при его активации. Именно это агент видит как инструкции во время работы навыка.

QMD — Query Markup Documents

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

Создан Tobi Lütke. Лицензия 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 "query"`	BM25-поиск по ключевым словам (без моделей)	~0,2 с
`qmd vsearch "query"`	Семантический векторный поиск (1 модель)	~3 с
`qmd query "query"`	Гибридный поиск + переранжирование (все 3 модели)	~2–3 с прогретый, ~19 с холодный
`qmd get <docid>`	Получить полное содержимое документа	мгновенно
`qmd multi-get "glob"`	Получить несколько файлов	мгновенно
`qmd collection add <path> --name <n>`	Добавить директорию как коллекцию	мгновенно
`qmd context add <path> "description"`	Добавить контекстные метаданные для улучшения поиска	мгновенно
`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 "Personal notes, ideas, and journal entries"
qmd context add qmd://project-docs "Technical documentation for the main project"
qmd context add qmd://meetings "Meeting transcripts and action items from team syncs"

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

qmd embed

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

4. Проверка

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

Режимы поиска

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

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

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

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

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

qmd vsearch "how does the rate limiter handle burst traffic"
qmd vsearch "ideas for improving onboarding flow"

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

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

qmd query "what decisions were made about the database migration"

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

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

# BM25 для точного термина + векторный для концепции
qmd query $'lex: rate limiter\nvec: how does throttling work under load'

# С расширением запроса
qmd query $'expand: database migration plan\nlex: "schema change"'

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

Синтаксис	Эффект	Пример
`term`	Поиск по префиксу	`perf` найдёт “performance”
`"phrase"`	Точная фраза	`"rate limiter"`
`-term`	Исключить термин	`performance -sports`

HyDE (Hypothetical Document Embeddings)

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

qmd query $'hyde: The migration plan involves three phases. First, we add the new columns without dropping the old ones. Then we backfill data. Finally we cut over and remove legacy columns.'

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

qmd search "query" --collection notes
qmd query "query" --collection project-docs

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

qmd search "query" --json        # JSON-вывод (удобно для парсинга)
qmd search "query" --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-сервер, который передаёт инструменты поиска напрямую Hermes Agent через нативный MCP-клиент. Это предпочтительный способ интеграции: после настройки агент получает инструменты qmd автоматически, без необходимости каждый раз загружать навык.

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

Добавьте в ~/.hermes/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

Затем настройте Hermes Agent на подключение через 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 user service)

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-инструмент	Команда CLI	Описание
`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": "how user login is verified"}
  ],
  "collections": ["project-docs"],
  "limit": 10
}

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

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

terminal(command="qmd query 'what was decided about the API redesign' --json", timeout=30)

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

terminal(command="qmd collection add ~/Documents/notes --name notes")
terminal(command="qmd context add qmd://notes 'Personal research notes and ideas'")
terminal(command="qmd embed")
terminal(command="qmd status")

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

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

Расширение запроса — дообученная модель на 1,7 млрд параметров генерирует 2 альтернативных варианта запроса. Исходный запрос получает двойной вес при слиянии результатов.
Параллельный поиск — 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 автоматически загружает ~2 ГБ GGUF-моделей при первом использовании. Операция разовая.

Долгий холодный старт (~19 с)

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

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

macOS: «unable to load extension»

Установите SQLite через Homebrew: brew install sqlite Затем убедитесь, что он стоит в PATH раньше системного SQLite.

«No collections found»

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

Замена модели эмбеддингов (CJK/мультиязычный контент)

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

export QMD_EMBED_MODEL="your-multilingual-model"

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

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