Motor de memoria integrado

El motor integrado es el backend de memoria predeterminado. Almacena tu índice de memoria en una base de datos SQLite por agente y no necesita dependencias adicionales para empezar.

# Qué proporciona

• Búsqueda por palabras clave mediante indexación de texto completo FTS5 (puntuación BM25).
• Búsqueda vectorial mediante embeddings de cualquier proveedor compatible.
• Búsqueda híbrida que combina ambas para obtener mejores resultados.
• Compatibilidad con CJK mediante tokenización por trigramas para chino, japonés y coreano.
• Aceleración sqlite-vec para consultas vectoriales dentro de la base de datos (opcional).

# Primeros pasos

Si tienes una clave de API para OpenAI, Gemini, Voyage, Mistral o DeepInfra, el motor integrado la detecta automáticamente y habilita la búsqueda vectorial. No hace falta configuración.

Para establecer un proveedor explícitamente:

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

Sin un proveedor de embeddings, solo está disponible la búsqueda por palabras clave.

Para forzar el proveedor integrado de embeddings locales, instala el paquete de runtime opcional node-llama-cpp junto a OpenClaw y, después, apunta local.modelPath a un archivo GGUF:

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

# Proveedores de embeddings compatibles

Proveedor	ID	Detectado automáticamente	Notas
OpenAI	openai	Sí	Predeterminado: text-embedding-3-small
Gemini	gemini	Sí	Compatible con multimodal (imagen + audio)
Voyage	voyage	Sí
Mistral	mistral	Sí
DeepInfra	deepinfra	Sí	Predeterminado: BAAI/bge-m3
Ollama	ollama	No	Local, establecer explícitamente
Local	local	Sí (primero)	Runtime opcional node-llama-cpp

La detección automática elige el primer proveedor cuya clave de API se pueda resolver, en el orden mostrado. Establece memorySearch.provider para sobrescribirlo.

# Cómo funciona la indexación

OpenClaw indexa MEMORY.md y memory/*.md en fragmentos (~400 tokens con solapamiento de 80 tokens) y los almacena en una base de datos SQLite por agente.

• Ubicación del índice: ~/.openclaw/memory/<agentId>.sqlite
• Mantenimiento del almacenamiento: los archivos complementarios WAL de SQLite se limitan con checkpoints periódicos y al apagar.
• Vigilancia de archivos: los cambios en archivos de memoria activan una reindexación con debounce (1,5 s).
• Reindexación automática: cuando cambia el proveedor de embeddings, el modelo o la configuración de fragmentación, todo el índice se reconstruye automáticamente.
• Reindexación bajo demanda: openclaw memory index --force

# Cuándo usarlo

El motor integrado es la opción adecuada para la mayoría de los usuarios:

• Funciona de inmediato sin dependencias adicionales.
• Gestiona bien la búsqueda por palabras clave y vectorial.
• Es compatible con todos los proveedores de embeddings.
• La búsqueda híbrida combina lo mejor de ambos enfoques de recuperación.

Considera cambiar a QMD si necesitas reranking, expansión de consultas o quieres indexar directorios fuera del espacio de trabajo.

Considera Honcho si quieres memoria entre sesiones con modelado automático de usuarios.

# Solución de problemas

¿Búsqueda de memoria deshabilitada? Comprueba openclaw memory status. Si no se detecta ningún proveedor, establece uno explícitamente o añade una clave de API.

¿Proveedor local no detectado? Confirma que la ruta local existe y ejecuta:

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

Tanto los comandos CLI independientes como el Gateway usan el mismo id de proveedor local. Si el proveedor se establece en auto, los embeddings locales se consideran primero solo cuando memorySearch.local.modelPath apunta a un archivo local existente.

¿Resultados obsoletos? Ejecuta openclaw memory index --force para reconstruir. El vigilante puede no detectar cambios en casos límite poco frecuentes.

¿sqlite-vec no carga? OpenClaw recurre automáticamente a la similitud del coseno en proceso. openclaw memory status --deep informa del almacén vectorial local por separado del proveedor de embeddings, por lo que Vector store: unavailable apunta a la carga de sqlite-vec, mientras que Embeddings: unavailable apunta a la autenticación/proveedor o a la disponibilidad del modelo. Consulta los registros para ver el error de carga específico.

# Configuración

Para la configuración del proveedor de embeddings, el ajuste de búsqueda híbrida (pesos, MMR, decaimiento temporal), la indexación por lotes, memoria multimodal, sqlite-vec, rutas adicionales y todos los demás parámetros de configuración, consulta la referencia de configuración de memoria.

# Relacionado

• Descripción general de memoria
• Búsqueda de memoria
• Active Memory