Referencia de configuración de memoria

Esta página enumera cada opción de configuración para la búsqueda de memoria de OpenClaw. Para descripciones conceptuales generales, consulta:

Todas las opciones de búsqueda de memoria viven bajo agents.defaults.memorySearch en openclaw.json, salvo que se indique lo contrario.

Selección del proveedor

Cuando provider no está configurado, OpenClaw usa embeddings de OpenAI. Configura provider explícitamente para usar Gemini, Voyage, Mistral, DeepInfra, Bedrock, GitHub Copilot, Ollama, un modelo GGUF local o un endpoint /v1/embeddings compatible con OpenAI. Las configuraciones heredadas que todavía dicen provider: "auto" se resuelven como openai.

Cuando provider no está definido, está presente el provider: "auto" heredado, o provider: "none" selecciona intencionadamente el modo solo FTS, la recuperación de memoria todavía puede usar la clasificación FTS léxica cuando los embeddings no están disponibles.

Los proveedores explícitos no locales fallan de forma cerrada. Si configuras memorySearch.provider con un proveedor concreto respaldado por remoto como OpenAI, Gemini, Voyage, Mistral, Bedrock, GitHub Copilot, DeepInfra, Ollama, LM Studio o un proveedor personalizado compatible con OpenAI, y ese proveedor no está disponible en tiempo de ejecución, memory_search devuelve un resultado no disponible en lugar de usar silenciosamente recuperación solo FTS. Corrige la configuración de proveedor/autenticación, cambia a un proveedor alcanzable o configura provider: "none" si quieres una recuperación deliberadamente solo FTS.

IDs de proveedor personalizados

memorySearch.provider puede apuntar a una entrada personalizada models.providers.<id> para adaptadores de proveedor específicos de memoria como ollama, o para APIs de modelo compatibles con OpenAI como openai-responses / openai-completions. OpenClaw resuelve el propietario de api de ese proveedor para el adaptador de embeddings, conservando a la vez el ID de proveedor personalizado para el manejo de endpoint, autenticación y prefijo de modelo. Esto permite que las configuraciones multi-GPU o multi-host dediquen los embeddings de memoria a un endpoint local específico:

{  models: {    providers: {      "ollama-5080": {        api: "ollama",        baseUrl: "http://gpu-box.local:11435",        apiKey: "ollama-local",        models: [{ id: "qwen3-embedding:0.6b" }],      },    },  },  agents: {    defaults: {      memorySearch: {        provider: "ollama-5080",        model: "qwen3-embedding:0.6b",      },    },  },}

Resolución de clave de API

Los embeddings remotos requieren una clave de API. Bedrock usa en su lugar la cadena de credenciales predeterminada del AWS SDK (roles de instancia, SSO, claves de acceso).

Configuración de endpoint remoto

Usa provider: "openai-compatible" para un servidor genérico /v1/embeddings compatible con OpenAI que no deba heredar las credenciales globales de chat de OpenAI.

{  agents: {    defaults: {      memorySearch: {        provider: "openai-compatible",        model: "text-embedding-3-small",        remote: {          baseUrl: "https://api.example.com/v1/",          apiKey: "YOUR_KEY",        },      },    },  },}

Configuración específica del proveedor

{  agents: {    defaults: {      memorySearch: {        provider: "openai-compatible",        remote: {          baseUrl: "https://embeddings.example/v1",          apiKey: "${EMBEDDINGS_API_KEY}",        },        model: "asymmetric-embedder",        queryInputType: "query",        documentInputType: "passage",      },    },  },}

{  agents: {    defaults: {      memorySearch: {        provider: "bedrock",        model: "amazon.titan-embed-text-v2:0",      },    },  },}

{  "Effect": "Allow",  "Action": "bedrock:InvokeModel",  "Resource": "*"}

arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0

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

Tiempo de espera de embeddings en línea

Configuración de búsqueda híbrida

Todo bajo memorySearch.query.hybrid:

Ejemplo completo

{  agents: {    defaults: {      memorySearch: {        query: {          hybrid: {            vectorWeight: 0.7,            textWeight: 0.3,            mmr: { enabled: true, lambda: 0.7 },            temporalDecay: { enabled: true, halfLifeDays: 30 },          },        },      },    },  },}

Rutas de memoria adicionales

{  agents: {    defaults: {      memorySearch: {        extraPaths: ["../team-docs", "/srv/shared-notes"],      },    },  },}

Las rutas pueden ser absolutas o relativas al espacio de trabajo. Los directorios se analizan de forma recursiva en busca de archivos .md. El manejo de enlaces simbólicos depende del backend activo: el motor integrado ignora los enlaces simbólicos, mientras que QMD sigue el comportamiento del escáner QMD subyacente.

Para la búsqueda de transcripciones entre agentes con alcance de agente, usa agents.list[].memorySearch.qmd.extraCollections en lugar de memory.qmd.paths. Esas colecciones adicionales siguen la misma forma { path, name, pattern? }, pero se combinan por agente y pueden preservar nombres compartidos explícitos cuando la ruta apunta fuera del espacio de trabajo actual. Si la misma ruta resuelta aparece tanto en memory.qmd.paths como en memorySearch.qmd.extraCollections, QMD conserva la primera entrada y omite el duplicado.

Memoria multimodal (Gemini)

Indexa imágenes y audio junto con Markdown usando Gemini Embedding 2:

Formatos compatibles: .jpg, .jpeg, .png, .webp, .gif, .heic, .heif (imágenes); .mp3, .wav, .ogg, .opus, .m4a, .aac, .flac (audio).

Caché de embeddings

Evita volver a generar embeddings de texto sin cambios durante la reindexación o las actualizaciones de transcripciones.

Indexación por lotes

Disponible para openai, gemini y voyage. Los lotes de OpenAI suelen ser la opción más rápida y económica para grandes cargas iniciales.

remote.nonBatchConcurrency controla las llamadas de embeddings en línea usadas por proveedores locales/autohospedados y proveedores alojados cuando las API de lotes del proveedor no están activas. Ollama usa de forma predeterminada 1 para la indexación sin lotes para evitar sobrecargar hosts locales más pequeños; establece un valor más alto en máquinas más grandes.

Esto es independiente de sync.embeddingBatchTimeoutSeconds, que controla el tiempo de espera de las llamadas de embeddings en línea.

Búsqueda de memoria de sesión (experimental)

Indexa transcripciones de sesiones y muéstralas mediante memory_search:

Las coincidencias de transcripciones de sesión también obedecen tools.sessions.visibility. La visibilidad predeterminada tree solo expone la sesión actual y las sesiones que esta inició. Para recuperar desde una sesión diferente, como un DM, una sesión no relacionada despachada por el Gateway del mismo agente, amplía intencionalmente la visibilidad a agent (o a all solo cuando también se requiere recuperación entre agentes y la política entre agentes lo permite).

Los ejemplos siguientes colocan estos ajustes bajo agents.defaults. También puedes aplicar ajustes equivalentes de memorySearch en una anulación por agente cuando solo un agente deba indexar y buscar transcripciones de sesión.

Para recuperación Gateway-a-DM del mismo agente:

{  agents: {    defaults: {      memorySearch: {        experimental: { sessionMemory: true },        sources: ["memory", "sessions"],      },    },  },  tools: {    sessions: { visibility: "agent" },  },}

{  agents: {    defaults: {      memorySearch: {        experimental: { sessionMemory: true },        sources: ["memory", "sessions"],      },    },  },  memory: {    backend: "qmd",    qmd: {      sessions: { enabled: true },    },  },  tools: {    sessions: { visibility: "agent" },  },}

Al usar QMD, agents.defaults.memorySearch.experimental.sessionMemory y sources: ["sessions"] no exportan por sí solos las transcripciones a QMD. Configura también memory.qmd.sessions.enabled: true.

Aceleración vectorial de SQLite (sqlite-vec)

Cuando sqlite-vec no está disponible, OpenClaw recurre automáticamente a la similitud coseno en proceso.

Almacenamiento de índices

Los índices de memoria integrados residen en la base de datos SQLite de OpenClaw de cada agente en agents/<agentId>/agent/openclaw-agent.sqlite.

Configuración del backend QMD

Configura memory.backend = "qmd" para habilitarlo. Todos los ajustes de QMD residen bajo memory.qmd:

searchMode: "search" es solo léxico/BM25. OpenClaw no ejecuta pruebas de preparación vectorial semántica ni mantenimiento de embeddings de QMD para ese modo, incluso durante memory status --deep; vsearch y query siguen requiriendo preparación vectorial y embeddings de QMD.

rerank: false solo cambia el modo query de QMD y requiere QMD 2.1 o una versión más reciente. En modo CLI directo, OpenClaw pasa --no-rerank; en modo MCP respaldado por mcporter, pasa rerank: false a la herramienta de consulta unificada de QMD. Déjalo sin configurar para usar el comportamiento predeterminado de reordenamiento de consultas de QMD.

OpenClaw prefiere las formas actuales de colección de QMD y consulta MCP, pero mantiene funcionando versiones anteriores de QMD intentando flags compatibles de patrón de colección y nombres de herramientas MCP antiguos cuando sea necesario. Cuando QMD anuncia compatibilidad con múltiples filtros de colección, las colecciones de la misma fuente se buscan con un único proceso de QMD; las compilaciones anteriores de QMD mantienen la ruta de compatibilidad por colección. Misma fuente significa que las colecciones de memoria duradera se agrupan juntas, mientras que las colecciones de transcripciones de sesión permanecen como un grupo separado para que la diversificación de fuentes siga teniendo ambas entradas.

{  memory: {    qmd: {      scope: {        default: "deny",        rules: [{ action: "allow", match: { chatType: "direct" } }],      },    },  },}

Cuando la inicialización de QMD al iniciar el Gateway está habilitada, OpenClaw inicia QMD solo para los agentes elegibles. Si update.onBoot es true y no se configuró mantenimiento de intervalos/incrustación, el inicio usa un administrador de una sola ejecución para la actualización de arranque y lo cierra. Si se configura un intervalo de actualización o incrustación, el inicio abre el administrador QMD de larga duración para que pueda controlar el observador y los temporizadores de intervalo; update.onBoot: false omite solo la actualización inmediata de arranque.

Ejemplo completo de QMD

{  memory: {    backend: "qmd",    citations: "auto",    qmd: {      includeDefaultMemory: true,      update: { interval: "5m", debounceMs: 15000 },      limits: { maxResults: 6, timeoutMs: 4000 },      scope: {        default: "deny",        rules: [{ action: "allow", match: { chatType: "direct" } }],      },      paths: [{ name: "docs", path: "~/notes", pattern: "**/*.md" }],    },  },}

Dreaming

Dreaming se configura en plugins.entries.memory-core.config.dreaming, no en agents.defaults.memorySearch.

Dreaming se ejecuta como un barrido programado único y usa fases internas ligera/profunda/REM como detalle de implementación.

Para el comportamiento conceptual y los comandos slash, consulta Dreaming.

Configuración de usuario

Ejemplo

{  plugins: {    entries: {      "memory-core": {        subagent: {          allowModelOverride: true,          allowedModels: ["anthropic/claude-sonnet-4-6"],        },        config: {          dreaming: {            enabled: true,            frequency: "0 3 * * *",            model: "anthropic/claude-sonnet-4-6",          },        },      },    },  },}

Relacionado

• Referencia de configuración
• Descripción general de la memoria
• Búsqueda de memoria