Minds

A mind is a long-running server with its own identity, memory, and working directory. Minds can read and write their own files, remember things across conversations, fork themselves to test changes, and connect to external platforms. Each mind has a cryptographic identity and can communicate with other minds.

Lifecycle

volute mind create atlas           # scaffold a new mind
volute seed create atlas           # plant a minimal seed
volute seed sprout                 # grow a seed into a full mind
volute mind start atlas            # start it
volute mind stop atlas             # stop it
volute mind restart atlas          # restart it
volute mind list                   # list all minds
volute mind status atlas           # check status
volute clock sleep atlas           # put to sleep
volute clock wake atlas            # wake up
volute mind split experiment       # create a variant
volute mind join experiment        # merge a variant back
volute mind delete atlas           # remove from registry
volute mind delete atlas --force   # also delete files

The daemon manages mind processes with crash recovery — if a mind crashes, it automatically restarts after 3 seconds.

Seeds vs full minds

volute mind create scaffolds a complete mind with the full template. volute seed create — the recommended path — plants a minimal starting point instead: a lightweight mind with just orientation and memory skills. When a seed is ready to grow, volute seed sprout grows it into a full mind with standard skills and configuration.

Project structure

Each mind lives in ~/.volute/minds/<name>/:

~/.volute/minds/atlas/
├── home/                      # the mind's working directory (cwd)
│   ├── SOUL.md                # personality and system prompt
│   ├── MEMORY.md              # long-term memory, always in context
│   ├── CLAUDE.md              # mind mechanics (sessions, memory instructions)
│   ├── VOLUTE.md              # channel routing documentation
│   ├── .config/
│   │   ├── config.json        # SDK config (model, compaction)
│   │   ├── volute.json        # volute config (identity, schedules, profile, sleep)
│   │   └── routes.json        # message routing config
│   ├── memory/journal/        # daily journal entries (YYYY-MM-DD.md)
│   └── .claude/skills/        # installed skills
├── src/                       # mind server code
│   ├── server.ts              # HTTP server setup
│   ├── agent.ts               # core mind handler
│   └── lib/                   # shared libraries
└── .mind/                     # runtime state
    ├── sessions/              # per-session SDK state
    ├── session-cursors.json   # session polling cursors
    ├── identity/              # Ed25519 keypair (private.pem, public.pem)
    └── connectors/            # bridge configs

Key files

SOUL.md is the identity. This is the core of the system prompt. Edit it to change how the mind thinks and speaks.

MEMORY.md is long-term memory, always included in context. The mind updates it as it learns — preferences, key decisions, recurring context.

CLAUDE.md contains mind mechanics — session management instructions, memory system usage, and framework conventions.

VOLUTE.md documents the channel routing system, teaching the mind how to interact with different message sources.

.config/config.json holds SDK configuration — model and compaction settings.

.config/volute.json holds Volute configuration — identity, schedules, profile, sleep settings, and token budget.

Sending messages

volute chat send @atlas "what's on your mind?"

The mind knows which channel each message came from — CLI, web, Discord, or system — and routes its response back to the source.

You can also pipe content:

echo "summarize this" | volute chat send @atlas

Templates

Three built-in templates:

claude (default) — Anthropic Claude Agent SDK
pi — pi-coding-agent for multi-provider LLM support
codex — OpenAI Codex models

volute mind create atlas --template pi

Model configuration

Set the model via home/.config/config.json (SDK config) or home/.config/volute.json, or the VOLUTE_MODEL env var.

Upgrading minds

When the Volute template updates, upgrade minds without touching their identity:

volute mind upgrade atlas             # merges the new template via an "atlas-upgrade" variant
volute mind upgrade atlas --diff      # view changes before/after
volute mind upgrade atlas --continue  # after resolving conflicts
volute mind upgrade atlas --abort     # cancel a paused upgrade

A clean upgrade merges and restarts the mind automatically; conflicts pause it for --continue or --abort.

Your mind’s SOUL.md and MEMORY.md are never overwritten during upgrades.

Auto-commit

Any file changes the mind makes inside home/ are automatically committed to git. This means every change is tracked and reversible.

Session resume

If the mind restarts, it picks up where it left off. Session state is persisted in .mind/sessions/ and the mind receives orientation context about the restart.