---
read_when:
    - Ви хочете налаштувати QMD як бекенд пам’яті
    - Вам потрібні розширені функції пам’яті, як-от повторне ранжування або додаткові індексовані шляхи
summary: Локальний допоміжний сервіс пошуку з BM25, векторами, повторним ранжуванням і розширенням запитів
title: Рушій пам’яті QMD
x-i18n:
    generated_at: "2026-07-12T13:12:07Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: d4fc87c31835a6a1fdabbb271902334755b9801e51a5b2a3cb5525f1657e9317
    source_path: concepts/memory-qmd.md
    workflow: 16
---

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

## Переваги порівняно з вбудованим механізмом

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

## Як працює допоміжний процес

- OpenClaw створює колекції з файлів пам’яті робочого простору та всіх
  налаштованих шляхів `memory.qmd.paths`, а потім запускає `qmd update` під час
  відкриття диспетчера QMD і періодично після цього (`memory.qmd.update.interval`,
  типове значення — `5m`). Оновлення виконуються через підпроцеси QMD, а не
  через обхід файлової системи всередині процесу. Режими семантичного пошуку
  також запускають `qmd embed` (`memory.qmd.update.embedInterval`, типове значення — `60m`).
- Типова колекція робочого простору відстежує `MEMORY.md` разом із деревом
  `memory/`. Файл `memory.md` у нижньому регістрі не індексується як кореневий файл пам’яті.
- Власний сканер QMD ігнорує приховані шляхи та поширені каталоги залежностей і
  збірок, як-от `.git`, `.cache`, `node_modules`, `vendor`, `dist` і `build`.
  За замовчуванням під час запуску Gateway не ініціалізує QMD
  (`memory.qmd.update.startup` має типове значення `off`), тому холодний запуск
  не імпортує середовище виконання пам’яті та не створює довготривалий спостерігач
  до першого використання пам’яті.
- Установіть `memory.qmd.update.startup` у `idle` або `immediate`, щоб усе одно
  ініціалізувати QMD під час запуску Gateway. `memory.qmd.update.onBoot` має типове
  значення `true` і виконує початкове оновлення під час запуску; установіть його
  в `false`, щоб пропустити це негайне оновлення (довготривалий диспетчер усе одно
  відкривається, якщо налаштовано інтервали оновлення або побудови вбудовувань,
  тому QMD продовжує керувати своїм регулярним спостерігачем і таймерами).
- Пошук використовує налаштований `searchMode` (типове значення: `search`;
  також підтримуються `vsearch` і `query`). `search` використовує лише BM25,
  тому в цьому режимі OpenClaw пропускає перевірки готовності семантичних векторів
  і обслуговування вбудовувань. Якщо режим завершується помилкою, OpenClaw повторює
  спробу за допомогою `qmd query`.
- Коли `searchMode` має значення `query`, установіть `memory.qmd.rerank` у `false`,
  щоб використовувати гібридний шлях запитів QMD без переранжувальника
  (потрібна QMD 2.1 або новіша). OpenClaw передає `--no-rerank` безпосередньому
  шляху CLI QMD і `rerank: false` інструменту запитів MCP QMD.
- Для випусків 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 передаються без змін із процесу 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` розпізнає цей префікс і читає
з правильного кореня колекції.

## Індексування розшифровок сеансів

Увімкніть індексування сеансів, щоб шукати в попередніх розмовах. QMD потребує
і загального джерела сеансів `memorySearch`, і експортера розшифровок QMD:

```json5
{
  agents: {
    defaults: {
      memorySearch: {
        experimental: { sessionMemory: true },
        sources: ["memory", "sessions"],
      },
    },
  },
  memory: {
    backend: "qmd",
    qmd: {
      sessions: { enabled: true },
    },
  },
}
```

Розшифровки експортуються як очищені ходи користувача й асистента до окремої
колекції QMD у `~/.openclaw/agents/<id>/qmd/sessions/`. Налаштування лише
`memorySearch.experimental.sessionMemory` не експортує розшифровки до QMD.

Результати із сеансів усе ще фільтруються за допомогою
[`tools.sessions.visibility`](/uk/gateway/config-tools#toolssessions). Типове
значення видимості `tree` не надає доступу до непов’язаних сеансів того самого
агента. Якщо сеанс, запущений через Gateway, має бути доступний для пошуку з
окремого сеансу приватних повідомлень, свідомо встановіть
`tools.sessions.visibility: "agent"`.

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

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

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

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

## Посилання на джерела

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

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

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

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

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

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

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

Якщо `qmd --version` працює у вашій оболонці, але OpenClaw усе одно повідомляє
`spawn qmd ENOENT`, процес Gateway, імовірно, має інший `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`
(типове значення: 4000ms). Для повільнішого обладнання встановіть більше
значення, наприклад `120000`.

**Порожні результати в групових чатах або чатах каналів?** Це очікувана
поведінка з типовим `memory.qmd.scope`, який дозволяє лише прямі сеанси.
Додайте правило `allow` для типів чату `group` або `channel`, якщо хочете
отримувати там результати QMD.

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

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

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

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

## Пов’язані матеріали

- [Огляд пам’яті](/uk/concepts/memory)
- [Вбудований механізм пам’яті](/uk/concepts/memory-builtin)
- [Пам’ять Honcho](/uk/concepts/memory-honcho)