What it does
| Area | Summary |
|---|
| Memory | Learns what matters and forgets what doesn't. Structured memory items — identity, preferences, projects, events — extracted with source attribution and deduplication. Hybrid retrieval (dense + sparse) ranks results semantically and lexically, with staleness windows per memory type. Per-user and per-channel isolation. Embeddings run locally by default. |
| Identity | Becomes its own. Behavior lives in SOUL.md, and during onboarding the assistant observes how you communicate and writes its own personality files. A per-user journal captures its reflections on past interactions. NOW.md acts as an ephemeral scratchpad for current focus and active threads. |
| Proactivity | Reaches out when something matters, without being asked. Every hour it checks in with itself: re-reads its notes, notices what's unfinished or due soon, and sends a message if needed. Notifications are routed to the right channel and won't interrupt you if you're already talking. |
| Security | Fail-closed by design. Actor identity is resolved once (guardian, trusted, or unknown) and enforced everywhere. Untrusted actors cannot read or write memory, trigger tools, or escalate. Credentials live in a separate process and never reach the model. Every tool runs in a sandbox. |
Get started
1. Download the latest release
2. Open the app and pick your mode
- Managed — sign in via Vellum Cloud, no local runtime required
- Local — everything runs on your machine
3. Hatch your assistant
- Give it a name, a personality, and the keys to your work
Prefer the terminal? See CLI install below.
Quick demo
https://github.com/user-attachments/assets/009bd0ae-95ac-4cf3-81bc-d54cd8631583
CLI
The CLI works but the desktop app is our primary focus. Available for advanced users, contributors, and non-macOS environments.
Install
bun install -g vellum
vellum hatch
Install from source
git clone https://github.com/vellum-ai/vellum-assistant.git
cd vellum-assistant
./setup.sh
vellum hatch
Common commands
vellum wake # start services
vellum sleep # stop services, keep data
vellum client # interact through the terminal
vellum ps # view running assistants
vellum terminal # open a shell into a managed assistant container
vellum upgrade # upgrade to latest version
All commands target the default assistant. If you have multiple, pass the assistant ID as the second argument.
Infra and security
| Area | Summary |
|---|
| Trust engine | Decides who can do what, and defaults to no. Fail-closed trust system that resolves actor identity once (guardian, trusted, or unknown) and enforces it everywhere. Untrusted actors cannot read or write memory, trigger tools, or escalate. Your credentials live in a separate process and never reach the model. |
| Skills | Add new capabilities through sandboxed plugins. Manifest-driven plugins (SKILL.md + TOOLS.json) that inject tools and prompt sections at runtime. Skills can be bundled, installed from a catalog, or added from the workspace. |
| Channels | One assistant, everywhere you need it. Use it from the macOS app, Telegram, or Slack, with shared memory across all of them. More channels coming soon. |
| Multi-provider support | Swap models without changing anything else. Supports Anthropic Claude, OpenAI, Google Gemini, and Ollama for local models. Embeddings follow the same pattern: local ONNX by default, with automatic fallback to cloud providers. |
Foundational documents
The canonical sources for who we are and how we talk about what we're building. The docs site at vellum.ai/docs is a rendered view of these files.
| Doc | What it is |
|---|
| Constitution | Who we are, what we believe, and what we refuse to compromise on |
| Glossary | The shared vocabulary we use to talk about personal intelligence |
Documentation
| Section | What's covered |
|---|
| Architecture | Platform domains, repo structure, runtime · clients · gateway |
| Security & Permissions | Sandbox, credentials, trust rules, permission modes |
| Features & Capabilities | Integrations, dynamic skills, browser, attachments, media embeds |
| API & Communication | SSE event stream, event payloads, remote access |
| Development Workflow | Claude Code commands, parallel PRs, review loops, release pipeline |
📖 Full documentation →
Contributing
We welcome contributions from everyone.
Community
License
MIT — see License. Integration logos from Simple Icons, licensed CC0 1.0.
Vellum Assistant is open-source software built by Vellum AI, a for-profit company. We also offer a managed product, the Vellum Platform, which sustains the business. Free to use and modify under MIT, and we're committed to keeping it that way.
