Domina la memoria de OpenClaw: Guía práctica

¿Alguna vez has sentido que tu agente tiene memoria de pez? Es frustrante explicar lo mismo tres veces porque el contexto se llenó y los datos importantes se borraron. En OpenClaw, la solución es sorprendentemente simple: archivos Markdown.

Olvida las bases de datos complejas por un momento. Aquí, los archivos en tu workspace son la única fuente de verdad. El modelo solo “recuerda” lo que escribes en el disco. Esto te da control total y hace que debuguear sea tan fácil como abrir un editor de texto.

What You’ll Need

• Tener OpenClaw instalado y funcionando.
• Node.js en una versión reciente.
• Una API key de OpenAI o Gemini (o espacio para un modelo local).
• Permisos de escritura en tu carpeta de workspace.

Quick Start: Memoria lista en 5 minutos

Para activar la memoria básica, no necesitas una configuración gigante. Sigue estos pasos para que tu agente empiece a anotar cosas.

1. Crea los archivos: Asegúrate de que existan las carpetas memory/ en tu workspace (por defecto en ~/.openclaw/workspace).
2. Configura el Gateway: Añade esto a tu archivo de configuración para activar la búsqueda semántica básica.

{
  agents: {
    defaults: {
      memorySearch: {
        enabled: true,
        provider: "openai", // O "gemini" o "local"
        sync: { watch: true }
      }
    }
  }
}

Con esto, el agente ya puede usar las herramientas memory_search y memory_get. Si le dices “recuerda que mi servidor usa el puerto 8080”, el agente lo escribirá en un archivo y podrá consultarlo después.

Cómo funcionan los archivos de memoria

OpenClaw organiza la información en dos capas principales para mantener el orden:

• memory/YYYY-MM-DD.md: Es el log diario. Aquí se guarda el contexto del día a día y las notas rápidas. Al empezar una sesión, el agente lee lo de hoy y lo de ayer.
• MEMORY.md: Aquí va la memoria a largo plazo. Es el lugar para decisiones importantes, preferencias fijas y datos que no cambian. Solo se carga en sesiones privadas, nunca en grupos.

El “Memory Flush”: Guardar antes de olvidar

Cuando una sesión está por llenarse y necesita compactar el contexto, OpenClaw hace un movimiento inteligente: el memory flush. Es un turno silencioso donde el sistema le dice al agente: “Oye, voy a limpiar la memoria RAM, escribe lo que sea importante en el disco ahora mismo”.

Puedes ajustar este comportamiento en tu configuración:

{
  agents: {
    defaults: {
      compaction: {
        memoryFlush: {
          enabled: true,
          softThresholdTokens: 4000,
          prompt: "Escribe notas importantes en memory/YYYY-MM-DD.md; responde NO_REPLY si no hay nada que guardar.",
        },
      },
    },
  },
}

Búsqueda híbrida: Lo mejor de dos mundos

A veces buscas por significado (“¿cómo configuro el servidor?”) y otras por palabras exactas (“error 404”). OpenClaw usa búsqueda híbrida para combinar vectores (semántica) y BM25 (palabras clave).

• Vectores: Encuentran conceptos similares aunque uses palabras distintas.
• BM25: Encuentra IDs, símbolos de código o términos técnicos precisos.

Para activarlo, usa esta estructura:

memorySearch: {
  query: {
    hybrid: {
      enabled: true,
      vectorWeight: 0.7,
      textWeight: 0.3
    }
  }
}

QMD: Búsqueda local avanzada (Experimental)

Si prefieres no depender de servicios externos para buscar en tus archivos, puedes usar el backend de QMD. Es un sidecar que corre localmente y gestiona el indexado con una velocidad increíble.

Requisitos rápidos:

• Instalar el CLI de QMD (bun install -g https://github.com/tobi/qmd).
• Tener SQLite instalado en tu sistema.

Configuración de ejemplo para QMD:

memory: {
  backend: "qmd",
  qmd: {
    includeDefaultMemory: true,
    update: { interval: "5m" },
    limits: { maxResults: 6 }
  }
}

Troubleshooting

• Error de API Key: Si usas OpenAI o Gemini para embeddings, verifica que la key esté en tus variables de entorno o en el perfil de auth. Las keys de Codex no sirven para embeddings.
• Búsqueda lenta: Si el primer inicio tarda mucho, es probable que QMD esté descargando los modelos GGUF locales. Ten paciencia la primera vez.
• Archivos no indexados: Revisa que tus archivos tengan extensión .md. OpenClaw ignora otros formatos y enlaces simbólicos.
• Fallo en local: Si usas el modo local y falla, asegúrate de haber corrido pnpm approve-builds para que node-llama-cpp funcione correctamente.

¿Necesitas ayuda para configurar tu caso específico? Prueba nuestro AI Setup Assistant.

What’s Next

• Gestión de sesiones y compactación
• Configuración avanzada del Agent Workspace
• Uso de embeddings locales con Node.js
• Guía de herramientas de búsqueda de memoria