Managing Agent Memory & Context

OpenClaw takes a file-first approach to memory. Unlike cloud-based AI assistants that store everything on remote servers, OpenClaw stores core cognitive states, identity, and knowledge in plain-text Markdown files within your workspace. This gives you complete transparency and ownership over your agent's memory.

Understanding this memory architecture is essential for building reliable, persistent agents that remember what you tell them and stay consistent across sessions.

The eight auto-loaded files

OpenClaw automatically loads eight specific filenames at boot. These files are injected into the agent's context at the start of every session, making them the foundation of your agent's knowledge and identity:

• SOUL.md - Core identity, personality, tone, and hard rules
• AGENTS.md - Operational instructions and routing rules
• USER.md - What the agent knows about you (preferences, context)
• TOOLS.md - Environment-specific tool configurations
• IDENTITY.md - Agent name, emoji, and brand description
• HEARTBEAT.md - Heartbeat automation rules and schedules
• BOOTSTRAP.md - Initial system bootstrapping instructions
• MEMORY.md - Long-term curated facts and knowledge

Critical knowledge that your agent must know every session belongs in one of these files. Custom-named files are not automatically injected, even if they exist on disk.

Understanding SOUL.md

SOUL.md is the most important file in your OpenClaw setup. It defines who your agent is. Think of it as a Constitution for your agent, not a personality quirk list.

What belongs in SOUL.md

• Name and role - "You are Aria, a customer support agent for Meridian SaaS"
• Tone and communication style - Direct, friendly, patient, admits when information is unknown
• Hard limits and security invariants - "Never discuss competitor pricing", "Always recommend consulting a professional for legal questions"
• Core behaviors - "Teach first, sell second", "Always cite sources"
• Cost guardrails - Rules about token usage and API call limits
• Memory rules - Instructions about what to remember and how

What does NOT belong in SOUL.md

• Mission statements or "personality fluff"
• Detailed task instructions (put those in AGENTS.md or MEMORY.md)
• Project-specific context (put that in daily notes)
• User preferences (put those in USER.md)

SOUL.md best practices

• Treat it as non-negotiable rules, not suggestions
• Add explicit rules that ban overwrites to prevent tampering
• Keep it stable - frequent changes indicate an unstable identity
• Focus on trust boundaries, tool limitations, and approval requirements

Understanding MEMORY.md

MEMORY.md is where you store curated, durable facts that should persist across sessions. Unlike daily notes which are ephemeral, MEMORY.md contains knowledge you want your agent to always have access to.

What belongs in MEMORY.md

• Preferred answer formats and styles
• Ongoing projects and their current state
• Tool defaults and configurations
• Rules that should apply consistently over time
• Important facts about your work or business
• Recurring patterns and preferences

MEMORY.md vs daily notes

Think of it this way:

• MEMORY.md = durable truths (like an encyclopedia)
• memory/YYYY-MM-DD.md = running context (like a journal)

Daily notes capture what happened today, current projects, and temporary context. MEMORY.md stores what should be true forever. Keep MEMORY.md concise and focused on enduring truths.

USER.md: Your agent's knowledge of you

USER.md is specifically for what the agent knows about you. This includes your communication preferences, timezone, relevant context about your work, and anything else that helps the agent serve you better.

USER.md has no strict size limit and is the go-to file for user-specific knowledge. If your agent needs to know something about you that should persist across sessions, USER.md is the place.

The three-layer memory architecture

Community-developed best practice organizes memory into three layers:

Layer 1: Core Identity (SOUL.md)

Who the agent is. Stable, rarely changes. Defines personality and non-negotiable rules.

Layer 2: Long-Term Operational Memory (MEMORY.md + AGENTS.md)

How the agent works. Preferences, patterns, ongoing projects. Updates occasionally but not frequently.

Layer 3: Ephemeral Memory (daily notes)

What is happening now. Today's tasks, recent context, temporary information. Resets or archives after each day.

Preventing context loss

Context loss is one of the most common complaints about OpenClaw. Here is how to prevent it:

Pre-compaction memory flush

Before the context window fills up, explicitly save important information to MEMORY.md. You can prompt your agent to "save what we've discussed to MEMORY.md" before hitting context limits.

Use the right file for the right purpose

If you tell your agent something in chat that it should remember permanently, explicitly say "Remember this for future sessions - add it to MEMORY.md." Do not assume it will remember.

Context window guards

Add rules in AGENTS.md that remind the agent to periodically consolidate important information to memory files before the context gets too full.

Staged summarization

For long-running projects, create summary notes in MEMORY.md at key milestones rather than relying on the full conversation history.

Memory protection stack

The memory protection stack is a set of practices to keep your agent's memory secure and reliable:

• In-file write rules: Add rules in memory files that the agent should not modify them without explicit permission
• SOUL.md behavioral rules: Explicitly ban overwrites in SOUL.md
• AGENTS.md routing: Use AGENTS.md to route "remember" requests appropriately
• Automated backups: Regularly backup memory files
• Size checks: Monitor memory file sizes and detect unexpected changes
• Auto-restore on wipe: Have a process to restore from backup if memory is wiped

Common memory mistakes to avoid

• Relying on chat alone: If it is important, put it in a file
• Using custom filenames: OpenClaw only auto-loads the 8 specific files
• Symlinks: They are blocked - use real files only
• Too much in daily notes: Important info gets lost when notes are archived
• Changing SOUL.md too often: It destabilizes the agent's identity
• Putting project details in SOUL.md: Use MEMORY.md or daily notes instead

Version control for memory

Integrate your OpenClaw workspace with Git. This gives you:

• History of changes to memory files
• Easy restore to previous versions
• Backup and redundancy
• Detection of unexpected modifications

Building reliable memory habits

Your agent's memory is only as good as what you put into it. Build these habits:

1. When you tell your agent something important, explicitly direct it to save to the appropriate file
2. Regularly review and clean up MEMORY.md to prevent bloat
3. At the end of significant sessions, have the agent summarize key points to MEMORY.md
4. Use daily notes for running context but consolidate important points to MEMORY.md
5. Periodically verify that memory files contain what you expect

OpenClaw's file-first memory approach gives you transparency and control that cloud-based systems cannot match. Take advantage of it by being intentional about what goes where.