OpenClaw MEMORY.md Guide: Persistent AI Agent Memory
MEMORY.md is OpenClaw's persistent knowledge base — a curated Markdown file that lets your agent remember facts, preferences, and context across every session. Unlike ephemeral session logs, MEMORY.md stores only what you deliberately want preserved: the information that makes your agent smarter each time it starts.
What is MEMORY.md? MEMORY.md is a plain Markdown file in OpenClaw's workspace directory (~/.openclaw/workspace/MEMORY.md) that stores curated long-term notes for your AI agent. It holds durable truths, learned preferences, and persistent context that carry across sessions. OpenClaw is the first AI agent to solve the persistence problem using local-first Markdown storage — no database, no external API, just files on your disk that you fully own and control.
Key distinction: MEMORY.md is a compact, maintained reference for durable facts. Short-lived session context goes in daily log files (memory/YYYY-MM-DD.md). Together, they give your agent both long-term memory and a working journal.
This guide covers everything about OpenClaw's memory system: how it works, best practices, templates, common mistakes, and the full file ecosystem.
Trusted by 194+ business owners who configured OpenClaw in our live workshop — endorsed by Josh Nelson's 7 Figure Agency community (20,000+ agency owners)
What is MEMORY.md?
MEMORY.md is the persistent brain of your OpenClaw agent. It is the single file where your agent stores everything it needs to remember across sessions.
Durable Truths
Facts that remain true over time: project conventions, technology choices, client preferences, and architectural decisions your agent should always know.
Learned Preferences
Patterns your agent discovers through working with you: your coding style, communication tone, preferred tools, and how you like things organized.
Persistent Context
Important context that should survive across sessions: ongoing project states, key contacts, recurring workflows, and decisions that affect future work.
Local-First Storage: You Own Your Data
OpenClaw stores all memory as plain Markdown files on your local disk. There is no database, no external API, and no cloud dependency. MEMORY.md lives at ~/.openclaw/workspace/MEMORY.md and can be opened, edited, versioned, or backed up with any tool you already use.
This local-first approach means your agent's memory is as portable and private as a text file. Move it between machines, check it into Git, or sync it with Dropbox — it is just Markdown.
The 4 Layers of OpenClaw Memory
OpenClaw's memory architecture is built in layers. Each layer serves a distinct purpose — understanding all four helps you use the system effectively.
Short-Term Memory
Conversation layer
The active context window of your current conversation. Everything said in this session is immediately available to the agent. This layer is ephemeral — it resets when the conversation ends. It is the fastest layer but the shortest-lived. Important facts from short-term memory should be promoted to higher layers before the session closes.
Session Memory
Workspace layer — memory/YYYY-MM-DD.md
Automatic daily log files written to the workspace directory. Each session date gets its own Markdown file capturing tasks, decisions, and context from that day. Session memory persists across restarts but is scoped to recent activity. It bridges short-term conversation context and long-term project knowledge.
Project Memory
Repo-level layer — .openclaw/MEMORY.md
Repository-scoped memory stored alongside your code. This layer captures project-specific facts: architecture decisions, team conventions, deployment details, and codebase patterns. Project memory is version-controlled with the repo, making it portable and shareable with teammates who use OpenClaw on the same project.
Long-Term Memory
Global layer — ~/.openclaw/workspace/MEMORY.md
The global MEMORY.md that persists across all projects and sessions. This is your agent's permanent knowledge base — preferences, identity, cross-project conventions, and durable truths that apply everywhere. Long-term memory is the highest-value layer: what lives here shapes every interaction your agent has, regardless of which project you are working on.
MEMORY.md vs Daily Logs
Understanding when to use each file type is essential to keeping your agent's memory clean and effective.
MEMORY.md (Long-Term)
~/.openclaw/workspace/MEMORY.md
- Durable truths that persist indefinitely
- User preferences and working style
- Project conventions and architecture decisions
- Key contacts and their roles
- Learned corrections ("User prefers tabs over spaces")
- Technology stack and environment details
- Curated and maintained — not a raw log
Daily Logs (Short-Term)
~/.openclaw/workspace/memory/YYYY-MM-DD.md
- What tasks were worked on today
- Temporary decisions and context
- Session-specific notes and observations
- Debugging steps and troubleshooting logs
- Draft ideas not yet promoted to MEMORY.md
- Communication summaries from the day
- Automatically created per session date
The Analogy That Makes It Click
MEMORY.md is your notebook. You choose what goes in it, you edit it for clarity, and every entry earns its place. Daily logs are your surveillance camera — they capture everything automatically, comprehensively, and without judgment. Both are useful. Neither replaces the other. The notebook gives you the highlights; the camera gives you the full record.
Rule of Thumb
Ask yourself: "Will this still be true and useful next week?" If yes, it belongs in MEMORY.md. If it is only relevant today or this session, put it in the daily log. When a daily log entry proves to be durable over multiple sessions, promote it to MEMORY.md.
memory_search vs memory_get
OpenClaw provides two distinct tools for retrieving memory. Knowing when to use each one makes a significant difference in retrieval quality.
memory_search
Semantic similarity search
When to Use
- You want to find memories related to a topic
- You are exploring what the agent knows about a subject
- You are not sure of the exact entry ID
- You want the most relevant memories surfaced by meaning
How It Works
Performs semantic search across your memory index using vector similarity. Returns entries ranked by conceptual relevance to your query — even if they don't contain the exact words you used.
Example
memory_search("client communication preferences") returns all entries related to how clients like to communicate, even if none use those exact words.
memory_get
Direct ID-based retrieval
When to Use
- You know the exact memory entry ID
- You want a specific, predictable result
- You are building a workflow that references a known memory
- You need exact retrieval without ranking noise
How It Works
Fetches a specific memory entry directly by its unique ID. Fast and deterministic — returns exactly the entry you specified, or nothing if the ID does not exist.
Example
memory_get("mem_acme_corp_contact") returns exactly the Acme Corp contact entry, nothing more.
Default to memory_search for Most Use Cases
In practice, memory_search is the right default for agent-initiated retrieval. It surfaces the most relevant context without requiring the agent to know exact IDs. Reserve memory_get for workflows where you have pre-established memory IDs and need guaranteed, predictable retrieval — such as automation scripts or templated workflows.
Monthly Memory Review
A regular review practice keeps MEMORY.md accurate, lean, and high-value. Treat it like pruning a garden — a monthly review prevents bloat and keeps what remains genuinely useful.
Remove Outdated Facts
Projects complete, clients churned, technology decisions reversed — these entries no longer serve your agent and add noise. Delete them without hesitation. If you might need historical reference, move them to an archive section at the bottom of the file.
Consolidate Redundant Entries
Over time, you may accumulate multiple entries that say similar things. Merge them into a single, authoritative entry. Redundancy wastes context window space and can cause the agent to weight a preference more heavily than intended.
Add Frequently-Repeated Context
If you have been telling the agent the same thing repeatedly in your sessions — your meeting schedule, a project constraint, a communication preference — that belongs in MEMORY.md. The friction of repetition is a signal that something is missing from your long-term memory.
Review for Accuracy
Facts become stale. The API version you documented six months ago may have changed. The team member you listed may have left. Read through every entry with fresh eyes once a month and verify it still reflects reality. Date-stamp corrections so you know when a fact was last verified.
Schedule It Like a Meeting
The monthly review only takes 10-15 minutes, but it compounds over time. Put a recurring monthly calendar event on the first of each month: "Review MEMORY.md". Agents that are maintained monthly outperform agents with stale or bloated memory files significantly. This single habit is the highest-leverage practice in the entire OpenClaw workflow.
3 Memory Failure Modes and How to Fix Them
Most MEMORY.md problems fall into one of three patterns. Recognize them early and apply the right fix before they degrade your agent's performance.
Memory Bloat
Failure ModeSymptom
Too many entries — retrieval becomes noisy and the agent starts surfacing irrelevant context
Root Cause
Adding entries without ever removing them. Every project, every session, every fact gets appended indefinitely.
Solution
Monthly pruning. Set a hard limit of 200 lines. When you hit that limit, you must remove something before adding something new. Treat MEMORY.md like a fixed-size whiteboard, not an infinite scroll.
Memory Stale
Failure ModeSymptom
Outdated facts leading to wrong actions — the agent confidently acts on information that is no longer true
Root Cause
Facts added months ago that were never updated. Technology versions, team members, project status, and preferences change over time.
Solution
Date-stamp every entry and review quarterly. Format: [YYYY-MM-DD] Updated: new fact. Entries older than 6 months without a review date should be treated as suspect and verified before relying on them.
Circular References
Failure ModeSymptom
The agent contradicts itself — it knows fact A from one entry and fact B from another, but A and B are mutually exclusive
Root Cause
An entry was added that conflicts with an existing entry without removing or updating the older one. This often happens when a fact changes but only the new version is added, not the old version removed.
Solution
Before adding a new fact that replaces an old one, search MEMORY.md for the old fact and delete it first. Maintain a single source of truth per concept. Use the Corrections Log section to explicitly mark overrides with dates.
MEMORY.md vs USER.md: Which File Should You Use?
New OpenClaw users often confuse these two files. Both store information about you — but they serve fundamentally different purposes.
MEMORY.md
~/.openclaw/workspace/MEMORY.md
Dynamic, session-learned knowledge
- Facts the agent discovered through working with you
- Corrections made during past conversations
- Project-specific context and architecture decisions
- Preferences revealed through interaction patterns
- Time-stamped entries that change as your work evolves
- Information that accumulates and gets pruned over time
When to Use
When you want the agent to remember something it learned — from a correction you made, a pattern it observed, or context built up across sessions.
USER.md
~/.openclaw/workspace/USER.md
Static identity and preference declaration
- Your name, role, timezone, and working hours
- Declared communication style preferences
- Expertise level in different domains
- How you want to be addressed and treated
- Stable facts you set once and rarely change
- Onboarding information — not learned, but stated
When to Use
When you want to declare who you are and how you want to be treated upfront — before any interaction has happened. Think of it as the onboarding doc you hand to a new assistant.
The Simple Rule: Declaration vs Discovery
USER.md is for declaration — facts you intentionally tell the agent before work begins. It is your onboarding document. MEMORY.md is for discovery — facts the agent learns by working with you over time. It is your shared notebook.
In practice, many users start with USER.md to provide baseline context, then let MEMORY.md grow organically as the agent learns. You can also migrate entries: if you find yourself repeatedly correcting USER.md entries with new context, those corrections belong in MEMORY.md where they carry timestamps and history.
3 Copy-Paste MEMORY.md Templates
Start with one of these templates and customize it for your context. Each is designed for a different use case.
1. Basic Memory Config
Minimal starter template with title, description, format metadata, and owner profile
# MEMORY.md — Basic Configuration
## About This File
- Title: My OpenClaw Agent Memory
- Description: Persistent knowledge base for my primary OpenClaw agent
- Format: Markdown sections, date-stamped corrections, pruned monthly
- Last reviewed: 2026-03-15
## Owner Profile
- Name: [Your Name]
- Role: [Your Role]
- Timezone: [e.g., US/Eastern]
- Primary language: English
## Communication Preferences
- [Add how you want responses formatted]
- [Add tone preferences: formal / casual / direct]
- [Add length preferences: brief bullets / detailed prose]
## Core Context
- [Add your most important persistent facts here]
- [Add technology stack or tools you use regularly]
- [Add key contacts the agent should know about]
## Corrections Log
- [YYYY-MM-DD] [Fact that was wrong] → [Corrected fact]2. Project Memory Template
For teams and developers — tracks key facts, dates, contacts, and architecture decisions per project
# MEMORY.md — Project Memory
## Active Projects
- Project Alpha: [Brief description]. Started [date]. Owner: [name].
- Key files: [path/to/important/files]
- Status: [in-progress / blocked / review]
- Next milestone: [milestone and date]
- Project Beta: [Brief description]. Started [date]. Owner: [name].
- Dependencies: [list key dependencies]
- Known blockers: [list current blockers or "none"]
## Key Contacts
- [Name]: [Role]. Contact: [email/slack]. Notes: [anything agent should know].
- [Name]: [Role]. Contact: [email/slack]. Notes: [preferences, availability, etc.].
## Architecture Decisions
- [YYYY-MM-DD]: [Decision made and rationale]
- [YYYY-MM-DD]: [Decision made and rationale]
## Known Issues
- [Issue description] — tracked in [ticket/issue #]. Workaround: [workaround or "none"].
## Important Dates
- [YYYY-MM-DD]: [Event or deadline]
- [YYYY-MM-DD]: [Event or deadline]3. Conversation Memory Template
For capturing interaction preferences, learned patterns, and corrections from past conversations
# MEMORY.md — Conversation Memory
## Interaction Preferences
- Response style: [e.g., concise bullets / detailed explanations]
- Assumed knowledge level: [e.g., senior developer / marketing beginner]
- Preferred greeting: [e.g., skip pleasantries and get to the point]
- Emoji use: [e.g., never / sparingly / freely]
## Recurring Patterns the Agent Has Learned
- [YYYY-MM-DD] I prefer [specific preference discovered in session]
- [YYYY-MM-DD] I always want [specific behavior or output format]
- [YYYY-MM-DD] Never suggest [something the user dislikes]
## Corrections Made More Than Once
- [YYYY-MM-DD] Corrected: [what the agent got wrong] → [what's correct]
- [YYYY-MM-DD] Corrected: [what the agent got wrong] → [what's correct]
## Session Boundaries
- Topics to never bring up: [list sensitive or off-limits topics]
- Topics to always check before acting on: [list topics needing confirmation]
- Default escalation preference: [ask / act and report / always proceed]
## Vocabulary and Terminology
- We call [X] "[preferred term]", not "[term to avoid]"
- [Technical term] means [specific meaning in this context]How Does Memory Persistence Work in OpenClaw?
OpenClaw is the first AI agent to solve the persistence problem. Here is how the memory lifecycle works from session to session.
Session Start: Agent Reads Memory Files
When OpenClaw boots up, it reads MEMORY.md and the most recent daily log files. This restores the agent's full context — durable facts from MEMORY.md and recent session details from daily logs. The agent starts every session already knowing who you are, what you are working on, and how you prefer things done.
During Session: Agent Learns and Works
As you interact with the agent, it identifies information worth remembering. New facts, corrections to previous assumptions, discovered preferences, and important decisions are all candidates for memory. The agent distinguishes between short-lived context (today's tasks) and durable truths (project-wide conventions).
Session End: Agent Writes to Memory
Before a session ends, the agent writes short-lived context to the daily log file (memory/YYYY-MM-DD.md) and updates MEMORY.md with any new durable truths. Old or corrected entries in MEMORY.md are updated or removed. The daily log captures what happened today; MEMORY.md captures what matters long-term.
Next Session: Cycle Repeats
The next time OpenClaw starts, it reads the updated files and has full continuity. There is no token limit on memory size, no context window to overflow, and no risk of the agent forgetting what it learned. Memory grows organically and is pruned through regular maintenance.
What Does a MEMORY.md Template Look Like?
Here is a well-structured MEMORY.md you can use as a starting point. Copy and customize it for your workspace.
# MEMORY.md — Long-Term Agent Memory ## User Profile - Name: Sarah Chen - Role: Full-stack developer, freelance consultant - Timezone: US/Pacific (PST/PDT) - Prefers concise responses; dislikes unnecessary preamble ## Technology Stack - Frontend: React 18 + TypeScript + Tailwind CSS - Backend: Node.js with Express, PostgreSQL - Hosting: Vercel (frontend), Railway (backend) - Version control: GitHub, prefers squash merges ## Code Preferences - Tabs for indentation (width: 2) - Single quotes in TypeScript, double quotes in JSX - Prefers named exports over default exports - Always include error handling in async functions - Component files: PascalCase. Utility files: camelCase ## Active Projects - **ClientPortal v2**: Dashboard rebuild for Acme Corp. - Deadline: March 15, 2026 - Key contact: James Wu (james@acme.com) - Uses Shadcn/UI component library - **PersonalSite**: Blog migration from WordPress to Astro - Low priority, no deadline ## Learned Corrections - [2026-02-10] User does NOT want semi-colons in TS files - [2026-02-14] Railway deployments need RAILWAY_TOKEN env var - [2026-02-17] Acme Corp API uses v3, NOT v2 (v2 deprecated) ## Communication Rules - Draft emails in professional but warm tone - Never use emoji in client-facing communication - Always CC sarah@sarahchen.dev on project emails
# Daily Log — 2026-02-18 ## Session Summary - Worked on ClientPortal v2 dashboard charts - Refactored bar chart component to use Recharts - Fixed timezone bug in date picker (was showing UTC) ## Decisions Made - Switched from Chart.js to Recharts for better React integration - Will use date-fns instead of moment.js (lighter bundle) ## Tomorrow - Start on the notification preferences page - Review James's feedback on the sidebar navigation ## Notes - PostgreSQL query for user metrics is slow (~3s) - Consider adding an index on created_at column - Ask Sarah if caching is acceptable for dashboard data
Important: MEMORY.md Does Not Load in Group Chats
MEMORY.md only loads automatically in main OpenClaw sessions. When OpenClaw is operating in a group chat, sub-agent context, or multi-agent collaboration mode, MEMORY.md is not automatically available to all agents in the conversation.
Main sessions: MEMORY.md loads automatically at session start.
Group chats / sub-agents: MEMORY.md is NOT automatically loaded. Verify memory availability before relying on it in these contexts.
If you are building multi-agent workflows, explicitly pass the relevant context from MEMORY.md in your agent handoff instructions rather than assuming it will be available.
What Are the Best Practices for MEMORY.md?
A well-maintained MEMORY.md dramatically improves your agent's performance. Follow these practices to get the most out of persistent memory.
Keep It Curated, Not Raw
MEMORY.md is a reference document, not a transcript. Every entry should be edited for clarity and usefulness. If you would not put it in a team wiki, do not put it in MEMORY.md.
Use Clear Section Headers
Organize entries under descriptive Markdown headers (## User Profile, ## Code Preferences, ## Active Projects). This helps both you and the agent find information quickly.
Date Your Corrections
When adding learned corrections, include the date: "[2026-02-18] API endpoint changed to /v3". This helps you track when facts were updated and identify stale entries.
Review and Prune Weekly
Set a weekly reminder to scan MEMORY.md. Remove completed projects, outdated preferences, and facts that are no longer true. A lean file gives your agent clearer context.
Never Store Secrets
API keys, passwords, tokens, and credentials do not belong in MEMORY.md. Use environment variables, .env files, or a secrets manager. Memory files are plain text and may be backed up or shared.
Promote Recurring Patterns
If the same fact appears in multiple daily logs, it is a durable truth. Promote it to MEMORY.md and remove it from the daily logs. This prevents your agent from re-learning the same thing.
What Does the Full OpenClaw File Ecosystem Look Like?
MEMORY.md is one part of a larger system. Each Markdown file in the workspace directory serves a specific purpose in configuring your agent.
MEMORY.mdLong-term notesCurated durable truths, learned preferences, and persistent context across sessions.
memory/YYYY-MM-DD.mdDaily session logsShort-lived session context, tasks worked on, temporary decisions, and daily notes.
AGENTS.mdOperating contractDefines agent behavior, rules, boundaries, and how the agent should operate.
SOUL.mdPhilosophy and valuesCore principles, ethical guidelines, and the agent's philosophical foundation.
IDENTITY.mdPresentation and voiceHow the agent presents itself, tone of voice, and communication style.
USER.mdUser preferencesInformation about the user: working style, preferences, and personal context.
TOOLS.mdTool configurationAvailable tools, their settings, and how the agent should use them.
HEARTBEAT.mdSchedulerRecurring tasks, scheduled actions, and periodic check-in definitions.
BOOT.md / BOOTSTRAP.mdInitializationStartup sequence, files to load, and the order of operations when the agent wakes up.
What Are Common MEMORY.md Mistakes and How Do You Fix Them?
Avoid these pitfalls to keep your agent's memory clean, fast, and useful.
Using MEMORY.md as a raw transcript
Keep only curated, durable truths. Move session details to daily logs.
Never cleaning up outdated entries
Review weekly. Remove facts that are no longer true or relevant.
Duplicating information across files
User preferences belong in USER.md, behavior rules in AGENTS.md. MEMORY.md is for learned facts only.
Making MEMORY.md too long (500+ lines)
Aim for under 200 lines. Consolidate related entries and archive old sections.
Storing sensitive credentials in MEMORY.md
Never put API keys, passwords, or tokens in memory files. Use environment variables or a secrets manager.
Mixing short-term tasks with long-term memory
Today's to-do list goes in memory/YYYY-MM-DD.md. Only persistent facts go in MEMORY.md.
Why Does Local-First Memory Matter?
OpenClaw's decision to use plain Markdown files on disk is a deliberate architectural choice with real advantages.
Privacy by Default
Your agent's memory never leaves your machine. No cloud database, no third-party storage, no data processing agreements needed. MEMORY.md is as private as any file on your hard drive.
Full Ownership
You can read, edit, back up, version control, and migrate your memory files freely. No vendor lock-in, no export tools needed. If you stop using OpenClaw, your data stays with you.
Human-Readable Format
Markdown is universally understood. You do not need a special viewer, database client, or admin panel to inspect or modify your agent's memory. Open it in any text editor.
What Are the Most Common MEMORY.md Questions?
Stop Wasting 40-60% of Your AI Budget
Download the free '6 Token Drains' guide — identify the hidden patterns burning through your tokens and get copy-paste fixes for each one.
Read the Free GuideYour Competitors Are Already Automating. Are You?
Every week we send one automation that saves 10+ hours of manual work — the same playbooks our clients use to run their businesses on autopilot. Miss a week, miss the edge.
Get the Automation Playbook (Free)
One deploy-ready automation every week. Same strategies our clients pay thousands for. 400+ business owners already inside.
Need it done for you?
Book a Free Strategy Call See what we've built for real businesses →Related OpenClaw Configuration Guides
SOUL.md Guide
Configure your agent's core philosophy, ethical principles, and foundational values — the deepest layer of OpenClaw's identity stack.
USER.md Guide
Declare who you are and how you want to be treated. USER.md is the onboarding document your agent reads before any interaction begins.
Identity Architecture
How SOUL.md, AGENTS.md, USER.md, and MEMORY.md layer together to form a complete, coherent OpenClaw agent identity system.
OpenClaw .md Files Hub
The complete reference for every OpenClaw configuration file: SOUL.md, AGENTS.md, USER.md, MEMORY.md, and more.