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

Esta página lista todos os controles de configuração para a busca de memória do OpenClaw. Para visões conceituais gerais, consulte:

Todas as configurações de busca de memória ficam em agents.defaults.memorySearch no openclaw.json, 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 Gemini, Voyage, Mistral, DeepInfra, Bedrock, GitHub Copilot, Ollama, um modelo GGUF local ou um endpoint /v1/embeddings compatível com OpenAI. Configurações legadas que ainda dizem provider: "auto" são resolvidas para openai.

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

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

IDs de provedores personalizados

memorySearch.provider pode apontar para uma entrada personalizada models.providers.<id> para adaptadores de provedor específicos de memória, como ollama, ou para APIs de modelo compatíveis com OpenAI, como openai-responses / openai-completions. O OpenClaw resolve o proprietário de api desse provedor para o adaptador de embeddings preservando o ID de provedor personalizado para tratamento de endpoint, autenticação e prefixo de modelo. Isso permite que configurações com várias GPUs ou vários hosts dediquem 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" }],      },    },  },  agents: {    defaults: {      memorySearch: {        provider: "ollama-5080",        model: "qwen3-embedding:0.6b",      },    },  },}

Resolução de chave de API

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

Configuração de endpoint remoto

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

Configuração de busca híbrida

Tudo em memorySearch.query.hybrid:

Exemplo completo

{  agents: {    defaults: {      memorySearch: {        query: {          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. Diretórios são varridos recursivamente em busca de arquivos .md. O tratamento de symlinks depende do backend ativo: o mecanismo integrado ignora symlinks, enquanto o QMD segue o comportamento do scanner QMD subjacente.

Para busca de transcritos entre agentes com escopo de agente, use agents.list[].memorySearch.qmd.extraCollections em vez de memory.qmd.paths. Essas coleções extras 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 workspace atual. Se o mesmo caminho resolvido aparecer em memory.qmd.paths e memorySearch.qmd.extraCollections, o QMD mantém a primeira entrada e ignora a duplicada.

Memória multimodal (Gemini)

Indexe imagens e áudio junto com Markdown usando 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 embeddings novamente para texto inalterado durante reindexação ou atualizações de transcritos.

Indexação em lote

Disponível para openai, gemini e voyage. O lote da OpenAI costuma ser o mais rápido e barato para grandes preenchimentos retroativos.

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

Isso é separado de sync.embeddingBatchTimeoutSeconds, que controla o tempo limite para chamadas de embedding inline.

Busca de memória de sessão (experimental)

Indexe transcritos de sessão e exponha-os via memory_search:

As ocorrências em transcrições de sessão também obedecem a tools.sessions.visibility. A visibilidade padrão tree expõe apenas a sessão atual e as sessões que ela criou. Para recuperar uma sessão não relacionada, do mesmo agente, despachada pelo Gateway a partir de outra sessão, como uma DM, amplie intencionalmente a visibilidade para agent (ou 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. Você também pode aplicar configurações equivalentes de memorySearch em uma substituição por agente quando apenas um agente deve indexar e pesquisar transcrições de sessão.

Para recuperação Gateway-para-DM 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 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 SQLite (sqlite-vec)

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

Armazenamento de índice

Í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 habilitar. Todas as configurações do QMD ficam em memory.qmd:

searchMode: "search" é apenas lexical/BM25. O OpenClaw não executa sondagens 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 prontidão vetorial e embeddings do QMD.

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

O OpenClaw prefere os formatos atuais de coleção e consulta MCP do QMD, mas mantém versões mais antigas do QMD funcionando ao tentar flags compatíveis de padrão de coleção e nomes antigos de ferramentas MCP quando necessário. Quando o QMD anuncia suporte a vários filtros de coleção, coleções da mesma fonte são pesquisadas com um único processo QMD; builds mais antigos do QMD mantêm o caminho de compatibilidade por coleção. Mesma fonte significa que coleções de memória durável são agrupadas, enquanto coleções de transcrições de sessão permanecem um grupo separado para que a diversificação de fontes ainda tenha ambas as entradas.

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

Quando a inicialização QMD ao iniciar o gateway está habilitada, o OpenClaw inicia o QMD apenas para agentes elegíveis. Se update.onBoot for verdadeiro e nenhuma manutenção de intervalo/embedding estiver configurada, a inicialização usa um gerenciador de execução única para a atualização de inicialização e o fecha. Se um intervalo de atualização ou embedding estiver configurado, a inicialização abre o gerenciador QMD de longa duração para que ele possa controlar o observador e os timers de intervalo; update.onBoot: false ignora apenas a atualização imediata na inicialização.

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

Dreaming é executado como uma varredura agendada e usa fases internas light/deep/REM como detalhe de implementação.

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

Relacionado

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