The Complete OpenClaw Memory Configuration Guide: From Default to Bulletproof

Out of the box, OpenClaw's memory is a single markdown file that gets bigger with every session. The agent dumps everything into it, search quality degrades as it grows, and compaction silently erases context you thought was safe. Most users accept this as "just how it works" and waste tokens re-explaining their projects every session.

It doesn't have to be this way.

This guide walks you through building a proper memory system — from file architecture to compaction settings to retrieval configuration. Every config block is copy-paste ready, and every setting is explained so you understand why it matters, not just what to change. If your memory is already broken and you need to diagnose the problem, start with our OpenClaw Memory Not Working: Fix Guide instead. For a broader overview of all available memory approaches, see 5 Ways to Give OpenClaw Persistent Memory. This guide is part of our Complete Guide to OpenClaw.

Before You Touch Anything: Diagnose What You Have

OpenClaw's /context list command reveals exactly what your agent sees, including which files are loaded, their sizes, and whether any content is being truncated.

/context list

This shows you exactly what your agent sees. Pay attention to three things:

Are your workspace files loading? Look for MEMORY.md, AGENTS.md, SOUL.md in the output. If any of these show "missing" or aren't listed, they have zero effect on your agent.

Is anything truncated? OpenClaw has a per-file limit of 20,000 characters and a combined limit of 150,000 characters across all bootstrap files. If a file exceeds the limit, the agent only sees part of it. The output will show "TRUNCATED" next to affected files.

Do raw characters equal injected characters? If the "raw" and "injected" numbers don't match for a file, content is being cut. This is the most common invisible problem — your config file looks fine, but the agent is working with incomplete information.

Save this output somewhere. You'll reference it as you make changes.

Step 1: Build the File Architecture

OpenClaw's workspace has two categories of files, and understanding the difference is critical.

Bootstrap files are loaded into context at every session start. They survive compaction because they're reloaded from disk, not from conversation history. These are your most durable memory layer.

Daily memory logs live in the memory/ directory. They're not loaded automatically at session start — the system reads today's and yesterday's logs, and everything else is pulled on-demand through memory search.

Here's what goes where:

SOUL.md — Who the Agent Is

This file defines your agent's personality, tone, and broad behavioural boundaries. Think of it as character, not process.

# Identity

You are a senior technical assistant. You communicate directly and concisely.
You ask clarifying questions when requirements are ambiguous rather than assuming.
You favour working solutions over theoretical perfection.

# Boundaries

- Never send any message (email, Slack, etc.) without showing a draft first
- Never delete files without explicit confirmation
- When uncertain, say so rather than guessing

Keep this focused. SOUL.md is about who the agent is, not what it does.

AGENTS.md — How the Agent Operates

This is your operational rulebook. Workflow rules, tool conventions, and — critically — what not to do. In practice, negative instructions are often the most valuable additions to this file. Every time your agent does something annoying, add a rule to prevent it.

# Operational Rules

## Memory Protocol
- Before answering questions about past work: search memory first
- Before starting any new task: check memory for today's date for active context
- When you learn something important: write it to the appropriate file immediately
- When corrected on a mistake: add the correction as a rule to MEMORY.md
- When a session is ending or context is large: summarise to memory/YYYY-MM-DD.md

## Retrieval Protocol
Before doing non-trivial work:
1. memory_search for the project/topic/user preference
2. memory_get the referenced file chunk if needed
3. Then proceed with the task

## Response Guidelines
- Keep responses concise — shorter responses preserve context budget
- Never repeat instructions back to the user unless asked to confirm
- When presenting options, limit to 3 maximum

## Don'ts
- Never send emails without draft approval
- Never run destructive commands (rm, delete, drop) without confirmation
- Never assume today's date — check it first

The Memory Protocol and Retrieval Protocol sections are the most important additions you can make. Without them, the agent answers from whatever's in its current context window and never checks its notes.

If you're running OpenClaw in a team Discord or Slack channel, add group chat rules too — otherwise the agent will reply to every meme and side conversation:

## Group Chat Rules
- Only respond when: directly mentioned, asked a direct question, or have genuinely useful info
- Do NOT respond to: side conversations, banter, logistics between others, greetings, link shares
- When in doubt -> respond with only: NO_REPLY

USER.md — Who You Are

Your projects, clients, priorities, technical environment, and communication preferences.

# About Me
- Full-stack developer, primarily TypeScript/Next.js
- Running two businesses: [Agency Name] and [Product Name]
- Based in UK, working with clients across US and EU timezones

# Current Projects
- Project Alpha: Next.js migration, deadline March 15
- Project Beta: MVP build, early discovery phase

# Preferences
- Use British English spelling
- Prefer Tailwind CSS for styling
- Always use pnpm over npm

MEMORY.md — The Cheat Sheet

This is the most expensive file in terms of tokens and attention — it's always loaded, always in context. Keep it under 100 lines. This is a cheat sheet, not a journal.

Store: important decisions and why you made them, preferences the agent has learned, rules from past mistakes, active project states.

Don't store: transient thoughts, raw unprocessed logs, anything that's only relevant for a day or two (that goes in daily logs).

# Key Decisions
- Chose Supabase over Firebase for Project Alpha (2026-02-15): better Postgres support, row-level security
- Pricing set at $29/month after testing $9 and $49 tiers

# Learned Preferences
- User prefers short, direct responses
- Always check day of week before stating it (got this wrong twice in February)
- When user says "ship it" — that means deploy to production, not just merge to main

# Active Rules
- Never run database migrations without backup confirmation
- Always search memory before starting any new task

Daily Logs (memory/YYYY-MM-DD.md)

These are created automatically and store your working context for each day. The pre-compaction flush outputs land here. Decisions, task progress, and conversation summaries accumulate in these files.

You don't need to configure these — they happen automatically. But you should know they exist, because they're what makes memory search useful.

How Do You Configure the Pre-Compaction Memory Flush?

OpenClaw's pre-compaction memory flush is the single most impactful configuration change you can make.

OpenClaw has a built-in mechanism that triggers a silent save-to-disk step right before compaction fires. It's a safety net that preserves important context before the conversation history gets summarised. Most users never verify it's active, and many setups accidentally disable it because the default thresholds leave too little room.

There are two paths compaction can take. The good path: context approaches the threshold, the flush fires first, saves important context to disk, then compaction summarises the older history. The bad path: context gets too big, the API rejects the request, and OpenClaw goes into damage control — compressing everything at once with no flush, no saving, maximum loss.

The entire point of this configuration is to stay on the good path:

{
  "agents": {
    "defaults": {
      "compaction": {
        "reserveTokensFloor": 40000,
        "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."
        }
      }
    }
  }
}

reserveTokensFloor: 40000 — This is your headroom. With a 200K context window, the flush triggers at roughly 200K - 40K - 4K = 156K tokens. The default (around 20K) is often too tight. A single large tool output or file read can jump past the threshold before the flush gets a chance to run. Start at 40K. If you rarely use big tools, you can go lower. If you regularly read large files or web pages, go higher.

memoryFlush.enabled: true — Should be on by default in recent versions, but always verify. This is the switch that makes the safety net actually work.

softThresholdTokens: 4000 — How far before the reserve floor the flush triggers. The default of 4000 works well for most setups.

Remember: the flush is best-effort, not a guarantee. The agent might not save everything important, and a single large turn can jump past the threshold entirely. That's why you also need manual save habits and proper file architecture.

What Is Session Pruning and How Does It Differ from Compaction?

OpenClaw's pruning and compaction are completely different systems, and most users confuse them.

Compaction summarises your entire conversation history. It's permanent and lossy — it changes what the model sees going forward.

Pruning trims old tool results from context temporarily. The on-disk session history is untouched. It only affects tool result messages, never user or assistant messages.

Pruning is your friend. It reduces context bloat, delays compaction, and improves cache hit rates. Enable it:

{
  "agents": {
    "defaults": {
      "contextPruning": {
        "mode": "cache-ttl",
        "ttl": "5m"
      }
    }
  }
}

If you're using Claude (Anthropic), this is likely already enabled via smart defaults. The 5-minute TTL means tool results older than 5 minutes get trimmed from the in-memory context. The originals stay on disk.

There's also a cost benefit: prompt caching gives you ~90% savings on repeated tokens, but compaction invalidates the cache. Every compaction you avoid by using pruning instead is both a reliability win and a cost savings.

How Do You Configure OpenClaw Memory Search?

OpenClaw memory files are useless if the agent cannot find information in them, which is why configuring the retrieval tools correctly is essential. OpenClaw provides two retrieval tools: memory_search (searches across all memory files) and memory_get (reads a specific file directly).

Option A: Built-In Local Search (Start Here)

No extra installs needed. The built-in system indexes MEMORY.md and everything in the memory directory automatically:

{
  "agents": {
    "defaults": {
      "memorySearch": {
        "enabled": true,
        "provider": "local",
        "local": {
          "modelPath": "hf:ggml-org/embeddinggemma-300m-qat-q8_0-GGUF/embeddinggemma-300m-qat-Q8_0.gguf"
        },
        "query": {
          "hybrid": {
            "enabled": true,
            "vectorWeight": 0.7,
            "textWeight": 0.3
          }
        },
        "cache": {
          "enabled": true
        }
      }
    }
  }
}

Hybrid search combines two matching strategies. Keyword search finds exact word matches. Embedding (semantic) search captures meaning — so "pricing decision" and "we picked the $29 tier" are recognised as related even though they share no words. The 70/30 vector-to-text weighting works well as a default.

The embedding model downloads automatically the first time you use search. It runs locally on your machine — free, no API calls.

Option A+: Index Extra Directories

Before switching to a different backend, know that the built-in search supports additional paths. Point it at your project folder, a notes directory, an Obsidian vault — whatever you have:

{
  "agents": {
    "defaults": {
      "memorySearch": {
        "enabled": true,
        "provider": "local",
        "extraPaths": [
          "~/Documents/Obsidian/ProjectNotes/**/*.md",
          "~/Documents/specs/**/*.md"
        ]
      }
    }
  }
}

Option B: QMD (For Power Users)

Graduate to QMD when you have thousands of files, want to search past session transcripts, or need to index your entire Obsidian vault:

{
  "memory": {
    "backend": "qmd",
    "qmd": {
      "searchMode": "search",
      "includeDefaultMemory": true,
      "sessions": {
        "enabled": true
      },
      "paths": [
        { "name": "obsidian", "path": "~/Documents/Obsidian", "pattern": "**/*.md" }
      ]
    }
  }
}

QMD returns small, relevant snippets instead of entire files. This keeps context lean and helps avoid triggering compaction — a meaningful advantage with large knowledge bases.

One gotcha: QMD defaults to DM-only scope. If you're using OpenClaw in group channels and memory search seems broken, check the scope setting in your config. If you use Obsidian for note-taking, see our dedicated OpenClaw Obsidian Integration Guide for a step-by-step walkthrough of connecting your vault.

Step 5: Set Up Memory Hygiene

OpenClaw memory hygiene prevents daily logs from accumulating unchecked and MEMORY.md from bloating past the 20,000-character truncation limit over months of use, daily logs accumulate and MEMORY.md can bloat past the truncation limits. Build these habits:

Daily: The pre-compaction flush appends to daily logs automatically. No action needed.

Weekly: Review the week's daily logs. Promote important, durable decisions and rules into MEMORY.md. Remove anything outdated. You can automate this with a cron job that asks the agent to analyse the last seven days and distill the highlights.

Keep MEMORY.md lean. Anything that doesn't need to be in every single session can live in daily logs — the agent will find it through search when it needs it. The goal is a tight cheat sheet, not a comprehensive history.

Back up your workspace. Run git init in your workspace directory, set up auto-commit. Full history, diffs, rollback if something goes wrong. Just make sure the credentials folder and openclaw.json stay out of the repo — those contain API keys.

The Complete Copy-Paste Config

Here's everything combined. Pick Track A (built-in search) or Track B (QMD) based on your needs.

Track A: Built-In Search

{
  "agents": {
    "defaults": {
      "compaction": {
        "reserveTokensFloor": 40000,
        "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."
        }
      },
      "memorySearch": {
        "enabled": true,
        "provider": "local",
        "local": {
          "modelPath": "hf:ggml-org/embeddinggemma-300m-qat-q8_0-GGUF/embeddinggemma-300m-qat-Q8_0.gguf"
        },
        "query": {
          "hybrid": {
            "enabled": true,
            "vectorWeight": 0.7,
            "textWeight": 0.3
          }
        },
        "cache": {
          "enabled": true
        }
      },
      "contextPruning": {
        "mode": "cache-ttl",
        "ttl": "5m"
      }
    }
  }
}

Track B: QMD Backend

{
  "agents": {
    "defaults": {
      "compaction": {
        "reserveTokensFloor": 40000,
        "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."
        }
      },
      "contextPruning": {
        "mode": "cache-ttl",
        "ttl": "5m"
      }
    }
  },
  "memory": {
    "backend": "qmd",
    "qmd": {
      "searchMode": "search",
      "includeDefaultMemory": true,
      "sessions": {
        "enabled": true
      },
      "paths": [
        { "name": "obsidian", "path": "~/Documents/Obsidian", "pattern": "**/*.md" }
      ]
    }
  }
}

Essential Slash Commands

The Principle That Matters Most

OpenClaw memory configuration follows one core principle: if it's not written to a file, it doesn't exist.: if it's not written to a file, it doesn't exist.

Chat instructions vanish on compaction. Preferences mentioned mid-conversation disappear on session reset. Tool results get pruned from context after a few minutes.

Files on disk survive everything. Bootstrap files are reloaded every turn. Daily logs persist indefinitely. The retrieval index makes them searchable.

Build your memory system around files, and compaction goes from being the thing that breaks your agent to a routine maintenance step that barely matters. Keep in mind that memory configuration also directly affects your token costs — bloated memory files increase every API call. See our OpenClaw Token Cost Reduction Guide for strategies to keep costs under control.

Want This Done For You?

Setting up OpenClaw memory properly takes time and testing. If you'd rather skip the trial-and-error and get a production-ready deployment with optimised memory, security hardening, and 24/7 uptime, check out Remote OpenClaw. We handle the infrastructure so you can focus on actually using your agent.

See our deployment plans →