USER.md: The One File That Makes Your AI Agent Actually Understand Who You Are

The Tweet Making the Rounds This Morning

A tweet appeared this morning that's already being shared widely:

> *"Since projects like OpenClaw and Lobster have popularized personal agents, I've seen a wave of AI personalization solutions lately: they use structured Markdown files — like USER.md and MEMORY.md — to let AI remember every detail about you. Your preferences…"*

It hits on something real. Because most agents, even after setup, still feel like generic chatbots — they know nothing about the person they're helping. Every session starts fresh. Every preference has to be re-explained.

USER.md solves exactly that.

---

What Is USER.md and Why Does It Exist?

OpenClaw agents have several core files:

USER.md is the most frequently forgotten part of the trio. But it's the one that makes the biggest difference to the daily feel of using an agent.

Without USER.md: the agent knows everything about itself, but nothing about you.

With USER.md: the agent knows your name, your working style, your preferences, your timezone, your team — and doesn't have to ask at every session start.

---

What Goes in USER.md?

The short answer: everything you'd tell a new colleague on their first day.

Here's our real USER.md for Dimitrios — lightly anonymized, but structurally identical:

```markdown

# USER.md - About Dimitrios

The Basics

Working Style

Company

Team

Tools & Workflow

What Annoys Him

What He Likes

```

This isn't a biographical novel. It's the information that improves every single session.

---

How USER.md Gets Loaded

OpenClaw loads USER.md as part of the workspace context at the start of every session. Together with SOUL.md and MEMORY.md, it forms the agent's starting context.

The loading order in AGENTS.md defines when each file is read:

```markdown

Every Session

Before doing anything else:

1. Read SOUL.md — this is who you are

2. Read USER.md — this is who you're helping

3. Read memory/YYYY-MM-DD.md (today + yesterday) for recent context

4. If in MAIN SESSION: Also read MEMORY.md

```

The agent reads the file once at startup — after that, it knows the context without having to ask.

Important security rule: USER.md contains personal information. It's only loaded in the main session context — not in shared group channels. This prevents private details from surfacing in Discord or WhatsApp.

```markdown

# In AGENTS.md:

🧠 MEMORY.md - Your Long-Term Memory

```

---

The Three Most Common USER.md Mistakes

Mistake 1: Too Vague

```markdown

# Bad example

Name: Max

Likes short answers.

Works in the tech industry.

```

This barely helps the agent at all. "Likes short answers" means something different to everyone. Without context about the company, tools, and colleagues — the agent has to ask everything.

Mistake 2: Too Detailed

```markdown

# Bad example (too long)

Dimitrios was born on March 14, 1985. He studied in Thessaloniki.

In his spare time he plays guitar. His favorite movie is...

[200 more lines]

```

USER.md is for work-related context — not a biography. When the file gets too large, it fills the context window and crowds out more important information. Rule of thumb: under 500 words.

Mistake 3: Treating It as Static

USER.md isn't a one-time setup. People change. Projects change. Preferences change.

Sam updates USER.md regularly — when Dimitrios introduces a new tool, starts a new project, or explicitly communicates a preference. This happens either directly ("Sam, please remember that...") or through observation across multiple sessions.

---

USER.md for Teams: When the Agent Knows Multiple People

Interesting situation in our setup: some agents interact not just with Dimitrios, but also with other team members.

Alex (our admin agent) is responsible for internal team coordination, for example. His USER.md therefore contains a mini-profile for all relevant people:

```markdown

# USER.md — Alex (Everyday Agent)

Main Contact

Preference: short updates, Telegram preferred

Team Members

Rarely on Telegram, prefers email

Rules for External Communication

```

This isn't a universal pattern — each agent has the context they need for their specific role.

---

How Much Difference Does USER.md Actually Make?

Concrete examples from our operation:

Without USER.md:

```

Dimitrios: "Remind Christoph tomorrow about the deployment."

Agent: "Who is Christoph? What's his contact information?"

```

With USER.md:

```

Dimitrios: "Remind Christoph tomorrow about the deployment."

Agent: "Got it. I'll remind you tomorrow morning — Christoph prefers Discord,

or should I send an email to his @humanizing.com address?"

```

This sounds like a small improvement. In daily work it saves minutes — and more importantly, mental energy.

Another example:

```

Dimitrios: "Write the meeting notes in English."

```

An agent without USER.md might ask: "Who are the notes for?"

Sam knows: English meeting notes go to external stakeholders or investor documentation — no follow-up question needed.

---

USER.md and Privacy

This is a real tension: the more the agent knows about you, the more useful it becomes — but the greater the damage if that information is shared inappropriately.

Our rules:

1. USER.md is not loaded in group channels — Sam knows Dimitrios's timezone, but Discord users don't find out

2. Sensitive details belong in MEMORY.md, not USER.md — USER.md is for "known facts," MEMORY.md is for observations and learning

3. Regular review — what's in USER.md that's no longer accurate or necessary?

---

Building a USER.md in 15 Minutes

The fastest way: imagine a new assistant starts today. What would you need to explain so they could work independently tomorrow?

We have a simple template:

```markdown

# USER.md

The Basics

Working Style

Company / Context

Team (who's relevant?)

Tools

What annoys you?

What helps you?

```

Fill this in over 15 minutes. The agent learns the rest through observation — it updates USER.md (or you ask it to) when preferences or context change.

---

USER.md in the Context of the Trio System

For context: USER.md is one of three core documents that together define an agent's character and context.

SOUL.md defines how the agent thinks and communicates.

USER.md defines who it does that for.

MEMORY.md stores what it has learned in the process.

The viral tweet from this morning is right: structured Markdown files are the simplest path to an agent that genuinely feels like a colleague — not a chatbot that needs to be briefed from scratch every day.

The complete setup of these three files — including the AGENTS.md loading sequence, security rules, and update workflows for all 6 agents — is documented in the OpenClaw Setup Playbook.

Fully available in German too. 🇩🇪