Mecanismo de memória integrado

O mecanismo integrado é o backend de memória padrão. Ele armazena o índice de memória em um banco de dados SQLite por agente e não requer dependências adicionais para começar.

O que ele oferece

• Pesquisa por palavra-chave por meio da indexação de texto completo FTS5 (pontuação BM25).
• Pesquisa vetorial por meio de embeddings de qualquer provedor compatível.
• Pesquisa híbrida que combina ambas para obter os melhores resultados.
• Compatibilidade com CJK por meio de tokenização por trigramas para chinês, japonês e coreano.
• Aceleração com sqlite-vec para consultas vetoriais no banco de dados (opcional).

Primeiros passos

Por padrão, o mecanismo integrado usa embeddings da OpenAI. Se OPENAI_API_KEY ou models.providers.openai.apiKey já estiver configurado, a pesquisa vetorial funcionará sem nenhuma configuração adicional de memória.

Para definir explicitamente um provedor:

{  agents: {    defaults: {      memorySearch: {        provider: "openai",      },    },  },}

Sem um provedor de embeddings, somente a pesquisa por palavra-chave estará disponível.

Para forçar o uso de embeddings GGUF locais, instale o plugin oficial do provedor llama.cpp e aponte local.modelPath para um arquivo GGUF:

openclaw plugins install @openclaw/llama-cpp-provider

{  agents: {    defaults: {      memorySearch: {        provider: "local",        fallback: "none",        local: {          modelPath: "~/.node-llama-cpp/models/embeddinggemma-300m-qat-Q8_0.gguf",        },      },    },  },}

Provedores de embeddings compatíveis

Defina memorySearch.provider para deixar de usar a OpenAI.

Como a indexação funciona

O OpenClaw indexa MEMORY.md e memory/*.md em segmentos (400 tokens com sobreposição de 80 tokens por padrão) e os armazena em um banco de dados SQLite por agente.

• Localização do índice: o banco de dados do agente proprietário em ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite
• Manutenção do armazenamento: os arquivos auxiliares WAL do SQLite são limitados por checkpoints periódicos e no encerramento.
• Monitoramento de arquivos: alterações nos arquivos de memória acionam uma reindexação com debounce (1,5 s por padrão).
• Reindexação automática: o índice é recriado automaticamente quando há alterações no provedor de embeddings, no modelo, na configuração de segmentação, nas fontes configuradas ou no escopo.
• Reindexação sob demanda: openclaw memory index --force

Quando usar

O mecanismo integrado é a escolha certa para a maioria dos usuários:

• Funciona imediatamente, sem dependências adicionais.
• Lida bem com pesquisas por palavra-chave e vetoriais.
• É compatível com todos os provedores de embeddings.
• A pesquisa híbrida combina o melhor das duas abordagens de recuperação.

Considere mudar para o QMD se você precisar de reranqueamento, expansão de consultas ou quiser indexar diretórios fora do espaço de trabalho.

Considere o Honcho se você quiser memória entre sessões com modelagem automática do usuário.

Solução de problemas

Pesquisa de memória desativada? Verifique openclaw memory status. Se nenhum provedor for detectado, defina um explicitamente ou adicione uma chave de API.

Provedor local não detectado? Confirme se o caminho local existe e execute:

openclaw memory status --deep --agent mainopenclaw memory index --force --agent main

Tanto os comandos independentes da CLI quanto o Gateway usam o mesmo ID de provedor local. Defina memorySearch.provider: "local" quando quiser usar embeddings locais.

Resultados desatualizados? Execute openclaw memory index --force para recriar o índice. O monitor pode não detectar alterações em casos extremos raros.

O sqlite-vec não está sendo carregado? O OpenClaw recorre automaticamente à similaridade de cosseno no processo. openclaw memory status --deep informa o armazenamento vetorial local separadamente do provedor de embeddings; portanto, Vector store: unavailable indica o carregamento do sqlite-vec, enquanto Embeddings: unavailable indica problemas de prontidão do provedor/autenticação ou do modelo. Consulte os logs para identificar o erro específico de carregamento.

Configuração

Para configurar o provedor de embeddings, ajustar a pesquisa híbrida (pesos, MMR, decaimento temporal), indexação em lote, memória multimodal, sqlite-vec, caminhos adicionais e todas as outras opções de configuração, consulte a referência de configuração de memória.

Relacionado

• Visão geral da memória
• Pesquisa de memória
• Active Memory