Storage tiers

Where the brain keeps each kind of content, and the renamed settings.

A brain reads its pages from a brain repo: a git folder of markdown files. Storage tiers let you decide, folder by folder, whether pages are kept in git alongside the database or live only in the database. You set them in a file called nexusbrain.yml at the root of the brain repo.

Use tiers when some folders are too large or too noisy for git history, such as bulk imports or machine output. This guide also covers the renamed settings: the old names git_tracked and supabase_only are now db_tracked and db_only.

Time: 10 minutes
For: Anyone with a brain repo who wants to keep some folders out of git, or who sees the deprecated key warning

Before you start

A brain created with nexusbrain init and a brain repo registered as a source.
Write access to the root folder of the brain repo.

01What each tier means

A tier is assigned by folder. A page belongs to a tier when its slug (its path inside the brain repo, without .md) starts with one of the folders listed for that tier.

Folder matching is by whole path segment. media/x/ matches media/x/photo but not media/xerox/photo.
A folder cannot be in both tiers. The brain refuses the config if it is.
When nexusbrain doctor looks for pages that have no file on disk, it treats the brain's own output folders life/events/, atoms/, extracts/ and dream-cycle-summaries/ as database-only even when you do not list them.

Tier	Where the pages live	What the brain does
`db_tracked`	Markdown files in git and pages in the database	Nothing special. Files are committed and synced as usual.
`db_only`	Pages in the database only	After each successful sync, adds the folder to `.gitignore` so its files stay out of git history. Missing files can be written back with `nexusbrain export --restore-only`.
Unspecified	Markdown files in git and pages in the database	The default for any folder not listed. Pages are stored in git.

Note

On the local engine (PGLite) tiers have limited effect: every page lives in your local database file whatever its tier. The .gitignore handling still keeps bulk content out of git. For full tiering, move to Postgres with nexusbrain migrate --to supabase.

02Write the storage config

Create or open nexusbrain.yml at the root of your brain repo.
You should seeThe file sits next to your top-level page folders.
2
Add a storage: section with block-style lists.
Put each folder on its own line starting with -, and end each folder with /. The brain adds a missing / for you and prints a note saying so.
Only block-style lists are read. A one-line list such as db_only: [archive/] is not supported.
```
storage:
  db_tracked:
    - people/
    - companies/
  db_only:
    - imports/
    - media/transcripts/
```
You should seeThe file saves without errors.
3
Run a sync so the brain picks up the change.
```
nexusbrain sync
```
You should seeThe sync completes, and your .gitignore gains the db_only folders.

Warning

Folders in db_only are ignored by git, and both nexusbrain sync and nexusbrain import honor .gitignore. Do not list a folder that a collector writes new files into, or those files will never be imported.

03Check how pages are tiered

1
Show the storage status.
Add --repo <path> to check a brain repo other than the default source, or --json for machine-readable output.
```
nexusbrain storage status
```
You should seeA Storage Status report with Total pages:, a Storage Tiers: block counting DB tracked, DB only and Unspecified pages, and the folders in your configuration.
Read the missing files list, if there is one.
db_only pages with no file on disk are listed under Missing Files (need restore):. This is normal for database-only content.
You should seeEither no missing files, or a list followed by a suggested nexusbrain export --restore-only command.

04Rename the old setting names

Older brains used git_tracked and supabase_only. They still work, but the brain prints a deprecation warning each run and a future release will reject them. The new names describe the same tiers and work on every engine.

Open nexusbrain.yml in your brain repo.
You should seeYou see git_tracked: or supabase_only: under storage:.
2
Rename each key, keeping its folder list unchanged.
```
storage:
  db_tracked:
    - people/
  db_only:
    - imports/
```
You should seeNo old key names remain in the file.
3
Confirm the warning is gone.
```
nexusbrain storage status
```
You should seeThe report prints with no line saying is deprecated.

Old key	New key
`git_tracked`	`db_tracked`
`supabase_only`	`db_only`

Tip

The warning also mentions nexusbrain doctor --fix. Renaming by hand is the reliable path: in the current release doctor --fix repairs skill files and does not edit nexusbrain.yml. If a file has both old and new keys, the new keys win and the old ones are ignored.

05Restore database-only files to disk

Because db_only pages are not in git, a fresh clone of the brain repo does not have them as files. The export command can write them back from the database.

1
Write the missing db_only pages into your brain repo.
Without --dir, the files go to ./export in the current folder. Point --dir at the brain repo to restore them in place.
```
nexusbrain export --restore-only --repo ~/brain --dir ~/brain
```
You should seeRestoring N db_only pages to followed by the output folder. Pages that already have a file are skipped.

06Troubleshooting

A warning says git_tracked or supabase_only in nexusbrain.yml is deprecated.

Rename git_tracked to db_tracked and supabase_only to db_only, as shown above. The same applies when the warning names supabase_only.

The warning says the deprecated keys are ignored because canonical keys are present.

Your file has both old and new names. Delete the old keys and move any folders they listed under the new keys.

nexusbrain.yml: directory "imports/" appears in both db_tracked and db_only

Pick one tier for that folder and remove it from the other list.

exists but has no storage configuration.

nexusbrain.yml has no storage: section, or its lists are empty or written on one line. Add block-style lists, or delete the file if you do not use tiers.

Sync says mentions db_only but no directories resolved from it.

The brain found a db_only: key but could not read any folders from it, usually because of one-line list syntax. Rewrite the list in block style with one - folder/ per line.

nexusbrain export --restore-only requires a storage tiering config

Restore only works when nexusbrain.yml has a storage: section, because that is how it knows which pages are database-only. Add the section, or pass --repo pointing at the repo that has it.

Sync prints a note that it is skipping .gitignore management because the repo is a git submodule.

Add your db_only folders to the parent repo's .gitignore yourself.

You do not want the brain to edit .gitignore at all.

Set the environment variable NEXUS_BRAIN_NO_GITIGNORE=1 before running sync, and manage .gitignore yourself.

Storage tiers

Before you start

01What each tier means

02Write the storage config

Create or open `nexusbrain.yml` at the root of your brain repo.

Add a `storage:` section with block-style lists.

Run a sync so the brain picks up the change.

03Check how pages are tiered

Show the storage status.

Read the missing files list, if there is one.

04Rename the old setting names

Open `nexusbrain.yml` in your brain repo.

Rename each key, keeping its folder list unchanged.

Confirm the warning is gone.

05Restore database-only files to disk

Write the missing `db_only` pages into your brain repo.

06Troubleshooting

Storage tiers

Before you start

01What each tier means

02Write the storage config

Create or open nexusbrain.yml at the root of your brain repo.

Add a storage: section with block-style lists.

Run a sync so the brain picks up the change.

03Check how pages are tiered

Show the storage status.

Read the missing files list, if there is one.

04Rename the old setting names

Open nexusbrain.yml in your brain repo.

Rename each key, keeping its folder list unchanged.

Confirm the warning is gone.

05Restore database-only files to disk

Write the missing db_only pages into your brain repo.

06Troubleshooting

Create or open `nexusbrain.yml` at the root of your brain repo.

Add a `storage:` section with block-style lists.

Open `nexusbrain.yml` in your brain repo.

Write the missing `db_only` pages into your brain repo.