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

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.

Увімкнення

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

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

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

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

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

Це уникає запуску одного підпроцесу QMD для кожної колекції durable-memory. Колекції транскриптів сесій залишаються у власній групі джерела, тож змішані пошуки 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"

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

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

Спрямуйте 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 },    },  },}

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

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

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

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

{  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-ключів.

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

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

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. Явно закріпіть бінарний файл:

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

Повʼязане

• Огляд памʼяті
• Вбудований рушій памʼяті
• Памʼять Honcho