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

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.

Увімкнення

{  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.

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

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

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

qmd search "router notes" --json -n 10 -c memory-root-main -c memory-dir-main

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

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

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

qmd --help | grep -i collection

У поточній довідці QMD згадується вибір однієї або кількох колекцій. У старішій довідці зазвичай описано одну колекцію.

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

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

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 додаткові каталоги, щоб зробити їх доступними для пошуку:

{  memory: {    backend: "qmd",    qmd: {      paths: [{ name: "docs", path: "~/notes", pattern: "**/*.md" }],    },  },}

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

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

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

{  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. Типове значення видимості tree не надає доступу до непов’язаних сеансів того самого агента. Якщо сеанс, запущений через Gateway, має бути доступний для пошуку з окремого сеансу приватних повідомлень, свідомо встановіть tools.sessions.visibility: "agent".

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

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

{  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.

Для простіших конфігурацій вбудований механізм добре працює без додаткових залежностей.

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

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

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

{  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.*), режими пошуку, інтервали оновлення, правила області та всі інші налаштування дивіться в довіднику з конфігурації пам’яті.

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

• Огляд пам’яті
• Вбудований механізм пам’яті
• Пам’ять Honcho