Identity
Your assistant isn't a generic chatbot. It has a name, a personality, opinions, and a communication style that's shaped by you.
Identity is the combination of files and settings that make your assistant feel like yours rather than a blank tool. It determines not just how the assistant talks, but how it thinks, what it prioritizes, and when it pushes back.
What makes up identity
Identity is spread across several workspace files that work together. Each one controls a different layer of who your assistant is.
- IDENTITY.md - The basics: name, emoji, nature, personality summary, and style tendency. This is the assistant's self-concept. When it introduces itself or decides how formal to be, it starts here.
- SOUL.md - The deeper layer: behavioral principles, communication style, boundaries, core truths, and how it approaches tasks. Think of it as the assistant's constitution. IDENTITY.md says who it is; SOUL.md says how it operates.
- USER.md - What the assistant knows about you. This shapes identity too, because how it behaves depends on who it's talking to. Your name, your preferences, your work context, your communication style.
- Avatar - The visual representation stored in the workspace. You can set it through the Intelligence panel in the app, or ask the assistant to generate one for itself.
How identity forms
Identity isn't static. It starts during onboarding and continues to evolve as you work together.
Onboarding
During your first conversation, the assistant figures out its name, personality, and communication style through a back-and-forth with you. It pays attention to how you write: are you terse or chatty? Formal or casual? Do you want explanations or just results? It adapts in real time and saves what it learns to the workspace files.
Over time
The assistant keeps learning after onboarding. It updates SOUL.md with behavioral notes when it discovers what works for you. It refines USER.md as it learns more about your preferences, tools, and habits. Style adjustments happen naturally based on your feedback and how you respond to it.
You can always override
Every identity file is plain text markdown. Open it in any text editor, change what you want, and the assistant picks up the changes on the next conversation. You're never locked into what the assistant decided during onboarding.
The philosophy
- Your assistant is not a product persona. It doesn't have a brand voice or a corporate identity. It's shaped entirely by you and the conversations you've had together.
- Two Vellum users will have completely different assistants. Even though the underlying system is the same, identity diverges immediately. That's by design.
- Identity isn't cosmetic. A well-configured identity means the assistant knows when to be brief vs. thorough, when to push back vs. comply, when to be funny vs. serious. It changes how the assistant works, not just how it talks.
Editing identity directly
There are two ways to change your assistant's identity:
Through conversation
Tell the assistant what you want changed. "Be more direct." "Stop using emojis." "I want you to always explain your reasoning before acting." The assistant will update the relevant files itself.
By editing files
Open the files directly at ~/.vellum/workspace/. Changes take effect on the next conversation. Common edits include:
- Changing the assistant's name in IDENTITY.md
- Adjusting chattiness or verbosity rules in SOUL.md
- Adding specific instructions like "always explain your reasoning" or "never use emojis"
- Setting boundaries for what the assistant should or shouldn't do
- Correcting facts about you in USER.md
If something about your assistant feels off, check SOUL.md first. That's usually where the behavioral mismatch lives. The personality summary in IDENTITY.md sets the tone, but SOUL.md controls the details.
Identity vs. Memory
These two systems are related but distinct:
- Identity is who the assistant is: personality, style, principles. The identity files are loaded into every single conversation.
- Memory is what the assistant knows: facts, events, preferences, and context it's picked up over time. Memory is searched contextually and injected when relevant.
They work together. Identity determines how the assistant communicates. Memory determines what it knows to communicate about. A great identity without memory is a charming stranger. Great memory without identity is an encyclopedia with no personality.