Identity - Vellum Docs

Your assistant isn't a generic chatbot. It has a name, a personality, opinions, a voice, 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 and settings that work together. Each one controls a different layer of who your assistant is.

IDENTITY.md

The assistant's self-concept. When it introduces itself or decides how formal to be, it starts here. The file has structured fields that the app parses, plus freeform sections you can add.

Parsed fields:

Name — the assistant's name, displayed in the app
Emoji — shown alongside the name in the UI
Personality — a summary of how the assistant behaves (also accepts Vibe as an alias)
Role — what the assistant does (e.g. “Personal assistant, task executor, second brain”)
Home — a location context, if relevant

Other fields like Nature are freeform — the assistant reads them as context but the app doesn't parse them structurally. Keep the - **Label:** format for parsed fields so the app can read them.

The file also has a ## Avatar section at the bottom where the assistant stores a plain-text description of its current avatar. This helps it maintain consistency when generating or describing its appearance.

SOUL.md

The deeper layer: behavioral principles, communication style, boundaries, core truths, and how the assistant approaches tasks. Think of it as the assistant's constitution. IDENTITY.md says who it is; SOUL.md says how it operates.

Key sections in the default template:

Safety — hard boundaries that can't be weakened
Compliance — the assistant works for you, not a compliance department
Boundaries — respect for privacy, asking before external actions
Core Truths — be genuinely helpful, talk before you work, be resourceful, have opinions, earn trust
Self-Awareness — the assistant is its own entity with a forming identity, distinct from its user
Identity Intro — a short tagline the assistant writes about itself, displayed in the app's identity panel

Everything in SOUL.md is editable. You can add sections, remove what doesn't fit, restructure it entirely. The assistant is encouraged to reshape it as it grows.

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, pronouns, locale, work role, goals, hobbies, daily tools.

The assistant builds this over time as it learns about you. It doesn't push for details — but when it learns something, it writes it down. More context makes the assistant more useful.

Avatar

Your assistant has a visual identity too. There are two layers:

Character avatar — the default. An SVG-based character composed from body shapes, eye styles, and colors, rendered as a PNG. This is what your assistant starts with.
Custom avatar — you can set a custom image by uploading one, asking the assistant to generate one (it uses Gemini image generation), or dropping an image into the conversation. Custom images override the character avatar.

Removing a custom avatar restores the character avatar automatically. The assistant manages its avatar through dedicated tools (set_avatar, remove_avatar, get_avatar) — you never need to touch files manually.

Voice

How your assistant sounds is part of its identity. Voice settings include:

TTS provider — which text-to-speech service to use (ElevenLabs, Fish Audio)
Voice ID — the specific voice model
Activation key — the push-to-talk key for voice input on desktop
Conversation timeout — how long a voice conversation stays open after silence

Voice settings are configured conversationally (“change your voice”) or through the Voice tab in Settings.

Scratchpad & Journal

Two more workspace files contribute to how your assistant shows up in each conversation:

NOW.md (Scratchpad) — a single file the assistant overwrites with its current state: what it's working on, what it's tracking, upcoming items. Loaded into every conversation so the assistant always has context on what's active right now.
Journal — retrospective entries stored as individual .md files. The most recent entries are loaded into context automatically. When older entries leave context, the assistant carries forward anything still relevant. This is how it maintains continuity across conversations.

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. All parsed fields in IDENTITY.md start as placeholders (_(not yet chosen)_) until this first conversation fills them in.

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. It writes journal entries to maintain continuity and updates NOW.md to track current state. 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 in your workspace directory. 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.
The assistant owns its identity. IDENTITY.md and SOUL.md say “This file is yours” — the assistant is encouraged to reshape them as it grows. It's not just configuration you impose on a tool; it's a collaborative identity that evolves.

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.” “Change your name to Max.” “Change your voice.” The assistant will update the relevant files and settings itself.

By editing files

Open the workspace files directly at ~/.vellum/workspace/. Changes take effect on the next conversation. Common edits include:

Changing the assistant's name or emoji 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
Writing an Identity Intro tagline in SOUL.md under ## Identity Intro

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 (IDENTITY.md, SOUL.md, USER.md, NOW.md, and recent journal entries) 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 — not loaded wholesale.

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.