Справочник по настройке памяти

На этой странице перечислены все параметры конфигурации для поиска по памяти OpenClaw. Концептуальные обзоры см. здесь:

Все настройки поиска по памяти находятся в agents.defaults.memorySearch в openclaw.json, если не указано иное.

Выбор провайдера

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

Когда provider не задан, присутствует устаревший provider: "auto" или provider: "none" намеренно выбирает режим только FTS, восстановление памяти все равно может использовать лексическое ранжирование FTS, когда embeddings недоступны.

Явные нелокальные провайдеры завершаются закрыто. Если вы задаете memorySearch.provider как конкретного удаленного провайдера, например OpenAI, Gemini, Voyage, Mistral, Bedrock, GitHub Copilot, DeepInfra, Ollama, LM Studio или OpenAI-совместимого пользовательского провайдера, и этот провайдер недоступен во время выполнения, memory_search возвращает результат о недоступности вместо неявного использования восстановления только через FTS. Исправьте конфигурацию провайдера/аутентификации, переключитесь на доступного провайдера или задайте provider: "none", если хотите намеренно использовать восстановление только через FTS.

Пользовательские ID провайдеров

memorySearch.provider может указывать на пользовательскую запись models.providers.<id> для специализированных адаптеров провайдера памяти, таких как ollama, или для OpenAI-совместимых API моделей, таких как openai-responses / openai-completions. OpenClaw разрешает владельца api этого провайдера для адаптера embedding, сохраняя пользовательский ID провайдера для endpoint, аутентификации и обработки префиксов моделей. Это позволяет конфигурациям с несколькими GPU или хостами выделять embeddings памяти на конкретный локальный endpoint:

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

Разрешение ключа API

Удаленные embeddings требуют ключ API. Вместо этого Bedrock использует цепочку учетных данных AWS SDK по умолчанию (роли экземпляра, SSO, ключи доступа).

Конфигурация удаленного endpoint

Используйте 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

Тайм-аут inline-эмбеддингов

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

Все находится в memorySearch.query.hybrid:

Полный пример

{  agents: {    defaults: {      memorySearch: {        query: {          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 (аудио).

Кэш эмбеддингов

Предотвращает повторное создание эмбеддингов для неизмененного текста при повторном индексировании или обновлении расшифровок.

Пакетное индексирование

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

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

Это отдельно от sync.embeddingBatchTimeoutSeconds, который управляет тайм-аутом встроенных вызовов создания эмбеддингов.

Поиск в памяти сеансов (экспериментально)

Индексируйте расшифровки сеансов и предоставляйте их через memory_search:

Совпадения в стенограммах сессий также подчиняются tools.sessions.visibility. Видимость по умолчанию tree открывает только текущую сессию и сессии, которые она запустила. Чтобы из другой сессии, например из личного сообщения (DM), вспомнить несвязанную сессию того же агента, отправленную через Gateway, намеренно расширьте видимость до agent (или до all только когда также требуется вспоминание между агентами и это разрешает политика взаимодействия агентов).

В примерах ниже эти настройки размещены в agents.defaults. Вы также можете применить эквивалентные настройки memorySearch в переопределении для отдельного агента, когда только один агент должен индексировать стенограммы сессий и искать по ним.

Для вспоминания из Gateway в DM в рамках одного агента:

{  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 автоматически переключается на внутрипроцессное косинусное сходство.

Хранилище индексов

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

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

Задайте memory.backend = "qmd", чтобы включить его. Все настройки QMD находятся в memory.qmd:

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

rerank: false меняет только режим QMD query и требует QMD 2.1 или новее. В режиме прямого CLI OpenClaw передает --no-rerank; в режиме MCP на базе mcporter он передает rerank: false в единый инструмент запросов QMD. Оставьте параметр незаданным, чтобы использовать стандартное поведение reranking запросов QMD.

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

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

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

Полный пример 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 как деталь реализации.

Концептуальное поведение и slash-команды см. в 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",          },        },      },    },  },}

Связанные материалы

• Справочник по конфигурации
• Обзор памяти
• Поиск в памяти