Saltar al contenido principal

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

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

Resumen de memoria

Cómo funciona la memoria.

Motor integrado

Backend SQLite predeterminado.

Motor QMD

Sidecar local-first.

Búsqueda de memoria

Canalización de búsqueda y ajuste.

Active Memory

Subagente de memoria para sesiones interactivas.
Todas las opciones de búsqueda de memoria se encuentran en agents.defaults.memorySearch en openclaw.json, salvo que se indique lo contrario.
Si buscas el interruptor de la función Active Memory y la configuración del subagente, eso se encuentra en plugins.entries.active-memory en lugar de memorySearch.Active Memory usa un modelo de dos puertas:
  1. el plugin debe estar habilitado y apuntar al id del agente actual
  2. la solicitud debe ser una sesión de chat persistente interactiva apta
Consulta Active Memory para conocer el modelo de activación, la configuración propiedad del plugin, la persistencia de transcripciones y el patrón de despliegue seguro.

Selección de proveedor

ClaveTipoPredeterminadoDescripción
providerstringdetectado automáticamenteID del adaptador de embeddings, como bedrock, deepinfra, gemini, github-copilot, local, mistral, ollama, openai o voyage; también puede ser un models.providers.<id> configurado cuyo api apunte a uno de esos adaptadores
modelstringpredeterminado del proveedorNombre del modelo de embeddings
fallbackstring"none"ID del adaptador de respaldo cuando falla el principal
enabledbooleantrueHabilita o deshabilita la búsqueda de memoria

Orden de detección automática

Cuando provider no está definido, OpenClaw selecciona el primero disponible:
1

local

Seleccionado si memorySearch.local.modelPath está configurado y el archivo existe.
2

github-copilot

Seleccionado si se puede resolver un token de GitHub Copilot (variable de entorno o perfil de autenticación).
3

openai

Seleccionado si se puede resolver una clave de OpenAI.
4

gemini

Seleccionado si se puede resolver una clave de Gemini.
5

voyage

Seleccionado si se puede resolver una clave de Voyage.
6

mistral

Seleccionado si se puede resolver una clave de Mistral.
7

deepinfra

Seleccionado si se puede resolver una clave de DeepInfra.
8

bedrock

Seleccionado si la cadena de credenciales del AWS SDK se resuelve (rol de instancia, claves de acceso, perfil, SSO, identidad web o configuración compartida).
ollama es compatible, pero no se detecta automáticamente (defínelo explícitamente).

ID de proveedores personalizados

memorySearch.provider puede apuntar a una entrada personalizada models.providers.<id>. OpenClaw resuelve el propietario api de ese proveedor para el adaptador de embeddings mientras conserva el id del 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 claves 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).
ProveedorVariable de entornoClave de configuración
BedrockCadena de credenciales de AWSNo se necesita clave de API
DeepInfraDEEPINFRA_API_KEYmodels.providers.deepinfra.apiKey
GeminiGEMINI_API_KEYmodels.providers.google.apiKey
GitHub CopilotCOPILOT_GITHUB_TOKEN, GH_TOKEN, GITHUB_TOKENPerfil de autenticación mediante inicio de sesión de dispositivo
MistralMISTRAL_API_KEYmodels.providers.mistral.apiKey
OllamaOLLAMA_API_KEY (marcador de posición)
OpenAIOPENAI_API_KEYmodels.providers.openai.apiKey
VoyageVOYAGE_API_KEYmodels.providers.voyage.apiKey
Codex OAuth cubre solo chat/completions y no satisface solicitudes de embeddings.

Configuración de endpoint remoto

Para endpoints personalizados compatibles con OpenAI o para sobrescribir los valores predeterminados del proveedor:
remote.baseUrl
string
URL base de API personalizada.
remote.apiKey
string
Sobrescribe la clave de API.
remote.headers
object
Encabezados HTTP adicionales (combinados con los valores predeterminados del proveedor).
{
  agents: {
    defaults: {
      memorySearch: {
        provider: "openai",
        model: "text-embedding-3-small",
        remote: {
          baseUrl: "https://api.example.com/v1/",
          apiKey: "YOUR_KEY",
        },
      },
    },
  },
}

Configuración específica del proveedor

ClaveTipoPredeterminadoDescripción
modelstringgemini-embedding-001También admite gemini-embedding-2-preview
outputDimensionalitynumber3072Para Embedding 2: 768, 1536 o 3072
Cambiar el modelo o outputDimensionality activa una reindexación completa automática.
Los endpoints de embeddings compatibles con OpenAI pueden optar por usar campos de solicitud input_type específicos del proveedor. Esto resulta útil para modelos de embeddings asimétricos que requieren etiquetas diferentes para embeddings de consulta y documento.
ClaveTipoPredeterminadoDescripción
inputTypestringsin definirinput_type compartido para embeddings de consulta y documento
queryInputTypestringsin definirinput_type en tiempo de consulta; sobrescribe inputType
documentInputTypestringsin definirinput_type de índice/documento; sobrescribe inputType
{
  agents: {
    defaults: {
      memorySearch: {
        provider: "openai",
        remote: {
          baseUrl: "https://embeddings.example/v1",
          apiKey: "env:EMBEDDINGS_API_KEY",
        },
        model: "asymmetric-embedder",
        queryInputType: "query",
        documentInputType: "passage",
      },
    },
  },
}
Cambiar estos valores afecta la identidad de la caché de embeddings para la indexación por lotes del proveedor y debe ir seguido de una reindexación de memoria cuando el modelo upstream trate las etiquetas de forma diferente.

Configuración de embeddings de Bedrock

Bedrock usa la cadena de credenciales predeterminada del AWS SDK; no se necesitan claves de API. Si OpenClaw se ejecuta en EC2 con un rol de instancia habilitado para Bedrock, solo define el proveedor y el modelo:
{
  agents: {
    defaults: {
      memorySearch: {
        provider: "bedrock",
        model: "amazon.titan-embed-text-v2:0",
      },
    },
  },
}
ClaveTipoPredeterminadoDescripción
modelstringamazon.titan-embed-text-v2:0Cualquier ID de modelo de embeddings de Bedrock
outputDimensionalitynumberpredeterminado del modeloPara Titan V2: 256, 512 o 1024
Modelos compatibles (con detección de familia y dimensiones predeterminadas):
ID de modeloProveedorDims predeterminadasDims configurables
amazon.titan-embed-text-v2:0Amazon1024256, 512, 1024
amazon.titan-embed-text-v1Amazon1536
amazon.titan-embed-g1-text-02Amazon1536
amazon.titan-embed-image-v1Amazon1024
amazon.nova-2-multimodal-embeddings-v1:0Amazon1024256, 384, 1024, 3072
cohere.embed-english-v3Cohere1024
cohere.embed-multilingual-v3Cohere1024
cohere.embed-v4:0Cohere1536256-1536
twelvelabs.marengo-embed-3-0-v1:0TwelveLabs512
twelvelabs.marengo-embed-2-7-v1:0TwelveLabs1024
Las variantes con sufijo de capacidad de procesamiento (por ejemplo, amazon.titan-embed-text-v1:2:8k) heredan la configuración del modelo base.Autenticación: la autenticación de Bedrock usa el orden estándar de resolución de credenciales del AWS SDK:
  1. Variables de entorno (AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY)
  2. Caché de tokens SSO
  3. Credenciales de token de identidad web
  4. Credenciales compartidas y archivos de configuración
  5. Credenciales de metadatos de ECS o EC2
La región se resuelve desde AWS_REGION, AWS_DEFAULT_REGION, el baseUrl del proveedor amazon-bedrock, o toma us-east-1 de forma predeterminada.Permisos de IAM: el rol o usuario de IAM necesita:
{
  "Effect": "Allow",
  "Action": "bedrock:InvokeModel",
  "Resource": "*"
}
Para privilegios mínimos, limita InvokeModel al modelo específico:
arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0
ClaveTipoPredeterminadoDescripción
local.modelPathstringdescargado automáticamenteRuta al archivo de modelo GGUF
local.modelCacheDirstringpredeterminado de node-llama-cppDirectorio de caché para modelos descargados
local.contextSizenumber | "auto"4096Tamaño de la ventana de contexto para el contexto de embeddings. 4096 cubre fragmentos típicos (128–512 tokens) y limita la VRAM no asociada a pesos. Redúzcalo a 1024–2048 en hosts con recursos limitados. "auto" usa el máximo entrenado del modelo; no se recomienda para modelos de 8B+ (Qwen3-Embedding-8B: 40 960 tokens → ~32 GB de VRAM frente a ~8.8 GB con 4096).
Modelo predeterminado: embeddinggemma-300m-qat-Q8_0.gguf (~0.6 GB, descargado automáticamente). Los checkouts de origen aún requieren aprobación de compilación nativa: pnpm approve-builds y luego pnpm rebuild node-llama-cpp.Use la CLI independiente para verificar la misma ruta de proveedor que usa el Gateway:
openclaw memory status --deep --agent main
openclaw memory index --force --agent main
Si provider es auto, local se selecciona solo cuando local.modelPath apunta a un archivo local existente. Las referencias de modelo hf: y HTTP(S) aún pueden usarse explícitamente con provider: "local", pero no hacen que auto seleccione local antes de que el modelo esté disponible en disco.

Tiempo de espera de embeddings en línea

sync.embeddingBatchTimeoutSeconds
number
Sobrescriba el tiempo de espera para lotes de embeddings en línea durante la indexación de memoria.Si no se establece, usa el valor predeterminado del proveedor: 600 segundos para proveedores locales/autohospedados como local, ollama y lmstudio, y 120 segundos para proveedores hospedados. Aumente esto cuando los lotes de embeddings locales limitados por CPU estén sanos pero sean lentos.

Configuración de búsqueda híbrida

Todo bajo memorySearch.query.hybrid:
ClaveTipoPredeterminadoDescripción
enabledbooleantrueHabilitar búsqueda híbrida BM25 + vectorial
vectorWeightnumber0.7Peso para puntuaciones vectoriales (0-1)
textWeightnumber0.3Peso para puntuaciones BM25 (0-1)
candidateMultipliernumber4Multiplicador del tamaño del conjunto de candidatos
ClaveTipoPredeterminadoDescripción
mmr.enabledbooleanfalseHabilitar reranking MMR
mmr.lambdanumber0.70 = máxima diversidad, 1 = máxima relevancia

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

ClaveTipoDescripción
extraPathsstring[]Directorios o archivos adicionales para indexar
{
  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. El manejo de symlinks depende del backend activo: el motor integrado ignora los symlinks, mientras que QMD sigue el comportamiento del escáner QMD subyacente. Para la búsqueda de transcripciones entre agentes con alcance de agente, use 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 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 el duplicado.

Memoria multimodal (Gemini)

Indexe imágenes y audio junto con Markdown usando Gemini Embedding 2:
ClaveTipoPredeterminadoDescripción
multimodal.enabledbooleanfalseHabilitar indexación multimodal
multimodal.modalitiesstring[]["image"], ["audio"] o ["all"]
multimodal.maxFileBytesnumber10000000Tamaño máximo de archivo para indexación
Solo se aplica a archivos en extraPaths. Las raíces de memoria predeterminadas siguen siendo solo Markdown. Requiere gemini-embedding-2-preview. fallback debe ser "none".
Formatos compatibles: .jpg, .jpeg, .png, .webp, .gif, .heic, .heif (imágenes); .mp3, .wav, .ogg, .opus, .m4a, .aac, .flac (audio).

Caché de incrustaciones

ClaveTipoPredeterminadoDescripción
cache.enabledbooleanfalseAlmacena en caché incrustaciones de fragmentos en SQLite
cache.maxEntriesnumber50000Máximo de incrustaciones en caché
Evita volver a incrustar texto sin cambios durante la reindexación o las actualizaciones de transcripciones.

Indexación por lotes

ClaveTipoPredeterminadoDescripción
remote.nonBatchConcurrencynumber4Incrustaciones en línea paralelas
remote.batch.enabledbooleanfalseHabilita la API de incrustaciones por lotes
remote.batch.concurrencynumber2Trabajos por lotes paralelos
remote.batch.waitbooleantrueEspera a que finalice el lote
remote.batch.pollIntervalMsnumberIntervalo de sondeo
remote.batch.timeoutMinutesnumberTiempo de espera del lote
Disponible para openai, gemini y voyage. Los lotes de OpenAI suelen ser los más rápidos y económicos para grandes rellenos históricos. remote.nonBatchConcurrency controla las llamadas de incrustación en línea usadas por proveedores locales/autohospedados y proveedores alojados cuando las API por lotes del proveedor no están activas. Ollama usa 1 de forma predeterminada para la indexación sin lotes a fin de evitar saturar 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 para las llamadas de incrustación en línea.

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

Indexa transcripciones de sesión y las expone mediante memory_search:
ClaveTipoPredeterminadoDescripción
experimental.sessionMemorybooleanfalseHabilita la indexación de sesiones
sourcesstring[]["memory"]Agrega "sessions" para incluir transcripciones
sync.sessions.deltaBytesnumber100000Umbral de bytes para reindexar
sync.sessions.deltaMessagesnumber50Umbral de mensajes para reindexar
La indexación de sesiones es opcional y se ejecuta de forma asíncrona. Los resultados pueden estar ligeramente desactualizados. Los registros de sesión residen en disco, así que trata el acceso al sistema de archivos como el límite de confianza.

Aceleración vectorial de SQLite (sqlite-vec)

ClaveTipoPredeterminadoDescripción
store.vector.enabledbooleantrueUsa sqlite-vec para consultas vectoriales
store.vector.extensionPathstringincluidoSobrescribe la ruta de sqlite-vec
Cuando sqlite-vec no está disponible, OpenClaw recurre automáticamente a la similitud del coseno en proceso.

Almacenamiento de índices

ClaveTipoPredeterminadoDescripción
store.pathstring~/.openclaw/memory/{agentId}.sqliteUbicación del índice (admite el token {agentId})
store.fts.tokenizerstringunicode61Tokenizador FTS5 (unicode61 o trigram)

Configuración del backend QMD

Establece memory.backend = "qmd" para habilitarlo. Todos los ajustes de QMD residen en memory.qmd:
ClaveTipoPredeterminadoDescripción
commandstringqmdRuta del ejecutable QMD; establece una ruta absoluta cuando el PATH del servicio difiera del de tu shell
searchModestringsearchComando de búsqueda: search, vsearch, query
includeDefaultMemorybooleantrueIndexa automáticamente MEMORY.md + memory/**/*.md
paths[]arrayRutas adicionales: { name, path, pattern? }
sessions.enabledbooleanfalseIndexa transcripciones de sesión
sessions.retentionDaysnumberRetención de transcripciones
sessions.exportDirstringDirectorio de exportación
searchMode: "search" es solo léxico/BM25. OpenClaw no ejecuta sondeos de preparación vectorial semántica ni mantenimiento de incrustaciones de QMD para ese modo, incluso durante memory status --deep; vsearch y query siguen requiriendo preparación vectorial de QMD e incrustaciones. OpenClaw prefiere la colección de QMD actual y las formas de consulta MCP actuales, pero mantiene funcionando versiones anteriores de QMD probando indicadores de patrones de colección compatibles y nombres de herramientas MCP más antiguos cuando es necesario. Cuando QMD anuncia compatibilidad con varios filtros de colección, las colecciones de la misma fuente se buscan con un proceso QMD; las compilaciones anteriores de QMD conservan 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.
Las anulaciones de modelo de QMD permanecen del lado de QMD, no en la configuración de OpenClaw. Si necesitas anular globalmente los modelos de QMD, establece variables de entorno como QMD_EMBED_MODEL, QMD_RERANK_MODEL y QMD_GENERATE_MODEL en el entorno de ejecución del gateway.
ClaveTipoPredeterminadoDescripción
update.intervalstring5mIntervalo de actualización
update.debounceMsnumber15000Debounce de cambios de archivos
update.onBootbooleantrueActualiza cuando se abre el gestor QMD de larga duración; también controla la actualización de inicio opcional
update.startupstringoffActualización opcional al iniciar el gateway: off, idle o immediate
update.startupDelayMsnumber120000Retraso antes de que se ejecute la actualización startup: "idle"
update.waitForBootSyncbooleanfalseBloquea la apertura del gestor hasta que se complete su actualización inicial
update.embedIntervalstringCadencia de incrustación separada
update.commandTimeoutMsnumberTiempo de espera para comandos QMD
update.updateTimeoutMsnumberTiempo de espera para operaciones de actualización de QMD
update.embedTimeoutMsnumberTiempo de espera para operaciones de incrustación de QMD
ClaveTipoPredeterminadoDescripción
limits.maxResultsnumber6Resultados máximos de búsqueda
limits.maxSnippetCharsnumberLimita la longitud del fragmento
limits.maxInjectedCharsnumberLimita el total de caracteres inyectados
limits.timeoutMsnumber4000Tiempo de espera de búsqueda
Controla qué sesiones pueden recibir resultados de búsqueda de QMD. El mismo esquema que session.sendPolicy:
{
  memory: {
    qmd: {
      scope: {
        default: "deny",
        rules: [{ action: "allow", match: { chatType: "direct" } }],
      },
    },
  },
}
El valor predeterminado incluido permite sesiones directas y de canal, mientras sigue denegando grupos.El valor predeterminado es solo DM. match.keyPrefix coincide con la clave de sesión normalizada; match.rawKeyPrefix coincide con la clave sin procesar, incluido agent:<id>:.
memory.citations se aplica a todos los backends:
ValorComportamiento
auto (predeterminado)Incluye el pie Source: <path#line> en los fragmentos
onIncluye siempre el pie
offOmite el pie (la ruta aún se pasa internamente al agente)
Las actualizaciones de arranque de QMD usan una ruta de subproceso de una sola ejecución durante el inicio del gateway. El gestor QMD de larga duración sigue siendo dueño del observador de archivos regular y de los temporizadores de intervalo cuando se abre la búsqueda de memoria para uso interactivo.

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 y usa fases internas ligera/profunda/REM como detalle de implementación. Para el comportamiento conceptual y los comandos de barra diagonal, consulta Dreaming.

Configuración de usuario

ClaveTipoPredeterminadoDescripción
enabledbooleanfalseActiva o desactiva Dreaming por completo
frequencystring0 3 * * *Cadencia cron opcional para el barrido completo de Dreaming
modelstringmodelo predeterminadoAnulación opcional del modelo del subagente Dream Diary

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",
          },
        },
      },
    },
  },
}
  • Dreaming escribe el estado de máquina en memory/.dreams/.
  • Dreaming escribe salida narrativa legible por humanos en DREAMS.md (o el dreams.md existente).
  • dreaming.model usa la puerta de confianza de subagente del plugin existente; establece plugins.entries.memory-core.subagent.allowModelOverride: true antes de habilitarlo.
  • Dream Diary reintenta una vez con el modelo predeterminado de la sesión cuando el modelo configurado no está disponible. Los fallos de confianza o de lista de permitidos se registran y no se reintentan silenciosamente.
  • La política y los umbrales de las fases ligera/profunda/REM son comportamiento interno, no configuración expuesta al usuario.

Relacionado