OpenClaw Memory Explained: MEMORY.md File Guide

Look, I'll save you the frustration I went through. You just spun up your first OpenClaw agent, it worked beautifully for about ten minutes, and then it started repeating itself, forgetting what you told it, or doing something you explicitly told it not to do three messages ago. You poked around the docs, maybe the repo, and you found a file called MEMORY.md. You opened it, read it, and now you have more questions than when you started.

That's fine. That's where everyone starts. Let me walk you through what MEMORY.md actually does, why it exists, and — more importantly — how to configure it so your OpenClaw agents stop acting like they have amnesia.

The Core Problem: Your Agent Forgets Everything

Here's the scenario that brings everyone to this file. You build an OpenClaw agent. Maybe it's a research assistant, maybe it handles customer questions, maybe it manages tasks for your side project. Early on, it's great. It's responsive, it follows instructions, it remembers context.

Then one of two things happens:

The conversation gets long — around 8 to 15 turns — and suddenly the agent starts contradicting itself, losing track of key details, or hallucinating things you never said.
You close the session and come back later, and the agent has zero recollection that you ever spoke. Your preferences, your project context, the decisions you made together — gone.

This isn't a bug in OpenClaw. It's the fundamental challenge of giving any AI agent a working memory. Large language models don't inherently "remember" anything between calls. Every interaction is, at the raw level, a fresh start. The MEMORY.md file is OpenClaw's answer to that problem, and once you understand it, your agents go from cute demos to genuinely useful tools.

What MEMORY.md Actually Is

MEMORY.md is OpenClaw's configuration and specification file for how your agent handles memory. Think of it as the blueprint for your agent's brain — not the intelligence part, but the storage and retrieval part.

It sits in your project's root directory (or in your agent's config folder, depending on your setup) and defines three things:

What gets remembered — which parts of interactions are worth storing
How it's organized — the structure and hierarchy of stored memories
When it's recalled — the retrieval strategy for pulling relevant memories back into context

At its simplest, the file looks something like this:

# MEMORY.md

## memory_mode
persistent

## short_term
max_tokens: 4000
strategy: sliding_window

## long_term
store: vector
embedding_model: default
top_k: 5
relevance_threshold: 0.72

## consolidation
enabled: true
interval: every_10_turns
method: summarize_and_extract

## entities
track: true
types: [user_preferences, decisions, facts, project_context]

If you've been running your agent without this file, or with the defaults, you've been operating with whatever OpenClaw ships out of the box — which is usually just a basic sliding window of recent messages. That works for quick one-off interactions. It does not work for anything you actually care about.

Breaking Down Each Section

Memory Mode

## memory_mode
persistent

You have two primary options here: session and persistent.

Session means memory lives and dies with the current conversation. Close the tab, lose the context. This is fine for throwaway interactions, but it's not what you want for an agent you're building a relationship with over days or weeks.

Persistent means OpenClaw writes memories to a store that survives across sessions. When your agent starts a new conversation, it pulls relevant memories from previous interactions. This is where the real value lives.

If you set nothing else in this file, change this to persistent. It's the single highest-impact configuration change you can make.

Short-Term Memory

## short_term
max_tokens: 4000
strategy: sliding_window

Short-term memory is your agent's working memory — the recent conversation context it holds in its active prompt. The max_tokens value controls how much of the recent conversation stays in view. The strategy determines what happens when you exceed that limit.

sliding_window is the default. It keeps the most recent N tokens of conversation and drops the oldest messages. Simple, predictable, but lossy. If you mentioned something important 20 messages ago, it's gone.

summarize is the alternative I recommend for most use cases:

## short_term
max_tokens: 4000
strategy: summarize
summary_model: default
preserve_last: 3

With this strategy, when the conversation exceeds max_tokens, OpenClaw summarizes the older messages into a compressed block and keeps the last few turns intact. You lose some fidelity, but you retain the gist of the entire conversation instead of just the tail end.

The preserve_last parameter is key. Setting it to 3 means the three most recent exchanges are always kept verbatim, and everything before that gets summarized. This gives you the best of both worlds — accurate recent context plus a summary of everything that came before.

A practical setting I use for most agents:

## short_term
max_tokens: 6000
strategy: summarize
summary_model: default
preserve_last: 5

This is generous enough to handle substantive conversations without blowing up your token costs.

Long-Term Memory

This is where MEMORY.md really earns its keep.

## long_term
store: vector
embedding_model: default
top_k: 5
relevance_threshold: 0.72
decay: true
decay_halflife: 7d

Long-term memory is your agent's ability to recall information from previous sessions — facts about you, decisions you've made, preferences you've stated, outcomes of past tasks.

store can be vector, graph, or hybrid. Vector is the standard approach: memories get embedded and stored in a vector database, then retrieved via semantic similarity search. Graph stores memories as entities and relationships (useful if your agent needs to reason about connections between things). Hybrid uses both.

For most people getting started, vector is the right call. It's simpler, it works well, and it doesn't require you to think about schema design.

top_k is how many memories get pulled into context for each interaction. Setting this too high bloats your prompt and costs you tokens. Setting it too low means your agent misses relevant information. Five is a solid starting point. If you find your agent is missing context it should have, bump it to 8 or 10.

relevance_threshold is the minimum similarity score a memory needs to be included. This prevents your agent from pulling in vaguely related noise. I recommend starting at 0.72 and tuning from there. If your agent is recalling irrelevant stuff, raise it. If it's forgetting things it shouldn't, lower it.

decay is something a lot of people miss. When enabled, older memories gradually lose their retrieval priority. The decay_halflife determines how fast. A 7-day halflife means a memory from a week ago has half the retrieval weight of an identical memory from today. This is incredibly useful because it means your agent naturally prioritizes recent information without you having to manually prune old data.

Here's the config I use for a long-running project management agent:

## long_term
store: vector
embedding_model: default
top_k: 8
relevance_threshold: 0.68
decay: true
decay_halflife: 14d
metadata_filter: true

The metadata_filter flag tells OpenClaw to tag memories with metadata (source conversation, date, topic, entity references) and use those tags to improve retrieval precision. Always turn this on.

Consolidation

## consolidation
enabled: true
interval: every_10_turns
method: summarize_and_extract

Consolidation is your agent's ability to periodically review recent interactions and distill them into cleaner, more useful memories. Without consolidation, your long-term memory fills up with raw conversational fragments — "User said they prefer dark mode" mixed with "User asked about the weather" mixed with actual important project decisions.

interval controls how often consolidation runs. every_10_turns means after every 10 exchanges, the agent pauses (this happens in the background, you won't notice it) and processes recent memories.

method has a few options:

summarize — compresses recent memories into summaries
extract — pulls out discrete facts and entities
summarize_and_extract — does both, which is what you want

After consolidation, instead of having a memory like "In message 47, the user mentioned they tried Postgres and it was too slow for their use case," your agent stores a clean fact: "User found Postgres too slow for their use case. Prefers SQLite for local development."

This makes retrieval dramatically better.

Entity Tracking

## entities
track: true
types: [user_preferences, decisions, facts, project_context]

This tells your agent to actively identify and track entities across conversations. When you say "I prefer Remix over Next.js," the agent doesn't just store that as a random memory — it creates a structured entity record under user_preferences that can be reliably recalled even if the exact wording of your query doesn't match the original statement.

The types array determines what categories of entities your agent watches for. You can customize this based on your use case:

## entities
track: true
types: [user_preferences, decisions, facts, project_context, contacts, deadlines, tool_configs]

For a personal assistant agent, I'd add contacts and deadlines. For a coding agent, tool_configs and tech_stack. For a research agent, sources and findings. The more specific you are, the better your agent's memory becomes.

A Real Working Example

Here's a complete MEMORY.md that I'd recommend for someone building a general-purpose personal assistant in OpenClaw:

# MEMORY.md

## memory_mode
persistent

## short_term
max_tokens: 6000
strategy: summarize
summary_model: default
preserve_last: 5

## long_term
store: vector
embedding_model: default
top_k: 8
relevance_threshold: 0.70
decay: true
decay_halflife: 14d
metadata_filter: true

## consolidation
enabled: true
interval: every_10_turns
method: summarize_and_extract
max_facts_per_consolidation: 20

## entities
track: true
types: [user_preferences, decisions, facts, project_context, deadlines]

## rules
never_forget: [user_preferences, decisions]
auto_prune: true
prune_threshold: 500
prune_strategy: lowest_relevance

Notice the rules section at the bottom. This is where you set hard constraints:

never_forget — these entity types are exempt from decay and pruning. Your agent will always remember your preferences and past decisions, no matter how old they are.
auto_prune — when the memory store exceeds prune_threshold entries, it automatically removes the lowest-relevance memories to keep things clean.

This prevents the memory bloat problem that kills most long-running agents.

Common Mistakes I See

Setting top_k too high. People think "more memories = better agent." Wrong. More memories = more noise in the prompt, higher token costs, and an agent that gets confused trying to reconcile contradictory information from different time periods. Start low, increase only if you see gaps.

Forgetting consolidation. Without it, your long-term memory becomes a junk drawer of raw conversation fragments. Turn it on. Always.

Not using decay. If your agent has been running for months, you don't want a memory from January competing equally with a memory from yesterday. Decay handles this elegantly.

Leaving memory_mode on session. This is the number one reason people think their agent is broken. It's not broken — it just has no persistence. One line change fixes this.

Skip the Setup If You Want

If you're reading this and thinking "I just want this to work without manually tuning all of these parameters," I get it. Honestly, the configuration isn't hard once you understand it, but getting all the pieces right — the memory settings, the skills, the retrieval tuning — takes some iteration.

Felix's OpenClaw Starter Pack on Claw Mart comes with a pre-configured MEMORY.md and a set of skills that are already tuned to work together. It's $29, and it includes persistent memory, consolidation, entity tracking, and a handful of pre-built skills that cover the most common agent use cases. If you don't want to set this all up manually, it's genuinely the fastest way to get a working OpenClaw agent with proper memory handling. I've recommended it to a few people who were stuck in configuration hell and they were up and running in under an hour.

What to Do Next

Create your MEMORY.md in your project root if you don't have one. Copy the complete example above as a starting point.
Set memory_mode to persistent immediately. This is the highest-leverage change.
Enable consolidation. Your future self will thank you when the agent still works cleanly after 200 conversations.
Define your entity types based on what your agent actually needs to remember. Be specific.
Test with a real multi-session workflow. Have a conversation, close it, start a new one, and see if the agent recalls the important parts. If it doesn't, lower your relevance_threshold or increase top_k.
Monitor your memory store size over time. If it's growing unbounded, turn on auto_prune or tighten your consolidation settings.

Memory is the difference between a toy and a tool. An agent that remembers your context, your preferences, and your past decisions is an agent that actually saves you time. An agent without memory is just a fancy chat window you have to re-explain yourself to every single time.

Get your MEMORY.md right, and your OpenClaw agents become something you actually rely on. That's the whole point.