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 resúmenes conceptuales, consulta:

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

# Selección de proveedor

# Orden de detección automática

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

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).

# Configuración de endpoint remoto

Para endpoints personalizados compatibles con OpenAI o para sobrescribir 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

{
  agents: {
    defaults: {
      memorySearch: {
        provider: "openai",
        remote: {
          baseUrl: "https://embeddings.example/v1",
          apiKey: "env: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 main
openclaw 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 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:

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

# Caché de incrustaciones

Evita volver a incrustar 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 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:

# Aceleración vectorial de SQLite (sqlite-vec)

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

# Almacenamiento de índices

# Configuración del backend QMD

Establece memory.backend = "qmd" para habilitarlo. Todos los ajustes de QMD residen en memory.qmd:

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.

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

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

# 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