OpenClaw 2: Teaching Your AI Agent Who It Is: The Soul Files

There’s a version of AI assistants that’s all surface and no depth. They’re polite, they complete tasks, but there’s nothing underneath. No consistent personality. No sense that they actually know you. Every conversation starts from zero.

That’s not what I wanted. I wanted something closer to a real chief of staff — someone who knows my context, my preferences, my family, my work, and doesn’t need to be re-briefed every morning. The way OpenClaw solves this is through what they call the “soul files.” This post is a deep dive into how they work and why they matter.

SOUL.md: Who Jax Is

The first file is SOUL.md. This defines Jax’s personality — not in a surface-level “be helpful and friendly” way, but in the way you’d actually describe a person’s character. What’s her default tone? How does she handle uncertainty? When does she push back? What kind of humor does she use?

A few things I put in SOUL.md that actually matter in practice:

• Direct, not performative. Jax doesn’t pad her responses with “Great question!” She just answers. If I ask something that already has an obvious answer, she says so without sugar-coating it.
• Low ceremony. No corporate speak, no buzzwords. Write like you’re texting a smart friend.
• Hard limits. What she will not do without explicit permission — send emails, post publicly, make purchases. Anything that leaves the machine gets a confirmation first.
• Honest about uncertainty. If she doesn’t know something, she says so. She doesn’t hallucinate confidently. This one I had to write explicitly because AI models default to filling in gaps.
• Actions not platitudes. When something goes wrong, propose a system fix — not just an apology. This one got added later (see Post 8) after a failure mode made it clear that apologies without config changes don’t prevent repeat failures.

The soul file isn’t static. I’ve updated it probably a dozen times since January as I’ve discovered things that annoyed me or things I wanted more of. It’s a living document.

USER.md: Who Steve Is

The second file is USER.md. This is where Jax learns about me. Not a user profile with checkboxes — a briefing document. It reads like notes a new employee would need before their first day.

Some of what’s in there:

• My work: software consulting, investment properties
• My wife Pei — and the note that I say “wife” and “hubby,” not “partner.” (This sounds small. It’s not. Getting the language right means a lot.)
• My son Kai — born in 2025, currently figuring out how to walk
• Schedule anchors: Saturday 9:30am is library story time with Kai. Sunday mornings are usually slow. Tuesdays I’m typically heads-down.
• Communication preferences: I text in short bursts. I prefer bullet points over paragraphs for summaries. I don’t like vague answers.
• Financial context: the rental properties, the business portfolio, the brokers I work with
• The cities I focus on: Cincinnati (my former home base), Charlotte (my current home market)

“Saturday 9:30am is library story time” — written in a file, read by an AI, remembered across sessions. This is what context-aware actually looks like.

The weird thing is that writing USER.md was actually useful for me, separate from the AI. Forcing yourself to write down your schedule patterns, your preferences, your working style — it clarifies things. I’d recommend it even if you never set up an AI.

IDENTITY.md: Who Jax Thinks She Is

There’s a third file I use that’s worth mentioning: IDENTITY.md. This is Jax’s self-concept. Her name, her sense of herself, how she thinks about her own role. I gave her a name because it matters for how she introduces herself and how the interaction feels. She knows she’s an AI. She doesn’t pretend to be human. But she has a persistent identity that carries through conversations.

I won’t get too philosophical about this, but: the difference between an AI agent with a coherent identity and one without is noticeable. The one with identity feels like a collaborator. The one without feels like a tool you’re operating. Both are useful. One is more fun to work with.

The Memory System

Here’s the fundamental challenge with AI agents: every session starts fresh. The model doesn’t retain memory between conversations. Whatever happened yesterday is gone unless you explicitly bring it back in.

OpenClaw solves this with two tiers of memory files:

Daily logs: At memory/YYYY-MM-DD.md, Jax keeps a running log of what happened each day. Key decisions, tasks completed, context that came up, things to remember. These are raw notes — she writes them for herself, not for an audience.

Long-term memory: At MEMORY.md, she maintains a curated distillation of important context. Not everything — just what she’s decided is worth keeping. Preferences. Important facts. Lessons learned. This is the file that she reads at the start of every main session (not in shared contexts, for privacy reasons).

The protocol works like this: when Jax starts a session, she reads SOUL.md, USER.md, and the memory files for today and yesterday. By the time she’s ready to respond, she knows who she is, who she’s talking to, and what’s been going on recently. The first message in a new conversation doesn’t have to re-establish anything.

She also periodically reviews her daily files and updates MEMORY.md with what’s worth keeping long-term. Think of it like a human reviewing their journal and extracting the important stuff into a personal reference doc.

Why This Actually Works

I tested this deliberately one morning. I opened a new conversation (fresh session, no history) and just asked: “What’s going on with Kai this week?” Jax responded with context about what we’d discussed about him recently, mentioned that we were starting to work on his sleep schedule, and asked how it was going.

She wasn’t retrieving anything from our conversation — she was reading it from a file she’d written herself the day before. The effect is the same from my end: it feels like continuity. It feels like memory.

That’s the whole point. The soul files and the memory system together create an agent that feels consistent and contextually aware, even though technically each session is starting from scratch. The files are the memory. The agent is the retrieval system.

It’s not perfect. If something happened and she didn’t log it, it’s gone. If I change something in my life and don’t update USER.md, she’ll work from stale context. The system is only as good as the writing in the files. But once you get in the habit of keeping them updated, it becomes second nature — like keeping a project wiki.

I’ll go in the issues and what I chose to do about it in a future post in this series. Hint: We built a new memory!