Búsqueda en la memoria

memory_search encuentra notas relevantes en los archivos de memoria, incluso cuando la redacción difiere del texto original. Divide la memoria en fragmentos pequeños y los busca mediante embeddings, palabras clave o ambos.

Inicio rápido

OpenClaw utiliza embeddings de OpenAI de forma predeterminada. Para utilizar otro proveedor, configúrelo explícitamente:

{  memory: {    search: {      provider: "openai", // o "gemini", "voyage", "mistral", "bedrock", "local", "ollama", "lmstudio", "github-copilot", "openai-compatible"    },  },}

provider también puede hacer referencia a una entrada models.providers.<id> personalizada (por ejemplo, ollama-5080), siempre que dicha entrada establezca api en "ollama" u otro id de proveedor con un adaptador de embeddings de memoria.

Para usar embeddings locales sin clave de API, instale el Plugin oficial del proveedor llama.cpp y configure provider: "local":

openclaw plugins install @openclaw/llama-cpp-provider

Los checkouts del código fuente siguen requiriendo aprobación para la compilación nativa: pnpm approve-builds y, después, pnpm rebuild node-llama-cpp.

Algunos endpoints de embeddings compatibles con OpenAI requieren etiquetas input_type asimétricas, como "query" para las búsquedas y "document"/"passage" para los fragmentos indexados. Configúrelas con queryInputType y documentInputType; consulte la referencia de configuración de memoria.

Proveedores compatibles

Cómo funciona la búsqueda

OpenClaw ejecuta dos rutas de recuperación en paralelo y combina los resultados:

flowchart LR
    Q["Consulta"] --> E["Embedding"]
    Q --> T["Tokenizar"]
    E --> VS["Búsqueda vectorial"]
    T --> BM["Búsqueda BM25"]
    VS --> M["Combinación ponderada"]
    BM --> M
    M --> R["Resultados principales"]

• La búsqueda vectorial encuentra significados similares ("host del gateway" coincide con "la máquina que ejecuta OpenClaw").
• La búsqueda por palabras clave BM25 encuentra términos exactos (ID, cadenas de error, claves de configuración).
• La búsqueda por nombre de archivo indexa las rutas por separado del contenido de las notas. Las rutas completas exactas, los nombres base y las raíces de los nombres de archivo se clasifican por encima de las coincidencias parciales de rutas, mientras que los fragmentos y las puntuaciones de palabras clave del contenido siguen procediendo del contenido de las notas.

Si solo hay una ruta disponible, esta se ejecuta por sí sola.

Modo solo FTS. Establezca provider: "none" para desactivar intencionadamente los embeddings y buscar solo con palabras clave. Si se deja provider sin configurar o se establece en "auto", también se recurre a la clasificación solo por palabras clave si no se ha configurado la autenticación de embeddings, sin generar errores; lo mismo ocurre con provider: "local" (el proveedor GGUF/llama.cpp) cuando falla.

Proveedor explícito no disponible. Si especifica explícitamente cualquier otro proveedor (por ejemplo, openai, ollama, gemini) y deja de estar disponible en el momento de la solicitud (autenticación incorrecta, fallo de red), memory_search indica que la memoria no está disponible en lugar de degradarse silenciosamente a resultados solo FTS. Esto permite detectar un proveedor configurado que no funciona. Establezca provider: "none" para una recuperación intencionada solo mediante FTS, o corrija la configuración del proveedor o de la autenticación para restaurar la clasificación semántica.

Mejora de la calidad de la búsqueda

Dos funciones opcionales resultan útiles cuando se dispone de un amplio historial de notas.

Decaimiento temporal

Las notas antiguas pierden gradualmente peso en la clasificación para que la información reciente aparezca primero. Con la semivida predeterminada de 30 días, una nota del mes pasado obtiene el 50 % de su peso original. MEMORY.md y otros archivos sin fecha dentro de memory/ son permanentes y nunca sufren decaimiento; solo lo hacen los archivos memory/YYYY-MM-DD.md con fecha.

MMR (diversidad)

Reduce los resultados redundantes. Si cinco notas mencionan la misma configuración del router, MMR garantiza que los resultados principales abarquen temas distintos en lugar de repetirse.

Activar ambas opciones

{  memory: {    search: {      query: {        hybrid: {          mmr: { enabled: true },          temporalDecay: { enabled: true },        },      },    },  },}

Memoria multimodal

Con gemini-embedding-2-preview, se pueden indexar imágenes y audio junto con Markdown. Esto solo se aplica a los archivos dentro de memory.search.extraPaths; las raíces de memoria predeterminadas (MEMORY.md, memory/*.md) siguen limitándose a Markdown. Las consultas de búsqueda siguen siendo de texto, pero se comparan con contenido visual y de audio. Consulte la referencia de configuración de memoria para obtener instrucciones de configuración.

Búsqueda en la memoria de sesiones

Para recuperar texto completo exacto de las transcripciones de sesiones, utilice sessions_search y, después, abra un resultado con sessions_history. La búsqueda en la memoria de sesiones sigue siendo el complemento semántico y experimental.

Opcionalmente, indexe las transcripciones de sesiones para que memory_search pueda recuperar conversaciones anteriores. Esta función es opcional: establezca experimental.sessionMemory: true y añada "sessions" a sources (el valor predeterminado de sources es ["memory"]).

Los resultados de sesiones respetan tools.sessions.visibility: el valor predeterminado "tree" expone la sesión actual, las sesiones que esta inició y las sesiones de grupo del mismo agente supervisadas mediante el conocimiento ambiental de grupos. Con session.dmScope: "main", una configuración de mensajes directos multiusuario comparte esa sesión principal, por lo que los usuarios dirigidos allí pueden recuperar contenido de sus grupos supervisados. Utilice un dmScope por interlocutor para aislar los mensajes directos, o establezca la visibilidad en "self" para excluirse de las lecturas ambientales de sesiones supervisadas. Otras sesiones no relacionadas del mismo agente siguen requiriendo visibilidad "agent".

Cuando se utilice el backend QMD, establezca también memory.qmd.sessions.enabled: true para que las transcripciones se exporten a la colección QMD; experimental.sessionMemory y sources por sí solos no exportan las transcripciones a QMD. Consulte la referencia de configuración.

Solución de problemas

¿No hay resultados? Ejecute openclaw memory status para comprobar el índice. Si está vacío, ejecute openclaw memory index --force.

¿Solo hay coincidencias de palabras clave? Es posible que el proveedor de embeddings no esté configurado. Compruebe openclaw memory status --deep.

¿Se agota el tiempo de espera de los embeddings locales? ollama, lmstudio y local utilizan plazos de procesamiento por lotes más largos, gestionados por el proveedor. Compruebe el estado del proveedor y vuelva a ejecutar openclaw memory index --force.

¿No se encuentra texto CJK? Reconstruya el índice FTS con openclaw memory index --force.

Temas relacionados

• Descripción general de la memoria
• Active Memory
• Motor de memoria integrado
• Referencia de configuración de memoria