IDENTITY.md is the quick reference card for who your agent is: the name, creature type, vibe, emoji, and the compact summary that tells a human everything they need in a few seconds. It is a small file with an outsize effect, because identity is the anchor the rest of the setup hangs on. This guide explains what it holds, how it fits with the other workspace files, and the mistakes that quietly keep agents generic.
What IDENTITY.md is for
Every agent workspace can carry a small file at its root named IDENTITY.md. It answers one question: who is this assistant? The answer is short on purpose. Name first, then a one-line role, a handful of traits, and a mental model for how it behaves. The best version reads like a label that fits, not a manifesto.
The file does real work even though it is tiny. A named agent is easier to direct, because you have a stable reference point instead of a random interface. It is easier to remember, for both the human and the system. And it is easier to keep consistent over time: once the name, vibe, and role are stable, every other setting has something to hang onto.
What the file contains
Each field earns its place by being parseable and stable. The name is what everyone calls the agent. The creature line says what kind of thing it is: an AI, a robot, a familiar, a ghost in the machine. The vibe is the plain-language personality summary, sharp or warm or chaotic or calm. The emoji is the signature that shows up across interfaces, and the avatar is an image reference, a workspace-relative path, an HTTP URL, or a data URI. Placeholders in the template are ignored until you fill them, so the file works even half-complete, which is exactly how the bootstrap default survives.
The identity stack: four files, four jobs
IDENTITY.md does not work alone. It is one of four small files that define an agent, and the division of labor matters:
- IDENTITY.md: the summary card. Who this is, at a glance.
- SOUL.md: the full personality. How the agent thinks and acts in detail, its mission and voice.
- AGENTS.md: the operating rules. Workflow, red lines, memory habits, group behavior.
- MEMORY.md: the long-term memory. Durable facts and preferences that carry across sessions.
The diagram shows how the four divide the work:
Use both identity files because they serve different jobs. SOUL.md explains how the agent thinks; IDENTITY.md gives the compact summary that anchors everything else. Together with the rules in AGENTS.md and the memory in MEMORY.md, they are four views of the same assistant, and the system works best when all four agree.
Identity shows up in the agent registry
Identity is not just a file; it surfaces in the operational view of the system. On the host behind this site, the main agent is named Jarvis, and that name comes straight from its IDENTITY.md:
Notice what the registry line carries: the name and a pointer to the identity file. The identity fields feed into this view, which is one reason keeping the file accurate matters beyond aesthetics. If the summary says one thing and the personality file says another, the muddiness shows up everywhere the agent appears.
Identity is also meant to stay in sync with the agent’s configuration. The Theme, Creature, and Vibe fields feed the effective identity value when tooling syncs the file into agent config, and they are read in a specific order: Theme wins if set, then Creature, then Vibe. When that sync runs, the Name, Theme, Emoji, and Avatar are written back into the file, which means the file and the registry can drift apart if you edit one side by hand. If your agent’s name changes in one place and not the other, the file is the source of truth to fix first.
A filled example
A complete example makes the format concrete. The agent behind this site runs on an identity close to this:
That combination, name, creature, vibe, and emoji, tells you a lot in very little space. The test for your own file is the same: can a human read it in five seconds and know what kind of assistant they are dealing with?
Why does any of this matter for how the agent actually performs? Identity sets expectations on both sides of the conversation. A human who knows the agent has a name and a defined role directs it more specifically, and the agent, operating inside a consistent self-description, answers more consistently. The effect compounds across a long setup: identity is the frame that makes the rules in AGENTS.md and the personality in SOUL.md land as one coherent assistant instead of a pile of settings.
Common mistakes
Four mistakes account for most weak identity files. The biggest is leaving the bootstrap default in place forever; it works as a placeholder, not a finished identity, and a placeholder identity keeps the whole system feeling generic. The second is making the identity too broad or too clever to be useful; vague vibes produce vague behavior. The third is misalignment: the summary card and the personality file should feel like two views of the same assistant, not two different systems. The fourth is overstuffing. IDENTITY.md is a summary, and when it stops being short, it stops being read.
Quick tips
- Keep the name short and memorable.
- Describe the vibe in plain language, not poetry.
- Make the summary consistent with SOUL.md and AGENTS.md.
- Use identity to reinforce the role, not decorate it.
- Do not overstuff the file; sharp beats sprawling.
IDENTITY.md is part of the workspace file family, and the sibling guide to its closest relative is MEMORY.md explained. For the full platform picture, The Complete OpenClaw Guide covers how the workspace files fit into the whole setup.
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
I didnt expect the name to matter this much but honestly it makes the agent feel more real, maybe too real lol.
Naming helps because it gives the agent a stable identity anchor. Even a simple name can improve consistency in tone and reduce generic responses.
What is really the difference between IDENTITY.md and SOUL.md, they seem pretty close from the outside.
Good question. SOUL.md is about how the agent behaves, while IDENTITY.md is about who it is. One sets style and mission, the other sets the core persona and name.
So does the actual name matter or can it just be a fun label, I might call mine something weird if it still works.
A fun label is totally fine if it is memorable and consistent. The important part is that the name supports the persona and helps the system stay anchored across sessions.
I did not think the name itself would matter, but it really does make the agent feel less generic.
Exactly, a stable name gives the system something concrete to anchor around. Even simple identity cues can improve consistency.
So IDENTITY.md is more about the core persona and SOUL.md is more about how it talks and acts, right?
Yep, that is the clean split. Identity is who it is, soul is how it shows up.
I might give mine a weird name just for fun if it still stays consistent, kind of like naming a character in a game.
That works fine as long as the name stays stable. Consistency matters more than sounding serious.