How to Structure MEMORY.md for Better Agent Continuity

If you want an agent to stay useful over time, MEMORY.md should capture the durable things that should not have to be rediscovered every session. The best structure is simple: preferences, active projects, standing rules, important decisions, and anything that changes how the agent should work next time. That is the practical answer.

A lot of memory files go wrong in one of two ways. They are either too empty to help, or they become a junk drawer of every detail the agent has ever seen. Neither one is good for continuity.

A strong MEMORY.md is not a transcript. It is a working memory layer. It should help the agent remember what matters without making retrieval messy.

This guide walks through how to structure MEMORY.md, what belongs there, what does not, and how to keep the file useful as the workspace grows.

If you want the broader memory context first, read OpenClaw Memory Best Practices, OpenClaw Workspace Design Best Practices, and the memory guide.

What MEMORY.md is for

MEMORY.md is for durable context.

That means information that should keep shaping future work, such as:

• user preferences
• standing operating rules
• active project context
• important decisions that should not be re-litigated every session
• recurring pitfalls or lessons learned

It is not meant to hold every transient update. That is what daily logs, project notes, and other narrower files are better for.

The easiest way to think about it

A good MEMORY.md answers questions like:

• how should I work with this user?
• what is already decided?
• what active work should I remember?
• what patterns keep coming up?
• what should I avoid forgetting next time?

If a note does not help answer those kinds of questions, it may belong somewhere else.

What to put in MEMORY.md

Here are the sections that tend to pay off most.

1. User preferences

This is where you capture durable collaboration preferences.

Examples:

• prefers direct, pragmatic communication
• likes bullets over long prose
• wants draft-first behavior for external messages
• dislikes fluff and unnecessary ceremony

These are the kinds of details that improve every future interaction.

2. Standing rules

This is where you note persistent operational rules.

Examples:

• always ask before destructive actions
• use Telegram for reminders by default
• do not send overnight noise unless urgent
• report failures clearly instead of hiding them

These are not just preferences. They are behavioral constraints that should keep applying.

3. Active project context

This is where you capture live work that still matters across sessions.

Examples:

• OpenClawCrew daily blog pipeline is running daily
• GSC MCP server is still unavailable
• image generation provider has recently been unstable
• certain recurring blockers or dependencies are still open

This gives the agent working continuity instead of forcing it to rediscover the situation each time.

4. Important decisions

This section is underrated.

A lot of wasted time comes from revisiting the same decision because nobody wrote it down clearly.

Examples:

• chose short heredoc writes for blog publishing because long writes hit approval guards
• use draft-first messaging for sensitive or external communication
• prefer assistant-style operational workflows over broad autonomous runs

Once a decision keeps affecting future work, it belongs in memory.

5. Lessons learned

This is where repeated mistakes become cheaper.

Examples:

• certain commands trigger guardrails if they are too long
• a missing MCP server blocks a recurring external action
• a certain workflow gets noisy if it reports every cycle instead of only changed states

This section makes the agent better over time in a very practical way.

What should not go in MEMORY.md

A few things usually do not belong here.

Every daily update

That belongs in daily logs, not in the main memory file.

Raw transcripts

Those are too noisy and too specific.

One-off details with no future value

If the fact will not matter again, it probably should not sit in durable memory.

Huge unstructured note dumps

If the file becomes a landfill, retrieval quality drops and continuity gets worse instead of better.

A simple structure that works well

Here is a clean structure most teams can start with:

# MEMORY.md

## User preferences
- prefers direct updates
- wants bullets and copy-paste-ready output

## Standing rules
- ask before destructive changes
- draft external messages before sending

## Active projects
- OpenClawCrew blog pipeline is active
- GSC MCP server unavailable

## Important decisions
- use short heredoc writes for content creation
- keep recurring automations low-noise

## Lessons learned
- long inline writers can hit approval guards
- image generation availability may vary by session

This is enough structure to stay useful without getting bloated.

How to decide if a note belongs in MEMORY.md

Use this quick test:

• will this still matter next week?
• will forgetting it make future work worse?
• does it change how the agent should behave?
• is it broader than one single task run?

If the answer is mostly yes, it probably belongs in memory.

If the answer is no, it likely belongs in a daily note or project-specific file instead.

How MEMORY.md should work with daily logs

This is important.

Daily logs are the raw stream.

MEMORY.md is the distilled layer.

That means the usual flow should be:

1. capture events and work in daily logs
2. notice repeated patterns or durable decisions
3. distill those into MEMORY.md

That keeps the main memory file useful and readable.

Common mistakes when structuring memory

Mistake 1: making it too vague

If the note does not change future behavior, it is not doing enough.

Mistake 2: making it too crowded

If the file tries to remember everything, it remembers nothing well.

Mistake 3: never pruning old context

Memory should stay alive. If a project is done or a rule changed, update the file.

Mistake 4: mixing durable memory with task-by-task logs

This makes retrieval harder and lowers signal.

How I would maintain MEMORY.md

A practical rhythm looks like this:

• update daily logs as work happens
• promote only durable information into MEMORY.md
• review and prune memory periodically
• rewrite sections when they become cluttered or stale

That process works better than treating memory as either frozen or endlessly appended.

Why structure matters for continuity

The goal is not just storage.

The goal is usable recall.

A well-structured memory file helps the agent answer the hidden question behind every new session:

• what should I already know before I start?

That is what continuity really means in practice.

My recommendation

If you are building MEMORY.md today, start with five sections only:

• user preferences
• standing rules
• active projects
• important decisions
• lessons learned

That is enough to create real continuity without creating noise.

If you want the official references, review the OpenClaw docs, the OpenClaw GitHub repository, OpenClaw Memory Best Practices, and the memory guide. Those are the best companion sources if you want memory that improves agent usefulness instead of turning into clutter.

FAQ

What should go in MEMORY.md?

Durable context such as user preferences, standing rules, active projects, important decisions, and lessons learned.

What should not go in MEMORY.md?

Daily logs, raw transcripts, one-off details with no future value, and large unstructured note dumps.

How is MEMORY.md different from daily logs?

Daily logs capture events as they happen. MEMORY.md keeps the distilled, durable context that should matter across future sessions.

How often should I update MEMORY.md?

Whenever a decision, preference, lesson, or active context becomes durable enough that forgetting it would hurt future work.

How do I keep MEMORY.md from getting messy?

Use clear sections, keep only durable notes, and prune stale information regularly.

A practical example of bad memory vs good memory

Here is the difference in plain terms.

Bad memory

- talked about blog stuff
- user likes concise updates
- project blocked sometimes
- fix image generation later
- lots of OpenClaw work happened this week

This is too vague to help much.

Good memory

## User preferences
- prefers direct, pragmatic collaboration
- wants bullets and copy-paste-ready output

## Active projects
- OpenClawCrew daily blog pipeline is active
- image generation provider has recently failed in-session

## Important decisions
- use short heredoc writes for blog posts because long writers trigger approval guards

## Lessons learned
- GSC submission is blocked until the gsc MCP server is configured

The second version actually changes future behavior.

That is the standard to aim for.

When to create a separate memory file instead

Sometimes people try to make MEMORY.md carry too much.

If a topic is getting large, create a narrower file instead.

Good examples:

• memory/projects/openclawcrew.md
• memory/resources/seo-notes.md
• memory/projects/client-alpha.md

This keeps the main memory file focused while still preserving deeper context elsewhere.

A simple maintenance rule

A note should stay in MEMORY.md only if it is still helping the next session.

If it is stale, completed, or no longer behavior-shaping, remove it or move it to a more specific file.

That one habit keeps memory from turning into a graveyard of old context.

A good weekly memory review question

Once a week, ask:

• what would I be annoyed to have to re-explain next week?

That is often exactly what belongs in durable memory.