Довідник з конфігурації пам’яті

На цій сторінці наведено всі параметри конфігурації для пошуку пам’яті OpenClaw. Для концептуальних оглядів див.:

Огляд пам’яті — як працює пам’ять
Вбудований рушій — типовий бекенд SQLite
Рушій QMD — локальний sidecar
Пошук пам’яті — конвеєр пошуку та налаштування

Усі параметри пошуку пам’яті розташовані в agents.defaults.memorySearch у openclaw.json, якщо не зазначено інше.

Вибір провайдера

Ключ	Тип	Типове значення	Опис
`provider`	`string`	визначається автоматично	ID адаптера ембедингів: `openai`, `gemini`, `voyage`, `mistral`, `ollama`, `local`
`model`	`string`	типове значення провайдера	Назва моделі ембедингів
`fallback`	`string`	`"none"`	ID резервного адаптера, якщо основний завершується помилкою
`enabled`	`boolean`	`true`	Увімкнути або вимкнути пошук пам’яті

Порядок автовизначення

Коли provider не задано, OpenClaw вибирає перший доступний:

local — якщо налаштовано memorySearch.local.modelPath і файл існує.
openai — якщо вдається визначити ключ OpenAI.
gemini — якщо вдається визначити ключ Gemini.
voyage — якщо вдається визначити ключ Voyage.
mistral — якщо вдається визначити ключ Mistral.

ollama підтримується, але не визначається автоматично (вкажіть його явно).

Визначення API-ключа

Для віддалених ембедингів потрібен API-ключ. OpenClaw визначає його з: профілів автентифікації, models.providers.*.apiKey або змінних середовища.

Провайдер	Змінна середовища	Ключ конфігурації
OpenAI	`OPENAI_API_KEY`	`models.providers.openai.apiKey`
Gemini	`GEMINI_API_KEY`	`models.providers.google.apiKey`
Voyage	`VOYAGE_API_KEY`	`models.providers.voyage.apiKey`
Mistral	`MISTRAL_API_KEY`	`models.providers.mistral.apiKey`
Ollama	`OLLAMA_API_KEY` (заповнювач)	—

Codex OAuth охоплює лише chat/completions і не підходить для запитів ембедингів.

Конфігурація віддаленої кінцевої точки

Для користувацьких OpenAI-сумісних кінцевих точок або перевизначення типових значень провайдера:

Ключ	Тип	Опис
`remote.baseUrl`	`string`	Користувацька базова URL-адреса API
`remote.apiKey`	`string`	Перевизначення API-ключа
`remote.headers`	`object`	Додаткові HTTP-заголовки (об’єднуються з типовими значеннями провайдера)

{
  agents: {
    defaults: {
      memorySearch: {
        provider: "openai",
        model: "text-embedding-3-small",
        remote: {
          baseUrl: "https://api.example.com/v1/",
          apiKey: "YOUR_KEY",
        },
      },
    },
  },
}

Конфігурація, специфічна для Gemini

Ключ	Тип	Типове значення	Опис
`model`	`string`	`gemini-embedding-001`	Також підтримується `gemini-embedding-2-preview`
`outputDimensionality`	`number`	`3072`	Для Embedding 2: 768, 1536 або 3072

Зміна моделі або outputDimensionality запускає автоматичну повну переіндексацію.

Конфігурація локальних ембедингів

Ключ	Тип	Типове значення	Опис
`local.modelPath`	`string`	завантажується автоматично	Шлях до файлу моделі GGUF
`local.modelCacheDir`	`string`	типове значення node-llama-cpp	Каталог кешу для завантажених моделей

Типова модель: embeddinggemma-300m-qat-Q8_0.gguf (~0.6 GB, завантажується автоматично). Потрібна native-збірка: pnpm approve-builds, потім pnpm rebuild node-llama-cpp.

Конфігурація гібридного пошуку

Усе в memorySearch.query.hybrid:

Ключ	Тип	Типове значення	Опис
`enabled`	`boolean`	`true`	Увімкнути гібридний пошук BM25 + векторний
`vectorWeight`	`number`	`0.7`	Вага для векторних оцінок (0-1)
`textWeight`	`number`	`0.3`	Вага для оцінок BM25 (0-1)
`candidateMultiplier`	`number`	`4`	Множник розміру пулу кандидатів

MMR (різноманітність)

Ключ	Тип	Типове значення	Опис
`mmr.enabled`	`boolean`	`false`	Увімкнути повторне ранжування MMR
`mmr.lambda`	`number`	`0.7`	0 = максимальна різноманітність, 1 = максимальна релевантність

Часове згасання (актуальність)

Ключ	Тип	Типове значення	Опис
`temporalDecay.enabled`	`boolean`	`false`	Увімкнути підсилення за актуальністю
`temporalDecay.halfLifeDays`	`number`	`30`	Оцінка зменшується вдвічі кожні N днів

Для постійних файлів (MEMORY.md, файли без дати в memory/) згасання ніколи не застосовується.

Повний приклад

{
  agents: {
    defaults: {
      memorySearch: {
        query: {
          hybrid: {
            vectorWeight: 0.7,
            textWeight: 0.3,
            mmr: { enabled: true, lambda: 0.7 },
            temporalDecay: { enabled: true, halfLifeDays: 30 },
          },
        },
      },
    },
  },
}

Додаткові шляхи до пам’яті

Ключ	Тип	Опис
`extraPaths`	`string[]`	Додаткові каталоги або файли для індексації

{
  agents: {
    defaults: {
      memorySearch: {
        extraPaths: ["../team-docs", "/srv/shared-notes"],
      },
    },
  },
}

Шляхи можуть бути абсолютними або відносними до робочого простору. Каталоги скануються рекурсивно на наявність файлів .md. Обробка символьних посилань залежить від активного бекенда: вбудований рушій ігнорує символьні посилання, тоді як QMD дотримується поведінки сканера QMD. Для пошуку транскриптів між агентами в межах агента використовуйте agents.list[].memorySearch.qmd.extraCollections замість memory.qmd.paths. Ці додаткові колекції мають ту саму структуру { path, name, pattern? }, але об’єднуються для кожного агента окремо й можуть зберігати явні спільні назви, коли шлях вказує за межі поточного робочого простору. Якщо той самий визначений шлях з’являється і в memory.qmd.paths, і в memorySearch.qmd.extraCollections, QMD зберігає перший запис і пропускає дублікат.

Мультимодальна пам’ять (Gemini)

Індексуйте зображення й аудіо разом із Markdown за допомогою Gemini Embedding 2:

Ключ	Тип	Типове значення	Опис
`multimodal.enabled`	`boolean`	`false`	Увімкнути мультимодальну індексацію
`multimodal.modalities`	`string[]`	—	`["image"]`, `["audio"]` або `["all"]`
`multimodal.maxFileBytes`	`number`	`10000000`	Максимальний розмір файлу для індексації

Застосовується лише до файлів у extraPaths. Типові корені пам’яті залишаються лише для Markdown. Потрібен gemini-embedding-2-preview. fallback має бути "none". Підтримувані формати: .jpg, .jpeg, .png, .webp, .gif, .heic, .heif (зображення); .mp3, .wav, .ogg, .opus, .m4a, .aac, .flac (аудіо).

Кеш ембедингів

Ключ	Тип	Типове значення	Опис
`cache.enabled`	`boolean`	`false`	Кешувати ембединги фрагментів у SQLite
`cache.maxEntries`	`number`	`50000`	Максимальна кількість кешованих ембедингів

Запобігає повторному створенню ембедингів для незмінного тексту під час переіндексації або оновлень транскриптів.

Пакетна індексація

Ключ	Тип	Типове значення	Опис
`remote.batch.enabled`	`boolean`	`false`	Увімкнути API пакетних ембедингів
`remote.batch.concurrency`	`number`	`2`	Паралельні пакетні завдання
`remote.batch.wait`	`boolean`	`true`	Очікувати завершення пакета
`remote.batch.pollIntervalMs`	`number`	—	Інтервал опитування
`remote.batch.timeoutMinutes`	`number`	—	Тайм-аут пакета

Доступно для openai, gemini і voyage. Пакетний режим OpenAI зазвичай найшвидший і найдешевший для великих зворотних заповнень.

Пошук у пам’яті сесій (експериментально)

Індексуйте транскрипти сесій і надавайте їх через memory_search:

Ключ	Тип	Типове значення	Опис
`experimental.sessionMemory`	`boolean`	`false`	Увімкнути індексацію сесій
`sources`	`string[]`	`["memory"]`	Додайте `"sessions"`, щоб включити транскрипти
`sync.sessions.deltaBytes`	`number`	`100000`	Поріг байтів для переіндексації
`sync.sessions.deltaMessages`	`number`	`50`	Поріг повідомлень для переіндексації

Індексація сесій вмикається явно та виконується асинхронно. Результати можуть бути трохи застарілими. Журнали сесій зберігаються на диску, тому межу довіри слід вважати рівнем доступу до файлової системи.

Прискорення векторів SQLite (sqlite-vec)

Ключ	Тип	Типове значення	Опис
`store.vector.enabled`	`boolean`	`true`	Використовувати sqlite-vec для векторних запитів
`store.vector.extensionPath`	`string`	bundled	Перевизначити шлях до sqlite-vec

Коли sqlite-vec недоступний, OpenClaw автоматично повертається до обчислення косинусної подібності в процесі.

Зберігання індексу

Ключ	Тип	Типове значення	Опис
`store.path`	`string`	`~/.openclaw/memory/{agentId}.sqlite`	Розташування індексу (підтримує токен `{agentId}`)
`store.fts.tokenizer`	`string`	`unicode61`	Токенізатор FTS5 (`unicode61` або `trigram`)

Конфігурація бекенда QMD

Встановіть memory.backend = "qmd", щоб увімкнути. Усі параметри QMD розташовані в memory.qmd:

Ключ	Тип	Типове значення	Опис
`command`	`string`	`qmd`	Шлях до виконуваного файла QMD
`searchMode`	`string`	`search`	Команда пошуку: `search`, `vsearch`, `query`
`includeDefaultMemory`	`boolean`	`true`	Автоматично індексувати `MEMORY.md` + `memory/*/.md`
`paths[]`	`array`	—	Додаткові шляхи: `{ name, path, pattern? }`
`sessions.enabled`	`boolean`	`false`	Індексувати транскрипти сесій
`sessions.retentionDays`	`number`	—	Зберігання транскриптів
`sessions.exportDir`	`string`	—	Каталог експорту

Розклад оновлення

Ключ	Тип	Типове значення	Опис
`update.interval`	`string`	`5m`	Інтервал оновлення
`update.debounceMs`	`number`	`15000`	Затримка після змін файлів
`update.onBoot`	`boolean`	`true`	Оновлювати під час запуску
`update.waitForBootSync`	`boolean`	`false`	Блокувати запуск до завершення оновлення
`update.embedInterval`	`string`	—	Окрема періодичність ембедингів
`update.commandTimeoutMs`	`number`	—	Тайм-аут для команд QMD
`update.updateTimeoutMs`	`number`	—	Тайм-аут для операцій оновлення QMD
`update.embedTimeoutMs`	`number`	—	Тайм-аут для операцій ембедингів QMD

Обмеження

Ключ	Тип	Типове значення	Опис
`limits.maxResults`	`number`	`6`	Максимальна кількість результатів пошуку
`limits.maxSnippetChars`	`number`	—	Обмеження довжини фрагмента
`limits.maxInjectedChars`	`number`	—	Обмеження загальної кількості вставлених символів
`limits.timeoutMs`	`number`	`4000`	Тайм-аут пошуку

Область дії

Визначає, які сесії можуть отримувати результати пошуку QMD. Та сама схема, що й для session.sendPolicy:

{
  memory: {
    qmd: {
      scope: {
        default: "deny",
        rules: [{ action: "allow", match: { chatType: "direct" } }],
      },
    },
  },
}

Типово — лише DM. match.keyPrefix відповідає нормалізованому ключу сесії; match.rawKeyPrefix відповідає сирому ключу, включно з agent:<id>:.

Цитування

memory.citations застосовується до всіх бекендів:

Значення	Поведінка
`auto` (типово)	Додавати нижній колонтитул `Source: <path#line>` до фрагментів
`on`	Завжди додавати нижній колонтитул
`off`	Не додавати нижній колонтитул (шлях усе одно передається агенту внутрішньо)

Повний приклад QMD

{
  memory: {
    backend: "qmd",
    citations: "auto",
    qmd: {
      includeDefaultMemory: true,
      update: { interval: "5m", debounceMs: 15000 },
      limits: { maxResults: 6, timeoutMs: 4000 },
      scope: {
        default: "deny",
        rules: [{ action: "allow", match: { chatType: "direct" } }],
      },
      paths: [{ name: "docs", path: "~/notes", pattern: "**/*.md" }],
    },
  },
}

Dreaming (експериментально)

Dreaming налаштовується в plugins.entries.memory-core.config.dreaming, а не в agents.defaults.memorySearch. Dreaming використовує три взаємодоповнювальні фази (light, deep, REM), кожна з яких має власний розклад і конфігурацію. Докладніше про концепцію та команди чату див. у Dreaming.

Глобальні налаштування

Ключ	Тип	Типове значення	Опис
`enabled`	`boolean`	`true`	Головний перемикач для всіх фаз
`timezone`	`string`	не задано	Часовий пояс для оцінювання розкладу та щоденних нотаток
`verboseLogging`	`boolean`	`false`	Виводити докладні журнали dreaming для кожного запуску
`storage.mode`	`string`	`"inline"`	`inline`, `separate` або `both`
`storage.separateReports`	`boolean`	`false`	Записувати окремі файли звітів для кожної фази

Фаза light (`phases.light`)

Сканує нещодавні сліди, видаляє дублікати та готує кандидатів до щоденної нотатки. Не записує в MEMORY.md.

Ключ	Тип	Типове значення	Опис
`enabled`	`boolean`	`true`	Увімкнути фазу light
`cron`	`string`	`0 /6 * *`	Розклад (кожні 6 годин)
`lookbackDays`	`number`	`2`	Скільки днів слідів сканувати
`limit`	`number`	`100`	Максимум кандидатів для підготовки
`dedupeSimilarity`	`number`	`0.9`	Поріг Jaccard для видалення дублікатів
`sources`	`string[]`	`["daily","sessions","recall"]`	Джерела даних

Фаза deep (`phases.deep`)

Просуває кваліфікованих кандидатів до MEMORY.md. Це єдина фаза, яка записує довготривалі факти. Також відповідає за відновлення, коли пам’яті замало.

Ключ	Тип	Типове значення	Опис
`enabled`	`boolean`	`true`	Увімкнути фазу deep
`cron`	`string`	`0 3 * * *`	Розклад (щодня о 3 AM)
`limit`	`number`	`10`	Максимум кандидатів для просування за цикл
`minScore`	`number`	`0.8`	Мінімальна зважена оцінка для просування
`minRecallCount`	`number`	`3`	Мінімальний поріг кількості recall
`minUniqueQueries`	`number`	`3`	Мінімальна кількість різних запитів
`recencyHalfLifeDays`	`number`	`14`	Кількість днів, за яку оцінка актуальності зменшується вдвічі
`maxAgeDays`	`number`	`30`	Максимальний вік щоденної нотатки для просування
`sources`	`string[]`	`["daily","memory","sessions","logs","recall"]`	Джерела даних

Відновлення deep (`phases.deep.recovery`)

Ключ	Тип	Типове значення	Опис
`enabled`	`boolean`	`true`	Увімкнути автоматичне відновлення
`triggerBelowHealth`	`number`	`0.35`	Поріг оцінки здоров’я для запуску відновлення
`lookbackDays`	`number`	`30`	Наскільки далеко назад шукати матеріали для відновлення
`maxRecoveredCandidates`	`number`	`20`	Максимум кандидатів для відновлення за запуск
`minRecoveryConfidence`	`number`	`0.9`	Мінімальна впевненість для кандидатів на відновлення
`autoWriteMinConfidence`	`number`	`0.97`	Поріг автозапису (без ручного перегляду)

Фаза REM (`phases.rem`)

Записує теми, роздуми та нотатки про патерни в щоденну нотатку. Не записує в MEMORY.md.

Ключ	Тип	Типове значення	Опис
`enabled`	`boolean`	`true`	Увімкнути фазу REM
`cron`	`string`	`0 5 * * 0`	Розклад (щотижня, неділя 5 AM)
`lookbackDays`	`number`	`7`	Кількість днів матеріалу для роздумів
`limit`	`number`	`10`	Максимум патернів або тем для запису
`minPatternStrength`	`number`	`0.75`	Мінімальна сила співзустрічальності тегів
`sources`	`string[]`	`["memory","daily","deep"]`	Джерела даних для роздумів

Перевизначення виконання

Кожна фаза приймає блок execution. Також існує глобальний блок execution.defaults, від якого фази успадковують значення.

Ключ	Тип	Типове значення	Опис
`speed`	`string`	`"balanced"`	`fast`, `balanced` або `slow`
`thinking`	`string`	`"medium"`	`low`, `medium` або `high`
`budget`	`string`	`"medium"`	`cheap`, `medium`, `expensive`
`model`	`string`	не задано	Перевизначити модель для цієї фази
`maxOutputTokens`	`number`	не задано	Обмежити кількість вихідних токенів
`temperature`	`number`	не задано	Температура семплювання (0-2)
`timeoutMs`	`number`	не задано	Тайм-аут фази в мілісекундах

Приклад

{
  plugins: {
    entries: {
      "memory-core": {
        config: {
          dreaming: {
            enabled: true,
            timezone: "America/New_York",
            phases: {
              light: { cron: "0 */4 * * *", lookbackDays: 3 },
              deep: { minScore: 0.85, recencyHalfLifeDays: 21 },
              rem: { lookbackDays: 14 },
            },
          },
        },
      },
    },
  },
}

CLI commands

RPC and API

Templates

Technical reference

Concept internals

Project

Release policy

Довідник з конфігурації пам’яті

Довідник з конфігурації пам’яті

Вибір провайдера

Порядок автовизначення

Визначення API-ключа

Конфігурація віддаленої кінцевої точки

Конфігурація, специфічна для Gemini

Конфігурація локальних ембедингів

Конфігурація гібридного пошуку

MMR (різноманітність)

Часове згасання (актуальність)

Повний приклад

Додаткові шляхи до пам’яті

Мультимодальна пам’ять (Gemini)

Кеш ембедингів

Пакетна індексація

Пошук у пам’яті сесій (експериментально)

Прискорення векторів SQLite (sqlite-vec)

Зберігання індексу

Конфігурація бекенда QMD

Розклад оновлення

Обмеження

Область дії

Цитування

Повний приклад QMD

Dreaming (експериментально)

Глобальні налаштування

Фаза light (`phases.light`)

Фаза deep (`phases.deep`)

Відновлення deep (`phases.deep.recovery`)

Фаза REM (`phases.rem`)

Перевизначення виконання

Приклад

CLI commands

RPC and API

Templates

Technical reference

Concept internals

Project

Release policy

​Довідник з конфігурації пам’яті

​Вибір провайдера

​Порядок автовизначення

​Визначення API-ключа

​Конфігурація віддаленої кінцевої точки

​Конфігурація, специфічна для Gemini

​Конфігурація локальних ембедингів

​Конфігурація гібридного пошуку

​MMR (різноманітність)

​Часове згасання (актуальність)

​Повний приклад

​Додаткові шляхи до пам’яті

​Мультимодальна пам’ять (Gemini)

​Кеш ембедингів

​Пакетна індексація

​Пошук у пам’яті сесій (експериментально)

​Прискорення векторів SQLite (sqlite-vec)

​Зберігання індексу

​Конфігурація бекенда QMD

​Розклад оновлення

​Обмеження

​Область дії

​Цитування

​Повний приклад QMD

​Dreaming (експериментально)

​Глобальні налаштування

​Фаза light (phases.light)

​Фаза deep (phases.deep)

​Відновлення deep (phases.deep.recovery)

​Фаза REM (phases.rem)

​Перевизначення виконання

​Приклад

Довідник з конфігурації пам’яті

Вибір провайдера

Порядок автовизначення

Визначення API-ключа

Конфігурація віддаленої кінцевої точки

Конфігурація, специфічна для Gemini

Конфігурація локальних ембедингів

Конфігурація гібридного пошуку

MMR (різноманітність)

Часове згасання (актуальність)

Повний приклад

Додаткові шляхи до пам’яті

Мультимодальна пам’ять (Gemini)

Кеш ембедингів

Пакетна індексація

Пошук у пам’яті сесій (експериментально)

Прискорення векторів SQLite (sqlite-vec)

Зберігання індексу

Конфігурація бекенда QMD

Розклад оновлення

Обмеження

Область дії

Цитування

Повний приклад QMD

Dreaming (експериментально)

Глобальні налаштування

Фаза light (`phases.light`)

Фаза deep (`phases.deep`)

Відновлення deep (`phases.deep.recovery`)

Фаза REM (`phases.rem`)

Перевизначення виконання

Приклад