Referencia de configuración de memoria

Esta página enumera todas las opciones de configuración de la búsqueda en memoria de OpenClaw. Para obtener descripciones conceptuales generales, consulte:

Todos los ajustes de búsqueda en memoria se encuentran en agents.defaults.memorySearch dentro de openclaw.json (o en una anulación por agente de agents.list[].memorySearch), salvo que se indique lo contrario.

Selección del proveedor

Cuando provider no está establecido, OpenClaw utiliza embeddings de OpenAI. Establezca provider explícitamente para utilizar Bedrock, DeepInfra, Gemini, GitHub Copilot, Mistral, Ollama, Voyage, un modelo GGUF local o un endpoint /v1/embeddings compatible con OpenAI. Las configuraciones heredadas que aún indican provider: "auto" se resuelven como openai.

Cuando provider no está establecido, existe el valor heredado provider: "auto" o provider: "none" selecciona intencionadamente el modo de solo FTS, la recuperación de memoria aún puede utilizar la clasificación léxica de FTS cuando los embeddings no están disponibles.

Los proveedores no locales explícitos se cierran ante errores. Si establece memorySearch.provider en un proveedor concreto respaldado por un servicio remoto, como Bedrock, DeepInfra, Gemini, GitHub Copilot, LM Studio, Mistral, Ollama, OpenAI, Voyage o un proveedor personalizado compatible con OpenAI, y ese proveedor no está disponible durante la ejecución, memory_search devuelve un resultado de indisponibilidad en lugar de utilizar silenciosamente la recuperación de solo FTS. Corrija la configuración del proveedor o la autenticación, cambie a un proveedor accesible o establezca provider: "none" si desea utilizar deliberadamente la recuperación de solo FTS.

Identificadores de proveedores personalizados

memorySearch.provider puede apuntar a una entrada models.providers.<id> personalizada para adaptadores de proveedor específicos de memoria, como ollama, o para API de modelos compatibles con OpenAI, como openai-responses / openai-completions. OpenClaw resuelve el propietario api de ese proveedor para el adaptador de embeddings y conserva el identificador del proveedor personalizado para gestionar el endpoint, la autenticación y el prefijo del modelo. Esto permite que las configuraciones con varias GPU o varios hosts 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", name: "Qwen3 Embedding 0.6B" }],      },    },  },  agents: {    defaults: {      memorySearch: {        provider: "ollama-5080",        model: "qwen3-embedding:0.6b",      },    },  },}

Resolución de claves de API

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

Configuración del endpoint remoto

Utilice provider: "openai-compatible" para un servidor /v1/embeddings genérico 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 las incrustaciones en línea

Comportamiento de la indexación

Todo se encuentra bajo memorySearch.sync, salvo que se indique lo contrario:

Configuración de la búsqueda híbrida

Todo se encuentra bajo memorySearch.query:

Y bajo memorySearch.query.hybrid:

Ejemplo completo

{  agents: {    defaults: {      memorySearch: {        query: {          maxResults: 6,          minScore: 0.35,          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 examinan recursivamente en busca de archivos .md. La gestión de enlaces simbólicos depende del backend activo: el motor integrado omite los enlaces simbólicos, mientras que QMD sigue el comportamiento del analizador QMD subyacente.

Para realizar búsquedas de transcripciones entre agentes en el ámbito de un agente, use agents.list[].memorySearch.qmd.extraCollections en lugar de memory.qmd.paths. Esas colecciones adicionales siguen la misma estructura de { path, name, pattern? }, pero se combinan por agente y pueden conservar 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 la duplicada.

Memoria multimodal (Gemini)

Indexe imágenes y audio junto con Markdown mediante 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 los embeddings de texto sin cambios durante la reindexación o las actualizaciones de transcripciones. Deje maxEntries sin definir para disponer de una caché ilimitada; establézcalo cuando el crecimiento del disco sea más importante que la velocidad máxima de reindexación. Cuando se establece, las entradas más antiguas (según la hora de la última actualización) se eliminan primero una vez que la caché supera el límite.

Indexación por lotes

Disponible para gemini, openai y voyage. El procesamiento por lotes de OpenAI suele ser el más rápido y económico para grandes cargas históricas.

remote.nonBatchConcurrency controla las llamadas de embeddings en línea utilizadas por proveedores locales o autoalojados y por proveedores alojados cuando las API de procesamiento por lotes del proveedor no están activas. Ollama utiliza de forma predeterminada 1 para la indexación sin lotes a fin de evitar sobrecargar los hosts locales más pequeños; establezca un valor mayor en máquinas más potentes.

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

Búsqueda en la memoria de sesiones (experimental)

Indexe las transcripciones de sesiones y muéstrelas mediante memory_search:

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

Los ejemplos siguientes colocan estos ajustes en agents.defaults. También se pueden aplicar ajustes equivalentes de memorySearch en una configuración específica por agente cuando solo un agente deba indexar y buscar transcripciones de sesiones.

Para la recuperación del Gateway a mensajes directos 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 utilizar QMD, agents.defaults.memorySearch.experimental.sessionMemory y sources: ["sessions"] no exportan por sí solos las transcripciones a QMD. Establezca 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 del coseno dentro del proceso.

Almacenamiento del índice

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

Configuración del backend QMD

Establezca memory.backend = "qmd" para habilitarlo. Todos los ajustes de QMD se encuentran en memory.qmd:

searchMode: "search" utiliza únicamente búsqueda léxica/BM25. OpenClaw no ejecuta sondeos de disponibilidad de vectores semánticos ni mantenimiento de embeddings de QMD para ese modo, ni siquiera durante memory status --deep; vsearch y query siguen requiriendo que los vectores y embeddings de QMD estén disponibles.

rerank: false solo cambia el modo query de QMD y requiere QMD 2.1 o posterior. En el modo CLI directo, OpenClaw pasa --no-rerank; en el modo MCP respaldado por mcporter, pasa rerank: false a la herramienta de consultas unificada de QMD. Déjelo sin definir para utilizar el comportamiento predeterminado de reclasificación de consultas de QMD.

OpenClaw prefiere las formas actuales de colecciones y consultas MCP de QMD, pero mantiene la compatibilidad con versiones anteriores de QMD probando indicadores de patrones de colecciones compatibles y nombres antiguos de herramientas MCP cuando es necesario. Cuando QMD anuncia que admite varios filtros de colecciones, las colecciones de la misma fuente se buscan mediante 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 (los archivos de memoria predeterminados y las rutas personalizadas) se agrupan, mientras que las colecciones de transcripciones de sesiones permanecen en un grupo independiente para que la diversificación de fuentes siga disponiendo de ambas entradas.

Integración con mcporter

Todo se configura en memory.qmd.mcporter. Enruta las búsquedas de QMD a través de un daemon MCP mcporter de larga duración en lugar de iniciar qmd para cada consulta, lo que reduce la sobrecarga del arranque en frío para los modelos de mayor tamaño.

Requiere que mcporter esté instalado y disponible en PATH, además de un servidor mcporter configurado que ejecute qmd mcp. Manténgalo deshabilitado en configuraciones locales más sencillas donde el coste de iniciar un proceso por consulta sea aceptable.

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

Cuando está habilitada la inicialización de QMD al iniciar el Gateway, OpenClaw inicia QMD únicamente para los agentes aptos. Si update.onBoot es true y no se ha configurado ningún mantenimiento por intervalos ni de incrustaciones, el inicio utiliza un administrador de una sola ejecución para la actualización de arranque y después lo cierra. Si se configura un intervalo de actualización o de 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 únicamente la actualización inmediata al arrancar.

Ejemplo completo de QMD

{  memory: {    backend: "qmd",    citations: "auto",    qmd: {      includeDefaultMemory: true,      update: { interval: "5m", debounceMs: 15000 },      limits: { maxResults: 4, 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 único barrido programado y utiliza internamente fases ligera, profunda y REM como detalle de implementación.

Para consultar el comportamiento conceptual y los comandos con barra, véase Dreaming.

Configuración del 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",          },        },      },    },  },}

Contenido relacionado

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