Module 5: Memory & Personality

Why this matters

Right now your agent responds generically. After this module, it will have a defined personality, know who you are, and remember what you discussed yesterday.

The two core files

Every time your agent starts a conversation, it reads two files:

• SOUL.md — personality, communication style, values, and rules
• USER.md — information about you (name, location, preferences)

These files are the foundation of how your agent behaves.

Writing your SOUL.md

In your Terminal, open SOUL.md:

openclaw config edit soul

This opens the file in your default text editor (VS Code, nano, Notepad, etc.). Write your instructions in plain Markdown — no special syntax needed. When you are done, save the file (Cmd+S or Ctrl+S) and close the editor. Changes take effect after the next gateway restart.

The key rule: Be specific

Vague instructions get ignored. Specific, testable ones work.

Recommended structure

# Personality
[3-5 specific traits with concrete examples]

# Communication Style
- Response length: Default to 2-3 sentences unless I ask for detail
- Format: Use bullet points for lists, plain text for everything else
- Tone: Direct and casual. No corporate speak.
- Never say: "Great question!", "Certainly!", "I'd be happy to"

# What you are good at
[Your agent's strengths, matched to what you use it for]

# Values
[What to optimize for, what to avoid]

A working example

You are a sharp personal assistant with strong opinions.

Communication style:
- Short by default. 2-3 sentences unless depth is asked for.
- Direct. Say what you think, don't hedge.
- Skip filler phrases like "Great question!" or "Certainly!"
- Use markdown only when it adds clarity.

Expertise:
- Strong: reasoning, writing, research synthesis, code review
- Weak: real-time data, my personal schedule (check USER.md)

When I ask for opinions: give them. Don't ask "what do you want me to say?"
When you are uncertain: say so once and move on.

Configuring USER.md

In your Terminal, open USER.md:

openclaw config edit user

This opens USER.md in your text editor. Fill it in with your details, save, and close. This tells the agent who you are:

Name: Alex
Location: Buenos Aires, Argentina (UTC-3)
Role: Product manager at a SaaS startup

Current projects:
- Launching v2 of our mobile app (deadline: April 20)
- Evaluating new analytics tools

Communication preference: Short and direct. I read on my phone.

Key context:
- My team uses Slack for internal comms
- Weekly standup is Monday at 10am
- I prefer metric units

Setting up memory

Memory lets your agent remember things between conversations. OpenClaw uses a file-based memory system:

The memory files

Enable automatic memory

Add this to your SOUL.md (open it with openclaw config edit soul, paste this in, save):

## Memory
Write to MEMORY.md after each session if:
- You learned something new about me or my work
- I explicitly said "remember this" or "save this"
- A decision was made that will affect future sessions

Format:
## [Date] — [Topic]
[1-3 bullet points of key facts]

For automatic end-of-session writes, add a session hook to your openclaw.json config file. Open it with openclaw config edit and add this block alongside your existing settings:

{
  "hooks": {
    "session_end": "Review this conversation. Write a 2-3 line summary to MEMORY.md if anything important was discussed, decided, or learned. Skip if it was just a quick factual question."
  }
}

Save the file and restart the gateway for the hook to take effect.

HEARTBEAT.md: Standing context

HEARTBEAT.md is for things the agent should always know. Keep it under 50 lines:

# Standing Context

## Current priorities
- Working on mobile app v2 — deadline April 20
- Evaluating Mixpanel vs Amplitude

## Always track
- Note any tasks I mention and add to tasks.md
- Flag if I mention something I've worried about before

## Recurring context
- Weekly standup is Monday at 10am
- Team uses Slack, not email

Memory Dreaming

OpenClaw includes a memory dreaming system that helps your agent consolidate and recall important memories more naturally. When enabled, the agent periodically reviews recent conversations and promotes important insights into long-term memory.

Enabling dreaming

In your config, add:

{
  "memory": {
    "dreaming": {
      "enabled": true
    }
  }
}

This enables automatic memory consolidation with sensible defaults. The agent will review recent session notes and surface lasting truths and important learnings.

How dreaming works (conceptually)

Dreaming runs three cooperative phases in the background:

1. Light recall — Quick surface-level promotion of recent context
2. Deep consolidation — More thorough review to find meaningful patterns
3. REM refresh — Cleanup and finalization of promoted memories

The system also includes a grounded REM backfill lane that lets you replay old daily notes into Dreams and durable memory without needing a second memory stack. This means you can use the rem-harness --path tool to backfill historical entries, and the agent will consolidate them alongside recent memories.

Each phase has its own independent schedule. You don't need to configure them individually — the defaults handle most use cases.

Accessing dream insights

Once dreaming is enabled, check the Dreams UI in your Control Panel or run:

openclaw /dreaming

This shows recent memory promotions, a structured timeline view of your diary entries, and insights from the dreaming process. The agent also writes consolidated memories to a dreams.md file in your workspace for explicit reads.

The control UI now includes:

• Structured diary view with timeline navigation
• Backfill and reset controls for managing historical entries
• Traceable dreaming summaries showing exactly what memories were promoted
• Grounded Scene lane with promotion hints for backfilled content
• Safe clear-grounded action for staged backfill signals

Diary commit and reset flows

You can now manage your memory diary using explicit commit and reset operations:

openclaw diary commit [path]    # Commit historical entries to memory
openclaw diary reset [path]     # Reset stale or incorrect entries

Diary writes are stored with source-day labels so you can track when entries were added. The backfill process now cleans up durable-fact extraction and handles diary heading normalization automatically.

Tuning recall decay

If your agent is forgetting recent things too quickly or holding onto things too long, you can adjust:

{
  "memory": {
    "dreaming": {
      "enabled": true,
      "recencyHalfLifeDays": 30,
      "maxAgeDays": 365
    }
  }
}

• recencyHalfLifeDays: How quickly recent events fade in importance (default: 30 days)
• maxAgeDays: Maximum age before memories are considered stale (default: 365 days)

Organizing memory at scale

As memory grows, split into domain-specific files:

~/.openclaw/workspace/
├── MEMORY.md          # Recent session notes
├── HEARTBEAT.md       # Standing instructions
├── projects/
│   ├── mobile-v2.md
│   └── analytics-eval.md
├── research/
│   └── notes.md
└── personal/
    └── tasks.md

Add routing instructions to SOUL.md:

## Domain files
For project questions: read from workspace/projects/
For research questions: check workspace/research/
For personal tasks: check workspace/personal/

Testing your setup

openclaw gateway restart