Pesquisa de memória

memory_search encontra notas relevantes nos seus arquivos de memória, mesmo quando a redação difere do texto original. Ele divide a memória em pequenos trechos e faz buscas neles usando embeddings, palavras-chave ou ambos.

Início rápido

O OpenClaw usa embeddings da OpenAI por padrão. Para usar outro provedor, defina-o explicitamente:

{  agents: {    defaults: {      memorySearch: {        provider: "openai", // ou "gemini", "voyage", "mistral", "bedrock", "local", "ollama", "lmstudio", "github-copilot", "openai-compatible"      },    },  },}

provider também pode referenciar uma entrada personalizada models.providers.<id> (por exemplo, ollama-5080), desde que essa entrada defina api como "ollama" ou outro ID de provedor com um adaptador de embeddings de memória.

Para embeddings locais sem chave de API, instale o plugin oficial do provedor llama.cpp e defina provider: "local":

openclaw plugins install @openclaw/llama-cpp-provider

Checkouts do código-fonte ainda exigem aprovação da compilação nativa: pnpm approve-builds e, em seguida, pnpm rebuild node-llama-cpp.

Alguns endpoints de embeddings compatíveis com OpenAI exigem rótulos assimétricos de input_type, como "query" para buscas e "document"/"passage" para trechos indexados. Defina-os com queryInputType e documentInputType; consulte a Referência de configuração de memória.

Provedores compatíveis

Como a busca funciona

O OpenClaw executa duas rotas de recuperação em paralelo e combina os resultados:

flowchart LR
    Q["Consulta"] --> E["Embedding"]
    Q --> T["Tokenizar"]
    E --> VS["Busca vetorial"]
    T --> BM["Busca BM25"]
    VS --> M["Combinação ponderada"]
    BM --> M
    M --> R["Principais resultados"]

• Busca vetorial encontra significados semelhantes ("host do gateway" corresponde a "a máquina que executa o OpenClaw").
• Busca por palavras-chave BM25 encontra termos exatos (IDs, strings de erro, chaves de configuração).
• Busca por nome de arquivo indexa os caminhos separadamente do conteúdo das notas. Caminhos completos exatos, nomes de arquivos e nomes sem extensão aparecem antes de correspondências parciais de caminhos, enquanto os trechos e as pontuações de palavras-chave do conteúdo ainda vêm do conteúdo das notas.

Se apenas uma rota estiver disponível, ela será executada sozinha.

Modo somente FTS. Defina provider: "none" para desativar intencionalmente os embeddings e buscar apenas com palavras-chave. Deixar provider sem definição ou definido como "auto" também recorre à classificação apenas por palavras-chave se nenhuma autenticação de embeddings estiver configurada, sem gerar erro, assim como provider: "local" (o provedor GGUF/llama.cpp) quando falha.

Provedor explícito indisponível. Se você nomear explicitamente qualquer outro provedor (por exemplo, openai, ollama, gemini) e ele ficar indisponível no momento da solicitação (autenticação incorreta, falha de rede), memory_search informa que a memória está indisponível em vez de degradar silenciosamente para resultados somente FTS. Isso mantém visível um provedor configurado com problemas. Defina provider: "none" para uma recuperação deliberadamente somente FTS ou corrija a configuração do provedor/autenticação para restaurar a classificação semântica.

Como melhorar a qualidade da busca

Dois recursos opcionais ajudam quando há um grande histórico de notas.

Decaimento temporal

Notas antigas perdem gradualmente peso na classificação para que informações recentes apareçam primeiro. Com a meia-vida padrão de 30 dias, uma nota do mês passado recebe 50% do seu peso original. MEMORY.md e outros arquivos sem data em memory/ são perenes e nunca sofrem decaimento; apenas arquivos datados memory/YYYY-MM-DD.md sofrem decaimento.

MMR (diversidade)

Reduz resultados redundantes. Se cinco notas mencionarem a mesma configuração de roteador, o MMR garante que os principais resultados abranjam diferentes tópicos em vez de se repetirem.

Ativar ambos

{  agents: {    defaults: {      memorySearch: {        query: {          hybrid: {            mmr: { enabled: true },            temporalDecay: { enabled: true },          },        },      },    },  },}

Memória multimodal

Com gemini-embedding-2-preview, você pode indexar imagens e áudio junto com Markdown. Isso se aplica apenas aos arquivos em memorySearch.extraPaths; as raízes de memória padrão (MEMORY.md, memory/*.md) permanecem restritas a Markdown. As consultas de busca continuam sendo texto, mas encontram correspondências em conteúdo visual e de áudio. Consulte a Referência de configuração de memória para saber como configurar.

Busca na memória de sessões

Para recuperação exata de texto completo nas transcrições de sessões, use sessions_search e depois abra um resultado com sessions_history. A busca na memória de sessões continua sendo o complemento semântico e experimental.

Opcionalmente, indexe as transcrições de sessões para que memory_search possa recuperar conversas anteriores. Esse recurso é opcional: defina experimental.sessionMemory: true e adicione "sessions" a sources (o valor padrão de sources é ["memory"]).

Os resultados de sessões obedecem a tools.sessions.visibility: o padrão "tree" apenas expõe a sessão atual e as sessões que ela iniciou. Para recuperar uma sessão não relacionada do mesmo agente a partir de outra sessão (por exemplo, uma sessão despachada pelo gateway a partir de uma DM), amplie a visibilidade para "agent".

Ao usar o backend QMD, defina também memory.qmd.sessions.enabled: true para que as transcrições sejam exportadas para a coleção QMD; experimental.sessionMemory e sources sozinhos não exportam transcrições para o QMD. Consulte a referência de configuração.

Solução de problemas

Nenhum resultado? Execute openclaw memory status para verificar o índice. Se estiver vazio, execute openclaw memory index --force.

Apenas correspondências de palavras-chave? Seu provedor de embeddings pode não estar configurado. Verifique openclaw memory status --deep.

Os embeddings locais atingem o tempo limite? ollama, lmstudio e local usam um tempo limite maior para lotes em linha por padrão. Se o host estiver apenas lento, defina agents.defaults.memorySearch.sync.embeddingBatchTimeoutSeconds e execute novamente openclaw memory index --force.

Texto CJK não encontrado? Recrie o índice FTS com openclaw memory index --force.

Relacionados

• Visão geral da memória
• Active Memory
• Mecanismo de memória integrado
• Referência de configuração de memória