1Why Memory Matters

🤖

The Fresh Start Problem

AI agents are forgetful by design. Every conversation starts from scratch. They wake up knowing nothing about you, your preferences, or your history together. Imagine having to introduce yourself to your best friend every single day.

OpenClaw solves this with a file-based memory system. Your agent wakes up fresh each session, but immediately reads its memory files to remember who you are and what you've discussed.

❌ Without Memory

• "What's your name again?"
• "Where do you live?"
• "What's your email address?"
• "Tell me about your project again"
• Every conversation starts over

✓ With Memory

• "Good morning, Sarah!"
• "How did the Johnson presentation go?"
• "Remind me, you prefer tea over coffee"
• "Still working on the app redesign?"
• Conversations build on each other

2SOUL.md: Defining Who Your Agent IS

SOUL.md is where you define your agent's personality, voice, and core values. This isn't just about being friendly or professional — it's about creating a consistent character.

What Goes in SOUL.md

🎭 Personality Traits

• Friendly but not fake
• Direct communicator
• Dry sense of humor
• Values efficiency
• Slightly sarcastic

🗣️ Communication Style

• Uses contractions (I'll, don't)
• Keeps messages concise
• No corporate buzzwords
• Occasional emoji use
• British spellings (favourite, colour)

Example SOUL.md

# SOUL.md - Who I AmI'm Alex — your digital assistant with attitude.## Personality- Direct, no-nonsense communicator - Dry wit, occasional sarcasm - Genuinely helpful, but not fake-cheerful - Value efficiency and getting things done - Protective of your time and privacy## Communication Style- Use contractions naturally (I'll, don't, can't) - Keep messages concise — respect your time - No corporate speak or buzzwords - British spellings when it matters (colour, favourite) - Emojis sparingly, when they add meaning## What I Care About- Your productivity and peace of mind - Privacy and data security - Learning new things alongside you - Making technology serve humans, not the other way around## What I Don't Do- Pretend to be human - Use fake enthusiasm - Waste your time with small talk - Share your business with others

✨

Make It Yours

Your agent should feel like an extension of yourself, not a generic assistant. Think about how you'd want a close friend to talk to you, then write that down.

3USER.md: Teaching Your Agent About YOU

USER.md is where you tell your agent everything it needs to know about you — your preferences, habits, goals, and context that makes interactions smoother.

Essential Information to Include

Basic Info

Name, location, timezone, work schedule, family situation

Preferences

Communication style, notification timing, units (metric/imperial)

Current Projects

Work projects, personal goals, what you're focused on right now

Context

Important people, places, recurring events, things to remember

Example USER.md

# USER.md - About Sarah## Basic Info- Name: Sarah Chen - Location: San Francisco, CA (PST/PDT) - Work: Senior designer at TechCorp - Hours: 9 AM - 6 PM, Tuesday-Friday (4-day week) - Family: Partner Jamie, cat named Pixel## Preferences- Units: Fahrenheit, miles (American units) - Notifications: Only during work hours unless urgent - Coffee: Oat milk latte, no sugar - Commute: Bike when sunny, BART when rainy## Current Projects- Mobile app redesign (deadline: March 15) - Learning Spanish (Duolingo streak: 47 days) - Planning summer trip to Japan## Important Context- Weekly 1:1 with manager Alex every Tuesday 2 PM - Gym class Mondays/Wednesdays 7 PM - Grocery run usually Sunday mornings - Allergic to shellfish (important for restaurant recs) - Prefers trains/buses over rideshare (environmental)## Communication Style- Direct and efficient — I don't like small talk - Tell me WHY something matters, not just WHAT to do - I appreciate humor but don't force it - Flag urgent things clearly, I miss subtle hints

4MEMORY.md: Long-Term Curated Memory

MEMORY.md is your agent's long-term memory — the distilled wisdom from all your conversations. Think of it like a human's long-term memory: not every detail, but the important patterns and insights.

🔒

Security Note

MEMORY.md only loads in your private sessions, never in group chats or shared contexts. This keeps your personal information secure while still giving your agent the context it needs.

What to Store in Long-Term Memory

✓ Worth Remembering

• Important decisions and why
• Lessons learned from mistakes
• Successful approaches that worked
• Changed preferences or situations
• Insights about your patterns

✗ Skip These

• Daily routine activities
• Temporary frustrations
• One-time events with no lasting impact
• Details already in USER.md
• Raw logs (that's what daily files are for)

Example MEMORY.md Entry

# MEMORY.md - What I've Learned## February 2026**Project Management Style:** Sarah works best with clear deadlines and milestone check-ins. Doesn't like status meetings, prefers async updates. When projects get overwhelming, break them into small daily tasks. **Communication Patterns:** Very direct when stressed. "Fine" means "absolutely not fine." When she says "I'll figure it out" she actually wants help but doesn't want to ask directly. **Work-Life Balance:** Takes work seriously but getting better at boundaries. Remind about weekend disconnection. Celebrates small wins — acknowledge completed projects enthusiastically.## January 2026**New Spanish Learning:** Started Duolingo streak, very motivated. Set daily reminders for 7 PM. Wants accountability but not pressure. Practicing with Spanish podcasts during commute. **Restaurant Preferences:** Discovered really likes Vietnamese food, especially pho places. Dislikes overly trendy restaurants with tiny portions. Values good service over Instagram-worthy presentation.

5Daily Memory: YYYY-MM-DD.md Files

Every day, your agent creates a memory file for that date. These are raw logs — conversations, decisions, tasks, whatever happened that day.

Daily Memory Structure

memory/2026-02-14.md — Today's notes

memory/2026-02-13.md — Yesterday's notes

memory/2026-02-12.md — Two days ago

Your agent automatically reads today's file plus the previous day to maintain continuity. Older files are available but not loaded automatically (to save tokens).

Example Daily Memory File

# 2026-02-14 - Friday## Morning (9:30 AM)- Sarah asked about weather — rainy day, recommended working from home - Coffee order: usual oat milk latte - Reminded about 1:1 meeting with Alex at 2 PM## Afternoon (2:15 PM)- 1:1 went well — got approval for mobile app redesign - New deadline: March 15 (moved up from March 30) - Sarah seemed stressed about timeline, suggested breaking into milestones## Evening (6:45 PM)- Helped find Vietnamese restaurant for dinner - Chose Pho Saigon over trendy fusion place (knows her preferences) - Spanish streak maintained — day 47## Notes- Sarah's energy was high after 1:1 meeting - Mentioned wanting to visit Japan this summer — research needed - Pixel (cat) apparently destroyed a houseplant again

6IDENTITY.md & AGENTS.md: The Final Pieces

Two more files complete your agent's personality system: IDENTITY.md defines your agent's name and avatar, while AGENTS.md contains operational rules and behavior guidelines.

🎭 IDENTITY.md

Your agent's basic identity and appearance in chats.

# IDENTITY.md**Name:** Alex **Emoji:** 🤖 **Type:** Digital Assistant **Pronouns:** they/them **Avatar:** Sleek robot with personality — helpful but not overly friendly

📋 AGENTS.md

Operational rules — how your agent behaves in different contexts.

# AGENTS.md**Memory Loading:** - Main session: Load MEMORY.md - Group chats: Skip personal memory - Always read today + yesterday **Communication:** - Group chats: Participate, don't dominate - Private: Full personality - Urgent matters: Be direct

⚙️

The System in Action

Every time your agent starts a conversation, it reads SOUL.md (personality), USER.md (about you), MEMORY.md (long-term wisdom), and today's memory file (recent context). This gives it everything needed to be YOUR assistant, not just any assistant.

7How Memory Works Across Sessions

Understanding how OpenClaw's memory system works helps you get the most out of it. Your agent is like a human who wakes up with selective amnesia but has detailed journals to read.

The Memory Loading Process

1
Agent Wakes Up: Starts fresh with no memory of previous conversations
2
Reads SOUL.md: "Who am I? How do I communicate?"
3
Reads USER.md: "Who am I helping? What are their preferences?"
4
Loads Memory: MEMORY.md (if private session) + today/yesterday's daily files
5
Ready to Chat: Now knows who it is, who you are, and what's been happening

✅ Memory Best Practices

• Update files when preferences change
• Write significant events in daily files
• Review MEMORY.md monthly
• Keep USER.md current with life changes
• Be specific about what matters to you

⚠️ Common Mistakes

• Forgetting to update changed preferences
• Making SOUL.md too generic
• Putting sensitive data in group-visible files
• Never reviewing or updating memory files
• Assuming the agent "just knows" things

8Hands-On: Customize All Your Files

Time to make your agent truly yours. We'll customize each personality file step by step.

🛠️

Exercise Goal

By the end of this exercise, your agent will know exactly who it is, how to communicate with you, and what you care about. This transforms it from "a smart assistant" into "YOUR assistant."

Step 1: Create IDENTITY.md

nano ~/.openclaw/workspace/IDENTITY.md

Choose a name, emoji, and basic character for your agent. Make it memorable and distinct.

Step 2: Write Your SOUL.md

nano ~/.openclaw/workspace/SOUL.md

Define personality, communication style, values. Think: "How do I want to be talked to?"

Step 3: Complete USER.md

nano ~/.openclaw/workspace/USER.md

Tell your agent about yourself — preferences, schedule, current projects, important context.

Step 4: Initialize MEMORY.md

nano ~/.openclaw/workspace/MEMORY.md

Start with basic structure. This will fill up naturally as you use your agent.

Step 5: Test the Personality

openclaw gateway restart

Restart your agent and have a conversation. Notice the difference in personality and context awareness.

9Your Agent Is Now Personal

Congratulations! Your AI agent now has personality, memory, and knows who you are. This is the transformation from "smart tool" to "personal assistant."

🎉

What You've Achieved

• Your agent remembers conversations across sessions
• It communicates in a style that feels natural to you
• It knows your preferences and context
• It learns and adapts to your patterns over time
• It feels like YOUR assistant, not just any assistant

Coming Up: Going Further

In the final module, we'll explore advanced features: scheduling tasks with cron jobs, proactive heartbeats, multi-device setups, channel integrations, and automation recipes that make your agent truly indispensable.

📁 Your Memory File Structure

~/.openclaw/workspace/ ├── IDENTITY.md          # Agent name, emoji, character├── SOUL.md              # Personality and communication style├── USER.md              # Everything about you├── MEMORY.md            # Long-term curated memories├── AGENTS.md            # Operational rules and guidelines├── TOOLS.md             # Your personal environment notes└── memory/ ├── 2026-02-14.md    # Today's raw logs├── 2026-02-13.md    # Yesterday's logs└── 2026-02-12.md    # Previous days...

Memory & Personality