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

# Рушій пам’яті QMD

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

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

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

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

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

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

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

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

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

## Як працює sidecar

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

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

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

Змінні середовища моделей QMD передаються без змін із процесу Gateway,
тому ви можете глобально налаштовувати 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` Gateway. Якщо OpenClaw
працює як сервіс, створіть символічне посилання:
`sudo ln -s ~/.bun/bin/qmd /usr/local/bin/qmd`.

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

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

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

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

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

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