> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

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

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

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

* **Повторне ранжування та розширення запиту** для кращого пригадування.
* **Індексування додаткових каталогів** -- документації проєкту, нотаток команди, будь-чого на диску.
* **Індексування транскриптів сесій** -- пригадування попередніх розмов.
* **Повністю локально** -- працює з офіційним провайдерським plugin llama.cpp і
  автоматично завантажує моделі GGUF.
* **Автоматичний fallback** -- якщо 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 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  memory: {
    backend: "qmd",
  },
}
```

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

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

* OpenClaw створює колекції з файлів памʼяті вашого робочого простору та будь-яких
  налаштованих `memory.qmd.paths`, потім запускає `qmd update`, коли менеджер QMD
  відкривається, і періодично після цього (типово кожні 5 хвилин). Ці оновлення
  виконуються через підпроцеси QMD, а не через in-process обхід файлової системи. Семантичні
  режими також запускають `qmd embed`.
* Типова колекція робочого простору відстежує `MEMORY.md` плюс дерево `memory/`.
  Нижній регістр `memory.md` не індексується як кореневий файл памʼяті.
* Власний сканер QMD ігнорує приховані шляхи та поширені каталоги залежностей/збірки,
  такі як `.git`, `.cache`, `node_modules`, `vendor`, `dist` і
  `build`. Запуск Gateway типово не ініціалізує QMD, тому холодне завантаження
  уникає імпорту runtime памʼяті або створення довгоживучого watcher до
  першого використання памʼяті.
* Якщо ви все одно хочете ініціалізувати QMD під час старту Gateway, установіть
  `memory.qmd.update.startup` у `idle` або `immediate`. З
  `memory.qmd.update.onBoot: true` старт виконує початкове оновлення. З
  `onBoot: false` старт пропускає це негайне оновлення, але все одно відкриває
  довгоживучий менеджер, коли налаштовано інтервали update або embed, тож QMD може
  володіти своїм регулярним watcher і таймерами.
* Пошуки використовують налаштований `searchMode` (типово: `search`; також підтримує
  `vsearch` і `query`). `search` є лише BM25, тож OpenClaw пропускає перевірки
  готовності семантичних векторів і обслуговування embedding у цьому режимі. Якщо режим
  не спрацьовує, OpenClaw повторює спробу з `qmd query`.
* Коли `searchMode` дорівнює `query`, установіть `memory.qmd.rerank` у `false`, щоб використовувати
  гібридний шлях запиту QMD без reranker. OpenClaw передає `--no-rerank` до
  прямого CLI-шляху QMD і `rerank: false` до MCP-інструмента запиту QMD. Цей параметр
  потребує QMD 2.1 або новішого.
* З випусками QMD, які оголошують фільтри кількох колекцій, OpenClaw групує
  колекції з однаковим джерелом в один виклик пошуку QMD. Старіші випуски QMD
  зберігають сумісний fallback для кожної колекції.
* Якщо QMD повністю не спрацьовує, OpenClaw fallback до вбудованого рушія SQLite.
  Повторні спроби під час ходів чату ненадовго відступають після помилки відкриття, щоб
  відсутній бінарний файл або зламана залежність супровідного процесу не створювали шторм повторних спроб;
  `openclaw memory status` і одноразові CLI-перевірки все ще напряму повторно перевіряють QMD.

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

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

OpenClaw підтримує шлях пошуку QMD сумісним як з поточними, так і зі старішими
інсталяціями QMD.

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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
qmd search "router notes" --json -n 10 -c memory-root-main -c memory-dir-main
```

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

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

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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
qmd --help | grep -i collection
```

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

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

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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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 повторно запустіть embeddings, щоб індекс відповідав
новому векторному простору.

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

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

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  memory: {
    backend: "qmd",
    qmd: {
      paths: [{ name: "docs", path: "~/notes", pattern: "**/*.md" }],
    },
  },
}
```

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

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

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

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  agents: {
    defaults: {
      memorySearch: {
        experimental: { sessionMemory: true },
        sources: ["memory", "sessions"],
      },
    },
  },
  memory: {
    backend: "qmd",
    qmd: {
      sessions: { enabled: true },
    },
  },
}
```

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

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

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

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

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  memory: {
    qmd: {
      scope: {
        default: "deny",
        rules: [{ action: "allow", match: { chatType: "direct" } }],
      },
    },
  },
}
```

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

## Цитування

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

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

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

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

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

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

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

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

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  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`; інакше він зберігає старіший
fallback для кожної колекції заради коректності.

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

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

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

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

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

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

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

## Повʼязане

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