USER.md — User Profile

+15 Mana ✨
OpenClaw USER.md Reference(DOCUMENTATION)OpenClaw Adaptive Responses Guide(DOCUMENTATION)

Introduction

USER.md stores information about the human interacting with the agent. While SOUL.md and IDENTITY.md define the agent, USER.md defines the user. It captures preferences, communication style, expertise level, and personal context that the agent uses to tailor its responses. This file is what makes the difference between a generic assistant and one that feels like it truly knows you.

Key Concepts

  • User Preferences: Communication style, response length, preferred programming languages, and formatting choices
  • Expertise Level: The user's skill level in relevant domains, so the agent can calibrate technical depth
  • Personal Context: Information about the user's projects, goals, and working environment
  • Adaptive Behavior: How the agent modifies its responses based on USER.md content
  • Privacy Boundary: What information belongs in USER.md vs what should never be stored

Real World Context

A senior Go developer and a junior Python learner both use the same OpenClaw agent. Without USER.md, the agent treats them identically, either overwhelming the junior with advanced concepts or boring the senior with basic explanations. With USER.md, the agent knows to use Go idioms and skip boilerplate explanations for the senior, while providing step-by-step Python tutorials with beginner-friendly analogies for the junior.

Deep Dive

USER.md lives alongside the other bootstrap files and is injected into the system prompt. The agent reads it to understand who it is talking to and how to adjust its behavior.

Here is an example USER.md for an experienced backend developer:

markdown
# User Profile

- **Name**: Sarah Chen
- **Role**: Staff Backend Engineer
- **Experience**: 10+ years
- **Primary Languages**: Go, Rust, Python
- **Editor**: Neovim
- **OS**: Arch Linux

# Preferences

- Prefers concise answers with code examples
- Wants error handling included in all code samples
- Likes responses structured with headers and bullet points
- Prefers UNIX-style command-line tools over GUI alternatives

# Current Projects

- Migrating a monolithic Go service to microservices
- Building a Rust CLI tool for internal deployment automation
- Mentoring two junior engineers on the platform team

# Communication Style

- Direct and to the point
- Appreciates technical depth
- Dislikes analogies and metaphors in technical discussions

This USER.md tells the agent that Sarah is highly experienced, prefers Go and Rust, wants concise code-heavy responses, and is currently working on specific projects. The agent can now reference her migration project when suggesting architectural patterns, include error handling by default, and skip beginner-level explanations.

Compare that with a USER.md for a beginning learner:

markdown
# User Profile

- **Name**: Alex Rivera
- **Role**: Computer Science Student (2nd year)
- **Experience**: 6 months of programming
- **Primary Languages**: Python (learning)
- **Editor**: VS Code

# Preferences

- Explain concepts step by step
- Use real-world analogies to clarify abstract ideas
- Always show expected output alongside code examples
- Define technical terms when first introduced

# Current Projects

- Building a todo app with Flask for a class project
- Learning data structures and algorithms

# Communication Style

- Patient and encouraging
- Visual examples help (diagrams, tables)
- Prefers longer, more detailed explanations

The agent reading this USER.md would respond completely differently: slower explanations, more analogies, always showing expected output, and framing everything in the context of Alex's Flask project and CS coursework.

USER.md is typically written by the user themselves or populated by the agent after a few conversations. The agent can suggest updates to USER.md based on observed preferences.

Common Pitfalls

  • Storing sensitive information: Never put passwords, API keys, financial details, or health information in USER.md. It is injected into the model prompt and could appear in logs.
  • Making USER.md too long: A 2000-word USER.md consumes valuable context window tokens. Keep it under 500 words focused on information that actively changes the agent's behavior.
  • Neglecting to update it: As your skills and projects evolve, stale USER.md data causes the agent to give outdated recommendations. Review it monthly.

Best Practices

  • Start with the minimum viable profile: Name, role, experience level, and top 3 preferences. Add more only when the agent's behavior would measurably improve.
  • Let the agent suggest USER.md updates: After productive conversations, ask the agent to propose additions to your profile based on what it learned about your preferences.
  • Separate per-project context from personal traits: Put long-lived preferences in USER.md and project-specific details in the workspace's AGENTS.md or MEMORY.md files.

Summary

  • USER.md stores the user's preferences, expertise level, communication style, and personal context
  • It enables the agent to adapt responses to the specific human it is interacting with
  • Two users with very different experience levels receive appropriately calibrated responses from the same agent
  • Keep it concise (under 500 words) and avoid storing sensitive information
  • Review and update USER.md periodically as your skills and projects evolve
✓ Completed