Your Assistant's Identity
One of the things that makes Vellum different is that your assistant isn't a faceless tool. It has an identity. A name, a personality, a look, an email address, even its own online accounts. This section explains the files that define who your assistant is and how to shape them.
IDENTITY.md — The basics
This file holds the fundamentals:
- Name — Whatever you named it during onboarding
- Role — How it describes its job (“personal AI assistant,” “creative partner,” etc.)
- Personality — A brief summary of its vibe
- Emoji — Its signature emoji, chosen based on its personality
Your assistant picked these during your very first conversation. You can change any of them at any time, either by editing the file or just telling your assistant:
“I want to rename you to Atlas.”
“Change your emoji to 🦊.”
SOUL.md — The personality engine
If IDENTITY.md is the birth certificate, SOUL.md is the personality. This is the file that determines how your assistant communicates, makes decisions, and behaves.
It includes:
- Core principles — The non-negotiable rules (be genuinely helpful, earn trust, have opinions)
- Personality section — Detailed traits. Is it sarcastic? Warm? Formal? All of the above?
- Quirks — Little behavioral details that give it character (“Will roast you affectionately when the opportunity presents itself”)
- Preferences — Communication style (brevity vs. depth, action vs. explanation)
- Boundaries — Rules your assistant will not break (privacy, not sending messages without permission)
Your assistant evolves this file over time. If it notices you prefer shorter responses, it might add that to its preferences. If you correct its tone, it updates accordingly. But you always have the final say. Open the file, read it, edit it.
💡 Fun experiment: Read your SOUL.md after a week of using your assistant. You'll see a personality profile that's been shaped by your interactions. It's like a mirror of how you communicate, reflected back through your assistant's voice.
LOOKS.md — The wardrobe
Your assistant has a visual avatar, and you control how it looks:
- Body color — violet, emerald, rose, amber, indigo, slate, cyan, blue, green, red, orange, pink
- Cheeks — The blush color
- Hat — top hat, crown, cap, beanie, wizard hat, cowboy hat, or none
- Shirt — t-shirt, suit, hoodie, tank top, sweater, or none
- Accessory — sunglasses, monocle, bowtie, necklace, scarf, cape, or none
- Held item — sword, staff, shield, balloon, or none
Mix and match. Give it a cowboy hat and a monocle. Put it in a hoodie with a sword. Express yourself. Or tell your assistant:
“Put on something fancy.”
“Make yourself look like a wizard.”
It'll update LOOKS.md and you'll see the change immediately.
USER.md — The file about you
This one isn't about your assistant's identity. It's about yours. USER.md is where your assistant stores everything it's learned about you:
- Your name and preferred name
- Your location
- Your communication style preferences
- Projects you're working on
- Things you've told it about yourself
- Patterns it's noticed
Your assistant adds to this over time. You can also add things directly. If you want your assistant to know something about you without having to mention it in conversation, just put it in USER.md.
The "not you" principle in action
Your assistant's identity is deliberately separate from yours. It has:
- Its own email address — Through AgentMail, not your personal email
- Its own accounts — It can create and manage its own GitHub, its own online presence
- Its own personality — Defined in its files, not inherited from you
When your assistant acts in the world (sending an email, posting somewhere, interacting with a service), it acts as itself. Not as you. Recipients know they're interacting with your assistant. This is the "not you" principle: it works for you, but it doesn't pretend to be you.