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. Alongside those, the workspace also contains databases for conversation history and memory, installed skills, and a sandboxed area where the assistant can read and write files on your behalf.
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 │ ├── BOOTSTRAP.md ← First-run onboarding (deleted after setup) │ ├── UPDATES.md ← Release notes (deleted after read) │ ├── config.json ← Runtime configuration │ ├── skills/ ← Installed and custom skills │ ├── hooks/ ← Event-triggered automation │ └── data/ ← Databases, logs, memory, apps │ ├── db/ ← Conversation history (SQLite) │ ├── qdrant/ ← Memory embeddings (vector DB) │ ├── memory/ ← Knowledge base documents │ ├── apps/ ← User-defined apps │ ├── logs/ ← Daemon logs │ └── avatar/ ← Avatar image ├── protected/ ← Credentials & secrets (never exported) └── hooks/ ← Global automation hooks
The core files
These three 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)
- Nature — how it thinks of itself
- Personality — a short description of its vibe and conversational style
- Emoji — its signature emoji, chosen during onboarding
- Appearance — avatar description and style tendency
- Name: Gigi - Nature: AI familiar - Personality: Witty, sharp, slightly irreverent - Emoji: 😏 - Style tendency: concise, opinionated
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)
- Personality traits — detailed communication style and energy level
- Preferences — how it approaches tasks (brevity over bloat, action over explanation)
- 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
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.
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.
The skills/ directory
Each skill gets its own folder containing:
- SKILL.md — instructions that teach the assistant when and how to use the skill
- TOOLS.json — a manifest of what tools the skill provides
- tools/ — the implementation code behind those tools
Built-in skills from the catalog live here alongside any custom skills you've built. You can inspect, modify, or delete any of them.
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:
- db/ — a SQLite database storing conversation history, messages, and tool invocations
- qdrant/ — a vector database powering the memory search system
- memory/ — knowledge base documents for long-term recall
- apps/ — definitions and records for any apps you've asked the assistant to build
- logs/ — daemon logs (useful for debugging)
The protected/ directory
~/.vellum/protected/ is separate from the workspace. It stores credentials, API keys, and OAuth tokens. This directory is never included in diagnostic exports — when you send logs to Vellum for debugging, your secrets stay on your machine.
The sandbox
Your assistant operates within a security boundary. Here's how it works:
- Workspace tools (file_read, file_write, file_edit) are restricted to
~/.vellum/workspace/. The assistant can freely create, read, and edit files within this boundary — no approval needed. - Host tools (host_file_read, host_file_write, host_file_edit) can access files anywhere on your machine, but they require your permission each time.
- Bash works the same way: sandboxed commands run within the workspace, host commands need 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 — sandbox-exec on macOS, bubblewrap on Linux.
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 portable. The workspace is a directory. Copy it, zip it, put it in git. The CLI's retire command will archive it as a tarball for you.
- 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.