Pular para o conteúdo principal

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

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

Visão geral da memória

Como a memória funciona.

Motor integrado

Backend SQLite padrão.

Motor QMD

Sidecar local-first.

Busca de memória

Pipeline de busca e ajuste.

Memória ativa

Subagente de memória para sessões interativas.
Todas as configurações de busca de memória ficam em agents.defaults.memorySearch no openclaw.json, salvo indicação em contrário.
Se você está procurando a alternância do recurso active memory e a configuração do subagente, isso fica em plugins.entries.active-memory em vez de memorySearch.A memória ativa usa um modelo de dois gates:
  1. o Plugin deve estar habilitado e mirar o ID do agente atual
  2. a solicitação deve ser uma sessão de chat persistente interativa elegível
Consulte Active Memory para ver o modelo de ativação, a configuração pertencente ao Plugin, a persistência da transcrição e o padrão de implantação segura.

Seleção do provedor

ChaveTipoPadrãoDescrição
providerstringdetectado automaticamenteID do adaptador de embedding, como bedrock, deepinfra, gemini, github-copilot, local, mistral, ollama, openai ou voyage; também pode ser um models.providers.<id> configurado cujo api aponta para um desses adaptadores
modelstringpadrão do provedorNome do modelo de embedding
fallbackstring"none"ID do adaptador de fallback quando o principal falha
enabledbooleantrueHabilita ou desabilita a busca de memória

Ordem de detecção automática

Quando provider não está definido, o OpenClaw seleciona o primeiro disponível:
1

local

Selecionado se memorySearch.local.modelPath estiver configurado e o arquivo existir.
2

github-copilot

Selecionado se um token do GitHub Copilot puder ser resolvido (variável de ambiente ou perfil de autenticação).
3

openai

Selecionado se uma chave da OpenAI puder ser resolvida.
4

gemini

Selecionado se uma chave do Gemini puder ser resolvida.
5

voyage

Selecionado se uma chave do Voyage puder ser resolvida.
6

mistral

Selecionado se uma chave do Mistral puder ser resolvida.
7

deepinfra

Selecionado se uma chave do DeepInfra puder ser resolvida.
8

bedrock

Selecionado se a cadeia de credenciais do AWS SDK for resolvida (função de instância, chaves de acesso, perfil, SSO, identidade web ou configuração compartilhada).
ollama é compatível, mas não é detectado automaticamente (defina explicitamente).

IDs de provedores personalizados

memorySearch.provider pode apontar para uma entrada personalizada models.providers.<id>. O OpenClaw resolve o proprietário api desse provedor para o adaptador de embedding, preservando o ID personalizado do provedor para o tratamento de endpoint, autenticação e prefixo de modelo. Isso permite que configurações com múltiplas GPUs ou múltiplos 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. Em vez disso, o Bedrock usa a cadeia de credenciais padrão do AWS SDK (funções de instância, SSO, chaves de acesso).
ProvedorVariável de ambienteChave de configuração
BedrockCadeia de credenciais da AWSNenhuma chave de API necessária
DeepInfraDEEPINFRA_API_KEYmodels.providers.deepinfra.apiKey
GeminiGEMINI_API_KEYmodels.providers.google.apiKey
GitHub CopilotCOPILOT_GITHUB_TOKEN, GH_TOKEN, GITHUB_TOKENPerfil de autenticação via login por dispositivo
MistralMISTRAL_API_KEYmodels.providers.mistral.apiKey
OllamaOLLAMA_API_KEY (placeholder)
OpenAIOPENAI_API_KEYmodels.providers.openai.apiKey
VoyageVOYAGE_API_KEYmodels.providers.voyage.apiKey
O OAuth do Codex cobre apenas chat/conclusões e não atende a solicitações de embedding.

Configuração de endpoint remoto

Para endpoints personalizados compatíveis com OpenAI ou para substituir os padrões do provedor:
remote.baseUrl
string
URL base personalizada da API.
remote.apiKey
string
Substitui a chave de API.
remote.headers
object
Cabeçalhos HTTP extras (mesclados com os padrões do provedor).
{
  agents: {
    defaults: {
      memorySearch: {
        provider: "openai",
        model: "text-embedding-3-small",
        remote: {
          baseUrl: "https://api.example.com/v1/",
          apiKey: "YOUR_KEY",
        },
      },
    },
  },
}

Configuração específica do provedor

ChaveTipoPadrãoDescrição
modelstringgemini-embedding-001Também oferece suporte a gemini-embedding-2-preview
outputDimensionalitynumber3072Para Embedding 2: 768, 1536 ou 3072
Alterar o modelo ou outputDimensionality aciona uma reindexação completa automática.
Endpoints de embedding compatíveis com OpenAI podem optar por campos de solicitação input_type específicos do provedor. Isso é útil para modelos de embedding assimétricos que exigem rótulos diferentes para embeddings de consulta e documento.
ChaveTipoPadrãoDescrição
inputTypestringnão definidoinput_type compartilhado para embeddings de consulta e documento
queryInputTypestringnão definidoinput_type em tempo de consulta; substitui inputType
documentInputTypestringnão definidoinput_type de índice/documento; substitui inputType
{
  agents: {
    defaults: {
      memorySearch: {
        provider: "openai",
        remote: {
          baseUrl: "https://embeddings.example/v1",
          apiKey: "env:EMBEDDINGS_API_KEY",
        },
        model: "asymmetric-embedder",
        queryInputType: "query",
        documentInputType: "passage",
      },
    },
  },
}
Alterar esses valores afeta a identidade do cache de embedding para indexação em lote do provedor e deve ser seguido por uma reindexação da memória quando o modelo upstream trata os rótulos de forma diferente.

Configuração de embedding do Bedrock

O Bedrock usa a cadeia de credenciais padrão do AWS SDK — nenhuma chave de API é necessária. Se o OpenClaw for executado no EC2 com uma função de instância habilitada para Bedrock, basta definir o provedor e o modelo:
{
  agents: {
    defaults: {
      memorySearch: {
        provider: "bedrock",
        model: "amazon.titan-embed-text-v2:0",
      },
    },
  },
}
ChaveTipoPadrãoDescrição
modelstringamazon.titan-embed-text-v2:0Qualquer ID de modelo de embedding do Bedrock
outputDimensionalitynumberpadrão do modeloPara Titan V2: 256, 512 ou 1024
Modelos compatíveis (com detecção de família e dimensões padrão):
ID do modeloProvedorDimensões padrãoDimensões configuráveis
amazon.titan-embed-text-v2:0Amazon1024256, 512, 1024
amazon.titan-embed-text-v1Amazon1536
amazon.titan-embed-g1-text-02Amazon1536
amazon.titan-embed-image-v1Amazon1024
amazon.nova-2-multimodal-embeddings-v1:0Amazon1024256, 384, 1024, 3072
cohere.embed-english-v3Cohere1024
cohere.embed-multilingual-v3Cohere1024
cohere.embed-v4:0Cohere1536256-1536
twelvelabs.marengo-embed-3-0-v1:0TwelveLabs512
twelvelabs.marengo-embed-2-7-v1:0TwelveLabs1024
Variantes com sufixo de taxa de transferência (por exemplo, amazon.titan-embed-text-v1:2:8k) herdam a configuração do modelo base.Autenticação: a autenticação do Bedrock usa a ordem padrão de resolução de credenciais do AWS SDK:
  1. Variáveis de ambiente (AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY)
  2. Cache de token SSO
  3. Credenciais de token de identidade web
  4. Arquivos compartilhados de credenciais e configuração
  5. Credenciais de metadados ECS ou EC2
A região é resolvida a partir de AWS_REGION, AWS_DEFAULT_REGION, do baseUrl do provedor amazon-bedrock ou usa us-east-1 como padrão.Permissões IAM: a função ou o usuário IAM precisa de:
{
  "Effect": "Allow",
  "Action": "bedrock:InvokeModel",
  "Resource": "*"
}
Para privilégio mínimo, restrinja InvokeModel ao modelo específico:
arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0
ChaveTipoPadrãoDescrição
local.modelPathstringbaixado automaticamenteCaminho para o arquivo de modelo GGUF
local.modelCacheDirstringpadrão do node-llama-cppDiretório de cache para modelos baixados
local.contextSizenumber | "auto"4096Tamanho da janela de contexto para o contexto de incorporação. 4096 cobre blocos típicos (128–512 tokens) enquanto limita a VRAM que não é de pesos. Reduza para 1024–2048 em hosts restritos. "auto" usa o máximo treinado do modelo — não recomendado para modelos 8B+ (Qwen3-Embedding-8B: 40.960 tokens → ~32 GB de VRAM contra ~8,8 GB em 4096).
Modelo padrão: embeddinggemma-300m-qat-Q8_0.gguf (~0,6 GB, baixado automaticamente). Checkouts do código-fonte ainda exigem aprovação de compilação nativa: pnpm approve-builds e depois pnpm rebuild node-llama-cpp.Use a CLI independente para verificar o mesmo caminho de provedor que o Gateway usa:
openclaw memory status --deep --agent main
openclaw memory index --force --agent main
Se provider for auto, local será selecionado apenas quando local.modelPath apontar para um arquivo local existente. Referências de modelo hf: e HTTP(S) ainda podem ser usadas explicitamente com provider: "local", mas elas não fazem auto selecionar local antes que o modelo esteja disponível em disco.

Tempo limite de incorporação em linha

sync.embeddingBatchTimeoutSeconds
number
Substitui o tempo limite para lotes de incorporação em linha durante a indexação de memória.Quando não definido, usa o padrão do provedor: 600 segundos para provedores locais/auto-hospedados, como local, ollama e lmstudio, e 120 segundos para provedores hospedados. Aumente isso quando os lotes de incorporação locais limitados por CPU estiverem íntegros, mas lentos.

Configuração de busca híbrida

Tudo em memorySearch.query.hybrid:
ChaveTipoPadrãoDescrição
enabledbooleantrueHabilita busca híbrida BM25 + vetorial
vectorWeightnumber0.7Peso das pontuações vetoriais (0-1)
textWeightnumber0.3Peso das pontuações BM25 (0-1)
candidateMultipliernumber4Multiplicador do tamanho do conjunto de candidatos
ChaveTipoPadrãoDescrição
mmr.enabledbooleanfalseHabilita reclassificação por MMR
mmr.lambdanumber0.70 = diversidade máx., 1 = relevância máx.

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 de memória adicionais

ChaveTipoDescrição
extraPathsstring[]Diretórios ou arquivos adicionais para indexar
{
  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 transcrições 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 pula a duplicata.

Memória multimodal (Gemini)

Indexe imagens e áudio junto com Markdown usando Gemini Embedding 2:
ChaveTipoPadrãoDescrição
multimodal.enabledbooleanfalseHabilita indexação multimodal
multimodal.modalitiesstring[]["image"], ["audio"] ou ["all"]
multimodal.maxFileBytesnumber10000000Tamanho máximo de arquivo para indexação
Aplica-se somente a arquivos em extraPaths. As raízes de memória padrão permanecem apenas em Markdown. Requer gemini-embedding-2-preview. fallback deve ser "none".
Formatos compatíveis: .jpg, .jpeg, .png, .webp, .gif, .heic, .heif (imagens); .mp3, .wav, .ogg, .opus, .m4a, .aac, .flac (áudio).

Cache de embeddings

ChaveTipoPadrãoDescrição
cache.enabledbooleanfalseArmazena embeddings de chunks em SQLite
cache.maxEntriesnumber50000Máximo de embeddings em cache
Impede a regeração de embeddings de texto inalterado durante reindexação ou atualizações de transcrições.

Indexação em lote

ChaveTipoPadrãoDescrição
remote.nonBatchConcurrencynumber4Embeddings inline paralelos
remote.batch.enabledbooleanfalseHabilita API de embedding em lote
remote.batch.concurrencynumber2Jobs em lote paralelos
remote.batch.waitbooleantrueAguarda a conclusão do lote
remote.batch.pollIntervalMsnumberIntervalo de sondagem
remote.batch.timeoutMinutesnumberTimeout do 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 APIs de lote do provedor não estão ativas. O Ollama usa 1 por padrão para indexação sem lote para evitar sobrecarregar hosts locais menores; defina um valor maior em máquinas mais robustas. Isso é separado de sync.embeddingBatchTimeoutSeconds, que controla o timeout para chamadas de embedding inline.

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

Indexa transcrições de sessão e as expõe via memory_search:
ChaveTipoPadrãoDescrição
experimental.sessionMemorybooleanfalseHabilita a indexação de sessões
sourcesstring[]["memory"]Adicione "sessions" para incluir transcrições
sync.sessions.deltaBytesnumber100000Limite de bytes para reindexação
sync.sessions.deltaMessagesnumber50Limite de mensagens para reindexação
A indexação de sessões é opcional e executa de forma assíncrona. Os resultados podem estar ligeiramente desatualizados. Os logs de sessão ficam no disco, então trate o acesso ao sistema de arquivos como o limite de confiança.

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

ChaveTipoPadrãoDescrição
store.vector.enabledbooleantrueUsa sqlite-vec para consultas vetoriais
store.vector.extensionPathstringbundledSubstitui o caminho do sqlite-vec
Quando sqlite-vec está indisponível, o OpenClaw recorre automaticamente à similaridade de cosseno em processo.

Armazenamento do índice

ChaveTipoPadrãoDescrição
store.pathstring~/.openclaw/memory/{agentId}.sqliteLocal do índice (compatível com token {agentId})
store.fts.tokenizerstringunicode61Tokenizador FTS5 (unicode61 ou trigram)

Configuração do backend QMD

Defina memory.backend = "qmd" para habilitar. Todas as configurações de QMD ficam em memory.qmd:
ChaveTipoPadrãoDescrição
commandstringqmdCaminho do executável QMD; defina um caminho absoluto quando o PATH do serviço diferir do seu shell
searchModestringsearchComando de busca: search, vsearch, query
includeDefaultMemorybooleantrueIndexa automaticamente MEMORY.md + memory/**/*.md
paths[]arrayCaminhos extras: { name, path, pattern? }
sessions.enabledbooleanfalseIndexa transcrições de sessão
sessions.retentionDaysnumberRetenção de transcrições
sessions.exportDirstringDiretório de exportação
searchMode: "search" é apenas lexical/BM25. O OpenClaw não executa sondagens de prontidão de vetores semânticos nem manutenção de embeddings do QMD para esse modo, inclusive durante memory status --deep; vsearch e query continuam exigindo prontidão de vetores e embeddings do QMD. O OpenClaw prefere a coleção atual do QMD e os formatos de consulta MCP, mas mantém versões antigas do QMD funcionando ao tentar flags de padrão de coleção compatíveis e nomes de ferramentas MCP mais antigos quando necessário. Quando o QMD anuncia suporte a vários filtros de coleção, coleções da mesma origem são pesquisadas com um único processo do QMD; builds antigos do QMD mantêm o caminho de compatibilidade por coleção. Mesma origem significa que coleções de memória durável são agrupadas, enquanto coleções de transcrições de sessão permanecem em um grupo separado para que a diversificação de origem ainda tenha ambas as entradas.
Substituições de modelo do QMD permanecem no lado do QMD, não na configuração do OpenClaw. Se você precisar substituir globalmente os modelos do QMD, defina variáveis de ambiente como QMD_EMBED_MODEL, QMD_RERANK_MODEL e QMD_GENERATE_MODEL no ambiente de runtime do gateway.
ChaveTipoPadrãoDescrição
update.intervalstring5mIntervalo de atualização
update.debounceMsnumber15000Aplica debounce a alterações de arquivos
update.onBootbooleantrueAtualiza quando o gerenciador QMD de longa duração abre; também controla a atualização de inicialização opcional
update.startupstringoffAtualização opcional ao iniciar o gateway: off, idle ou immediate
update.startupDelayMsnumber120000Atraso antes da execução da atualização startup: "idle"
update.waitForBootSyncbooleanfalseBloqueia a abertura do gerenciador até que a atualização inicial seja concluída
update.embedIntervalstringCadência separada de embed
update.commandTimeoutMsnumberTimeout para comandos QMD
update.updateTimeoutMsnumberTimeout para operações de atualização do QMD
update.embedTimeoutMsnumberTimeout para operações de embed do QMD
ChaveTipoPadrãoDescrição
limits.maxResultsnumber6Máximo de resultados de busca
limits.maxSnippetCharsnumberLimita o tamanho do snippet
limits.maxInjectedCharsnumberLimita o total de caracteres injetados
limits.timeoutMsnumber4000Timeout de busca
Controla quais sessões podem receber resultados de busca QMD. Mesmo esquema de session.sendPolicy:
{
  memory: {
    qmd: {
      scope: {
        default: "deny",
        rules: [{ action: "allow", match: { chatType: "direct" } }],
      },
    },
  },
}
O padrão entregue permite sessões diretas e de canal, enquanto ainda nega grupos.O padrão é apenas DM. match.keyPrefix corresponde à chave de sessão normalizada; match.rawKeyPrefix corresponde à chave bruta incluindo agent:<id>:.
memory.citations se aplica a todos os backends:
ValorComportamento
auto (padrão)Inclui rodapé Source: <path#line> nos snippets
onSempre inclui rodapé
offOmite rodapé (o caminho ainda é passado ao agente internamente)
Atualizações de boot do QMD usam um caminho de subprocesso único durante a inicialização do gateway. O gerenciador QMD de longa duração ainda é responsável pelo observador de arquivos regular e pelos temporizadores de intervalo quando a busca de memória é aberta para uso interativo.

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 executa uma única varredura agendada e usa fases internas leve/profunda/REM como detalhe de implementação. Para comportamento conceitual e comandos de barra, consulte Dreaming.

Configurações de usuário

ChaveTipoPadrãoDescrição
enabledbooleanfalseAtiva ou desativa dreaming completamente
frequencystring0 3 * * *Cadência cron opcional para a varredura completa de dreaming
modelstringmodelo padrãoSubstituição opcional do modelo do subagente Dream Diary

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",
          },
        },
      },
    },
  },
}
  • Dreaming grava estado de máquina em memory/.dreams/.
  • Dreaming grava saída narrativa legível por humanos em DREAMS.md (ou no dreams.md existente).
  • dreaming.model usa o gate de confiança de subagente de Plugin existente; defina plugins.entries.memory-core.subagent.allowModelOverride: true antes de ativá-lo.
  • Dream Diary tenta novamente uma vez com o modelo padrão da sessão quando o modelo configurado não está disponível. Falhas de confiança ou allowlist são registradas e não são repetidas silenciosamente.
  • A política e os limites das fases leve/profunda/REM são comportamento interno, não configuração voltada ao usuário.

Relacionados