DEV Community

Faris Han
Faris Han

Posted on Edited on Originally published at dev.to

Teaching your AI agent who you are: a portable USER.md template

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.md template.
  • GUIDE.md with the format spec, best practices, anti-patterns, and migration paths.
  • WORKSHEET.md to 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
Enter fullscreen mode Exit fullscreen mode

Or grab a pre-built binary from the releases page.

  1. Copy USER.md to your agent's workspace root (or ~/.hermes/memories/USER.md, or ~/.claude/CLAUDE.md global).
  2. Fill in WORKSHEET.md (5 questions) and paste the resulting directives into USER.md.
  3. Keep it under your harness's cap (Hermes: ~1,375 chars; OpenClaw: 4,000 chars).
  4. 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.
Enter fullscreen mode Exit fullscreen mode
  • One directive per entry, imperative voice (Always / Never / Prefer).
  • Record the date the preference was observed, not invented.
  • Status is only active or superseded.
  • 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.md at 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.md or 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:

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)