HUMAN.md: Teaching AI Agents Who You Are

HUMAN.md is a markdown file that gives an AI agent structured context about you: who you are, how you like to work, what you are working on, and what it should never do. It is the same idea as a project README, pointed at a person instead of a codebase, so that any agent you hand it to starts already knowing your preferences instead of relearning them every session.

The term is new and unsettled. It surfaced as the tagline of an open-source project, Intuition-Lab's personal-model (shipped as a product called Persome), which pitches "Your HUMAN.md" as shorthand for a portable model of a person. The project's own framing is sharp: "two people can give the same AI the same prompt and deserve different answers." A static HUMAN.md file is the simplest way to start delivering on that, and you can write one today.

Key Takeaways:

• HUMAN.md is a personal context file: a README about you, written for AI agents to read before they act.
• It sits alongside two adjacent standards: AGENTS.md describes a project to coding agents, and llms.txt describes a website to LLMs. HUMAN.md describes a person.
• The gap that makes the space interesting: llms.txt is published on 28% of 137,000 domains studied by Ahrefs, yet no major AI provider has committed to reading it. Deployment is not the same as consumption.
• A good HUMAN.md covers identity, preferences, constraints, communication style, and current projects, and stays short enough to fit in a prompt.
• HUMAN.md is a hand-maintained file. Agent memory is the dynamic counterpart that builds the same model from your actual behavior.

---

What Is HUMAN.md?

HUMAN.md is a plain markdown file that answers one question for an AI agent: who is the person I am working for. Instead of you re-explaining your role, your tools, your preferences, and your no-go zones at the start of every conversation, the agent reads the file once and carries that context into the task.

The analogy that makes it click is the README. A project README tells a new contributor what the codebase is, how it is organized, and how to work in it. A HUMAN.md tells a new agent the same things about you.

The personal-model project that popularized the phrase takes it further than a static file, building an evidence-linked model from your Mac activity and serving it to coding agents, but the file itself is the accessible entry point. You do not need a product to write one. You need a text editor and ten minutes.

Be clear about the maturity here, because honesty is the whole value of a definitional article. HUMAN.md is not a ratified standard. There is no spec committee, no required field list, no governance body. It is an emerging convention, closer to a good habit than to a protocol. That is exactly why writing one now is low-cost: you are not betting on a standard, you are giving your agents a better starting prompt.

When Dana, a freelance data analyst juggling ChatGPT, Claude, and a coding agent, got tired of typing "I work in Python, I prefer pandas over polars, never suggest Excel macros" into every new chat, she saved those lines as a HUMAN.md and pasted it as the first message of each session. Nothing sophisticated. Her drafts stopped arriving with the wrong tooling assumptions, and she stopped re-teaching three assistants the same facts about herself.

What this resolved: A working definition. HUMAN.md is a personal README for AI agents, and it is a convention you can adopt unilaterally.

What it left unsolved: No standard governs its shape yet, so the sections are conventions, not requirements.

---

HUMAN.md vs AGENTS.md vs llms.txt

HUMAN.md did not appear in a vacuum. It is the third corner of a pattern that has been forming for two years: give machines a predictable, human-readable file that describes a thing. The other two corners are further along, and comparing them is the fastest way to see where HUMAN.md fits and where the real gap is.

	HUMAN.md	AGENTS.md	llms.txt
Audience	AI agents and assistants	AI coding agents	LLMs reading a website
Describes	A person (you)	A software project	A website
Where it lives	Handed to the agent (file or personal-model tool)	Root of the repository	/llms.txt at the site root
Governance	None yet; emerging convention	Stewarded by the Agentic AI Foundation under the Linux Foundation	Proposed by Jeremy Howard / Answer.AI
Deployment	Experimental, near-zero	Over 60,000 open-source projects	28% of 137,000 domains studied
Actually read?	Emerging; depends on the agent	Yes, by mainstream coding agents	No major provider has committed to reading it

The last two rows are the ones worth staring at. AGENTS.md works because the agents that matter actually read it: it is "a README for agents," now used by over 60,000 open-source projects and stewarded by the Agentic AI Foundation under the Linux Foundation. Deployment and consumption line up.

llms.txt is the cautionary column. Ahrefs studied 137,000 domains and found 28% publish an llms.txt file, which sounds like momentum until you read the next finding: no major LLM provider has committed to parsing it, and 97% of those files received zero requests in the month studied. Sites did the work. The machines never showed up to read it.

That gap is the sharpest lesson for HUMAN.md. A personal context file is only worth maintaining if something consumes it. The bet that makes HUMAN.md different from llms.txt is that you control both ends: you write the file and you paste it into the agent yourself, so consumption is guaranteed by you, not by a vendor's roadmap. The moment HUMAN.md depends on platforms voluntarily reading a file at a fixed location, it inherits llms.txt's problem.

What this resolved: HUMAN.md is the person-shaped member of a three-file pattern. AGENTS.md proves the pattern works when agents read the file; llms.txt shows what happens when they do not.

What it left unsolved: HUMAN.md has no consumption guarantee at the platform level, so its value today depends on you feeding it to the agent yourself.

---

How to Write Your HUMAN.md (With Template)

Since no committee has published a required structure, here is a practical template that covers what agents actually need. Treat this as a starting proposal, not a spec, and cut anything that does not earn its place in your context window.

# HUMAN.md

## Identity
- Name and what I do: Ana Reyes, product manager at a B2B fintech.
- Domain: payments, compliance, and onboarding flows.
- Timezone and working hours: CET, 9-18.

## Preferences
- Answer format: lead with the recommendation, then the reasoning.
- Tooling: Figma, Linear, Notion. Never suggest Jira.
- Writing: plain English, no marketing adjectives, tables over paragraphs for comparisons.

## Constraints
- Never share customer data or internal metrics in external drafts.
- Do not auto-send anything. Draft, and I send.
- Regulated industry: flag anything that touches compliance for review.

## Communication style
- Direct. Skip the preamble. Correct me when I am wrong.
- I prefer being asked one sharp clarifying question over a wrong assumption.

## Current projects
- Q3: redesigning the merchant onboarding funnel.
- Ongoing: monthly competitive teardown of three named rivals.

Six things separate a HUMAN.md that helps from one that just adds tokens:

• Do lead with constraints. The "never do X" lines are the highest-value part. An agent that knows your no-go zones is safer than one that only knows your preferences.
• Do be specific. "I prefer pandas over polars" beats "I like clean code." Agents act on concrete instructions, not vibes.
• Do keep it short. Every line competes for context. If a section is not changing the agent's behavior, delete it.
• Don't write your life story. This is not a bio. It is an operating manual for working with you.
• Don't let it rot. A HUMAN.md that lists last quarter's project is worse than none, because it points the agent at stale context.
• Don't include secrets. Anything you would not paste into a chat window does not belong in a file you paste into a chat window.

Ravi, a founder running a two-person startup, keeps his HUMAN.md to 22 lines and updates the "current projects" section every Monday. He says the single most useful line is "do not auto-send anything, draft and I send," because it turned an agent that once fired off a half-finished investor email into one that reliably waits.

What this resolved: A copyable template and a rule set. Constraints first, be specific, stay short, keep it current.

What it left unsolved: A hand-maintained file is a snapshot. It cannot notice that your preferences changed unless you edit it.

---

Why AI Agents Need a Personal Model

The deeper reason HUMAN.md matters is alignment at the individual level. Most model alignment work is about making a model behave well for everyone. Personalization is the opposite problem: making an agent behave well for you specifically, given that the right answer genuinely differs from person to person.

The personal-model project states the case cleanly: two people giving the same AI the same prompt "deserve different answers." A senior engineer asking "how should I set up auth" wants a different depth of answer than a first-time founder asking the identical words. Without a model of who is asking, the agent has to guess, and it usually guesses toward a bland middle.

A HUMAN.md is the static, portable form of that personal model. You author it, you own it, and you can carry it to any agent. The tradeoff is that it is only as current as your last edit. The dynamic form is agent memory: instead of you describing your preferences, the agent infers them from what you actually do over time. The personal-model project builds exactly this kind of evidence-linked model, layering observations into patterns. A static file and runtime memory are not competitors. The file is the cold-start, the seed of context an agent has before it has watched you work. Memory is what refines it afterward.

What this resolved: Personalization is per-person alignment, and a HUMAN.md is its portable static form.

What it left unsolved: A file cannot keep up with a changing you. That job belongs to memory.

---

How MoClaw Learns Your Preferences

MoClaw sits on the memory side of that line. Where a HUMAN.md is a file you maintain by hand, MoClaw builds the equivalent model from your interactions, so the preferences you would have written down get learned instead.

The concrete version: the first time you tell MoClaw you want comparison tables instead of prose, or that a certain report should always go to a specific channel, that is not just applied once. It persists. The next task that involves a comparison arrives as a table without you re-asking. Over a few weeks, the accumulation of these small corrections becomes a working model of how you like output shaped, which is the same content a HUMAN.md holds, except you never had to write or update the file.

The honest boundary: a learned model and a hand-written file each have a failure mode. A file can be precise and wrong, because it says what you think you prefer rather than what you actually accept. Memory can be accurate but slow, because it needs enough interactions to infer a pattern. The strongest setup uses both: seed an agent with an explicit statement of your hard constraints, the things you cannot afford it to learn by trial and error, and let memory handle the softer preferences that reveal themselves over time. You can see how persistent preferences play out across tasks in MoClaw's use case library.

What this resolved: MoClaw is the dynamic counterpart to HUMAN.md, learning preferences from behavior instead of a maintained file.

What it left unsolved: Learned memory needs time and data. For hard constraints you want enforced from message one, an explicit statement still wins.

---

FAQ

What is a HUMAN.md file?

A HUMAN.md file is a markdown document that gives AI agents structured context about a person: their identity, preferences, constraints, communication style, and current work. It functions like a README written about you instead of a project, so agents start a task already knowing how you want to be worked with.

What is the difference between HUMAN.md and AGENTS.md?

They describe different subjects. AGENTS.md describes a software project to AI coding agents and lives at a repository root, where it is read by mainstream coding tools. HUMAN.md describes a person to any assistant. AGENTS.md is an established convention used by tens of thousands of projects; HUMAN.md is newer and not yet standardized.

Do AI tools support HUMAN.md?

Honestly, support is emerging, not standardized. No major platform automatically looks for a HUMAN.md file the way coding agents look for AGENTS.md. Its value today comes from you feeding it to the agent yourself, as a first message or a project instruction, which guarantees the file actually gets read.

How long should a HUMAN.md be?

Short enough to fit comfortably in a prompt, usually 15 to 40 lines. Every line competes for the agent's context window, so include only details that change its behavior. Lead with hard constraints, keep preferences specific, and delete anything stale rather than letting the file grow.

---

Where the Personal Context File Goes Next

The file-that-describes-a-thing pattern is clearly durable. AGENTS.md proved it works when agents actually read the file, and HUMAN.md extends it from projects to people. The open question is not whether personal context helps an agent, which is obvious the first time you use one, but whether HUMAN.md converges on a shape that platforms read automatically, or stays a private habit you paste in yourself.

The pragmatic path does not require that answer. Write a HUMAN.md this week because it improves every agent you already use, keep it short and current, and lead with the constraints you cannot afford an agent to learn the hard way. Then let runtime memory, in MoClaw or any tool that offers it, refine the softer preferences over time. The static file is your cold-start, memory is the follow-through, and together they are how an agent stops treating you like the average user and starts treating you like you.