--- read_when: - Ви хочете налаштувати QMD як бекенд пам’яті - Вам потрібні розширені функції пам’яті, як-от повторне ранжування або додаткові індексовані шляхи summary: Локально-орієнтований пошуковий сайдкар із BM25, векторами, повторним ранжуванням і розширенням запитів title: Рушій пам’яті QMD x-i18n: generated_at: "2026-04-29T07:52:05Z" model: gpt-5.5 provider: openai source_hash: 71980e3701f9a5ddcfbbfa41497ef51d2aae2993b2326591124cc0a87f9a849f source_path: concepts/memory-qmd.md workflow: 16 --- [QMD](https://github.com/tobi/qmd) — це локальний пошуковий sidecar, який працює поруч з OpenClaw. Він поєднує BM25, векторний пошук і reranking в одному бінарному файлі та може індексувати вміст за межами файлів пам’яті вашого робочого простору. ## Що він додає порівняно з вбудованим - **Reranking і розширення запитів** для кращого охоплення. - **Індексування додаткових каталогів** -- документація проєкту, нотатки команди, будь-що на диску. - **Індексування транскриптів сесій** -- пригадування попередніх розмов. - **Повністю локальний** -- працює з опційним пакетом runtime node-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 { memory: { backend: "qmd", }, } ``` OpenClaw створює самодостатній домашній каталог QMD у `~/.openclaw/agents//qmd/` і автоматично керує життєвим циклом sidecar: колекції, оновлення та запуски embedding обробляються за вас. Він віддає перевагу поточним формам колекцій QMD і MCP-запитів, але за потреби все ще повертається до альтернативних прапорців шаблонів колекцій і старіших назв інструментів MCP. Узгодження під час завантаження також відтворює застарілі керовані колекції до їхніх канонічних шаблонів, коли старіша колекція QMD з такою самою назвою все ще присутня. ## Як працює sidecar - OpenClaw створює колекції з файлів пам’яті вашого робочого простору та будь-яких налаштованих `memory.qmd.paths`, а потім запускає `qmd update`, коли менеджер QMD відкривається, і періодично після цього (типово кожні 5 хвилин). Ці оновлення виконуються через subprocess QMD, а не через сканування файлової системи всередині процесу. Семантичні режими також запускають `qmd embed`. - Типова колекція робочого простору відстежує `MEMORY.md` плюс дерево `memory/`. Нижній регістр `memory.md` не індексується як кореневий файл пам’яті. - Власний сканер QMD ігнорує приховані шляхи та поширені каталоги залежностей/збірки, такі як `.git`, `.cache`, `node_modules`, `vendor`, `dist` і `build`. Запуск Gateway типово не ініціалізує QMD, тому cold boot уникає імпорту runtime пам’яті або створення довготривалого watcher до того, як пам’ять уперше буде використана. - Якщо все ж потрібне оновлення під час запуску Gateway, установіть `memory.qmd.update.startup` на `idle` або `immediate`. Це opt-in оновлення під час запуску використовує одноразовий шлях subprocess QMD замість створення повного довготривалого in-process watcher. - Пошуки використовують налаштований `searchMode` (типово: `search`; також підтримує `vsearch` і `query`). `search` є лише BM25, тому OpenClaw пропускає семантичні перевірки готовності векторів і підтримку embedding у цьому режимі. Якщо режим завершується помилкою, OpenClaw повторює спробу з `qmd query`. - Із випусками QMD, які оголошують фільтри для кількох колекцій, OpenClaw групує колекції з одного джерела в один виклик пошуку QMD. Старіші випуски QMD зберігають сумісний fallback для окремих колекцій. - Якщо QMD повністю завершується помилкою, OpenClaw повертається до вбудованого рушія SQLite. Повторні спроби під час чат-ходів ненадовго відступають після помилки відкриття, щоб відсутній бінарний файл або зламана залежність sidecar не створювали шквал повторів; `openclaw memory status` і одноразові CLI probes усе ще перевіряють QMD напряму. Перший пошук може бути повільним -- QMD автоматично завантажує моделі GGUF (~2 GB) для reranking і розширення запитів під час першого запуску `qmd query`. ## Продуктивність пошуку та сумісність OpenClaw підтримує шлях пошуку QMD сумісним як з поточними, так і зі старішими інсталяціями QMD. Під час запуску OpenClaw один раз на менеджер перевіряє довідковий текст установленого QMD. Якщо бінарний файл оголошує підтримку кількох фільтрів колекцій, OpenClaw шукає в усіх колекціях з одного джерела однією командою: ```bash qmd search "router notes" --json -n 10 -c memory-root-main -c memory-dir-main ``` Це уникає запуску окремого subprocess QMD для кожної колекції durable-memory. Колекції транскриптів сесій залишаються у власній групі джерел, тому змішані пошуки `memory` + `sessions` усе ще передають diversifier результатів вхідні дані з обох джерел. Старіші збірки 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" ``` Після зміни моделі embedding повторно запустіть embeddings, щоб індекс відповідав новому векторному простору. ## Індексування додаткових шляхів Спрямуйте QMD на додаткові каталоги, щоб зробити їх доступними для пошуку: ```json5 { memory: { backend: "qmd", qmd: { paths: [{ name: "docs", path: "~/notes", pattern: "**/*.md" }], }, }, } ``` Фрагменти з додаткових шляхів з’являються як `qmd//` у результатах пошуку. `memory_get` розуміє цей префікс і читає з правильного кореня колекції. ## Індексування транскриптів сесій Увімкніть індексування сесій, щоб пригадувати попередні розмови: ```json5 { memory: { backend: "qmd", qmd: { sessions: { enabled: true }, }, }, } ``` Транскрипти експортуються як очищені ходи User/Assistant у спеціальну колекцію QMD під `~/.openclaw/agents//qmd/sessions/`. ## Область пошуку Типово результати пошуку QMD показуються в прямих і канальних сесіях (не в групах). Налаштуйте `memory.qmd.scope`, щоб змінити це: ```json5 { memory: { qmd: { scope: { default: "deny", rules: [{ action: "allow", match: { chatType: "direct" } }], }, }, }, } ``` Коли область забороняє пошук, OpenClaw записує попередження з виведеним каналом і типом чату, щоб порожні результати було легше налагоджувати. ## Цитування Коли `memory.citations` має значення `auto` або `on`, фрагменти пошуку містять footer `Source: `. Установіть `memory.citations = "off"`, щоб пропустити footer, але все одно передавати шлях агенту внутрішньо. ## Коли використовувати Оберіть QMD, коли вам потрібні: - Reranking для якісніших результатів. - Пошук у документації проєкту або нотатках поза робочим простором. - Пригадування минулих розмов сесій. - Повністю локальний пошук без API-ключів. Для простіших налаштувань [вбудований рушій](/uk/concepts/memory-builtin) добре працює без додаткових залежностей. ## Усунення несправностей **QMD не знайдено?** Переконайтеся, що бінарний файл є в `PATH` Gateway. Якщо OpenClaw працює як сервіс, створіть symlink: `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. **Багато subprocess QMD під час пошуку?** Оновіть QMD, якщо можливо. OpenClaw використовує один процес для пошуків у кількох колекціях з одного джерела лише тоді, коли встановлений QMD оголошує підтримку кількох фільтрів `-c`; інакше він зберігає старіший fallback для окремих колекцій задля коректності. **QMD лише BM25 усе ще намагається зібрати llama.cpp?** Установіть `memory.qmd.searchMode = "search"`. OpenClaw розглядає цей режим як лише лексичний, не запускає перевірки статусу векторів QMD або підтримку embedding і залишає семантичні перевірки готовності для налаштувань `vsearch` або `query`. **Пошук завершується за тайм-аутом?** Збільште `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 traversal або явні controls виключення. ## Конфігурація Повну поверхню конфігурації (`memory.qmd.*`), режими пошуку, інтервали оновлення, правила області та всі інші параметри дивіться в [довіднику конфігурації пам’яті](/uk/reference/memory-config). ## Пов’язане - [Огляд пам’яті](/uk/concepts/memory) - [Вбудований рушій пам’яті](/uk/concepts/memory-builtin) - [Пам’ять Honcho](/uk/concepts/memory-honcho)