Gestión de la memoria en OpenClaw: Mantén a los agentes listos tras sesiones maratonianas

OpenClaw’s best automations only work if past decisions stay accessible. The OpenClaw docs are clear: memory is just Markdown that agents must read and write intentionally. This guide distills the latest official guidance on file layout, automatic memory flushes, vector indexing, and the new QMD backend so that openclaw memory management stops being guesswork.

TL;DR

1. Memory lives in plain Markdown: memory/YYYY-MM-DD.md for daily logs and MEMORY.md for curated long-term facts. Agents should read today + yesterday on startup and only open MEMORY.md in private sessions.
2. Before context compaction kicks in, OpenClaw triggers a silent memory flush turn (default softThresholdTokens = 4000, reserveTokensFloor = 20000) so agents persist durable notes with NO_REPLY noise suppression.
3. Vector memory search selects an embedding provider automatically (local → OpenAI → Gemini → Voyage → Mistral) and can fall back when API keys are missing; you can keep everything local through memorySearch.provider = "local" or Ollama.
4. Heavy-duty retention now has the QMD sidecar: OpenClaw can manage a Bun + node-llama-cpp process, index markdown plus optional extra paths, and fall back to the builtin SQLite indexer if QMD is unavailable.
5. Operational hygiene still matters: scope memory search to DM contexts, monitor flush logs via openclaw status, and keep workspaces writable so silent housekeeping can run.

How OpenClaw actually stores memory

OpenClaw’s memory model is intentionally simple—everything is Markdown inside the agent workspace (~/.openclaw/workspace by default).

1. Daily context (memory/YYYY-MM-DD.md) is append-only and meant for raw transcripts, state, and to-dos. Read the current and previous day at the start of every session for continuity.
2. Curated memory (MEMORY.md) is optional and should only open in private/main sessions to avoid leaking long-term facts in group contexts.
3. The docs explicitly warn: if someone says “remember this,” do not trust the model’s latent state—write it down. This keeps memory consistent across restarts and compactions.

Automatic memory flush before compaction

OpenClaw watches token usage and, when a session approaches the compaction threshold, injects a silent turn so the agent can dump durable notes to disk before any truncation happens.

1. Controlled by agents.defaults.compaction.memoryFlush (enabled by default).
2. Default thresholds: softThresholdTokens = 4000, reserveTokensFloor = 20000. When contextWindow - reserveTokensFloor - softThresholdTokens is crossed, the flush fires once per compaction cycle.
3. The flush turn contains both a system and user prompt instructing the agent to write to memory/YYYY-MM-DD.md and reply with NO_REPLY if nothing needs storing, so users never see the housekeeping.
4. Flushes require the workspace to be writable; sandboxing with workspaceAccess: "ro" skips the event. Check openclaw status or /status if you suspect flushes aren’t running.

Vector memory search and provider selection

OpenClaw’s memory plugin (memory-core by default) indexes Markdown so agents can run semantic recall.

1. Provider auto-selection: the gateway tries local first (if a local model path exists), then openai, gemini, voyage, and mistral. If no credential resolves, memory search stays disabled until configured.
2. Local-first options: set memorySearch.provider = "local" or "ollama" to avoid hosted APIs. Ollama mode hits /api/embeddings on your own node; a placeholder API key satisfies local policy if needed.
3. Extra content: memorySearch.extraPaths lets you fold in Markdown (and, with Gemini embedding 2, select image/audio) outside the default memory/**/*.md tree.
4. Scope control: memory search results only surface in sessions allowed by memorySearch.scope. The default is DM-only; deny group channels unless you intentionally need shared recall.

QMD sidecar for large memory archives

For teams who need richer ranking or multimodal recall, OpenClaw can hand off indexing to QMD, an open-source Bun sidecar combining BM25 + vectors + reranking.

1. Actívalo con memory.backend = "qmd". OpenClaw gestiona el sidecar en ~/.openclaw/agents/<id>/qmd/, maneja qmd update/qmd embed y reintenta con el indexador SQLite integrado si QMD falla.
2. Requisitos: instala la CLI de qmd por separado, asegúrate de que existan Bun y una compilación de SQLite con soporte para extensiones (el sqlite de Homebrew funciona) y ejecútalo en macOS/Linux o WSL2.
3. Las colecciones de QMD pueden incluir MEMORY.md, memory/**/*.md, directorios adicionales e incluso transcripciones de sesión sanitizadas cuando memory.qmd.sessions.enabled = true.
4. Las búsquedas se ejecutan a través de qmd search --json (por defecto) con respaldo a qmd query cuando una compilación rechaza los flags. La primera consulta puede descargar modelos GGUF; OpenClaw establece XDG_CONFIG_HOME/XDG_CACHE_HOME automáticamente para que las cachés se mantengan específicas del agente.

Guía para el operador

1. Trata los archivos de memoria como código: versiónalos o haz copias de seguridad junto con el espacio de trabajo para poder recuperarte de problemas de disco.
2. Audita los vaciados silenciosos: activa el modo detallado o vigila openclaw status --all para saber cuándo se activan los ciclos de compactación y vaciado.
3. Mantén los embeddings asequibles: si los embeddings alojados son demasiado caros, fija memorySearch.provider = "local" o usa Ollama; la documentación enfatiza que los proveedores remotos facturarán contra sus respectivas claves.
4. Limita la exposición: restringe memorySearch.scope (denegar canales de grupo) y almacena notas a largo plazo solo en sesiones privadas para evitar la divulgación accidental.
5. Prepara QMD si está activado: ejecuta qmd update && qmd embed en los directorios XDG del agente después de las actualizaciones para que la primera consulta en vivo no bloquee una automatización.

Conclusión

La documentación más reciente de OpenClaw simplifica la gestión de la memoria: mantén los archivos Markdown ordenados, deja que el vaciado automático se ejecute antes de la compactación, configura la búsqueda vectorial con proveedores explícitos y pasa a QMD cuando necesites una recuperación más rica. Con esos controles implementados, los agentes de larga duración mantienen su contexto sin filtrar secretos ni agotar los presupuestos de embeddings.

Preguntas frecuentes

¿Cómo evito que OpenClaw pierda contexto a mitad de un proyecto?

Asegúrate de que el espacio de trabajo sea escribible para que el vaciado previo a la compactación pueda escribir en memory/YYYY-MM-DD.md, y recuerda a los agentes que añadan detalles importantes en lugar de esperar una recuperación latente. La compactación más el vaciado de memoria es la red de seguridad, no un sustituto de las notas explícitas.

¿Puedo ejecutar la búsqueda en memoria sin pagar por embeddings alojados?

Sí. Establece memorySearch.provider = "local" (node-llama-cpp) o "ollama" para mantenerte en el dispositivo. Aún puedes añadir extraPaths para Markdown compartido mientras evitas la facturación de OpenAI/Gemini.

¿Cuándo debo activar el backend de QMD?

Usa QMD cuando tu conjunto de memoria crezca más allá de los simples embeddings de Markdown, por ejemplo, decenas de miles de fragmentos, archivos de varios GB o cuando necesites BM25 + reranking para una mayor precisión. OpenClaw recurre automáticamente al indexador integrado si QMD no está disponible, por lo que es seguro experimentar.