> ## 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.

# Selecting a brain

> By name, by project, from anywhere: the resolution order, and why there is no machine-wide active brain.

Two questions, in this order, because a brain name means nothing until it is known whose vocabulary it belongs to.

**Which project** — a `vitruvio.toml`. First one wins:

1. `--config FILE` — that file, verbatim.
2. `--project NAME` — by name, from anywhere. Registered by `project init` or `project register`.
3. `$VITRUVIO_CONFIG` or `$VITRUVIO_PROJECT` — the same two answers, from the environment.
4. The nearest `vitruvio.toml`, walking up from the working directory.

**Which brain**, inside that project:

1. `--brain NAME` — a brain the project declares — or `--brain PATH`.
2. `$VITRUVIO_BRAIN` — how a container, a CI job, or one agent's session says it without editing files.
3. `[brain].path` in the project file.
4. The project's only brain, when it holds exactly one.
5. What `vitruvio brain use` last recorded **for this project**.

The file layers resolve a relative path **against the file's directory**, never against the working directory: a
config that means a different brain depending on which subdirectory you happened to be in is not a reproducibility
artifact.

One extra rule worth knowing: when `--brain` names a brain outside the current tree and the walk-up finds nothing, the
walk restarts *beside the brain*. Without it, the `vitruvio.toml` that `brain init` had just written would be ignored
by the very next command.

## Selecting a brain by name

```console theme={null}
vitruvio --brain optics ingest run notes.md
vitruvio --brain optics search "what is refraction"
```

The name is tried before the path, so a stray `./optics` directory cannot shadow the project member. Working on the
wrong brain in silence is the failure that ordering exists to prevent.

`$VITRUVIO_BRAIN=optics` works the same way, which is how a container or a CI job picks a subject without editing a
file. A project holding exactly one brain needs no flag at all.

## Selecting the project too, from anywhere

`project init` registers the project's name on this machine, so `--project` reaches it from any directory:

```console theme={null}
vitruvio --project coursework --brain mechanics search "conservation of momentum"
vitruvio --project benchmarks --brain metric-a search "selection bias"
```

Those two commands share no mutable state, so they can run **at the same time, in different terminals**. That is the
point: one invocation states its whole context — project and brain — and nothing about it depends on the working
directory or on anything another terminal did. Three agents, three projects, three subjects.

`$VITRUVIO_PROJECT=coursework` is the same answer from a shell profile or a container, and pairs with
`$VITRUVIO_BRAIN=mechanics`. Exporting both once is how one agent's session pins itself to one subject.

Managing the registry:

```console theme={null}
vitruvio project list                 # every project --project accepts, and their brains
vitruvio project register             # make the project in this directory addressable (for a clone)
vitruvio project forget benchmarks    # drop the name; touches no files at all
```

It is a registry of **names**: every entry is a path to a committed `vitruvio.toml`, and everything about a project is
still read from there. Nothing is configured in it, so losing it costs the `--project` shorthand and nothing else.

## There is no "active brain"

`vitruvio brain use` still exists, and it is now scoped to **one project**:

```console theme={null}
vitruvio --project coursework brain use mechanics
vitruvio --project coursework search "..."            # that brain, by default
vitruvio --project benchmarks search "..."            # still asks: metric-a or metric-b?
```

A choice made in `coursework` reaches no other project. This used to be a single machine-wide pointer, which had two
problems: two terminals could not disagree about which brain they were on, and worse, a pointer left behind in one
project answered for a *different* project whose brains were all addressed by name — a write into the wrong subject,
in silence, with no undo.

So it is a per-project convenience for a shell, and nothing more. In a script or an agent, pass `--project` and
`--brain`: they are the only layers that survive being read by somebody else.

A project that declares brains therefore asks by name instead of guessing:

```
error: this project holds 2 brains and none was selected
hint: pass --brain with one of: optics, acoustics-ii
```


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