Referencia de configuración de memoria

Referencia de configuración de memoria

Esta página enumera cada control de configuración para la búsqueda de memoria de OpenClaw. Para vistas conceptuales, consulte:

• Resumen de memoria — cómo funciona la memoria
• Motor integrado — backend SQLite predeterminado
• Motor QMD — sidecar local-first
• Búsqueda de memoria — canalización y ajuste de búsqueda

Todos los ajustes de búsqueda de memoria residen bajo agents.defaults.memorySearch en openclaw.json a menos que se indique lo contrario.

---

Selección de proveedor

Clave	Tipo	Predeterminado	Descripción
provider	string	autodetectado	ID del adaptador de incrustación: openai, gemini, voyage, mistral, ollama, local
model	string	predeterminado del proveedor	Nombre del modelo de incrustación
fallback	string	"none"	ID del adaptador de reserva cuando falla el principal
enabled	boolean	true	Habilitar o deshabilitar la búsqueda de memoria

Orden de autodetección

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

1. local — si memorySearch.local.modelPath está configurado y el archivo existe.
2. openai — si se puede resolver una clave de OpenAI.
3. gemini — si se puede resolver una clave de Gemini.
4. voyage — si se puede resolver una clave de Voyage.
5. mistral — si se puede resolver una clave de Mistral.

ollama es compatible pero no se detecta automáticamente (establézcalo explícitamente).

Resolución de clave de API

Las incrustaciones remotas requieren una clave API. OpenClaw la resuelve desde: perfiles de autenticación, models.providers.*.apiKey o variables de entorno.

Proveedor	Var. de entorno	Clave de configuración
OpenAI	OPENAI_API_KEY	models.providers.openai.apiKey
Gemini	GEMINI_API_KEY	models.providers.google.apiKey
Voyage	VOYAGE_API_KEY	models.providers.voyage.apiKey
Mistral	MISTRAL_API_KEY	models.providers.mistral.apiKey
Ollama	OLLAMA_API_KEY (marcador de posición)	—

Codex OAuth cubre solo chat/completions y no satisface las solicitudes de incrustación.

---

Configuración de punto de conexión remoto

Para puntos de conexión personalizados compatibles con OpenAI o para anular los valores predeterminados del proveedor:

Clave	Tipo	Descripción
remote.baseUrl	string	URL base de API personalizada
remote.apiKey	string	Anular clave API
remote.headers	object	Encabezados HTTP adicionales (combinados con los 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 de Gemini

Clave	Tipo	Predeterminado	Descripción
model	string	gemini-embedding-001	También admite gemini-embedding-2-preview
outputDimensionality	number	3072	Para Embedding 2: 768, 1536 o 3072

Warning

Cambiar el modelo o

outputDimensionality

activa un reindexado completo automático.

---

Configuración de incrustación local

Clave	Tipo	Predeterminado	Descripción
local.modelPath	string	descargado automáticamente	Ruta al archivo de modelo GGUF
local.modelCacheDir	string	predeterminado de node-llama-cpp	Directorio de caché para modelos descargados

Modelo predeterminado: embeddinggemma-300m-qat-Q8_0.gguf (~0.6 GB, descargado automáticamente). Requiere compilación nativa: pnpm approve-builds y luego pnpm rebuild node-llama-cpp.

---

Configuración de búsqueda híbrida

Todo bajo memorySearch.query.hybrid:

Clave	Tipo	Predeterminado	Descripción
enabled	boolean	true	Habilitar búsqueda híbrida BM25 + vectorial
vectorWeight	number	0.7	Peso para las puntuaciones vectoriales (0-1)
textWeight	number	0.3	Peso para las puntuaciones BM25 (0-1)
candidateMultiplier	number	4	Multiplicador del tamaño del grupo de candidatos

MMR (diversidad)

Clave	Tipo	Predeterminado	Descripción
mmr.enabled	boolean	false	Activar la reordenación MMR
mmr.lambda	number	0.7	0 = máxima diversidad, 1 = máxima relevancia

Decaimiento temporal (recencia)

Clave	Tipo	Predeterminado	Descripción
temporalDecay.enabled	boolean	false	Activar el impulso de recencia
temporalDecay.halfLifeDays	number	30	La puntuación se reduce a la mitad cada N días

Los archivos perennes (MEMORY.md, archivos sin fecha en memory/) nunca sufren decaimiento.

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

Clave	Tipo	Descripción
extraPaths	string[]	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 escanean recursivamente en busca de archivos .md. El manejo de enlaces simbólicos depende del backend activo: el motor integrado ignora 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.list[].memorySearch.qmd.extraCollections en lugar de memory.qmd.paths. Esas colecciones adicionales siguen la misma forma { path, name, pattern? }, pero se fusionan 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 mantiene la primera entrada y omite el duplicado.

---

Memoria multimodal (Gemini)

Indexar imágenes y audio junto con Markdown usando Gemini Embedding 2:

Clave	Tipo	Predeterminado	Descripción
multimodal.enabled	boolean	false	Habilitar la indexación multimodal
multimodal.modalities	string[]	—	["image"], ["audio"], o ["all"]
multimodal.maxFileBytes	number	10000000	Tamaño máximo de archivo para indexación

Solo se aplica a los archivos en extraPaths. Las raíces de memoria predeterminadas permanecen solo en 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 embeddings

Clave	Tipo	Predeterminado	Descripción
cache.enabled	boolean	false	Caché de fragmentos de embeddings en SQLite
cache.maxEntries	number	50000	Máximo de embeddings en caché

Evita volver a incrustar texto sin cambios durante la reindexación o actualizaciones de transcripciones.

---

Indexación por lotes

Clave	Tipo	Predeterminado	Descripción
remote.batch.enabled	boolean	false	Habilitar API de incrustación por lotes
remote.batch.concurrency	number	2	Trabajos por lotes paralelos
remote.batch.wait	boolean	true	Esperar a que se complete el lote
remote.batch.pollIntervalMs	number	—	Intervalo de sondeo
remote.batch.timeoutMinutes	number	—	Tiempo de espera del lote

Disponible para openai, gemini y voyage. El proceso por lotes de OpenAI es típicamente el más rápido y económico para rellenos masivos.

---

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

Indexe las transcripciones de sesión y muéstrelas a través de memory_search:

Clave	Tipo	Predeterminado	Descripción
experimental.sessionMemory	boolean	false	Habilitar la indexación de sesiones
sources	string[]	["memory"]	Añada "sessions" para incluir transcripciones
sync.sessions.deltaBytes	number	100000	Umbral de bytes para reindexar
sync.sessions.deltaMessages	number	50	Umbral 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 el disco, por lo que debe tratar el acceso al sistema de archivos como el límite de confianza.

---

Aceleración vectorial SQLite (sqlite-vec)

Clave	Tipo	Predeterminado	Descripción
store.vector.enabled	boolean	true	Usar sqlite-vec para consultas vectoriales
store.vector.extensionPath	string	incluido	Anular la ruta de sqlite-vec

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

---

Almacenamiento del índice

Clave	Tipo	Predeterminado	Descripción
store.path	string	~/.openclaw/memory/{agentId}.sqlite	Ubicación del índice (admite el token {agentId})
store.fts.tokenizer	string	unicode61	Tokenizador FTS5 (unicode61 o trigram)

---

Configuración del backend QMD

Establezca memory.backend = "qmd" para habilitar. Todas las configuraciones de QMD residen en memory.qmd:

Clave	Tipo	Predeterminado	Descripción
command	string	qmd	Ruta del ejecutable QMD
searchMode	string	search	Comando de búsqueda: search, vsearch, query
includeDefaultMemory	boolean	true	Autoíndice MEMORY.md + memory/**/*.md
paths[]	array	—	Rutas adicionales: { name, path, pattern? }
sessions.enabled	boolean	false	Indexar transcripciones de sesión
sessions.retentionDays	number	—	Retención de transcripciones
sessions.exportDir	string	—	Directorio de exportación

Programa de actualización

Clave	Tipo	Predeterminado	Descripción
update.interval	string	5m	Intervalo de actualización
update.debounceMs	number	15000	Debouncing de cambios de archivo
update.onBoot	boolean	true	Actualizar al inicio
update.waitForBootSync	boolean	false	Bloquear el inicio hasta que se complete la actualización
update.embedInterval	string	—	Cadencia de incrustación separada
update.commandTimeoutMs	number	—	Tiempo de espera para comandos QMD

Límites

Clave	Tipo	Predeterminado	Descripción
limits.maxResults	number	6	Máx. resultados de búsqueda
limits.maxSnippetChars	number	—	Limitar la longitud del fragmento
limits.maxInjectedChars	number	—	Limitar el total de caracteres inyectados
limits.timeoutMs	number	4000	Tiempo de espera de búsqueda

Ámbito

Controla qué sesiones pueden recibir resultados de búsqueda QMD. Mismo esquema que session.sendPolicy:

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

El valor predeterminado es solo MD (DM). match.keyPrefix coincide con la clave de sesión normalizada; match.rawKeyPrefix coincide con la clave sin procesar incluyendo agent:<id>:.

Citas

memory.citations se aplica a todos los backends:

Valor	Comportamiento
auto (predeterminado)	Incluir pie de página Source: <path#line> en fragmentos
on	Incluir siempre pie de página
off	Omitir pie de página (la ruta aún se pasa internamente al agente)

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