Motor de memoria QMD

​

Qué añade sobre el integrado

• Reranking y expansión de consultas para mejorar la recuperación.
• Indexa directorios adicionales: documentación del proyecto, notas del equipo, cualquier cosa en disco.
• Indexa transcripciones de sesiones: recupera conversaciones anteriores.
• Totalmente local: se ejecuta con el plugin de proveedor oficial de llama.cpp y descarga automáticamente modelos GGUF.
• Fallback automático: si QMD no está disponible, OpenClaw vuelve al motor integrado sin interrupciones.

​

Primeros pasos

​

Requisitos previos

• Instala QMD: npm install -g @tobilu/qmd o bun install -g @tobilu/qmd
• Compilación de SQLite que permita extensiones (brew install sqlite en macOS).
• QMD debe estar en el PATH del Gateway.
• macOS y Linux funcionan directamente. Windows tiene mejor soporte mediante WSL2.

​

Habilitar

{
  memory: {
    backend: "qmd",
  },
}

​

Cómo funciona el sidecar

• OpenClaw crea colecciones a partir de los archivos de memoria de tu espacio de trabajo y cualquier memory.qmd.paths configurado, y luego ejecuta qmd update cuando se abre el gestor de QMD y periódicamente después (memory.qmd.update.interval, valor predeterminado 5m). Las actualizaciones se ejecutan mediante subprocesos de QMD, no con un rastreo del sistema de archivos dentro del proceso. Los modos de búsqueda semántica también ejecutan qmd embed (memory.qmd.update.embedInterval, valor predeterminado 60m).
• La colección predeterminada del espacio de trabajo rastrea MEMORY.md más el árbol memory/. memory.md en minúsculas no se indexa como archivo raíz de memoria.
• El escáner propio de QMD ignora rutas ocultas y directorios comunes de dependencias/compilación como .git, .cache, node_modules, vendor, dist y build. El inicio del Gateway no inicializa QMD de forma predeterminada (memory.qmd.update.startup tiene off como valor predeterminado), por lo que un arranque en frío evita importar el runtime de memoria o crear el observador de larga duración antes de que se use memoria por primera vez.
• Establece memory.qmd.update.startup en idle o immediate para inicializar QMD al iniciar el Gateway de todos modos. memory.qmd.update.onBoot tiene true como valor predeterminado y ejecuta la actualización inicial al inicio; establécelo en false para omitir esa actualización inmediata (el gestor de larga duración se sigue abriendo cuando se configuran intervalos de actualización o embedding, por lo que QMD conserva la propiedad de su observador/temporizadores regulares).
• Las búsquedas usan el searchMode configurado (valor predeterminado: search; también admite vsearch y query). search es solo BM25, por lo que OpenClaw omite las comprobaciones de preparación vectorial semántica y el mantenimiento de embeddings en ese modo. Si un modo falla, OpenClaw reintenta con qmd query.
• Cuando searchMode es query, establece memory.qmd.rerank en false para usar la ruta de consulta híbrida de QMD sin el reranker (requiere QMD 2.1 o posterior). OpenClaw pasa --no-rerank a la ruta directa de la CLI de QMD y rerank: false a la herramienta de consulta MCP de QMD.
• Con versiones de QMD que anuncian filtros de múltiples colecciones, OpenClaw agrupa colecciones de la misma fuente en una sola invocación de búsqueda de QMD. Las versiones más antiguas de QMD conservan el fallback compatible por colección.
• Si QMD falla por completo, OpenClaw vuelve al motor SQLite integrado. Los intentos repetidos en turnos de chat aplican una pausa breve tras un fallo de apertura para que un binario ausente o una dependencia rota del sidecar no genere una tormenta de reintentos; openclaw memory status y las comprobaciones puntuales de CLI siguen volviendo a comprobar QMD directamente.

​

Rendimiento de búsqueda y compatibilidad

qmd search "router notes" --json -n 10 -c memory-root-main -c memory-dir-main

qmd --help | grep -i collection

​

Sobrescrituras de modelo

export QMD_EMBED_MODEL="hf:Qwen/Qwen3-Embedding-0.6B-GGUF/Qwen3-Embedding-0.6B-Q8_0.gguf"
export QMD_RERANK_MODEL="/absolute/path/to/reranker.gguf"
export QMD_GENERATE_MODEL="/absolute/path/to/generator.gguf"

​

Indexar rutas adicionales

{
  memory: {
    backend: "qmd",
    qmd: {
      paths: [{ name: "docs", path: "~/notes", pattern: "**/*.md" }],
    },
  },
}

​

Indexar transcripciones de sesiones

{
  agents: {
    defaults: {
      memorySearch: {
        experimental: { sessionMemory: true },
        sources: ["memory", "sessions"],
      },
    },
  },
  memory: {
    backend: "qmd",
    qmd: {
      sessions: { enabled: true },
    },
  },
}

​

Alcance de búsqueda

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

​

Citas

​

Cuándo usarlo

• Reranking para resultados de mayor calidad.
• Buscar documentación o notas del proyecto fuera del espacio de trabajo.
• Recuperar conversaciones de sesiones pasadas.
• Búsqueda totalmente local sin claves de API.

​

Solución de problemas

{
  memory: {
    backend: "qmd",
    qmd: {
      command: "/absolute/path/to/qmd",
    },
  },
}

​

Configuración

​

Relacionado

• Resumen de memoria
• Motor de memoria integrado
• Memoria de Honcho