OpenClaw memory.md: The Hidden File That Controls Everything

Your agent forgets everything the moment a conversation ends — unless memory.md exists. Three days after I set mine up deliberately, my agent knew my time zone, my preferred code style, my client names, and which tasks to never interrupt me about. It felt like a different product entirely.

What Is memory.md and Why It Matters

memory.md is a plain Markdown file that OpenClaw automatically injects at the top of every agent system prompt. Every single conversation starts with its contents already loaded. That means your agent has access to whatever you've stored there before you type a single word.

This is different from conversation history. History only persists within a single session. memory.md persists across every session, every restart, and every channel. Whether your agent receives a message via Telegram, WhatsApp, or the CLI — it reads memory.md first.

The mechanism is simple. When OpenClaw initializes a conversation, it reads the memory.md file from disk, prepends it to the system prompt as a section labeled "Persistent Memory", then proceeds normally. Your agent model sees this memory as authoritative context — not as user input — which means it's treated with the same weight as your soul.md and identity.md files.

How the Write Mechanism Works

When you tell your agent "remember that my standup is at 9am every weekday", it parses that instruction, formats it as a Markdown bullet, and appends it to memory.md. The agent then confirms what it wrote. You can verify the file directly — it's human-readable at all times.

The agent formats entries consistently: short bullets under topic headers. Over time the file organizes itself into logical sections — Preferences, People, Projects, Recurring Tasks. You don't have to structure it manually unless you want more control.

# Persistent Memory

## User Preferences
- Time zone: Europe/Berlin (UTC+1, UTC+2 in summer)
- Preferred code language: TypeScript with strict mode
- Communication style: bullet points over paragraphs

## People
- Client: Vera Holst at NordStream — prefers Slack, no calls before 10am
- Dev partner: James Chen — handles infrastructure tickets

## Recurring
- Standup: Mon–Fri 09:00 Berlin time, send summary at 08:55
- Weekly review: Friday 16:00, pull task completion report

File Location and Configuration

Default paths by operating system:

• macOS / Linux: ~/.openclaw/memory.md
• Windows: %APPDATA%\openclaw\memory.md

Override these defaults in two ways. First, set the environment variable:

export OPENCLAW_MEMORY_PATH=/path/to/custom/memory.md

Second, add it directly to your agent config:

memory_path: /home/user/projects/myagent/memory.md

The config-level setting takes precedence over the environment variable. Use this for multi-agent setups where each agent should have its own isolated memory file.

Writing Good Memory Entries

The quality of your memory.md directly determines how useful your agent becomes. Vague entries produce vague behavior. Specific, actionable entries produce specific, useful behavior.

What works

• Specific facts with no ambiguity: "My production server is at 192.168.1.50, username deploy"
• Behavioral rules: "Never suggest pausing a task mid-way — I prefer completing one thing fully"
• People with context: "Marcus at Acme Corp — decision maker, responds best to numbered lists"
• Recurring schedules: "Invoice reminder: first Monday of the month at 09:00"

What doesn't work

• Generic preferences: "I like efficiency" — meaningless to an LLM
• Stale context: outdated project names or cancelled schedules left in the file
• Duplicate entries: the same fact written three different ways wastes tokens

Here's what I've seen consistently: the agents that perform best have memory.md files that read like structured notes from a highly organized assistant. Tight, factual, organized. Not a stream of consciousness.

Managing Token Budget

Every line of memory.md costs tokens on every message. As of early 2025, this approach still makes economic sense as long as the file stays under 2,000 words — at that size, a typical GPT-4o conversation adds roughly $0.002 to cost per session. That's negligible. At 10,000 words, you're burning $0.01 per message in memory overhead alone, which adds up fast with heavy usage.

Prune memory.md regularly. Remove entries that are no longer relevant. Archive completed project context to a separate file and remove it from the active memory. Keep the active file tight and current.

Common Mistakes

The mistake that breaks the most setups: assuming the agent will automatically clean up memory.md. It won't. The agent adds entries on request. It does not remove stale ones unless you explicitly ask. After 90 days of use, most memory.md files are bloated with irrelevant context from old projects.

Sound familiar? Set a calendar reminder every 30 days to review and prune the file. It takes five minutes and makes a material difference in agent response quality.

The second most common mistake: writing memory entries that are too general to be actionable. "I prefer direct communication" is not useful. "When I ask for a summary, give me five bullets maximum and skip the preamble" is useful. Specificity is everything.

Third mistake: creating one giant memory.md for multiple agents running different jobs. Each specialized agent should have its own memory file scoped to its responsibilities. A customer support agent doesn't need to know about your development server credentials.

Frequently Asked Questions

What is the memory.md file in OpenClaw?

memory.md is a plain text Markdown file that OpenClaw prepends to every agent system prompt. It acts as persistent long-term memory — storing facts, preferences, and context your agent should always remember. Unlike session context, memory.md survives restarts and new conversations intact.

Where is memory.md stored?

By default it lives at ~/.openclaw/memory.md on macOS and Linux, or %APPDATA%\openclaw\memory.md on Windows. Override this path with the OPENCLAW_MEMORY_PATH environment variable or the memory_path setting in your agent config.

How does OpenClaw update memory.md automatically?

When you tell your agent to remember something, it writes a structured entry to memory.md automatically. The file remains human-readable throughout. You can also edit memory.md directly at any time — changes take effect on the next conversation.

Is there a size limit on memory.md?

No hard limit exists, but every byte costs tokens per conversation. As of early 2025, keeping memory.md under 2,000 words is best practice. Beyond that, you risk hitting context limits or paying significantly more per conversation on token-priced APIs.

Can I have multiple memory.md files for different agents?

Yes. Each agent config can specify its own memory_path. Point different agents at different files to give each isolated memories — essential for multi-agent setups where shared memory would cause confusion or security issues.

How do I clear or reset memory.md?

Delete or truncate the file directly. OpenClaw doesn't lock it. Run echo '' > ~/.openclaw/memory.md or open it in any text editor and clear the contents. The agent starts fresh on the next conversation with no persistent memory.

You now know exactly what memory.md is, where it lives, how it's written, and how to keep it performing well. An agent with a tight, well-maintained memory file is an agent that gets smarter every week. Start with three entries today — name, timezone, working style — and build from there. No account, no setup beyond a text editor. Takes under five minutes.