Understanding Memory in OpenClaw: A Complete Guide

Memory is one of the most frequently asked-about features in OpenClaw. Based on a recent Discord discussion, here's a comprehensive breakdown of how memory actually works.

The Two Layers of Memory

In OpenClaw, "memory" consists of two separate but related components:

1. Source-of-truth memory = Markdown files in the agent workspace
2. Retrieval layer = A search/index backend that helps the agent find relevant information

Layer 1: Workspace Markdown Files

OpenClaw doesn't have magical persistent RAM between runs. If you want something to persist across restarts, session compaction, or new sessions, it must end up on disk.

The default memory layout includes:

• memory/YYYY-MM-DD.md — Daily log/scratchpad (append-only style)
• MEMORY.md (or memory.md) — Curated long-term memory for preferences, durable facts, and decisions

These files live under the agent workspace (default ~/.openclaw/workspace).

Important: The index can always be rebuilt; the Markdown files are the real memory.

Layer 2: Memory Tools (memory-core)

The bundled Memory (Core) plugin provides two key tools:

• memory_search — Semantic search over your memory Markdown files (returns snippets + file/line ranges)
• memory_get — Safely read a specific memory file or a slice of it

This is backed by a per-agent SQLite index (default ~/.openclaw/memory/<agentId>.sqlite). It uses embeddings (remote or local) to do semantic retrieval.

What About QMD?

QMD is an experimental alternate backend for the search/index part of memory. Instead of OpenClaw's built-in SQLite search manager, you can use QMD which offers:

• Hybrid retrieval (BM25 + vectors + reranking)
• Local-first operation (no hosted vector DB required)
• Runs as a sidecar CLI with state under ~/.openclaw/agents/<agentId>/qmd/

To enable QMD:

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

Will QMD Run on a Low-Spec VM?

It can, but it's the least low-spec-friendly option because:

• QMD downloads local GGUF models (reranker/query expansion) on first use
• CPU-only is fine but slower
• Extra disk + RAM pressure vs the built-in backend

Recommendation for low-spec systems: Keep the default builtin backend and use remote embeddings so the VM isn't doing heavy local inference.

Minimum requirements: 2GB RAM is the commonly recommended floor. 512MB will cause issues; 1GB sometimes works but can OOM.

What About mem0/memos Plugins?

These are separate memory implementations (usually LLM memory products/services or different vector-store approaches). Key differences:

Important: Memory is an exclusive plugin slot. If you switch to a mem0/memos-style plugin, you're replacing the default memory-core tools, not adding another layer.

Memory in Group Chats and Threads

By default, memory is agent-scoped, not "per chat". The same agent running in a Discord thread/channel can use the same on-disk memory as in DMs.

Key nuances:

• Citations are suppressed outside DMs by default (memory.citations = "auto"). This affects Source: ... footers but doesn't prevent recall.
• QMD backend defaults to DM-only scope — group/channel/thread recall is blocked unless you loosen the scope policy. This is a privacy guardrail.

Quick Reference

Learn More

• Memory Concepts Docs
• QMD Backend Docs
• Plugin System Docs

Based on a community discussion in #help — thanks to Disco_Herb for the question and Krill for the detailed explanation!