> ## Documentation Index
> Fetch the complete documentation index at: https://vitruvio.sh/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a brain

> Standalone or inside a project, then one of four recipes, then two checks read separately.

## Standalone, or in a project?

A brain is the unit of *publication*: if somebody might want one subject without the others, those are separate
brains, each publishable, installable and droppable on its own. A **project** is what several brains share — one
actor, one retention policy, one embedder, one registry account — declared in one `vitruvio.toml`, with a
repository per brain derived as `<namespace>/<project>-<brain>`.

Choose **standalone** when there is one subject and you are the one writing. Choose a **project** when there are
several subjects you will publish separately, or several people, or you already know the brain will live beside
others. A standalone brain can join a project later — `project add NAME --path PATH --no-create` registers an
existing layout without touching it — so the cheaper mistake is starting standalone.

Unlike [governance](/docs/onboarding/governed-or-ungoverned), this is a decision vitruvio is happy to see you change.

## The actor, and who assists

Every write is attributed in provenance, so every write needs an actor: a lowercase address (`you@example.com`) or
a lowercase namespaced name (`openai/codex`). Passing `--actor` to `brain init` or `project init` writes it into
`vitruvio.toml`, and from then on it is the actor: a later `--actor` naming somebody else is refused, not obeyed.
Reads never need one.

Decide at the same time which agents will assist writes into the brain, and declare them with the global
`--assisted-by ID` flags on `brain init` or `project add` — one canonical id per agent, `anthropic/claude-code`,
`openai/codex`. They are written under `assisted_by` for that brain and become the only parties a write into it may
record; an agent that is not declared is refused rather than written down. A brain that declares none inherits the
project's `[[assisted_by]]`.

## The retention policy

`brain init --policy` takes a retention profile: `conservative` (the default), `permissive` or `archival`. It decides
which removals the protocol will allow later. Unlike governance, leaving the default is fine when you have no
opinion yet, and [Retention](/docs/brain/retention) is where to form one.

## Text embeddings

Choose whether this brain will use a semantic model or the default deterministic hashing/BOW index. Hashing/BOW
needs no download or key, but matches words rather than synonyms. For a shared project model, declare the canonical
model identity in `[embedding.text]` with `model_id`, plus `provider`, `model`, `revision` and `dims` when required.
The local runtime can be selected after creation without changing that shared declaration:

```bash theme={null}
vitruvio --brain ./brain config embedder use openrouter openai/text-embedding-3-small \
  --model-id openai/text-embedding-3-small --dims 1536 --revision YOUR_REVISION --json
vitruvio --brain ./brain config embedder use hashing bow --json
```

OpenAI, OpenRouter, Ollama, Cohere, Voyage and compatible gateways use the common embeddings transport.
`local-st` loads a Sentence Transformers model into RAM when needed. Keep credentials in environment variables;
the per-brain runtime choice is saved in local XDG state without secrets.

## Four recipes

The governed recipes need a fingerprint from `vitruvio auth keys`; the previous page says what else to have ready.

### Standalone, ungoverned

```bash theme={null}
vitruvio --actor you@example.com brain init ./brain
```

### Standalone, governed

```bash theme={null}
vitruvio --actor you@example.com brain init ./brain \
  --governed --sign-with SHA256:REPLACE_WITH_FINGERPRINT --govern-quorum 1
```

Or `--trust-root root.toml` in place of `--sign-with`, for distinct subjects or scopes.
The command warns when the quorum equals the number of `govern` holders; read it, it is telling you a lost key
would be unrecoverable.

### In a project, ungoverned

```bash theme={null}
mkdir coursework && cd coursework
vitruvio --actor you@example.com project init coursework --namespace docker.io/you
vitruvio --assisted-by anthropic/claude-code project add optics --description "optics notes"
vitruvio project show
```

`project init` writes the `vitruvio.toml` and registers the project's name on this machine, so `--project coursework`
reaches it from any directory afterwards. Start in a fresh directory: if a `vitruvio.toml` already exists above the
working directory, `project init` adds the project to that file instead of creating a new one. `--namespace` is where the brains will publish; leave it out if you do not
know yet, and the account you log in to later is used instead. `project add` creates the layout at
`./brains/optics` and declares it.

### In a project, governed

`project add` on its own always creates an **ungoverned** brain — it has no governance flags. For a governed brain
inside a project, create the genesis with `brain init` and then declare it with `--no-create`:

```bash theme={null}
mkdir coursework && cd coursework
vitruvio --actor you@example.com project init coursework
vitruvio --actor you@example.com brain init ./brains/optics \
  --governed --sign-with SHA256:REPLACE_WITH_FINGERPRINT
vitruvio project add optics --path ./brains/optics --no-create
vitruvio project show
```

Run inside the project directory, `brain init` finds the project's `vitruvio.toml` and writes no second one.

## Check it

```bash theme={null}
vitruvio brain verify          # integrity: every block against every module root
vitruvio auth status           # authenticity: trust root, signatures, pin
vitruvio brain state --json    # what this brain is, and where it came from
vitruvio project show          # in a project: every brain, and where each publishes
```

Read the first two separately. `brain verify` passing says the bytes are intact; `auth status` says whether an
authorized signature supports the head. On an ungoverned brain `auth status` reports exactly that — ungoverned, no
trust root — and that is a description, not a failure. In a project, add `--brain optics` to address one brain.

## Next

[First evidence and search](/docs/onboarding/first-evidence-and-search).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.