USER.md is the file that tells your agent who it is helping. Without it, the assistant has to guess your name, your timezone, your work style, and how direct it should be. That sounds minor until you use the agent every day, and the little misses start to accumulate: it keeps asking basic questions, assumes the wrong schedule, and answers in a tone that never quite fits.
This guide covers what USER.md is for, what happens without it, the fields worth filling in, and why the wording matters more than it looks like it should.
What USER.md is for
USER.md is the personal context file. It can hold your name, your preferred way of being addressed, your timezone, your communication style, your work focus, your priorities, and even the hours when you should not be interrupted. It gives the agent the background it needs before it starts making decisions, instead of after a string of setup questions.
That matters because context changes output. A design lead and a night-shift founder do not need the same default behavior, even when they ask for the same kind of help. The file is how the agent knows which one it is working for.
What happens without it
Without USER.md, the agent fills in the blanks badly. It asks questions it should already know, delivers generic answers, and misses the tone cues that would make a reply feel sharper and more useful. The misses show up most often in address style and scheduling assumptions: it guesses how formal to be, and it guesses when you are awake. One missing file turns every interaction into a small setup conversation, and the setup conversation repeats every time.
What the template holds
Note the shape of the file: hard facts at the top, open context below. The basics give the agent stable ground: name, what to call you, pronouns when relevant, timezone, and standing notes. The context section is the living part, the projects, priorities, and personality details that build up as you work together. The template itself carries the right instruction: you are learning about a person, not building a dossier, and the difference shows in how the file gets used.
Scope matters as much as content. USER.md is the file about the human, and it loads with the agent’s startup context in the same way MEMORY.md does, which is exactly why it should stay factual and current rather than padded. It is also why the file belongs to the person it describes: if more than one person uses an agent, each one should have their own workspace context rather than a shared file full of compromises. One agent, one owner, one USER.md keeps the context sharp.
A filled example
A complete example makes it concrete. The setup behind this site runs on an identity close to this:
That combination, name, address style, timezone, and a working note about values, is enough to shape tone in a useful way. The assistant can be direct, concise, and practical without needing a reminder every time. One file quietly improves almost every response, because it removes the part where the agent guesses who it is talking to.
Why the wording matters
The wording of the file is not cosmetic; it changes default behavior. Change one line from “prefers brief responses” to “wants full detail” and the whole feel of the assistant shifts. It stops compressing everything and starts expanding answers naturally, on every request, without being told each time.
The same mechanism runs on work context. A file that says the user is a marketer pushes the agent toward business outcomes, content clarity, and conversion-aware suggestions. A file that says developer shifts the emphasis to implementation, tradeoffs, and edge cases. Neither is better; each is a better fit for its owner, and the file is the switch.
The diagram shows the fields and what each one changes:
Keeping it current
People change roles, priorities, and preferences, and a frozen USER.md freezes the agent along with it. The file should be treated as living context: when the work shifts, when the schedule changes, when a big push starts, update the relevant line. The update takes seconds and it is how the agent keeps serving the person you are now instead of the person you were last year.
The privacy note is worth stating plainly: everything in USER.md is context handed to the agent, so it should contain what you want the agent to know and nothing you would not put in a briefing document. Secrets, credentials, and anything sensitive belong in the credential store, not in a context file that gets loaded, summarized, and potentially indexed for memory search.
Common mistakes
- Leaving the file empty or with only the placeholder fields.
- Being too vague to guide anything: “likes good communication” does not shape a single response.
- Filling it once and never touching it again.
- Treating it as a dossier instead of working context, which makes the agent weirdly formal instead of usefully informed.
The practical test for a good USER.md is simple: after a week of normal use, the agent should not be asking questions the file already answers. If it still asks about your timezone or your preferred level of detail, the file is either empty, vague, or out of date, and fixing the file fixes the conversation.
Quick tips
- Write the name and preferred address first; they set the relationship.
- Add timezone and quiet hours early; they prevent the most annoying mistakes.
- Include the tone you want, not just the facts about you.
- Update it when your work changes, and let context accumulate naturally.
USER.md is the counterpart to MEMORY.md explained: that file carries what the agent remembers about the world and the work, this one carries who it is working for. Both are part of the workspace file family covered in The Complete OpenClaw Guide.
Not Ready to Self-Host? Try ClawTrust
Building agents locally is powerful, but managing infrastructure, security, and scaling takes effort. ClawTrust provides managed OpenClaw hosting: your agents run securely in the cloud with automatic scaling, no DevOps overhead, and 24/7 monitoring.
This post contains affiliate links. If you buy through them, I may earn a small commission at no extra cost to you.
About The Author
This helped but I still dont know how much personal detail is too much for USER.md, do you keep it super minimal or add a lot.
Minimal usually works best, name, timezone, preferences, and a few stable facts are enough. Add only what improves decisions or prevents repeated mistakes.
How often would you update USER.md, only when something big changes or whenever your preferences shift a bit.
Use change threshold logic, if the detail affects how the agent should respond regularly, update it. Tiny temporary preferences usually belong in a session note, not USER.md.
The privacy part is the thing I care about most, I like the template but I would probably keep some notes out of it.
That is the right instinct. USER.md should be useful, not invasive, so avoid storing anything sensitive unless it clearly improves the agent’s behavior and you are comfortable keeping it local.
I keep overthinking USER.md, do you really need much more than name timezone and a couple preferences.
That is usually enough. The point is to help the agent make better choices, not to build a biography.
How do you decide when a preference is important enough to move into USER.md instead of leaving it in the chat history.
If it is stable and likely to improve future responses, put it in USER.md. If it is temporary or situational, leave it in session context.
The privacy angle felt balanced here, not too much personal data, just enough to make the agent useful.
That balance is the goal. Keep USER.md local, minimal, and practical, then add only what clearly pays for itself in better behavior.