Mecanismo de memória integrado

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

O que ele oferece

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

Primeiros passos

Por padrão, o mecanismo integrado usa embeddings da OpenAI. Se você já tiver OPENAI_API_KEY ou models.providers.openai.apiKey configurado, a busca vetorial funciona sem configuração extra de memória.

Para definir um provedor explicitamente:

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

Sem um provedor de embeddings, apenas a busca por palavra-chave fica disponível.

Para forçar embeddings GGUF locais, instale o plugin oficial de provedor llama.cpp e depois 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 mudar da OpenAI para outro provedor.

Como a indexação funciona

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

• Local do índice: o banco de dados do agente proprietário em ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite
• Manutenção do armazenamento: os sidecars WAL do SQLite são limitados com checkpoints periódicos e no desligamento.
• Monitoramento de arquivos: alterações em arquivos de memória acionam uma reindexação com debounce (1,5 s).
• Reindexação automática: quando o provedor de embeddings, modelo ou configuração de divisão em partes muda, todo o índice é reconstruído automaticamente.
• 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 extras.
• Lida bem com busca por palavra-chave e busca vetorial.
• Compatível com todos os provedores de embeddings.
• A busca híbrida combina o melhor das duas abordagens de recuperação.

Considere mudar para QMD se você precisar de reranking, expansão de consulta ou quiser indexar diretórios fora do workspace.

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

Solução de problemas

Busca 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 que o caminho local existe e execute:

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

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

Resultados obsoletos? Execute openclaw memory index --force para reconstruir. O watcher pode deixar de detectar alterações em casos extremos raros.

sqlite-vec não está carregando? O OpenClaw recorre automaticamente à similaridade de cosseno em processo. openclaw memory status --deep relata o armazenamento vetorial local separadamente do provedor de embeddings, portanto Vector store: unavailable aponta para o carregamento do sqlite-vec, enquanto Embeddings: unavailable aponta para prontidão do provedor/autenticação ou do modelo. Verifique os logs para o erro de carregamento específico.

Configuração

Para configuração de provedor de embeddings, ajuste de busca híbrida (pesos, MMR, decaimento temporal), indexação em lote, memória multimodal, sqlite-vec, caminhos extras e todos os outros controles de configuração, consulte a referência de configuração de memória.

Relacionados

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