AI agents are stateless by default. Every session starts from zero unless you give them a stable profile of the human operator: role, preferences, communication style, and constraints.
USER.md is the convention (originating in the OpenClaw workspace) for a small, durable file that holds who the human operator is — separate from the agent's persona (SOUL.md) and from project instructions (AGENTS.md).
I published a portable, harness-agnostic template for it: farishan-labs/user-md (MIT).
What's in the repo
- A clean, ready-to-fill
USER.mdtemplate. -
GUIDE.mdwith the format spec, best practices, anti-patterns, and migration paths. -
WORKSHEET.mdto seed your profile in 5 minutes. - Filled examples for OpenClaw, Hermes, Claude Code (global), and OptMem.
- A standalone validator CLI,
usermd-check.
Quick start
go install github.com/farishan-labs/user-md/checker@latest
Or grab a pre-built binary from the releases page.
- Copy
USER.mdto your agent's workspace root (or~/.hermes/memories/USER.md, or~/.claude/CLAUDE.mdglobal). - Fill in
WORKSHEET.md(5 questions) and paste the resulting directives intoUSER.md. - Keep it under your harness's cap (Hermes: ~1,375 chars; OpenClaw: 4,000 chars).
- Audit monthly.
The three-file split
| File | What it holds | Who writes it |
|---|---|---|
SOUL.md |
Agent's persona, voice, values | You (or the agent, agent-scoped) |
USER.md |
Your profile, preferences, constraints | You (seeded), agent (curated) |
AGENTS.md |
Project instructions, conventions | You / team |
MEMORY.md |
Durable non-profile facts and decisions | Agent |
Rule: SOUL.md and USER.md are separate systems that never feed each other.
Format (OpenClaw canonical)
<!-- observed: YYYY-MM-DD | status: active -->
- Prefer concise progress updates during implementation work.
- One directive per entry, imperative voice (Always / Never / Prefer).
- Record the date the preference was observed, not invented.
- Status is only
activeorsuperseded. - Supersede in place — never append contradictions.
- Keep it compact; it's not a dossier.
See GUIDE.md for the full spec.
Compatibility
Works with any harness that loads a user-profile file or global instructions:
-
OpenClaw —
USER.mdat workspace root (4,000-char budget) -
Hermes Agent —
~/.hermes/memories/USER.md(~1,375 chars) -
Claude Code — global
~/.claude/CLAUDE.md(layered) -
Codex / Copilot / Aider / Cursor — via
AGENTS.mdor global rules - OptMem — as a portable operator-profile note
Why this exists / research backing
This template comes from a survey of how AI agents recognize their human operator across OpenClaw, Hermes, Claude Code, Cursor, Aider, Codex, Continue, Cline, Roo, Windsurf, Goose, and memory frameworks (Letta, Mem0, Zep, Honcho). Full research notes (evidence ledger, 18 sources, ecosystem survey) are maintained privately; the public sources that ground each claim are cited below.
Key findings:
- Three separate problems: identity (who is operating), personalization (preferences), authorization (what the agent may do). Most coding agents solve only ambient identity (OS user / git author) plus project instructions. Sources: CSA NIST AI agent standards note, AgenTag attribution paper.
-
Dominant transferable pattern: the SOUL.md vs USER.md split — the agent's own persona (
SOUL.md) is kept strictly separate from the human's profile (USER.md) and from project instructions (AGENTS.md). OpenClaw docs state they "never feed each other." Sources: OpenClaw SOUL.md guide, OpenClaw memory overview, OpenClaw USER template, Hermes migration from OpenClaw. -
Coding-agent convergence:
AGENTS.mdis the cross-tool constitution, with tool-specific layers (CLAUDE.mdglobal+project,.cursor/rules/*.mdc). Personal preference lives in global instructions, not in project files. Sources: AGENTS.md vs CLAUDE.md vs .cursorrules (automatelab), AGENTS.md vs CLAUDE.md vs .cursorrules (stackitfast), OpenClaw AGENTS.md template. -
Memory ≠ identity: memory systems (Letta, Mem0, Zep, Honcho) recognize users via a stable
user_id(usually from an auth provider) and retrieve scoped memories; they don't replace an identity file. Sources: Letta memory docs, Mem0 memory layer guide, Hermes memory (remoteopenclaw), Mem0 build an agent that remembers users. -
Recommendation: keep the role/identity separation, and add one small, portable operator profile file (this
USER.md) consolidating rules scattered acrossAGENTS.mdfiles, with OptMem as cross-harness memory. Sources: Hermes tips & best practices, Hermes user profiling (Stanza). - Security: keep commit author (agent slot) distinct from push auth (human); never store secrets in identity files. Sources: AgenTag attribution paper, CSA NIST AI agent standards note.
The core claim: agents are stateless by default, and a small, curated, separate profile file is more reliable than stuffing preferences into AGENTS.md or hoping the agent remembers.
Top comments (0)