---
read_when:
    - Ви хочете налаштувати QMD як бекенд пам’яті
    - Вам потрібні розширені можливості пам’яті, як-от переранжування або додаткові індексовані шляхи
summary: Локальний пошуковий сайдкар із підтримкою BM25, векторів, переранжування та розширення запитів
title: Рушій пам’яті QMD
x-i18n:
    generated_at: "2026-04-28T03:20:30Z"
    model: gpt-5.4
    provider: openai
    source_hash: 09de0490a2584d1c7eeccd4ba8613d63ea4c69e62e5eb5a0492a8baa1a6c7eea
    source_path: concepts/memory-qmd.md
    workflow: 15
---

[QMD](https://github.com/tobi/qmd) — це локальний пошуковий сайдкар, який працює
поруч з OpenClaw. Він поєднує BM25, векторний пошук і переранжування в одному
бінарному файлі, а також може індексувати вміст за межами файлів пам’яті вашого робочого простору.

## Що він додає порівняно з вбудованим рушієм

- **Переранжування та розширення запитів** для кращої повноти пошуку.
- **Індексація додаткових каталогів** — документація проєкту, командні нотатки, будь-що на диску.
- **Індексація транскриптів сеансів** — для відновлення попередніх розмов.
- **Повністю локальний** — працює з необов’язковим пакетом середовища виконання node-llama-cpp і
  автоматично завантажує моделі GGUF.
- **Автоматичний резервний перехід** — якщо QMD недоступний, OpenClaw безшовно переходить на
  вбудований рушій.

## Початок роботи

### Передумови

- Встановіть QMD: `npm install -g @tobilu/qmd` або `bun install -g @tobilu/qmd`
- Збірка SQLite, яка дозволяє розширення (`brew install sqlite` на macOS).
- QMD має бути в `PATH` шлюзу.
- macOS і Linux працюють одразу. На Windows найкраща підтримка через WSL2.

### Увімкнення

```json5
{
  memory: {
    backend: "qmd",
  },
}
```

OpenClaw створює ізольований домашній каталог QMD у
`~/.openclaw/agents/<agentId>/qmd/` і автоматично керує життєвим циклом сайдкара —
колекції, оновлення та запуск ембедингів обробляються за вас.
Він надає перевагу актуальним формам колекцій QMD і запитів MCP, але за потреби
все одно використовує резервні прапорці альтернативних шаблонів колекцій і
старі назви інструментів MCP.
Під час узгодження на старті також повторно створюються застарілі керовані колекції
з поверненням до їхніх канонічних шаблонів, якщо стара колекція QMD з такою самою назвою
ще присутня.

## Як працює сайдкар

- OpenClaw створює колекції з файлів пам’яті вашого робочого простору та всіх
  налаштованих `memory.qmd.paths`, потім запускає `qmd update` під час старту і
  періодично (типово кожні 5 хвилин). Семантичні режими також запускають `qmd embed`.
- Типова колекція робочого простору відстежує `MEMORY.md` і дерево `memory/`.
  `memory.md` у нижньому регістрі не індексується як кореневий файл пам’яті.
- Оновлення під час старту виконується у фоновому режимі, тому запуск чату не блокується.
- Пошук використовує налаштований `searchMode` (типово: `search`; також підтримуються
  `vsearch` і `query`). `search` використовує лише BM25, тому OpenClaw пропускає перевірки
  готовності семантичних векторів і обслуговування ембедингів у цьому режимі. Якщо режим не спрацьовує,
  OpenClaw повторює спробу з `qmd query`.
- У випусках QMD, які оголошують підтримку фільтрів для кількох колекцій, OpenClaw групує
  колекції з однаковим джерелом в один виклик пошуку QMD. У старіших випусках QMD
  зберігається сумісний резервний варіант із пошуком по одній колекції.
- Якщо QMD повністю не спрацьовує, OpenClaw переходить на вбудований рушій SQLite.
  Повторні спроби в межах одного ходу чату після збою відкриття ненадовго сповільнюються,
  щоб відсутній бінарний файл або зламана залежність сайдкара не спричинили шторм повторних спроб;
  `openclaw memory status` і одноразові перевірки через CLI усе одно напряму повторно перевіряють QMD.

<Info>
Перший пошук може бути повільним — QMD автоматично завантажує моделі GGUF (~2 ГБ) для
переранжування і розширення запитів під час першого запуску `qmd query`.
</Info>

## Продуктивність пошуку та сумісність

OpenClaw зберігає сумісність шляху пошуку QMD як з актуальними, так і зі старішими
встановленнями QMD.

Під час запуску OpenClaw один раз для кожного менеджера перевіряє текст довідки встановленого QMD. Якщо
бінарний файл оголошує підтримку кількох фільтрів колекцій, OpenClaw виконує пошук в усіх
колекціях з однаковим джерелом однією командою:

```bash
qmd search "router notes" --json -n 10 -c memory-root-main -c memory-dir-main
```

Це дозволяє уникнути запуску окремого підпроцесу QMD для кожної колекції довготривалої пам’яті.
Колекції транскриптів сеансів залишаються у власній групі джерел, тому змішані пошуки
`memory` + `sessions` усе одно дають вхідні дані для диверсифікатора результатів з обох
джерел.

Старіші збірки QMD приймають лише один фільтр колекції. Коли OpenClaw виявляє одну з
таких збірок, він зберігає шлях сумісності та виконує пошук по кожній колекції окремо
перед об’єднанням і дедуплікацією результатів.

Щоб вручну перевірити контракт установленої версії, виконайте:

```bash
qmd --help | grep -i collection
```

У поточній довідці QMD зазначено, що фільтри колекцій можуть націлюватися на одну або кілька колекцій.
Старіша довідка зазвичай описує одну колекцію.

## Перевизначення моделей

Змінні середовища моделей QMD передаються без змін із процесу шлюзу,
тому ви можете глобально налаштовувати QMD без додавання нової конфігурації OpenClaw:

```bash
export QMD_EMBED_MODEL="hf:Qwen/Qwen3-Embedding-0.6B-GGUF/Qwen3-Embedding-0.6B-Q8_0.gguf"
export QMD_RERANK_MODEL="/absolute/path/to/reranker.gguf"
export QMD_GENERATE_MODEL="/absolute/path/to/generator.gguf"
```

Після зміни моделі ембедингів повторно запустіть побудову ембедингів, щоб індекс відповідав
новому векторному простору.

## Індексація додаткових шляхів

Спрямуйте QMD на додаткові каталоги, щоб зробити їх доступними для пошуку:

```json5
{
  memory: {
    backend: "qmd",
    qmd: {
      paths: [{ name: "docs", path: "~/notes", pattern: "**/*.md" }],
    },
  },
}
```

Фрагменти з додаткових шляхів з’являються як `qmd/<collection>/<relative-path>` у
результатах пошуку. `memory_get` розуміє цей префікс і читає дані з правильного
кореня колекції.

## Індексація транскриптів сеансів

Увімкніть індексацію сеансів, щоб відновлювати попередні розмови:

```json5
{
  memory: {
    backend: "qmd",
    qmd: {
      sessions: { enabled: true },
    },
  },
}
```

Транскрипти експортуються як очищені ходи User/Assistant в окрему колекцію QMD
у `~/.openclaw/agents/<id>/qmd/sessions/`.

## Область пошуку

Типово результати пошуку QMD відображаються в прямих сеансах і сеансах каналів
(але не в групах). Щоб змінити це, налаштуйте `memory.qmd.scope`:

```json5
{
  memory: {
    qmd: {
      scope: {
        default: "deny",
        rules: [{ action: "allow", match: { chatType: "direct" } }],
      },
    },
  },
}
```

Коли область видимості забороняє пошук, OpenClaw записує попередження з похідними значеннями каналу та
типу чату, щоб порожні результати було легше діагностувати.

## Цитати

Коли `memory.citations` має значення `auto` або `on`, фрагменти пошуку містять
нижній колонтитул `Source: <path#line>`. Установіть `memory.citations = "off"`, щоб прибрати
цей нижній колонтитул і водночас продовжити внутрішню передачу шляху агенту.

## Коли використовувати

Обирайте QMD, коли вам потрібно:

- Переранжування для вищої якості результатів.
- Шукати документацію проєкту або нотатки поза межами робочого простору.
- Відновлювати попередні розмови із сеансів.
- Повністю локальний пошук без API-ключів.

Для простіших налаштувань добре підходить [вбудований рушій](/uk/concepts/memory-builtin)
без додаткових залежностей.

## Усунення несправностей

**QMD не знайдено?** Переконайтеся, що бінарний файл є в `PATH` шлюзу. Якщо OpenClaw
працює як сервіс, створіть символьне посилання:
`sudo ln -s ~/.bun/bin/qmd /usr/local/bin/qmd`.

Якщо `qmd --version` працює у вашій оболонці, але OpenClaw усе ще повідомляє про
`spawn qmd ENOENT`, імовірно, процес шлюзу має інший `PATH`, ніж ваша
інтерактивна оболонка. Явно зафіксуйте шлях до бінарного файла:

```json5
{
  memory: {
    backend: "qmd",
    qmd: {
      command: "/absolute/path/to/qmd",
    },
  },
}
```

Використайте `command -v qmd` у середовищі, де встановлено QMD, а потім повторно перевірте
через `openclaw memory status --deep`.

**Перший пошук дуже повільний?** QMD завантажує моделі GGUF під час першого використання. Попередньо прогрійте
його за допомогою `qmd query "test"` з тими самими каталогами XDG, які використовує OpenClaw.

**Під час пошуку запускається багато підпроцесів QMD?** За можливості оновіть QMD. OpenClaw використовує
один процес для пошуків по кількох колекціях з однаковим джерелом лише тоді, коли встановлений
QMD оголошує підтримку кількох фільтрів `-c`; інакше він зберігає старий резервний
варіант по одній колекції для коректності.

**QMD лише з BM25 усе ще намагається зібрати llama.cpp?** Установіть
`memory.qmd.searchMode = "search"`. OpenClaw трактує цей режим як суто лексичний,
не запускає перевірки стану векторів QMD чи обслуговування ембедингів і залишає
перевірки семантичної готовності для конфігурацій `vsearch` або `query`.

**Пошук завершується за тайм-аутом?** Збільште `memory.qmd.limits.timeoutMs` (типово: 4000 мс).
Для повільнішого обладнання встановіть `120000`.

**Порожні результати в групових чатах?** Перевірте `memory.qmd.scope` — типове значення дозволяє
лише прямі сеанси й сеанси каналів.

**Пошук у кореневій пам’яті раптом став надто широким?** Перезапустіть шлюз або дочекайтеся
наступного узгодження під час запуску. OpenClaw повторно створює застарілі керовані колекції,
повертаючи їх до канонічних шаблонів `MEMORY.md` і `memory/`, коли виявляє конфлікт
однойменних колекцій.

**Тимчасові репозиторії, видимі в робочому просторі, спричиняють `ENAMETOOLONG` або ламане індексування?**
Обхід QMD наразі наслідує поведінку базового сканера QMD, а не правила символьних посилань
вбудованого рушія OpenClaw. Тримайте тимчасові checkout-и монорепозиторіїв у
прихованих каталогах, як-от `.tmp/`, або поза індексованими коренями QMD, доки QMD не надасть
безпечний щодо циклів обхід або явні засоби виключення.

## Конфігурація

Повний опис поверхні конфігурації (`memory.qmd.*`), режимів пошуку, інтервалів оновлення,
правил області видимості та всіх інших параметрів дивіться в
[довіднику з конфігурації пам’яті](/uk/reference/memory-config).

## Пов’язане

- [Огляд пам’яті](/uk/concepts/memory)
- [Вбудований рушій пам’яті](/uk/concepts/memory-builtin)
- [Рушій пам’яті Honcho](/uk/concepts/memory-honcho)
