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

На цій сторінці перелічено всі параметри конфігурації пошуку в пам’яті 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",          },        },      },    },  },}

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

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