How OpenCLAW Memory Actually Works

OpenCLAW agents don't have persistent memory between conversations. Every time you send a message, the agent reads several files (SOUL.md, USER.md, MEMORY.md, and recent session history) and constructs its "memory" from scratch. It's not remembering - it's reading its notes.

Why Your Agent Forgets Things

Reason 1: Your session is too old

Every message in your current session gets included in each new API call. After 2-3 weeks, this becomes thousands of tokens. The model either hits its context limit (old conversations get silently truncated) or OpenCLAW runs compaction which summarizes everything but loses detail.

Fix: Use /new regularly - daily at minimum, and before any big task. This clears the conversation buffer while keeping all files intact.

Reason 2: Important info is in chat history, not in files

If you told your agent something in a conversation 3 weeks ago, that info lives in session history which gets truncated. Anything your agent should ALWAYS know needs to be in a file, not in chat.

Fix: Put permanent information in USER.md:

# About me
- Name: [your name]
- Partner: [name]
- Location: [city]
- Job: [role]
- Timezone: [timezone]

Preferences

Communication: direct, no filler
Morning routine: briefing at 8am
Never schedule meetings before 10am
Coffee order: [whatever it is, seriously]

This file gets loaded every session and never gets truncated or compacted.

Reason 3: MEMORY.md is a bloated mess

Most people never structure MEMORY.md, so after a month it becomes a giant wall of text that the model skims instead of reads. Important facts get buried under irrelevant details.

Fix: Structure your MEMORY.md into clear sections:

# People
Sarah (wife): works at [company], birthday June 12
Mike (coworker): handles the frontend, prefers slack over email

Active Projects

Kitchen renovation: contractor is Dave, budget $15K, starts April
Q2 presentation: due March 28, needs sales data from Mike

Decisions Made

Switched from opus to sonnet on March 5 (cost reasons)
Using brave search API instead of google (free tier sufficient)

Recurring Tasks

Daily briefing at 8am (calendar + email + weather)
Weekly grocery list every Sunday at 6pm

Organized memory gets retrieved accurately. The agent reads structured text better than a wall of paragraphs.

Reason 4: You don't have a memory maintenance routine

Memory files grow forever without cleaning. After 2 months, MEMORY.md has 300 lines with half being outdated or irrelevant, wasting tokens on finished projects.

Fix: Set up a nightly memory cron. Add this to your agent's instructions:

every night at 11pm:


review today's conversations
extract any new facts, decisions, or commitments
add them to the correct section in MEMORY.md
remove anything that's no longer relevant
start a fresh session

Reason 5: You're confusing session memory with long-term memory

Understand the hierarchy:

• SOUL.md: Identity and personality. Loaded every time. Never changes unless you change it.
• USER.md: Facts about you. Loaded every time. Update when your life changes.
• MEMORY.md: Ongoing context. Loaded every time. Grows and gets pruned.