QMD — локальный поисковый движок по markdown-файлам и коду, который отдаёт агенту не файлы целиком, а top-k релевантных фрагментов. MCP (Model Context Protocol) — стандарт, по которому агент вызывает внешние инструменты; через него агент и обращается к QMD.

node -v && npm -v. Точную минимальную версию сверьте с документацией QMD.claude --version), Cursor или аналог.qmd --help).Как работает схема (поток данных):
1. QMD один раз обходит каталоги и строит локальный индекс: разбивает файлы на фрагменты и сохраняет их в файл на диске.
2. Агент вместо grep -r и чтения файлов целиком делает один MCP-вызов поиска.
3. QMD возвращает 3–10 фрагментов с путём и номером строки.
4. Агент открывает только тот файл, который ему действительно нужен.
Экономия возникает на шаге 3–4: агенту в контекст попадают сотни строк вместо десятков тысяч.
Пример: монорепозиторий, где документация лежит в docs/, а сервисы — в services/api/ и services/worker/. Создаём две коллекции — docs и services, — чтобы поиск по документации не разбавлялся кодом.
Если вместо лёгкого индекса нужен полноценный локальный семантический поиск с эмбеддингами, посмотрите разбор Как настроить локальный семантический поиск по файлам с Rummage и EmbeddingGemma 2 — там тот же принцип «сначала индекс, потом ответ».
Что сделать: поставить QMD глобально и убедиться, что бинарник доступен в PATH.
Зачем: агенту нужно запускать сервер по имени команды; если бинарник не в PATH, MCP-подключение упадёт ещё до поиска.
npm install -g qmd
qmd --version
qmd --help
Пример: qmd --help печатает список подкоманд. Если в вашей версии установка описана иначе (bun, Homebrew, готовый бинарник) — сверьтесь с разделом Install в документации проекта; имя пакета и флаги между версиями меняются.
Как проверить: команда qmd --version выводит строку с номером версии без ошибок, а qmd --help — список подкоманд. Запишите путь к бинарнику — он понадобится в Шаге 3:
which qmd
# например: /usr/local/bin/qmd
Почему это работает: MCP-клиент запускает процесс по имени или абсолютному пути; глобальная установка кладёт исполняемый файл в PATH, поэтому агент находит его без дополнительных настроек.

Что сделать: добавить каталоги как коллекции, собрать индекс и исключить мусор — node_modules, сборки, .env, логи.
Зачем: индекс по node_modules и dist раздувает файл на диске и подмешивает в выдачу нерелевантные фрагменты, из-за чего агент снова начинает читать лишнее.
cd <путь-к-репозиторию>
# регистрируем коллекции
qmd collection add ./docs --name docs
qmd collection add ./services --name services
# строим индекс
qmd index
# смотрим, что получилось
qmd status
qmd collections
Пример: после qmd index команда qmd status показывает число проиндексированных документов и фрагментов по каждой коллекции. Если по коллекции docs ноль документов — путь указан неверно.
Что включать и что исключать:
| Каталог | Включать | Причина |
|---|---|---|
| `docs/`, `*.md` | да | основные знания для агента |
| `services/**/*.ts` | да | исходники, по которым идёт поиск |
| `node_modules/`, `dist/`, `build/` | нет | шум и лишний объём индекса |
| `.env`, `*.pem`, ключи | нет | секреты не должны попадать ни в индекс, ни в контекст агента |
Правила исключения задаются в конфиге QMD или через фильтры коллекции — синтаксис сверьте с документацией (qmd collection add --help). Каталоги с секретами проще не регистрировать вовсе.
Как проверить: выполните тестовый поиск и убедитесь, что в выдаче есть пути из нужных каталогов:
qmd search "rate limit" --limit 5
Ожидаемый результат — 5 строк вида docs/api/limits.md:12 ...фрагмент.... Если выдача пустая или в ней только пути из node_modules — вернитесь к регистрации коллекций.
Пересобирайте индекс после крупных правок: qmd index. Если расходы на агента выходят за бюджет, ограничьте их отдельно — см. Как настроить лимиты расходов и бюджеты для ИИ-агентов: контроль затрат на API.

Что сделать: прописать QMD как MCP-сервер в конфиге агента и сравнить объём данных, который агент читает при обычном поиске и через QMD.
Зачем: без MCP-подключения агент про QMD не знает и продолжает жечь токены на grep и чтение файлов целиком.
Для Claude Code конфиг проекта — файл .mcp.json в корне репозитория:
{
"mcpServers": {
"qmd": {
"command": "/usr/local/bin/qmd",
"args": ["mcp"],
"env": {}
}
}
}
Для Cursor тот же блок кладётся в ~/.cursor/mcp.json. Точное имя подкоманды запуска сервера (mcp или иное) сверьте с qmd --help — это единственное место, где конфиг зависит от версии.
Пример: в Claude Code команда /mcp показывает список серверов; рядом с qmd должен быть статус connected. Если статус failed — смотрите раздел «Возможные проблемы».
Теперь замер. Сравниваем, сколько байт текста уходит в контекст при обычном поиске и при поиске через QMD:
# 1) «слепой» поиск: сколько байт в файлах, которые агент прочитал бы целиком
grep -rIl "rate limit" . --exclude-dir=node_modules | xargs wc -c | tail -1
# 2) выдача QMD
qmd search "rate limit" --limit 5 > /tmp/qmd.out
wc -c /tmp/qmd.out
Пример вывода: первая команда — 412033 total, вторая — 3800 /tmp/qmd.out. Подставьте свои значения: соотношение и есть ваша экономия в байтах. Байты переведите в токены тем же токенизатором, что использует ваша модель, — коэффициент зависит от языка и кода.
Чек-лист приёмки:
qmd --version отрабатывает без ошибокqmd status показывает ненулевое число документов в каждой коллекцииqmd search "<запрос>" возвращает релевантные пути/mcp в агенте показывает qmd со статусом connectedgrep -rПочему это работает: инструмент поиска попадает в список доступных агенту функций, и модель выбирает его вместо обхода файловой системы — контекст наполняется только найденными фрагментами.
Проблема. Агент не видит инструмент QMD
MCP error -32000: Connection closedPATH (типично для GUI-приложений), поэтому "command": "qmd" не находится.which qmd в поле command и перезапустите агент. Проверка — /mcp показывает connected.Проблема. Поиск возвращает пустую выдачу
qmd status печатает documents: 0 для коллекции, агент отвечает «No results found».qmd collection list, затем удалить и добавить коллекцию с корректным путём, после чего qmd index. Проверка — qmd search "..." --limit 5 отдаёт непустой результат.Проблема. Ошибка авторизации при построении индекса
Error: 401 Unauthorizedqmd index.export <ПЕРЕМЕННАЯ>=... — имя переменной сверьте с документацией), пересоберите индекс qmd index. Проверка — команда завершается без ошибок и qmd status показывает ненулевое число документов.Вы развернули локальный индекс QMD, подключили его к агенту через MCP и получили воспроизводимый замер расхода контекста до и после. Дальше имеет смысл автоматизировать пересборку индекса и отдельно ограничить бюджеты API-вызовов агента.
Что такое QMD простыми словами?
Локальный поисковый движок по markdown и коду, который по запросу возвращает несколько релевантных фрагментов с путями и номерами строк вместо целых файлов.
Экономит ли QMD токены, если агент всё равно открывает файл?
Да, потому что агент открывает один файл по точному пути, а не перебирает grep -r и не читает десятки кандидатов целиком; разницу покажет замер из Шага 3.
Нужен ли API-ключ для работы QMD?
Зависит от конфигурации: локальные модели эмбеддингов ключа не требуют, облачные — требуют. Поддерживаемые провайдеры и имена переменных сверьте с документацией.
Безопасно ли индексировать рабочий репозиторий?
Индекс хранится локально, но всё, что в него попало, может уйти в контекст агента. Не регистрируйте каталоги с .env, ключами и приватными данными — общие правила в Безопасность ИИ-агентов: как защитить данные и избежать утечек.
Статус: практическое руководство. Часть утверждений — заявления вендоров и проектов; проверяйте на своей среде.
Пошаговое руководство по установке, индексации проекта и подключению QMD к Claude Code и другим ИИ-агентам, чтобы меньше тратить токены на поиск файлов. Время выполнения: 30–45 минут Уровень сложности: Intermediate
Машинные данные публикации: Citation Map JSON · JSON-LD · Semantic Embeddings — отдельный этап.
| Сущность | Тип | Роль в публикации |
|---|---|---|
| QMD для кодинг-агентов | тема/инструмент | упоминается в заголовке, TL;DR или разделах гайда |
| как настроить QMD | тема/инструмент | упоминается в заголовке, TL;DR или разделах гайда |
| экономия токенов ИИ-агента | тема/инструмент | упоминается в заголовке, TL;DR или разделах гайда |
| Windows | платформа/технология | упоминается в заголовке, TL;DR или разделах гайда |
| Linux | платформа/технология | упоминается в заголовке, TL;DR или разделах гайда |
| macOS | платформа/технология | упоминается в заголовке, TL;DR или разделах гайда |
| Node.js | платформа/технология | упоминается в заголовке, TL;DR или разделах гайда |
| npm | платформа/технология | упоминается в заголовке, TL;DR или разделах гайда |
| Git | платформа/технология | упоминается в заголовке, TL;DR или разделах гайда |
| Claude | тема/инструмент | упоминается в заголовке, TL;DR или разделах гайда |
В материале нет отдельного независимого подтверждения; ниже разделены заявления источников и редакционные выводы.
| Источник | Тип | Роль |
|---|---|---|
| Внешние ссылки в материале не указаны | — | — |
Как цитировать: AI Release. Как настроить QMD для кодинг-агентов и сократить расход токенов на поиск файлов. ai-release.org.