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 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 agents.list[].memorySearch por agente), salvo indicação em contrário.

Seleção do 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 OpenAI. Configurações legadas que ainda especificam provider: "auto" são resolvidas como openai.

Quando provider não está definido, o provider: "auto" legado 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 estão disponíveis.

Provedores não locais definidos explicitamente falham de forma fechada. Se memorySearch.provider for definido 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 OpenAI, e esse provedor estiver indisponível em tempo de 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 deliberadamente a recuperação somente por FTS.

IDs de provedores personalizados

memorySearch.provider pode apontar para uma entrada models.providers.<id> personalizada para adaptadores de provedor específicos de memória, como ollama, ou para APIs de modelos compatíveis com OpenAI, como openai-responses / openai-completions. O OpenClaw resolve o proprietário api desse provedor para o adaptador de embeddings, preservando o ID personalizado do provedor para o tratamento do endpoint, da autenticação e do 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 padrão de credenciais do AWS SDK (funções de instância, SSO, chaves de acesso ou uma chave de API do Bedrock).

Configuração do endpoint remoto

Use provider: "openai-compatible" para um servidor /v1/embeddings genérico compatível com OpenAI que não deve 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 embedding em linha

Comportamento da indexação

Todos em memorySearch.sync, salvo indicação em contrário:

Configuração da busca 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 workspace. 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 a busca 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 de { path, name, pattern? }, mas são mescladas por agente e podem preservar nomes compartilhados explícitos quando o caminho aponta para fora do workspace 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 embeddings de texto inalterado durante a reindexação ou atualizações de transcrições. Deixe maxEntries não definido para um cache ilimitado; defina-o quando o crescimento do uso de disco for mais importante que a velocidade máxima de reindexação. Quando definido, as entradas mais antigas (pelo horário da última atualização) são removidas primeiro assim que o cache excede o limite.

Indexação em lote

Disponível para gemini, openai e voyage. O processamento em lote da OpenAI geralmente é a opção mais rápida e econômica para grandes preenchimentos retroativos.

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

Isso é independente de sync.embeddingBatchTimeoutSeconds, que controla o tempo limite das chamadas de embedding 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 respeitam tools.sessions.visibility. A visibilidade padrão tree expõe apenas a sessão atual e as sessões que ela iniciou. Para recuperar, a partir de uma sessão diferente, como uma mensagem direta, uma sessão não relacionada do mesmo agente despachada pelo Gateway, amplie intencionalmente a visibilidade para agent (ou somente para all 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 equivalentes de memorySearch em uma substituição por agente quando apenas um agente deve indexar e pesquisar transcrições de sessões.

Para recuperação do Gateway para mensagens diretas no 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 transcrições para o QMD por si só. 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 no processo.

Armazenamento do índice

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. O OpenClaw não executa verificações de prontidão vetorial semântica nem manutenção de embeddings do QMD nesse modo, inclusive durante memory status --deep; vsearch e query continuam exigindo a prontidão vetorial e os embeddings do QMD.

rerank: false altera apenas o modo query do QMD e requer o QMD 2.1 ou mais recente. No modo CLI direto, o OpenClaw passa --no-rerank; no modo MCP com mcporter, passa rerank: false para a ferramenta unificada de consulta do QMD. Deixe-o não definido para usar o comportamento padrão de reclassificação de consultas do QMD.

O OpenClaw dá preferência aos formatos atuais de coleções e consultas MCP do QMD, mas mantém versões mais antigas do QMD funcionando ao tentar, quando necessário, sinalizadores compatíveis de padrões de coleções e nomes antigos de ferramentas MCP. Quando o QMD anuncia compatibilidade com vários filtros de coleções, as coleções da mesma fonte são pesquisadas com um único processo do QMD; compilações antigas do QMD mantêm o caminho de compatibilidade por coleção. Mesma fonte significa que as coleções de memória persistente (arquivos de memória padrão mais 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 fontes continue tendo ambas as entradas.

Integração com o mcporter

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

Requer mcporter instalado e disponível no PATH, além de um servidor mcporter configurado que execute 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 ao iniciar o Gateway está habilitada, o OpenClaw inicia o QMD somente para agentes elegíveis. Se update.onBoot for true e nenhuma manutenção por intervalo/embedding 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 embedding estiver configurado, a inicialização abrirá o gerenciador QMD de longa duração para que ele possa gerenciar o observador e os temporizadores de intervalo; update.onBoot: false ignora apenas 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 consultar 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
• Busca na memória