Referencia de configuración de la memoria

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

Toda la configuración compartida de la memoria se encuentra 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 la opción global session.dmScope no está establecida 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 habilita 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 habilita la exportación de sesiones de ese agente; no se requiere una configuración 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 esta configuración 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 omita memory_search.

El límite de recuperación es más estricto 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
• los grupos y canales se excluyen 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

La configuración 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 fase de recuperación acotada y de solo lectura; si la recuperación no está disponible o agota el tiempo de espera, no se bloquea la respuesta.

Selección del proveedor

Cuando no se establece provider, 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 explícitos no locales rechazan de forma segura. Si establece memory.search.provider como un proveedor concreto con backend 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 durante la 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 y 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 la clave de API

Los embeddings remotos requieren una clave de API. Bedrock usa en su lugar la cadena predeterminada de credenciales 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 genérico /v1/embeddings 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 Compaction. OpenClaw mantiene habilitados estos comportamientos con valores predeterminados mantenidos, en lugar de exponer controles de temporización para cada instalación.

Configuración de la 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 de memoria adicionales

{  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. 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 escáner QMD subyacente.

Para la búsqueda de transcripciones entre 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 del texto que no ha cambiado 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 históricas.

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 las sesiones y expóngalas mediante memory_search:

La búsqueda ordinaria de transcripciones de sesiones invocada por el modelo respeta tools.sessions.visibility. La visibilidad predeterminada tree expone la sesión actual, las sesiones que esta generó y las sesiones de grupo del mismo agente observadas mediante el conocimiento ambiental del grupo. Las demás sesiones no relacionadas requieren la visibilidad agent (o all solo cuando también se requiere la 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 colocan estas opciones en el nivel superior de memory.search. También se pueden aplicar opciones equivalentes en una sobrescritura de memory.search 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:

{  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 opción de nivel superior rememberAcrossConversations: true es la excepción: implica la exportación de sesiones de QMD necesaria para ese agente. Las exportaciones implícitas permanecen privadas: siempre usan la ubicación interna de exportación predeterminada (un sessions.exportDir configurado solo se aplica a las exportaciones explícitas), solo se buscan durante la recuperación entre conversaciones de ese agente y el memory_get ordinario no puede leerlas. La opción explícita memory.qmd.sessions.enabled: true conserva su comportamiento existente y hace que las transcripciones exportadas formen parte del corpus de memoria ordinario.

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 de índices

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. Todas las opciones de QMD se encuentran en memory.qmd:

searchMode: "search" es exclusivamente léxico/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 una versión posterior. En el modo de CLI directa, 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 estructuras actuales de colecciones y consultas MCP de QMD, pero mantiene la compatibilidad con versiones anteriores de QMD probando indicadores compatibles de patrones de colecciones y nombres anteriores de herramientas MCP cuando es necesario. Cuando QMD anuncia compatibilidad con varios filtros de colecciones, las colecciones de la misma fuente se buscan mediante un único proceso de QMD; las compilaciones anteriores de QMD conservan la ruta de compatibilidad por colección. «Misma fuente» significa que las colecciones de memoria duradera (los archivos de memoria predeterminados más las rutas personalizadas) se agrupan, mientras que las colecciones de transcripciones de sesiones permanecen como un grupo independiente, de modo que la diversificación de fuentes siga disponiendo de ambas entradas.

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

QMD se inicializa de forma diferida cuando se usa la memoria por primera vez; su adaptador gestiona las programaciones de actualización y embeddings.

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 memory.search.

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

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

Opciones 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",          },        },      },    },  },}

Contenido relacionado

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