Skip to main content

​
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 loads both (deduplicated by realpath so symlinks pointing to the same file are not injected twice).
    • 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. The active memory plugin owns the prompt/path policy for that flush; the default memory-core plugin writes to the canonical daily file under memory/YYYY-MM-DD.md. 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. 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 adapter ids come from the active memory plugin. The default memory-core plugin ships built-ins for OpenAI, Gemini, Voyage, Mistral, Ollama, and local GGUF models, plus 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.