Brains and sources

What a brain is, what a source is, and how the two fit together.

A brain is one database. A source is one folder of notes (a git repo) inside that brain. A mount is a second brain you connect alongside your own. This guide explains how the three fit together, then walks through adding a source, syncing it, choosing which source a command uses, and connecting another brain.

Use it when you want to keep several collections of notes in one brain, or when you want your agent to reach a brain someone else published.

Time: 15 minutes
For: People organizing more than one set of notes, and teams sharing brains

Before you start

A working brain. If you do not have one yet, follow Setting up the brain for your AI agents.
Your notes in a git repository with the files committed.
No nexusbrain serve process running while you do this on the local engine, because only one process can open the database at a time.

01How brains, sources and mounts relate

Your brain is the database set up by nexusbrain init. Its settings live in ~/.nexusbrain/config.json, and the brain calls it the host brain.

A source is a repo of notes stored inside that one database. Every page belongs to exactly one source, and page names only have to be unique within their source. Every brain starts with a source called default.

A mount is a separate brain, with its own database, that you connect to your host brain. Mounts are listed in ~/.nexusbrain/mounts.json.

The two ideas are independent. --brain picks which database a command talks to. --source picks which repo inside that database.

Idea	What it is	Managed with	Pick it per command with
Brain	One database	`nexusbrain init`	`--brain host`
Source	One repo of notes inside a brain	`nexusbrain sources`	`--source <id>`
Mount	Another brain connected to yours	`nexusbrain mounts`	`--brain <mount-id>`

02Add a source

The brain reads files through git, so a folder only counts as a source once its files are committed. Source ids are 1 to 32 lowercase letters, numbers and hyphens, and they never change.

1
Commit the notes folder if it is not already a git repo.
```
git -C ~/notes init && git -C ~/notes add -A && git -C ~/notes commit -m "initial import"
```
You should seeGit reports the files it committed.
2
Register the folder as a source.
```
nexusbrain sources add notes --path ~/notes
```
You should seeCreated source "notes" with the path, then federated: false and a note that it is only searched when named with --source.
3
List your sources.
```
nexusbrain sources list
```
You should seeA SOURCES table with each id, whether it is federated or isolated, its page count, and never synced for the new one.

Flag for `sources add`	What it does
`--path <path>`	Use a folder that is already on this machine.
`--url <https-url>`	Clone a repo and manage the clone for you. Cannot be combined with `--path`.
`--clone-dir <path>`	Where to put the clone when you use `--url`.
`--name <display>`	A friendlier display name. The id stays the same.
`--federated`	Include this source in searches that do not name a source.
`--no-federated`	Only search this source when it is named. This is the default.
`--force`	Register the folder even though it is not a committed git repo yet.

Tip

Change your mind later with nexusbrain sources federate <id> or nexusbrain sources unfederate <id>. Rename the display name with nexusbrain sources rename <id> <new-name>.

03Sync sources into the brain

Sync reads the repo, imports new and changed files as pages, and then creates embeddings for them. It pulls from git first unless you pass --no-pull.

1
Sync one source.
```
nexusbrain sync --source notes
```
You should seeProgress for the import and embed steps. Afterward nexusbrain sources list shows a page count and a last sync time for notes.
2
Or sync every registered source at once.
```
nexusbrain sync --all
```
You should seeEach source syncs in turn or in parallel, with a summary of how many succeeded.
3
Check the health of every source.
```
nexusbrain sources status
```
You should seeA table per source with last sync, staleness, page count, embedding coverage and unacknowledged failures.

Flag for `sync`	What it does
`--source <id>`	Sync only this source.
`--all`	Sync every registered source.
`--parallel N`	With `--all`, run up to N sources at the same time. `--parallel 1` runs them one by one.
`--missing-path skip`	With `--all`, skip sources whose folder is not on this machine instead of failing.
`--no-embed`	Import only. Run `nexusbrain embed --stale` later.
`--no-pull`	Do not run `git pull` first.
`--dry-run`	Show what would be synced without writing anything.
`--json`	Print a JSON summary. Exit code 0 means every source was ok or skipped, 1 means an error.

Warning

On the local engine, stop nexusbrain serve before a large sync. See Running serve and sync together.

04Choose which source a command uses

Commands that read or write pages work on one source. When you do not pass --source, the brain works it out in this order and uses the first one that applies.

1
Tie a working folder to a source.
Run this inside the folder. Commands run there, or in any folder below it, will use this source.
```
nexusbrain sources attach notes
```
You should seeAttached followed by the folder path and to source "notes" via .nexusbrain-source.
2
Check which source a command would use, and why.
```
nexusbrain sources current
```
You should seesource: notes and a tier: line naming the rule that picked it, such as dotfile.
3
Search one source by name.
```
nexusbrain query "what did we decide about pricing" --source notes
```
You should seeResults from the notes source only.

Order	Where the source comes from
1	The `--source <id>` flag.
2	The `NEXUS_BRAIN_SOURCE` environment variable.
3	A `.nexusbrain-source` file in the current folder or a parent folder.
4	The source whose folder contains the current folder.
5	The brain default set with `nexusbrain sources default <id>`.
6	The only registered source other than `default`, if there is exactly one.
7	The `default` source.

Tip

Run nexusbrain sources current before anything destructive so you know which source you are about to change. Undo an attach with nexusbrain sources detach.

05Connect another brain as a mount

A mount lets your agent use a brain that lives in its own database, for example one a team publishes as a git repo. Each mount needs a local clone of its repo (for its skills) and the location of its database.

1
Clone the brain repo.
```
git clone https://example.com/team/media-brain.git ~/brains/team-media
```
You should seeGit finishes cloning into ~/brains/team-media.
2
Register it as a mount.
For a local engine brain, pass --engine pglite and --db-path. For a Postgres brain, pass --engine postgres and --db-url.
```
nexusbrain mounts add team-media --path ~/brains/team-media --engine pglite --db-path ~/brains/team-media/.pglite
```
You should seeMount "team-media" added with the path and engine: pglite.
3
List your mounts.
```
nexusbrain mounts list
```
You should seeMOUNTS (1) and an entry for team-media with its path and database location. Passwords in database URLs are shown as ***.
4
Run a command against the mounted brain.
```
nexusbrain --brain team-media query "latest episode plans"
```
You should seeResults from the team-media database instead of your own brain.

Without --brain, the brain is chosen in this order: the NEXUS_BRAIN_BRAIN_ID environment variable, a .nexusbrain-mount file in the current folder or a parent, a mount whose path contains the current folder, and finally host.
nexusbrain mounts disable <id> turns a mount off without removing it. nexusbrain mounts enable <id> turns it back on.
nexusbrain mounts remove <id> removes the mount from mounts.json. It does not delete the clone or its database. The host brain cannot be removed this way.

06How agents see skills from mounted brains

Agent hosts such as OpenClaw and Claude Code decide which skill to use by reading a resolver file, a table of trigger phrases and skills. Your brain repo has one at skills/RESOLVER.md.

When you have mounts, the brain also writes a combined resolver to ~/.nexusbrain/mounts-cache/RESOLVER.md, plus a manifest.json beside it. It lists your own skills and every mounted brain's skills, with a column saying which brain each skill comes from. Agent hosts should prefer this file over skills/RESOLVER.md when it exists.

1
Run mount commands from inside your brain repo.
The combined file is rewritten by mounts add, mounts remove, mounts enable, mounts disable, mounts trust-frontmatter and mounts untrust-frontmatter, but only when the current folder is inside a repo with skills/RESOLVER.md or skills/AGENTS.md.
```
cd ~/brain && nexusbrain mounts add team-media --path ~/brains/team-media --engine pglite --db-path ~/brains/team-media/.pglite
```
You should seeAfter the Mount "team-media" added lines, a cache: line with the path of the combined RESOLVER.md.
2
Open the combined resolver to check it.
```
cat ~/.nexusbrain/mounts-cache/RESOLVER.md
```
You should seeA file titled Nexus Brain Skill Resolver (aggregated) with Trigger, Skill and Brain columns. A Shadows section appears if one of your skills has the same name as a mounted one.

Warning

The combined file mentions nexusbrain mounts sync, but that command is not available yet. To refresh the file, run another mounts command, such as mounts disable then mounts enable, from inside your brain repo. Removing the last mount deletes the combined file.

07Retire a source safely

Removing a source deletes its pages, chunks and embeddings from the brain. Your notes repo on disk is not touched. Archive first if you might want it back.

1
Archive the source to hide it from search for 72 hours.
```
nexusbrain sources archive notes
```
You should seeSource "notes" archived (soft-deleted). with the number of pages kept, when it expires, and Removed from search. Data intact. Bring it back with nexusbrain sources restore notes.
2
Or preview a permanent removal.
```
nexusbrain sources remove notes --dry-run
```
You should seeAn impact summary and (dry-run; no side effects).
3
Remove it for good.
```
nexusbrain sources remove notes --confirm-destructive
```
You should seeRemoved source "notes" with the number of pages deleted.

Note

The default source cannot be archived or removed.

08Troubleshooting

sources add says the folder is not a git repository with committed, tracked files

Commit the files: git -C <path> init && git -C <path> add -A && git -C <path> commit -m "initial import", then run the command again.

To register now and commit later, add --force.

Source id "notes" is already registered.

Pick a different id, or remove the existing source first with nexusbrain sources remove notes --confirm-destructive.

sources add says the path overlaps with an existing source

Two sources cannot share a folder or sit inside each other. Register a folder that does not overlap, or remove the other source.

Refusing to remove without --yes or --confirm-destructive.

Removal is permanent, so it needs confirmation. Add --confirm-destructive, or use nexusbrain sources archive <id> for a 72 hour grace period.

NOTE: mounts-cache not refreshed (not inside a nexusbrain repo).

The mount was saved, but the combined resolver was not rewritten. cd into your brain repo (the folder containing skills/) and run a mounts command again.

Mount path does not exist:

Clone the mounted brain's repo to that path first, then run nexusbrain mounts add again.

--brain is not supported on a thin-client install

This machine connects to a brain on another machine and has no local mounts. Remove the flag, or run the command on a machine that has mounts.

Brains and sources

Before you start

01How brains, sources and mounts relate

02Add a source

Commit the notes folder if it is not already a git repo.

Register the folder as a source.

List your sources.

03Sync sources into the brain

Sync one source.

Or sync every registered source at once.

Check the health of every source.

04Choose which source a command uses

Tie a working folder to a source.

Check which source a command would use, and why.

Search one source by name.

05Connect another brain as a mount

Clone the brain repo.

Register it as a mount.

List your mounts.

Run a command against the mounted brain.

06How agents see skills from mounted brains

Run mount commands from inside your brain repo.

Open the combined resolver to check it.

07Retire a source safely

Archive the source to hide it from search for 72 hours.

Or preview a permanent removal.

Remove it for good.

08Troubleshooting