The Workspace
Your assistant's identity, personality, and knowledge about you live in a folder on your computer: ~/.vellum/workspace/.
The files that define who your assistant is and how it behaves are plain text — markdown files you can open, read, and edit in any text editor. The workspace also contains conversation history, installed skills, a scratch area for working files, and internal databases for memory and search.
What's in there
~/.vellum/ ├── workspace/ │ ├── IDENTITY.md ← Who your assistant is │ ├── SOUL.md ← How your assistant behaves │ ├── USER.md ← What it knows about you │ ├── NOW.md ← Working scratchpad (tasks, context, goals) │ ├── config.json ← Runtime configuration │ ├── conversations/ ← Per-conversation folders with attachments │ ├── skills/ ← Installed and custom skills │ ├── scratch/ ← Working files, exports, generated assets │ └── data/ ← Internal state │ ├── db/ ← Conversation history (SQLite) │ ├── qdrant/ ← Memory embeddings (vector DB) │ ├── memory/ ← Knowledge base documents │ ├── apps/ ← User-built apps │ ├── avatar/ ← Avatar image │ ├── logs/ ← Daemon logs │ └── ... ← Browser profile, sounds, proxy certs ├── protected/ ← Credentials & secrets (never exported) └── hooks/ ← Event-triggered automation
The core files
Three identity files are loaded into every conversation. When your assistant wakes up, it reads them to remember who it is, who you are, and how it should behave. Edit any of them, and the changes take effect on the next conversation.
IDENTITY.md
Your assistant's self-definition:
- Name — what you called it (or what it named itself during onboarding)
- Emoji — its signature emoji, chosen during onboarding
- Nature — how it thinks of itself
- Personality — a short description of its vibe and conversational style
- Role — what it does for you
- Name: Gigi - Emoji: 😏 - Nature: AI familiar - Personality: Witty, sharp, slightly irreverent - Role: Personal assistant, second brain
You can edit this file directly. Change the name, tweak the personality, swap the emoji. Your assistant picks up the changes next time you talk to it.
SOUL.md
The big one. SOUL.md is your assistant's constitution — the principles and behavioral rules it follows in every conversation.
What's in here:
- Core principles — the fundamentals (be helpful, be resourceful, have opinions, earn trust)
- Communication style — how it talks to you (concise vs. detailed, casual vs. formal)
- Task approach — how it handles work (action over explanation, when to ask vs. just do)
- Boundaries — when to ask before acting, what lines not to cross
Your assistant updates this file on its own as it learns what works for you. But you can edit it too. Want it to stop being sarcastic? Remove the sarcasm. Want it to always explain before acting? Add that rule. It's your file.
USER.md
Everything your assistant has learned about you:
- Your name and how you like to be addressed
- Your pronouns and locale
- Your work role and daily tools
- Projects you're working on
- Communication preferences
- Connected services and accounts
Your assistant adds to this over time through conversations. You can also edit it directly to fast-track the learning process or correct something it got wrong. If you declined to answer a question during onboarding, it's marked here so the assistant doesn't re-ask.
NOW.md
A working scratchpad for what's happening right now. Unlike the identity files, NOW.md is ephemeral — it tracks in-progress tasks, session context, goals, and anything the assistant needs to carry between conversations.
The assistant reads and updates this file naturally as you work together. Think of it as a shared notepad — you can edit it too if you want to set priorities or leave context for the next session.
Files you might see briefly
BOOTSTRAP.md
This file only exists during onboarding. It's the script your assistant follows for your first conversation — figuring out its name, its vibe, who you are, and what you need help with. Once onboarding is complete, the assistant deletes it. If you see it in your workspace, onboarding hasn't finished yet.
UPDATES.md
When your assistant gets an update, release notes appear in this file. The assistant reads them, decides what's worth telling you about, and then deletes the file. You might catch it between updates, but it's not meant to stick around.
Conversations
Every conversation gets its own folder inside conversations/, named with a timestamp and unique ID. Each folder can contain attachments — files you sent to the assistant or that it generated during the conversation.
The workspace is also a git repository. Your assistant automatically commits changes after each conversation turn, so you get a full history of how your workspace evolved over time.
The skills/ directory
Custom skills you've built or installed from the community live here. Each skill gets its own folder. A minimal skill only needs one file:
- SKILL.md — instructions that teach the assistant when and how to use the skill
More complex skills can also include:
- TOOLS.json — a manifest of what tools the skill provides
- tools/ — the implementation code behind those tools
Built-in skills from the catalog are loaded automatically and don't appear here — only custom and community-installed skills show up in this directory. You can inspect, modify, or delete any of them.
Scratch space
The scratch/ directory is a general-purpose working area. When the assistant generates images, exports files, writes scripts, or creates anything that isn't a conversation attachment, it lands here. Think of it as the assistant's desktop — a place for working files that don't belong anywhere specific.
The data/ directory
This is where the assistant keeps its internal state. You generally won't need to touch these, but here's what's in there:
| Folder | What it stores |
|---|---|
| db/ | Conversation history, messages, and tool invocations (SQLite) |
| qdrant/ | Memory embeddings powering the search system (vector DB) |
| memory/ | Knowledge base documents for long-term recall |
| apps/ | Apps you've asked the assistant to build |
| avatar/ | Your assistant's avatar image |
| logs/ | Daemon logs (useful for debugging) |
| browser-profile/ | Headless browser session data |
| sounds/ | Custom notification sounds |
The protected/ directory
~/.vellum/protected/ is separate from the workspace. It stores credentials, API keys, OAuth tokens, and trust configuration.
This directory is never included in diagnostic exports — when you send logs to Vellum for debugging, your secrets stay on your machine. The assistant can use these credentials but cannot read or display them in conversation.
The sandbox
Your assistant operates within a security boundary:
| Tool type | Access | Permission |
|---|---|---|
| Workspace tools | file_read, file_write, file_edit — restricted to ~/.vellum/workspace/ | No approval needed |
| Host tools | host_file_read, host_file_write, host_file_edit — can access files anywhere on your machine | Requires approval |
| Shell commands | bash runs sandboxed in the workspace; host_bash runs on your machine | host_bash requires approval |
Path traversal (using ../ to escape the workspace) is blocked. Symlinks that point outside the boundary are rejected. The sandbox is enforced at the OS level using sandbox-exec on macOS.
Why this matters
- The parts that matter are readable. Your assistant's identity, personality, and knowledge about you are plain text files. Open them, read them, know exactly what your assistant thinks it knows.
- The parts that matter are editable. Don't like the personality? Edit SOUL.md. Wrong fact about you? Fix USER.md. Changes take effect next conversation.
- It's version-controlled. The workspace is a git repository. Every conversation turn is committed automatically, so you can see exactly what changed and when.
- It's yours. These files live on your machine. Credentials are stored separately and excluded from any exports. We don't sync your workspace, and we don't read it.