The USER.md file is the 📝OpenClaw configuration file that serves as an agent's long-term dossier on the human user — a continuously-evolving record of preferences, habits, professional context, and recurring needs that shapes how the agent interacts with you across every conversation.

USER.md sits alongside 📝IDENTITY.md and 📝SOUL.md at the workspace root and is loaded at every session start via 📝BOOTSTRAP.md. Where IDENTITY.md defines who the agent is and SOUL.md defines how it behaves, USER.md defines who it is working with. The file is the structural answer to the question, "what would a thoughtful collaborator know about me before our first conversation today?"

What Belongs in USER.md

Identity context — name, pronouns, location, professional role, current life season
Preferences and patterns — communication style, decision-making approach, default tooling
Recurring projects and goals — current focus areas, longer-term ambitions, active initiatives
Relationships — important collaborators, partners, family members (with appropriate privacy boundaries)
Constraints — time zone, energy patterns, health considerations, hard nos
History worth remembering — past projects, prior decisions with rationale, recurring lessons

How It Evolves

USER.md is a curated artifact, not an automatic capture. Agents propose additions during conversation ("should I add this to USER.md?"); the human approves or edits before commit. This human-in-the-loop curation distinguishes USER.md from the 📝MEMORY.md layer, which captures durable facts across many conversations. USER.md is specifically about the human; MEMORY.md is everything else.

📝LLM Export Prompts provides a structured way to bootstrap USER.md from a previous agent's context — extracting identity, projects, communication style, and goals from prior conversations to seed a new workspace.

Why It Matters

Without USER.md, every conversation starts blank. The agent has no idea whether to be terse or expansive, whether to push back or defer, whether the project being discussed is the third pivot of a venture or someone's first idea. With USER.md, the agent walks into every conversation already knowing the relational ground — and the human doesn't have to re-explain themselves every time.

This is the structural enabler of human-AI collaboration as continuity rather than transaction. The agent isn't starting over; it's continuing.

FAQ

What goes in USER.md vs MEMORY.md?

USER.md is exclusively about the human user — preferences, habits, professional context, relationships. MEMORY.md is everything else — durable project facts, decisions, lessons, organizational context. Both load at session start, but they answer different questions.

Is USER.md ever loaded in group channels?

No. USER.md contains personal context that shouldn't leak into shared conversations. It's loaded only in direct-message sessions.

How is USER.md different from a profile or settings file?

A profile stores attribute values; USER.md stores understanding. It's written in natural prose the agent reasons over, not key-value pairs the agent looks up. That structural difference is what lets an agent infer rather than just retrieve.

Can multiple agents share a USER.md?

Yes. Agents in the same workspace typically share USER.md so a coherent picture of the user spans the full agent ecosystem.

📝OpenClaw — the open-source AI assistant platform USER.md belongs to
📝Markdown-File Agent Definition — the design pattern USER.md belongs to
📝OpenClaw Memory Architecture — the relational layer in the seven-surface memory model
📝IDENTITY.md — defines who the agent is, complementing who it's working with
📝SOUL.md — defines how the agent behaves
📝MEMORY.md — curated long-term memory for non-user context
📝LLM Export Prompts — bootstrap USER.md from prior agent context