Referência de configuração de memória

Esta página lista todas as opções de configuração da busca de memória do OpenClaw. Para obter visões gerais conceituais, consulte:

Todas as configurações de busca de memória ficam em agents.defaults.memorySearch no openclaw.json (ou em uma substituição por agente em agents.list[].memorySearch), salvo indicação em contrário.

Seleção de provedor

Quando provider não está definido, o OpenClaw usa embeddings da OpenAI. Defina provider explicitamente para usar Bedrock, DeepInfra, Gemini, GitHub Copilot, Mistral, Ollama, Voyage, um modelo GGUF local ou um endpoint /v1/embeddings compatível com a OpenAI. Configurações antigas que ainda usam provider: "auto" são resolvidas como openai.

Quando provider não está definido, a configuração antiga provider: "auto" está presente ou provider: "none" seleciona intencionalmente o modo somente FTS, a recuperação de memória ainda pode usar a classificação lexical FTS quando os embeddings não estiverem disponíveis.

Provedores não locais explícitos falham de forma fechada. Se você definir memorySearch.provider como um provedor concreto com backend remoto, como Bedrock, DeepInfra, Gemini, GitHub Copilot, LM Studio, Mistral, Ollama, OpenAI, Voyage ou um provedor personalizado compatível com a OpenAI, e esse provedor não estiver disponível durante a execução, memory_search retornará um resultado de indisponibilidade em vez de usar silenciosamente a recuperação somente por FTS. Corrija a configuração do provedor ou da autenticação, mude para um provedor acessível ou defina provider: "none" se quiser usar intencionalmente a recuperação somente por FTS.

IDs de provedores personalizados

memorySearch.provider pode apontar para uma entrada personalizada models.providers.<id> destinada a adaptadores específicos de provedor de memória, como ollama, ou a APIs de modelo compatíveis com a OpenAI, como openai-responses / openai-completions. O OpenClaw resolve o proprietário da api desse provedor para o adaptador de embeddings, preservando o ID personalizado do provedor para o tratamento de endpoint, autenticação e prefixo do modelo. Isso permite que configurações com várias GPUs ou vários hosts dediquem os embeddings de memória a um endpoint local específico:

{  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",      },    },  },}

Resolução da chave de API

Embeddings remotos exigem uma chave de API. O Bedrock usa a cadeia de credenciais padrão do AWS SDK (funções de instância, SSO, chaves de acesso ou uma chave de API do Bedrock).

Configuração de endpoint remoto

Use provider: "openai-compatible" para um servidor /v1/embeddings genérico compatível com a OpenAI que não deva herdar as credenciais globais de chat da OpenAI.

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

Configuração específica do provedor

{  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

Tempo limite de embeddings em linha

Comportamento da indexação

Todas as opções ficam em memorySearch.sync, salvo indicação em contrário:

Configuração da pesquisa híbrida

Tudo em memorySearch.query:

E em memorySearch.query.hybrid:

Exemplo completo

{  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 },          },        },      },    },  },}

Caminhos adicionais de memória

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

Os caminhos podem ser absolutos ou relativos ao espaço de trabalho. Os diretórios são examinados recursivamente em busca de arquivos .md. O tratamento de links simbólicos depende do backend ativo: o mecanismo integrado ignora links simbólicos, enquanto o QMD segue o comportamento do scanner QMD subjacente.

Para pesquisa de transcrições entre agentes com escopo por agente, use agents.list[].memorySearch.qmd.extraCollections em vez de memory.qmd.paths. Essas coleções adicionais seguem o mesmo formato { path, name, pattern? }, mas são mescladas por agente e podem preservar nomes compartilhados explícitos quando o caminho aponta para fora do espaço de trabalho atual. Se o mesmo caminho resolvido aparecer tanto em memory.qmd.paths quanto em memorySearch.qmd.extraCollections, o QMD mantém a primeira entrada e ignora a duplicata.

Memória multimodal (Gemini)

Indexe imagens e áudio junto com Markdown usando o Gemini Embedding 2:

Formatos compatíveis: .jpg, .jpeg, .png, .webp, .gif, .heic, .heif (imagens); .mp3, .wav, .ogg, .opus, .m4a, .aac, .flac (áudio).

Cache de embeddings

Evita gerar novamente os embeddings de textos inalterados durante a reindexação ou as atualizações de transcrições. Deixe maxEntries não definido para manter um cache ilimitado; defina-o quando o crescimento do uso de disco for mais importante do que a velocidade máxima de reindexação. Quando definido, as entradas mais antigas (por horário da última atualização) são removidas primeiro assim que o cache ultrapassa o limite.

Indexação em lote

Disponível para gemini, openai e voyage. O processamento em lote da OpenAI geralmente é mais rápido e econômico para grandes preenchimentos retroativos.

remote.nonBatchConcurrency controla as chamadas de embeddings em linha usadas por provedores locais/auto-hospedados e provedores hospedados quando as APIs de lote do provedor não estão ativas. O padrão do Ollama é 1 para indexação sem lote, a fim de evitar sobrecarregar hosts locais menores; defina um valor maior em máquinas mais potentes.

Isso é separado de sync.embeddingBatchTimeoutSeconds, que controla o tempo limite das chamadas de embeddings em linha.

Pesquisa na memória da sessão (experimental)

Indexe transcrições de sessões e disponibilize-as por meio de memory_search:

Os resultados de transcrições de sessões também obedecem a tools.sessions.visibility. A visibilidade tree padrão expõe somente a sessão atual e as sessões iniciadas por ela. Para recuperar, em outra sessão — como uma mensagem direta — uma sessão não relacionada, despachada pelo Gateway para o mesmo agente, amplie intencionalmente a visibilidade para agent (ou para all somente quando a recuperação entre agentes também for necessária e a política entre agentes permitir).

Os exemplos abaixo colocam essas configurações em agents.defaults. Também é possível aplicar configurações memorySearch equivalentes em uma substituição específica por agente quando apenas um agente deve indexar e pesquisar transcrições de sessões.

Para recuperação do Gateway em mensagens diretas pelo mesmo agente:

{  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" },  },}

Ao usar o QMD, agents.defaults.memorySearch.experimental.sessionMemory e sources: ["sessions"] não exportam, por si só, as transcrições para o QMD. Defina também memory.qmd.sessions.enabled: true.

Aceleração vetorial do SQLite (sqlite-vec)

Quando o sqlite-vec não está disponível, o OpenClaw recorre automaticamente à similaridade de cosseno executada no próprio processo.

Armazenamento dos índices

Os índices de memória integrados ficam no banco de dados SQLite do OpenClaw de cada agente, em agents/<agentId>/agent/openclaw-agent.sqlite.

Configuração do backend QMD

Defina memory.backend = "qmd" para habilitá-lo. Todas as configurações do QMD ficam em memory.qmd:

searchMode: "search" usa apenas pesquisa lexical/BM25. Nesse modo, o OpenClaw não executa verificações de prontidão dos vetores semânticos nem a manutenção de embeddings do QMD, inclusive durante memory status --deep; vsearch e query continuam exigindo que os vetores e embeddings do QMD estejam prontos.

rerank: false altera apenas o modo query do QMD e exige o QMD 2.1 ou mais recente. No modo de CLI direto, o OpenClaw passa --no-rerank; no modo MCP baseado no mcporter, ele passa rerank: false para a ferramenta de consulta unificada do QMD. Deixe essa opção sem definição para usar o comportamento padrão de reranqueamento de consultas do QMD.

O OpenClaw prefere os formatos atuais de coleções e consultas MCP do QMD, mas mantém versões anteriores do QMD funcionando ao tentar opções compatíveis de padrões de coleção e nomes antigos de ferramentas MCP quando necessário. Quando o QMD anuncia compatibilidade com vários filtros de coleção, coleções da mesma origem são pesquisadas com um único processo do QMD; compilações mais antigas do QMD mantêm o caminho de compatibilidade por coleção. Mesma origem significa que as coleções de memória durável — arquivos de memória padrão e caminhos personalizados — são agrupadas, enquanto as coleções de transcrições de sessões permanecem em um grupo separado, para que a diversificação de origens continue tendo ambas as entradas.

Integração com o mcporter

Todas as opções ficam em memory.qmd.mcporter. Encaminha as pesquisas do QMD por um daemon MCP mcporter de longa duração, em vez de iniciar o qmd a cada consulta, reduzindo a sobrecarga da inicialização a frio para modelos maiores.

Exige que o mcporter esteja instalado e disponível no PATH, além de um servidor mcporter configurado para executar qmd mcp. Mantenha desabilitado em configurações locais mais simples, nas quais o custo de iniciar um processo por consulta seja aceitável.

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

Quando a inicialização do QMD na inicialização do Gateway está habilitada, o OpenClaw inicia o QMD somente para agentes elegíveis. Se update.onBoot for true e nenhuma manutenção por intervalo/incorporação estiver configurada, a inicialização usará um gerenciador de execução única para a atualização de inicialização e o fechará. Se um intervalo de atualização ou incorporação estiver configurado, a inicialização abrirá o gerenciador QMD de longa duração para que ele possa controlar o observador e os temporizadores de intervalo; update.onBoot: false ignora somente a atualização imediata de inicialização.

Exemplo completo de 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 é configurado em plugins.entries.memory-core.config.dreaming, não em agents.defaults.memorySearch.

Dreaming é executado como uma única varredura agendada e usa fases internas leve/profunda/REM como detalhe de implementação.

Para conhecer o comportamento conceitual e os comandos de barra, consulte Dreaming.

Configurações do usuário

Exemplo

{  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",          },        },      },    },  },}

Relacionados

• Referência de configuração
• Visão geral da memória
• Pesquisa de memória