Довідник із налаштування пам’яті

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

Усі параметри пошуку в пам’яті розміщено в agents.defaults.memorySearch у openclaw.json (або в перевизначенні agents.list[].memorySearch для окремого агента), якщо не зазначено інше.

Вибір постачальника

Якщо provider не задано, OpenClaw використовує векторні подання OpenAI. Задайте provider явно, щоб використовувати Bedrock, DeepInfra, Gemini, GitHub Copilot, Mistral, Ollama, Voyage, локальну модель GGUF або сумісну з OpenAI кінцеву точку /v1/embeddings. Застарілі конфігурації, у яких досі вказано provider: "auto", зіставляються з openai.

Якщо provider не задано, наявний застарілий параметр provider: "auto" або provider: "none" навмисно вибирає режим лише FTS, пошук у пам’яті все одно може використовувати лексичне ранжування FTS, коли векторні подання недоступні.

Явно вказані нелокальні постачальники відмовляють у закритому режимі. Якщо для memorySearch.provider задано конкретного постачальника з віддаленою серверною частиною, наприклад Bedrock, DeepInfra, Gemini, GitHub Copilot, LM Studio, Mistral, Ollama, OpenAI, Voyage або сумісного з OpenAI власного постачальника, і цей постачальник недоступний під час виконання, memory_search повертає результат про недоступність замість непомітного використання пошуку лише через FTS. Виправте конфігурацію постачальника або автентифікації, перейдіть на доступного постачальника чи задайте provider: "none", якщо потрібен навмисний пошук лише через FTS.

Власні ідентифікатори постачальників

memorySearch.provider може вказувати на власний запис models.providers.<id> для адаптерів постачальника, призначених для пам’яті, як-от ollama, або для сумісних з OpenAI API моделей, як-от openai-responses / openai-completions. OpenClaw визначає власника api цього постачальника для адаптера векторних подань, зберігаючи власний ідентифікатор постачальника для обробки кінцевої точки, автентифікації та префікса моделі. Завдяки цьому конфігурації з кількома GPU або вузлами можуть виділити створення векторних подань пам’яті для певної локальної кінцевої точки:

{  models: {    providers: {      "ollama-5080": {        api: "ollama",        baseUrl: "http://gpu-box.local:11435",        apiKey: "ollama-local",        models: [{ id: "qwen3-embedding:0.6b", name: "Qwen3 Embedding 0.6B" }],      },    },  },  agents: {    defaults: {      memorySearch: {        provider: "ollama-5080",        model: "qwen3-embedding:0.6b",      },    },  },}

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

Для віддалених векторних подань потрібен ключ API. Натомість Bedrock використовує стандартний ланцюжок облікових даних AWS SDK (ролі екземплярів, SSO, ключі доступу або ключ API Bedrock).

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

Використовуйте provider: "openai-compatible" для універсального сумісного з OpenAI сервера /v1/embeddings, який не повинен успадковувати глобальні облікові дані чату OpenAI.

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

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

{  agents: {    defaults: {      memorySearch: {        provider: "openai-compatible",        remote: {          baseUrl: "https://embeddings.example/v1",          apiKey: "${EMBEDDINGS_API_KEY}",        },        model: "asymmetric-embedder",        queryInputType: "query",        documentInputType: "passage",      },    },  },}

{  agents: {    defaults: {      memorySearch: {        provider: "bedrock",        model: "amazon.titan-embed-text-v2:0",      },    },  },}

{  "Effect": "Allow",  "Action": "bedrock:InvokeModel",  "Resource": "*"}

arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0

openclaw memory status --deep --agent mainopenclaw memory index --force --agent main

Час очікування вбудовування в основному процесі

Поведінка індексування

Усі параметри містяться в memorySearch.sync, якщо не зазначено інше:

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

Усі параметри містяться в memorySearch.query:

І в memorySearch.query.hybrid:

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

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

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

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

Підтримувані формати: .jpg, .jpeg, .png, .webp, .gif, .heic, .heif (зображення); .mp3, .wav, .ogg, .opus, .m4a, .aac, .flac (аудіо).

Кеш вбудовувань

Запобігає повторному створенню вбудовувань для незміненого тексту під час переіндексування або оновлення транскриптів. Залиште maxEntries незаданим для необмеженого кешу; задайте його, якщо зростання використання диска важливіше за максимальну швидкість переіндексування. Коли значення задано, після перевищення кешем ліміту спочатку видаляються найстаріші записи (за часом останнього оновлення).

Пакетне індексування

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

remote.nonBatchConcurrency керує безпосередніми викликами вбудовування, які використовують локальні або самостійно розміщені провайдери, а також розміщені провайдери, коли їхні API пакетної обробки неактивні. Для непакетного індексування Ollama типово використовує 1, щоб не перевантажувати менші локальні хости; на потужніших машинах задайте вище значення.

Це налаштування відокремлене від sync.embeddingBatchTimeoutSeconds, яке керує часом очікування безпосередніх викликів вбудовування.

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

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

Збіги в транскриптах сеансів також підпорядковуються tools.sessions.visibility. Типова видимість tree надає доступ лише до поточного сеансу та породжених ним сеансів. Щоб з іншого сеансу, наприклад приватного повідомлення, відновити непов’язаний сеанс того самого агента, запущений через Gateway, навмисно розширте видимість до agent (або до all, лише коли також потрібне відновлення між агентами й це дозволяє політика взаємодії між агентами).

У наведених нижче прикладах ці налаштування розміщено в agents.defaults. Також можна застосувати еквівалентні налаштування memorySearch у перевизначенні для окремого агента, якщо лише один агент має індексувати транскрипти сеансів і здійснювати в них пошук.

Для відновлення з Gateway у приватному повідомленні в межах одного агента:

{  agents: {    defaults: {      memorySearch: {        experimental: { sessionMemory: true },        sources: ["memory", "sessions"],      },    },  },  tools: {    sessions: { visibility: "agent" },  },}

{  agents: {    defaults: {      memorySearch: {        experimental: { sessionMemory: true },        sources: ["memory", "sessions"],      },    },  },  memory: {    backend: "qmd",    qmd: {      sessions: { enabled: true },    },  },  tools: {    sessions: { visibility: "agent" },  },}

Під час використання QMD налаштування agents.defaults.memorySearch.experimental.sessionMemory і sources: ["sessions"] самі по собі не експортують транскрипти до QMD. Також задайте memory.qmd.sessions.enabled: true.

Векторне прискорення SQLite (sqlite-vec)

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

Сховище індексу

Вбудовані індекси пам’яті зберігаються в базі даних OpenClaw SQLite кожного агента за адресою agents/<agentId>/agent/openclaw-agent.sqlite.

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

Задайте memory.backend = "qmd", щоб увімкнути. Усі налаштування QMD містяться в memory.qmd:

searchMode: "search" використовує лише лексичний пошук/BM25. У цьому режимі OpenClaw не виконує перевірок готовності семантичних векторів або обслуговування вбудовувань QMD, зокрема під час memory status --deep; vsearch і query і надалі потребують готовності векторів та вбудовувань QMD.

rerank: false змінює лише режим QMD query і потребує QMD 2.1 або новішої версії. У режимі прямого CLI OpenClaw передає --no-rerank; у режимі MCP на основі mcporter він передає rerank: false уніфікованому інструменту запитів QMD. Залиште значення незаданим, щоб використовувати типову поведінку повторного ранжування запитів QMD.

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

Інтеграція з mcporter

Усі налаштування містяться в memory.qmd.mcporter. Спрямовує пошуки QMD через довготривалий демон MCP mcporter замість запуску qmd для кожного запиту, зменшуючи накладні витрати холодного запуску для більших моделей.

Потребує встановленого mcporter, доступного в PATH, а також налаштованого сервера mcporter, який запускає qmd mcp. Залиште вимкненим для простіших локальних конфігурацій, де витрати на запуск процесу для кожного запиту є прийнятними.

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

Коли ініціалізацію QMD під час запуску Gateway увімкнено, OpenClaw запускає QMD лише для відповідних агентів. Якщо update.onBoot має значення true і обслуговування за інтервалом оновлення/векторизації не налаштовано, під час запуску для початкового оновлення використовується одноразовий менеджер, який після цього закривається. Якщо налаштовано інтервал оновлення або векторизації, під час запуску відкривається довготривалий менеджер QMD, який керує засобом відстеження та таймерами інтервалів; update.onBoot: false пропускає лише негайне початкове оновлення.

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

{  memory: {    backend: "qmd",    citations: "auto",    qmd: {      includeDefaultMemory: true,      update: { interval: "5m", debounceMs: 15000 },      limits: { maxResults: 4, 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 виконується як один запланований прохід і використовує внутрішні легку/глибоку/REM-фази як деталь реалізації.

Концептуальну поведінку та команди зі скісною рискою описано в розділі Dreaming.

Налаштування користувача

Приклад

{  plugins: {    entries: {      "memory-core": {        subagent: {          allowModelOverride: true,          allowedModels: ["anthropic/claude-sonnet-4-6"],        },        config: {          dreaming: {            enabled: true,            frequency: "0 3 * * *",            model: "anthropic/claude-sonnet-4-6",          },        },      },    },  },}

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

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