Openclaw Memory Configuration: How to Make Your AI Agent Remember Everything

Your OpenClaw agent forgets things because it was never told how to remember them. Out of the box, OpenClaw stores daily notes in markdown files and hopes the language model decides to read them later. That is not memory. That is a filing cabinet nobody opens.

This guide walks through every layer of OpenClaw memory configuration: what the files do, how compaction destroys context, how to structure MEMORY.md so it stays useful over months, and how to wire the heartbeat so nothing slips through the cracks. If you followed our OpenClaw setup guide and got through Step 3, this is the deep dive that step pointed toward.

By the end, your agent will retain preferences, project context, contacts, and decisions across sessions without you having to repeat yourself.

---

How OpenClaw Memory Works

Before changing any settings, you need to understand what is happening under the hood. OpenClaw has four distinct layers that people lump together under “memory,” and confusing them is the root cause of most problems.

The Four Layers

Bootstrap files load at the start of every session. These include MEMORY.md, AGENTS.md, SOUL.md, USER.md, and IDENTITY.md. Whatever is in these files, your agent knows it from the first message. They survive restarts, compaction, and channel switches. This is your durable layer.

Daily notes are dated markdown files stored in the memory/ folder (format: YYYY-MM-DD.md). OpenClaw loads today’s and yesterday’s notes automatically. Older notes are searchable but not loaded by default. Think of these as a running journal.

The context window is the conversation happening right now. It has a hard token limit. When it fills up, OpenClaw triggers compaction, which summarizes old messages to make room. Anything not saved to a file before compaction may be lost.

Retrieval indices power the memory_search tool. When an embedding provider is configured, OpenClaw builds a searchable index across all your memory files. The agent can query this to pull relevant context from weeks or months ago.

The golden rule: if it is not written to a file, it does not exist. The context window is temporary. Bootstrap files and daily notes are permanent. Everything else is search infrastructure that reads from those files.

---

Why Your Agent Forgets: Compaction Explained

Compaction is the single biggest source of lost memory, and most users do not realize it is happening.

What Triggers Compaction

When the context window fills past a threshold (configurable, but typically around 80,000 tokens), OpenClaw summarizes the oldest messages into a compressed block and discards the originals. This frees token space for new conversation.

The problem: compaction is lossy. The summary captures the gist but drops specifics. If you told your agent your preferred email format, your daughter’s birthday, or a project deadline three hours ago and it was never written to a file, compaction may erase it.

The Memory Flush: Your Safety Net

OpenClaw has a built-in safety mechanism called the memory flush. Before compaction starts, it prompts the agent to save important context to disk. But here is the catch: it is not always enabled by default, and when it is, the flush prompt determines what gets saved.

Enable it with these commands in your OpenClaw terminal:

set compaction memory flush enable to true
set memory search.experimental.session memory to true

A bad flush prompt creates memory files full of noise. A good one captures decisions, state changes, and lessons. Add this to your AGENTS.md to shape what the flush captures:

## Memory Flush Rules
When flushing memory before compaction, prioritize:
1. Decisions made and their reasoning
2. New preferences or corrections to existing preferences
3. Project state changes (completed tasks, new blockers, updated deadlines)
4. Contact information or relationship updates
5. Lessons learned or patterns observed

Do NOT save: routine acknowledgments, small talk, or restated information already in MEMORY.md.

Tuning Compaction Thresholds

Two parameters control when compaction fires:

Parameter	Default	What It Does
reserveTokensFloor	40,000	Minimum tokens kept free. Higher values trigger compaction earlier, giving the flush more time.
softThresholdTokens	50,000	An early checkpoint where important context is flushed to durable memory before compaction runs.

Setting reserveTokensFloor to 120,000 means compaction triggers after about 80,000 tokens of use. This gives the agent more headroom for long sessions but compacts more aggressively. For most users, the default 40,000 works fine. Raise it only if you regularly hit context limits in long working sessions.

---

Structuring MEMORY.md: Categories That Scale

Most guides tell you to create MEMORY.md and start dumping information into it. That works for a week. After a month, you have a 3,000-word wall of text where your agent cannot find anything, and the file burns through your bootstrap token budget without delivering value.

The fix is categorical structure with enforced limits.

A Starter Template

Here is a MEMORY.md template organized by category. Copy it into your workspace and fill in the sections that apply to you:

# Long-Term Memory

## User Preferences
- Communication style: [e.g., direct, brief, no emojis]
- Timezone: [e.g., CET / Europe/Amsterdam]
- Preferred language: [e.g., English, with Dutch for personal notes]
- Writing style preferences: [e.g., no exclamation marks in professional messages]
- Tools: [e.g., VS Code for coding, Notion for project management, Linear for tickets]

## Key Contacts
- [Name] — [Role/Relationship] — [Key context, e.g., "CTO at ClientCo, prefers async communication"]
- [Name] — [Role/Relationship] — [Key context]

## Active Projects
- [Project name]: [One-line status] — [Key decisions or constraints]
- [Project name]: [One-line status] — [Key decisions or constraints]

## Recurring Workflows
- Weekly content planning: [Day, process, tools involved]
- Client invoicing: [Frequency, tool, any special rules]
- Code review process: [Standards, who reviews what]

## Decisions Log
- [Date]: [Decision made] — [Reasoning]
- [Date]: [Decision made] — [Reasoning]

## Lessons Learned
- [Insight from past experience, e.g., "OAuth method for OpenAI is stable; Anthropic OAuth occasionally triggers account flags — use a dedicated account"]

What Belongs in MEMORY.md vs What Does Not

This distinction is where most people go wrong. MEMORY.md is bootstrap context, loaded every session. It has a character limit (bootstrapMaxChars, default 20,000). Anything you put there competes with AGENTS.md, SOUL.md, and your other bootstrap files for a combined budget of 150,000 characters (bootstrapTotalMaxChars).

Put in MEMORY.md:

• Facts that are true for months or longer (timezone, preferred tools, contact details)
• Active project summaries that change weekly, not daily
• Decisions with lasting impact and their reasoning
• Patterns the agent should recognize (“When I say ‘ship it,’ I mean deploy to production”)

Keep out of MEMORY.md:

• Today’s task list (that goes in the daily note)
• Conversation details from a specific session (daily note)
• Temporary states (“Waiting for John’s email” belongs in the daily note; remove it when resolved)
• Duplicate information already in AGENTS.md or SOUL.md
• Long code snippets or documentation (link to the file instead)

Think of MEMORY.md as a briefing document for a new team member joining your project. It should take 30 seconds to scan, not 5 minutes to read.

---

The Memory Maintenance Loop: Heartbeat Integration

Even with compaction flush enabled, context can slip through gaps. Sessions end unexpectedly. The agent gets interrupted. The flush prompt misses something. The most reliable protection is redundancy: a heartbeat instruction that runs every 30 minutes and ensures memory is current.

Heartbeat Memory Instructions

Open your heartbeat.md file and add this section:

## Memory Maintenance
1. Check if today's daily memory file exists (memory/YYYY-MM-DD.md). Create it if missing.
2. From all current sessions, log a summary of:
   - Decisions made since last heartbeat
   - New information about contacts or projects
   - Tasks completed or newly created
   - Corrections to existing preferences
3. If any information in daily notes should be promoted to MEMORY.md (because it is durable, not transient), update MEMORY.md.
4. If MEMORY.md exceeds 15,000 characters, review and compress: remove resolved decisions, archive completed project entries, consolidate redundant preferences.

This creates a loop: conversations generate context, the heartbeat captures it to daily notes, and durable insights get promoted to MEMORY.md. Over time, your agent gets smarter without its memory files getting bloated.

Weekly Memory Review

Daily notes accumulate fast. After a month, you may have 30+ files in the memory/ folder. The agent can search them, but the signal-to-noise ratio degrades as old notes pile up.

Add a weekly review to your workflow (or to a Sunday cron job):

1. Read the past 7 daily notes
2. Promote anything valuable to MEMORY.md (new contacts, confirmed preferences, project outcomes)
3. Archive or delete daily notes older than 30 days
4. Check MEMORY.md for stale entries (completed projects, outdated contact info, resolved decisions)

You can tell your agent to do this: “Review the last 7 daily memory files. Promote anything important to MEMORY.md and flag stale entries for removal.”

---

Diagnosing Memory Problems

When your agent seems to forget things, resist the urge to change configuration. Diagnose first.

The Memory Audit Checklist

Run through this sequence before tweaking anything:

1. Check what the agent sees. Type /context list in your OpenClaw session. This shows every file loaded into the current context. If MEMORY.md is not listed, it is not being loaded. Check the filename and location.

2. Verify the memory flush is enabled. Run get compaction memory flush enable in your terminal. If it returns false, your agent is losing context on every compaction.

3. Watch memory search in action. Type /verbose to enable verbose mode. Then ask your agent something it should know from memory. If no memory_search call appears in the output, the agent is not checking its notes. Add this line to AGENTS.md: “Always search memory before answering questions about my preferences, contacts, projects, or past decisions.”

4. Check daily note freshness. Open the memory/ folder. Look at today’s file. If it is empty or does not exist, the heartbeat is not running or the agent is not writing memory. Run openclaw daemon status to check.

5. Inspect MEMORY.md size. If it exceeds bootstrapMaxChars (default 20,000 characters), it is being truncated. The agent sees only the first 20,000 characters. Compress or split the file.

Common Fixes

Symptom	Likely Cause	Fix
Agent forgets things after long sessions	Compaction without flush	Enable memory flush; raise reserveTokensFloor
Agent ignores known preferences	MEMORY.md not loaded or too large	Check /context list; reduce file size below 20K chars
Agent does not search old notes	No memory_search trigger	Add explicit search instruction to AGENTS.md
Daily notes are empty	Heartbeat not running	Check openclaw daemon status; restart daemon
Memory seems noisy or irrelevant	Bad flush prompt or no curation	Update flush rules in AGENTS.md; run weekly review

---

Frequently Asked Questions

Does MEMORY.md exist by default when I install OpenClaw?

No. You have to create it yourself. Open a chat with your agent and say: “Create a memory.md file in the workspace folder and start using it to log important things you learn about me.” Or create the file manually in your text editor and save it in the workspace root.

How big should MEMORY.md be?

Keep it under 15,000 characters to stay well within the default 20,000-character bootstrap limit. That is roughly 2,500 words. If you are hitting the limit, you are storing too much transient information. Move project details to separate files and link to them instead.

Can my agent remember things across different Telegram groups?

Yes, but with caveats. MEMORY.md and daily notes are loaded in all sessions, including group chats. However, OpenClaw respects channel boundaries for privacy. Information shared in a private DM is not automatically accessible in a group chat unless it was written to a shared memory file. If you want cross-channel memory, make sure the information lives in MEMORY.md or a daily note rather than only in the conversation context.

What happens if I edit MEMORY.md manually?

Nothing breaks. OpenClaw memory files are plain markdown. You can open them in any text editor, rewrite sections, delete entries, or reorganize the structure. The agent reads whatever is in the file at session start. Manual editing is the fastest way to fix incorrect memories or remove outdated information.

Should I use a third-party memory plugin like Mem0 or Hindsight?

For most users, native OpenClaw memory with proper configuration is sufficient. Third-party plugins like Mem0, Hindsight, or Cognee add value in specific scenarios: if you need enforced automatic capture (Mem0), knowledge graphs for complex relationship reasoning (Cognee), or zero-config persistent memory (Hindsight). Start with native configuration first. If you find the agent still forgets critical information after following this guide, a plugin may help fill the gap.

---

Key Takeaways

• OpenClaw memory has four layers: bootstrap files, daily notes, context window, and retrieval indices. Only the first two are durable.
• Enable the memory flush before compaction to prevent context loss. Shape the flush with explicit rules in AGENTS.md.
• Structure MEMORY.md with categories (preferences, contacts, projects, workflows, decisions, lessons) and keep it under 15,000 characters.
• Wire your heartbeat to run memory maintenance every 30 minutes so nothing falls through the gaps between sessions.
• Diagnose before configuring. Run /context list and /verbose to see what your agent loads and searches before changing parameters.
• Run a weekly memory review to promote insights from daily notes to MEMORY.md and prune stale entries.

---

What to Do Next

If you have not set up OpenClaw yet, start with our complete setup guide which covers installation, workspace files, model selection, and Telegram configuration.

If your agent is already running but memory is the bottleneck, work through this article top to bottom: enable the flush, restructure MEMORY.md with the template above, add the heartbeat maintenance section, and run the diagnostic checklist. Most memory problems resolve within a single session once the configuration is right.