Memory

OpenClaw memory is plain Markdown in the agent workspace. The files are the source of truth; the model only "remembers" what gets written to disk.

Memory search tools are provided by the active memory plugin (default: memory-core). Disable memory plugins with plugins.slots.memory = "none".

Memory files (Markdown)

The default workspace layout uses two memory layers:

memory/YYYY-MM-DD.md
- Daily log (append-only).
- Read today + yesterday at session start.
MEMORY.md (optional)
- Curated long-term memory.
- If both MEMORY.md and memory.md exist at the workspace root, OpenClaw only loads MEMORY.md.
- Lowercase memory.md is only used as a fallback when MEMORY.md is absent.
- Only load in the main, private session (never in group contexts).

These files live under the workspace (agents.defaults.workspace, default ~/.openclaw/workspace). See Agent workspace for the full layout.

Memory tools

OpenClaw exposes two agent-facing tools for these Markdown files:

memory_search -- semantic recall over indexed snippets.
memory_get -- targeted read of a specific Markdown file/line range.

memory_get now degrades gracefully when a file doesn't exist (for example, today's daily log before the first write). Both the builtin manager and the QMD backend return { text: "", path } instead of throwing ENOENT, so agents can handle "nothing recorded yet" and continue their workflow without wrapping the tool call in try/catch logic.

When to write memory

Decisions, preferences, and durable facts go to MEMORY.md.
Day-to-day notes and running context go to memory/YYYY-MM-DD.md.
If someone says "remember this," write it down (do not keep it in RAM).
This area is still evolving. It helps to remind the model to store memories; it will know what to do.
If you want something to stick, ask the bot to write it into memory.

Automatic memory flush (pre-compaction ping)

When a session is close to auto-compaction, OpenClaw triggers a silent, agentic turn that reminds the model to write durable memory before the context is compacted. The default prompts explicitly say the model may reply, but usually NO_REPLY is the correct response so the user never sees this turn.

This is controlled by agents.defaults.compaction.memoryFlush:

{
  agents: {
    defaults: {
      compaction: {
        reserveTokensFloor: 20000,
        memoryFlush: {
          enabled: true,
          softThresholdTokens: 4000,
          systemPrompt: "Session nearing compaction. Store durable memories now.",
          prompt: "Write any lasting notes to memory/YYYY-MM-DD.md; reply with NO_REPLY if nothing to store.",
        },
      },
    },
  },
}

Details:

Soft threshold: flush triggers when the session token estimate crosses contextWindow - reserveTokensFloor - softThresholdTokens.
Silent by default: prompts include NO_REPLY so nothing is delivered.
Two prompts: a user prompt plus a system prompt append the reminder.
One flush per compaction cycle (tracked in sessions.json).
Workspace must be writable: if the session runs sandboxed with workspaceAccess: "ro" or "none", the flush is skipped.

For the full compaction lifecycle, see Session management + compaction.

Vector memory search

OpenClaw can build a small vector index over MEMORY.md and memory/*.md so semantic queries can find related notes even when wording differs. Hybrid search (BM25 + vector) is available for combining semantic matching with exact keyword lookups.

Memory search supports multiple embedding providers (OpenAI, Gemini, Voyage, Mistral, Ollama, and local GGUF models), an optional QMD sidecar backend for advanced retrieval, and post-processing features like MMR diversity re-ranking and temporal decay.

For the full configuration reference -- including embedding provider setup, QMD backend, hybrid search tuning, multimodal memory, and all config knobs -- see Memory configuration reference.

4.3 KiB Raw Blame History