English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

Sessions and memory

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

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.

Увімкнення

{
  memory: {
    backend: "qmd",
  },
}

OpenClaw створює самодостатній домашній каталог QMD у ~/.openclaw/agents/<agentId>/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 напряму.

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

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

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

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

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

Старіші збірки 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 розуміє цей префікс і читає з правильного кореня колекції.

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

Увімкніть індексування сесій, щоб пригадувати попередні розмови:

{
  memory: {
    backend: "qmd",
    qmd: {
      sessions: { enabled: true },
    },
  },
}

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

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

Типово результати пошуку 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, коли вам потрібні:

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

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

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

QMD не знайдено? Переконайтеся, що бінарний файл є в PATH Gateway. Якщо OpenClaw працює як сервіс, створіть symlink: 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.

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

Пов’язане