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.

Five Reasons 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 (causing early conversations to 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]

Reason 3: MEMORY.md is a bloated mess

Most people never structure MEMORY.md. 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

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

Memory files grow forever. After 2 months, your MEMORY.md has 300 lines and half are outdated or irrelevant. The model wastes tokens reading about finished projects.

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

every night at 11pm:
1. review today's conversations
2. extract any new facts, decisions, or commitments
3. add them to the correct section in MEMORY.md
4. remove anything that's no longer relevant
5. 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.