---
read_when:
    - Ви хочете налаштувати QMD як свій backend пам’яті
    - Вам потрібні розширені функції пам’яті, як-от reranking або додаткові індексовані шляхи
summary: 'Локальний sidecar пошуку з пріоритетом локальної обробки: BM25, вектори, reranking і розширення запитів'
title: Рушій пам’яті QMD
x-i18n:
    generated_at: "2026-04-23T22:58:36Z"
    model: gpt-5.4
    provider: openai
    source_hash: 7d7af326291e194a04a17aa425901bf7e2517c23bae8282cd504802d24e9e522
    source_path: concepts/memory-qmd.md
    workflow: 15
---

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

## Що він додає порівняно з builtin

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

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

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

- Установіть 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 --
колекції, оновлення та запуски embedding обробляються автоматично.
Він надає перевагу актуальним формам колекцій QMD і запитів MCP, але все одно повертається до
застарілих прапорців колекцій `--mask` і старіших назв інструментів MCP, коли це потрібно.
Узгодження під час запуску також повторно створює застарілі керовані колекції відповідно до їхніх
канонічних шаблонів, якщо колекція QMD зі старішої версії з такою самою назвою все ще присутня.

## Як працює sidecar

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

<Info>
Перший пошук може бути повільним -- QMD автоматично завантажує моделі GGUF (~2 ГБ) для
reranking і розширення запитів під час першого запуску `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"
```

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

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

Спрямуйте 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, коли вам потрібно:

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

Для простіших конфігурацій [builtin engine](/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` -- типово
дозволено лише прямі та канальні сесії.

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

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

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

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

## Пов’язано

- [Огляд пам’яті](/uk/concepts/memory)
- [Builtin memory engine](/uk/concepts/memory-builtin)
- [Пам’ять Honcho](/uk/concepts/memory-honcho)
