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 gerais conceituais, 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 do provedor

# Ordem de detecção automática

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

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).

# Configuração de endpoint remoto

Para endpoints personalizados compatíveis com OpenAI ou para substituir 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

{
  agents: {
    defaults: {
      memorySearch: {
        provider: "openai",
        remote: {
          baseUrl: "https://embeddings.example/v1",
          apiKey: "env: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 main
openclaw memory index --force --agent main

# Tempo limite de incorporação em linha

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

{
  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:

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

# Cache de embeddings

Impede a regeração de embeddings de texto inalterado durante reindexação ou atualizações de transcrições.

# 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 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:

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

Quando sqlite-vec está indisponível, o OpenClaw recorre automaticamente à similaridade de cosseno em processo.

# Armazenamento do índice

# Configuração do backend QMD

Defina memory.backend = "qmd" para habilitar. Todas as configurações de QMD ficam em memory.qmd:

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.

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

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

# 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 de memória
• Busca de memória