Referencia de configuración de memoria

Esta página enumera todos los parámetros de configuración de la búsqueda de memoria de OpenClaw. Para obtener descripciones conceptuales generales, consulte:

Todos los ajustes de memoria compartida se encuentran en el nivel superior memory de openclaw.json. Los valores predeterminados de búsqueda usan memory.search; las anulaciones de búsqueda por agente usan agents.entries.*.memory.search.

Recordar entre conversaciones

Configúrelo por agente cuando solo un agente personal de confianza deba usar la recuperación de transcripciones entre conversaciones:

{  agents: {    entries: {      personal: {        memory: {          search: {            rememberAcrossConversations: true,          },        },      },    },  },}

El valor sigue la herencia normal de memory.search con una anulación por agente. Cuando no se establece, se activa de forma predeterminada solo si session.dmScope global no está establecido o es "main" y ningún enlace tiene una anulación session.dmScope. Cualquier aislamiento de mensajes directos configurado lo desactiva de forma predeterminada. Un valor explícito true o false siempre prevalece. Al activarlo, se presupone la indexación de las transcripciones de sesión y se añade sessions a las fuentes de memoria resueltas del agente. Con QMD, también se activa la exportación de sesiones de ese agente; no se requiere ningún ajuste memory.qmd.sessions.enabled independiente para este modo.

El proveedor de memoria integrado de OpenClaw admite esta ruta protegida tanto con el backend integrado como con QMD. Los proveedores de memoria alternativos pueden seguir usando sus propios hooks de recuperación y las herramientas avanzadas de Active Memory, pero este ajuste se omite a menos que el proveedor actual admita la recuperación protegida de transcripciones privadas. openclaw doctor informa de un proveedor no compatible o de una lista explícita toolsAllow de Active Memory que omite memory_search.

El límite de recuperación es más restringido que el de la búsqueda general de sesiones:

• solo son aptas las conversaciones privadas reconocidas del mismo agente
• se excluye la conversación que se está respondiendo
• se excluyen los grupos y canales como fuentes y destinos
• los tipos de conversación desconocidos se rechazan de forma segura
• la recuperación en un entorno aislado no puede usar la autorización especial entre conversaciones

El ajuste no modifica tools.sessions.visibility, las claves de sesión, el almacenamiento de transcripciones, el enrutamiento de entrega ni los permisos de sessions_list, sessions_history y sessions_send. Active Memory realiza una pasada de recuperación limitada y de solo lectura; una recuperación no disponible o que agote el tiempo de espera no bloquea la respuesta.

Selección del proveedor

Cuando provider no está establecido, OpenClaw usa embeddings de OpenAI. Establezca provider explícitamente para usar 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 exclusivo de FTS, la recuperación de memoria puede seguir usando la clasificación léxica de FTS cuando los embeddings no están disponibles.

Los proveedores no locales explícitos se rechazan de forma segura. Si establece memory.search.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 dicho proveedor no está disponible en tiempo de ejecución, memory_search devuelve un resultado de no disponibilidad en lugar de usar silenciosamente una recuperación exclusiva mediante FTS. Corrija la configuración del proveedor o de la autenticación, cambie a un proveedor accesible o establezca provider: "none" si desea usar deliberadamente una recuperación exclusiva mediante FTS.

ID de proveedores personalizados

memory.search.provider puede apuntar a una entrada models.providers.<id> personalizada para adaptadores de proveedores 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, al tiempo que conserva el ID 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" }],      },    },  },  memory: {    search: {      provider: "ollama-5080",      model: "qwen3-embedding:0.6b",    },  },}

Resolución de claves de API

Los embeddings remotos requieren una clave de API. Bedrock usa 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

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

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

Configuración específica del proveedor

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

{  memory: {    search: {      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

Comportamiento de la indexación

Los motores de memoria controlan la sincronización, el procesamiento por lotes, la supervisión y las heurísticas de indexación posteriores a la Compaction. OpenClaw mantiene estos comportamientos habilitados con valores predeterminados mantenidos, en lugar de exponer controles de temporización por instalación.

Configuración de búsqueda híbrida

Todo bajo memory.search.query:

La recuperación híbrida permanece habilitada; MMR y la disminución temporal permanecen deshabilitadas por la política integrada del motor.

Ejemplo completo

{  memory: {    search: {      query: {        maxResults: 6,        minScore: 0.35,      },    },  },}

Rutas adicionales de memoria

{  memory: {    search: {      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. El manejo 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 buscar transcripciones de otros agentes con ámbito de agente, utilice agents.entries.*.memory.search.qmd.extraCollections en lugar de memory.qmd.paths. Esas colecciones adicionales siguen la misma estructura { 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 memory.search.qmd.extraCollections, QMD conserva la primera entrada y omite el duplicado.

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.

Indexación por lotes

Disponible para gemini, openai y voyage. El procesamiento por lotes de OpenAI suele ser la opción más rápida y económica para grandes cargas retroactivas.

El proveedor controla la concurrencia, el sondeo y el comportamiento de los tiempos de espera.

Búsqueda en la memoria de sesiones

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

La búsqueda ordinaria de transcripciones de sesión invocada por el modelo respeta tools.sessions.visibility. La visibilidad predeterminada tree expone la sesión actual, las sesiones que esta inició y las sesiones de grupo del mismo agente observadas mediante el conocimiento contextual del grupo. Otras sesiones no relacionadas requieren la visibilidad agent (o all únicamente cuando también se requiere recuperación entre agentes y la política entre agentes lo permite).

rememberAcrossConversations no amplía esa configuración. Proporciona una autorización independiente, exclusiva del entorno de ejecución y limitada a las transcripciones privadas del mismo agente durante la ejecución acotada de Active Memory.

Los ejemplos siguientes sitúan esta configuración bajo el nivel superior memory.search. También se puede aplicar una configuración equivalente mediante una anulación memory.search por agente cuando solo uno deba indexar y buscar transcripciones de sesión.

Para la recuperación del Gateway a mensajes directos del mismo agente:

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

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

Al usar QMD, sources: ["sessions"] no exporta por sí solo las transcripciones a QMD. Configure también memory.qmd.sessions.enabled: true. La configuración de nivel superior rememberAcrossConversations: true es la excepción: implica la exportación de sesiones QMD necesaria para ese agente. Las exportaciones implícitas permanecen privadas: siempre utilizan la ubicación interna de exportación predeterminada (un sessions.exportDir configurado se aplica solo a las exportaciones explícitas), solo se buscan durante la recuperación entre conversaciones de ese agente y el acceso ordinario mediante memory_get no puede leerlas. La configuración explícita memory.qmd.sessions.enabled: true conserva su comportamiento actual e incorpora las transcripciones exportadas al corpus ordinario de memoria.

Aceleración vectorial de SQLite (sqlite-vec)

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

Almacenamiento del índice

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

Configuración del backend QMD

Configure memory.backend = "qmd" para habilitarlo. Toda la configuración de QMD se encuentra bajo memory.qmd:

searchMode: "search" utiliza únicamente búsqueda léxica/BM25. OpenClaw no ejecuta comprobaciones de disponibilidad de vectores semánticos ni tareas de mantenimiento de incrustaciones de QMD para ese modo, incluso durante memory status --deep; vsearch y query siguen requiriendo que los vectores y las incrustaciones 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 consulta unificada de QMD. Déjelo sin configurar para usar el comportamiento predeterminado de reclasificación de consultas de QMD.

OpenClaw prefiere las formas actuales de las colecciones y consultas MCP de QMD, pero mantiene la compatibilidad con versiones anteriores de QMD probando indicadores de patrones de colecciones compatibles y nombres anteriores de herramientas MCP cuando es necesario. Cuando QMD anuncia compatibilidad con varios filtros de colecciones, las colecciones del mismo origen se buscan con un único proceso QMD; las compilaciones anteriores de QMD conservan la ruta de compatibilidad por colección. «Mismo origen» significa que las colecciones de memoria persistente (los archivos de memoria predeterminados más las rutas personalizadas) se agrupan, mientras que las colecciones de transcripciones de sesión permanecen en un grupo independiente para que la diversificación de orígenes siga disponiendo de ambas entradas.

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

QMD se inicializa de forma diferida la primera vez que se utiliza la memoria; su adaptador gestiona las programaciones de actualización e incrustación.

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 bajo plugins.entries.memory-core.config.dreaming, no bajo memory.search.

Dreaming se ejecuta como un único barrido programado y utiliza fases internas 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",          },        },      },    },  },}

Temas relacionados

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