Механізм пам’яті 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/ і автоматично керує життєвим циклом допоміжного процесу: колекціями, оновленнями та створенням вкладень. Він віддає перевагу поточним форматам колекцій і запитів MCP у QMD, але за потреби повертається до альтернативних прапорців шаблонів колекцій і старіших назв інструментів 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. Це обмеження застосовується до власних команд пошуку QMD під час викликів агента memory_search; налаштування, синхронізація, вбудований резервний варіант і робота з додатковим корпусом мають власні коротші граничні терміни.

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

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

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

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

Повну поверхню конфігурації (memory.qmd.*), режими пошуку, інтервали оновлення, правила області та всі інші параметри наведено в довіднику з конфігурації пам’яті.

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

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