Nexus
Sign inStart building
Guides / Brain

Schema packs

Custom page types for your brain, and how to undo a schema change.

A schema pack tells your brain what kinds of pages exist (a person, a company, a meeting), which folders each kind lives in, and which link verbs connect them. nexusbrain uses the active pack to guess a page type from its path, to label links, and to decide which types get extracted and enriched.

This guide shows how to see which pack is active, switch to another pack, make your own, check how well your pages match it, and undo a switch.

Time
15 minutes
For
Anyone who wants page types that fit their own work, such as investors, engineers or creators

Before you start

  • nexusbrain is installed and a brain is set up (nexusbrain init has been run).
  • Commands that read page counts (stats, sync, detect, suggest, review-candidates, review-orphans) need the brain database to be reachable.

01What a schema pack contains

A pack is a YAML or JSON manifest with api_version: nexusbrain-schema-pack-v1, a name in lowercase slug form, and a version like 1.0.0. It can inherit another pack with extends, for example extends: nexusbrain-base.

Each page type has a name, a primitive (one of entity, media, temporal, annotation, concept), a list of path_prefixes such as people/, optional aliases, and two switches: extractable and expert_routing. The pack also lists link_types (link verbs) and takes_kinds (by default fact, take, bet, hunch).

Bundled packNotes
nexusbrain-baseThe default. Reproduces the built-in behavior from before schema packs existed.
nexusbrain-recommendedBundled.
nexusbrain-creatorBundled.
nexusbrain-investorBundled.
nexusbrain-engineerBundled.
nexusbrain-everythingBundled.
nexusbrain-base-v2Bundled.
Note

Bundled packs are read-only. Your own packs live in ~/.nexusbrain/schema-packs/<name>/ as pack.yaml, pack.yml or pack.json.

02See which pack is active

nexusbrain picks the active pack from the first of these that is set: a per-call --schema-pack flag, the NEXUS_BRAIN_SCHEMA_PACK environment variable, a per-source database setting schema_pack.source.<id>, the brain-wide database setting schema_pack, the schema: section of nexusbrain.yml, the schema_pack field in ~/.nexusbrain/config.json, and finally nexusbrain-base.

  1. Show the active pack.

    nexusbrain schema active

    You should seeLines starting Active pack:, Source:, Pack identity:, Page types:, Link verbs: and Takes kinds:. Source tells you which setting chose the pack.

  2. List every pack you can switch to.

    nexusbrain schema list

    You should seeA Bundled packs: list, then either Installed packs (~/.nexusbrain/schema-packs/): or a note that you have none.

  3. Look inside a pack before you use it.

    nexusbrain schema show nexusbrain-investor

    You should seeThe page types with their primitive, path prefixes, aliases and [extractable, expert] flags, then the link verbs, takes kinds and enrichable types. Leave out the name to show the active pack. Add --json for machine-readable output.

03Switch to a different pack

  1. Validate the pack you want.

    Always pass the pack name. With no name, validate checks nexusbrain-base.

    nexusbrain schema validate nexusbrain-investor

    You should seeA line ending in valid manifest, followed by the path and counts of page types, link verbs and takes kinds.

  2. Activate it.

    nexusbrain schema use nexusbrain-investor

    You should seeActive schema pack set to: nexusbrain-investor and the config file it wrote, which is ~/.nexusbrain/config.json. A pack that fails validation is refused with Refusing to activate.

  3. Confirm the switch took effect.

    nexusbrain schema active

    You should seeActive pack: shows the new pack.

  4. Preview which existing pages would get a type from the new pack.

    sync is a dry run unless you add --apply. It matches pages to the pack by path prefix.

    nexusbrain schema sync

    You should seeMode: DRY-RUN, one line per type and prefix with would_apply=, sample slugs, and a total.

  5. Write the page types.

    nexusbrain schema sync --apply

    You should seeMode: APPLY and applied= counts per prefix.

Warning

schema use writes ~/.nexusbrain/config.json, which is near the bottom of the resolution order. If NEXUS_BRAIN_SCHEMA_PACK or a database setting is set, that still wins. Check with nexusbrain schema active.

04Make your own pack

The quickest route is to copy an existing pack and edit the copy. init, fork, edit, diff, graph and explain are marked experimental in this version.

  1. Copy a pack under a new name.

    nexusbrain schema fork nexusbrain-base my-pack

    You should seeA line saying the pack was forked to ~/.nexusbrain/schema-packs/my-pack/pack.json.

  2. Add a page type.

    --primitive and --prefix are required. Add --extractable, --expert or one or more --alias values if you need them.

    nexusbrain schema add-type researcher --primitive entity --prefix people/researchers/ --pack my-pack

    You should seePack: my-pack (json) and a Sha8: line showing the file changed.

  3. Add a link verb.

    nexusbrain schema add-link-type advises --inverse advised_by --pack my-pack

    You should seeThe same Pack: and Sha8: lines.

  4. Lint the pack.

    Add --with-db to also run the checks that need your brain, such as types with no pages.

    nexusbrain schema lint my-pack

    You should seeOK and lint clean, or a list of ERROR and warn lines with hints.

  5. Activate it.

    nexusbrain schema use my-pack

    You should seeActive schema pack set to: my-pack.

Authoring commandWhat it does
schema init <name>Scaffold an empty pack that extends nexusbrain-base, at ~/.nexusbrain/schema-packs/<name>/pack.yaml.
schema fork <src> <new>Copy a pack to a new editable name.
schema edit <name>Print the pack file path so you can open it in an editor.
schema diff <a> <b>Show page types only in one pack, only in the other, and the common count.
schema add-type, remove-type, update-typeAdd, remove or change a page type. update-type takes --extractable, --expert and --primitive.
schema add-alias, remove-aliasAdd or remove an alias on a type.
schema add-prefix, remove-prefixAdd or remove a folder prefix on a type.
schema add-link-type, remove-link-typeAdd or remove a link verb. add-link-type takes --inverse, --page-type and --target-type.
schema set-extractable <type> <true|false>Turn extraction on or off for a type.
schema set-expert-routing <type> <true|false>Turn expert routing on or off for a type.
schema scaffold-extractable <type>Create prompts/extract/<type>.md and fixtures/extract/<type>.jsonl stubs for an extractor. Takes --dims a,b,c and --force.
Tip

Every editing command works on the active pack unless you pass --pack <name>. All the newer verbs accept --json.

05Check how well your pages fit

  1. Count pages per type.

    Add --source <id> to look at one source only.

    nexusbrain schema stats

    You should seeTotal pages, Typed with a coverage percentage, Untyped, a By type list, and any Dead prefixes (declared but 0 pages).

  2. Find pages that match no type in the active pack.

    nexusbrain schema review-orphans

    You should seeOrphan pages (no active-pack type match): with a count and up to 20 slugs. Use --json for the full list.

  3. Find folders that look like a missing type.

    nexusbrain schema review-candidates

    You should seeCandidate prefixes with page counts and a suggested type, or No candidate types found. Promote one with --apply <prefix>.

  4. See how often schema commands and events were recorded.

    --since takes a number with d, w or m, for example 2w. The default is 30d.

    nexusbrain schema usage --since 30d

    You should seeSchema CLI usage (last 30d):, a total, and a count per verb. Experimental verbs are tagged (experimental).

  • schema detect groups pages by folder and suggests page types. schema suggest refines that list.
  • schema graph prints each type with its primitive and aliases. schema explain <type> prints one type's settings.
  • schema reload [--pack <name>] clears the pack cache in the current process.

06Undo a schema change

  1. Restore a named pack.

    Passing --to is the reliable form. Without it, nexusbrain looks for the previous pack in ~/.nexusbrain/schema-pack-history.jsonl, and if it finds none it restores nexusbrain-base.

    nexusbrain schema downgrade --to nexusbrain-base

    You should seeActive pack restored to the pack name, the config path, and a note that the command restores config only.

  2. Confirm the active pack.

    nexusbrain schema active

    You should seeActive pack: shows the restored pack.

  3. Find pages that still carry types from the removed pack.

    Downgrade only changes which pack is active. Pages that were given custom types keep them, and cached and eval rows are not removed. These pages now show up as orphans.

    nexusbrain schema review-orphans --json

    You should seeA JSON list of every page with no type match in the restored pack. Retype or move those pages yourself, or switch back to the pack that defines them.

Warning

There is no command that deletes or rewrites custom-typed pages after a downgrade. Plan the cleanup before you switch, and keep a copy of your own pack so you can switch back.

07Troubleshooting

Unknown pack: <name>.

Run nexusbrain schema list. Your own pack must be a folder in ~/.nexusbrain/schema-packs/ containing pack.yaml, pack.yml or pack.json.

pack 'nexusbrain-base' is bundled and read-only.

Bundled packs cannot be edited. Run nexusbrain schema fork nexusbrain-base <new-name>, then edit the fork with --pack <new-name>.

Invalid manifest at <path> with a Code: line.

Fix the field named in the message. Common causes: name not in lowercase slug form, version not in M.m.p form, or a primitive that is not one of entity, media, temporal, annotation, concept.

Re-run nexusbrain schema validate <name>.

--primitive must be one of entity|media|temporal|annotation|concept or --prefix is required.

schema add-type needs both flags, for example --primitive entity --prefix people/researchers/.

schema use succeeded but schema active still shows the old pack.

A higher setting is overriding the config file. Unset NEXUS_BRAIN_SCHEMA_PACK, or change the database or nexusbrain.yml setting that the Source: line names.