# Configuration
## Agent homes (lobes)
`learn` links items into every configured agent home (a *lobe*). Each item is
linked under its kind subdirectory: `skills/`, `agents/`, `rules/`. The default
lobe is `~/.claude`. Configure more in `~/.mind/config.toml`:
```toml
lobes = ["~/.claude", "~/.config/some-other-agent"]
```
The file is created with the default lobe (`~/.claude`) on first use. For a single
invocation, set `MIND_AGENT_HOMES` to a `:`-separated path list instead.
**Lobe precedence (STO-14):** `MIND_AGENT_HOMES` wins over `lobes` in
`config.toml`, which wins over the default `~/.claude`. An unknown key in
`config.toml` is a hard error.
Use `mind config lobes add <path>` and `mind config lobes remove <path>` to
manage lobes without hand-editing the file; see [Commands](commands.md) for the
full verb list.
## Absorb destination
`mind absorb` moves an unmanaged item into a version-controlled source you own.
The destination source is resolved from three places, in order -- the first one
set wins:
1. `--to <path>` flag on the command line.
2. `MIND_ABSORB_TO` environment variable.
3. `absorb_to` key in `~/.mind/config.toml`.
When none of the three is set and the run is interactive, `absorb` prompts and
offers `~/.mind/personal` as the default. That directory is created and
`git init`-ed on demand if it does not exist. After an interactive resolution,
`absorb` offers to save the chosen path as `absorb_to` in `config.toml` so
future runs skip the prompt. A `--to` flag, `MIND_ABSORB_TO`, or an existing
`absorb_to` value is used as-is and never triggers a save.
A non-TTY run with no destination configured (none of the three sources set) is
an error; there is no silent default to assume.
Set the persistent default in `~/.mind/config.toml`:
```toml
absorb_to = "~/dev/my-agent-library"
```
`~` is expanded at use. The destination must be a git repository; a path that is
not a git repo is an error.
## SSH cloning
To authenticate with an SSH key instead of an https username/password, meld the
`git@host:owner/repo` form, or set `ssh = true` in `~/.mind/config.toml` so the
`owner/repo` shorthand clones over SSH. An https remote still prompts (or uses a
credential helper) as git normally does.
## Config example
A single `~/.mind/config.toml` may contain any combination of the keys:
```toml
lobes = ["~/.claude", "~/.config/some-other-agent"]
ssh = true
absorb_to = "~/dev/my-agent-library"
```
## Paths
```
~/.mind/
config.toml persistent settings (lobes, ssh, absorb_to)
sources.json source registry (melded repos)
manifest.json installed-item manifest and file registry
sources/<host>/<owner>/<repo> clone of each melded repo
store/<kind>/<name>/ installed copy of each item (name is effective)
personal/ built-in absorb destination, created on demand
.tmp/staging/ scratch for new copies during transactional installs
.tmp/backup/ previous copy held during a swap, for rollback
.lock global advisory lock
```
Override the roots with `MIND_HOME` (the `~/.mind` tree) and `CLAUDE_HOME` (the
default lobe).
## Concurrency
A global advisory lock (`~/.mind/.lock`) is held by every mutating command
(`meld`, `unmeld`, `learn`, `forget`, `sync`, `upgrade`, `introspect --fix`,
`config lobes add|remove`). A second concurrent `mind` invocation blocks until
the first finishes. The lock is released when the holding process exits, even on
crash, so an aborted run never wedges the next one. Read-only commands (`recall`,
`probe`, `introspect`, `config show`) take a shared lock and proceed concurrently
with each other, but never observe a writer mid-update (STO-40..43).
## Install and upgrade are transactional
A failed `learn` or `upgrade` never leaves you worse off. The new copy is built
in a staging directory first; the previous version is moved to a backup and only
dropped after the swap succeeds. A failure at any point restores the previous
version from backup (LIFE-1..4).
A prefix change (adding or removing `--as <prefix>` on a source) causes `upgrade`
to report `rename old -> new` and is handled the same way: the new name is
installed before the old one is removed (LIFE-14). This is normal, not an error.
For diagnosing a failed install or broken links, see
[Troubleshooting](troubleshooting.md).