​

Schema Packs

​

What ships in the box

• gbrain-base (default) — reproduces pre-v0.38 hardcoded behavior byte-for-byte. Existing brains see zero behavior change after upgrade. Covers: person, company, deal, meeting, project, place, concept, writing, analysis, guide, hardware, architecture, etc. (the original ALL_PAGE_TYPES list).
• modusbrain-recommended — extends gbrain-base with the 13 additional directories described in docs/MODUSBRAIN_RECOMMENDED_SCHEMA.md: deal, meeting, concept, project, source, daily, personal, civic, original, place, trip, conversation, writing. If you like the documented operational-brain pattern, activate this with:
  modusbrain schema use modusbrain-recommended
  

​

CLI surface

modusbrain schema active     # show resolved pack + which tier set it
modusbrain schema list       # list bundled + installed packs
modusbrain schema show       # pretty-print the active pack
modusbrain schema validate   # validate a manifest's shape
modusbrain schema use <pack> # activate a pack (writes ~/.modusbrain/config.json)

modusbrain schema detect              # propose types matching brain shape
modusbrain schema suggest             # LLM-refined proposals on top of detect
modusbrain schema review-candidates   # promote / rename / ignore candidates
modusbrain schema review-orphans      # surface pages with no matching type
modusbrain schema init <name>         # scaffold a stub pack    (experimental)
modusbrain schema fork <a> <b>        # copy + rename a pack    (experimental)
modusbrain schema edit <name>         # surface the pack path   (experimental)
modusbrain schema diff <a> <b>        # set-diff two packs      (experimental)
modusbrain schema graph               # ASCII type listing      (experimental)
modusbrain schema lint                # flag duplicates + missing prefixes
modusbrain schema explain <type>      # plain-English type description (experimental)
modusbrain schema downgrade --to <p>  # restore previous pack (recovery)
modusbrain schema usage --since 30d   # per-verb invocation counts (D14 telemetry)

​

Resolution chain (7 tiers)

​

How the agent uses the active pack

• parseMarkdown infers page type from path prefixes declared in the active pack (page_types[].path_prefixes). Without an active pack threaded, falls back to the legacy hardcoded inferType() so the byte-for-byte parity gate stays green.
• whoknows / find_experts scopes candidates to expert_routing: true types in the active pack.
• extract_facts runs only on extractable: true types.
• enrichment-service routes person/company enrichment based on the pack’s primitive declarations.
• Search hybrid cache (knobsHash) folds in pack name + version (v0.39 T21). A cache row written under pack A is unreachable when pack B is active. Cross-pack contamination is structurally impossible.

​

The magical moment (T2-T4 + T10)

1. Import warn (T7): the end of modusbrain import prints [schema] X of Y pages (Z%) have no type matching the active schema pack. Run modusbrain schema detect to propose a pack matching your content shape.
2. modusbrain doctor schema_pack_consistency check keeps surfacing the warning persistently after the import session ends.

modusbrain schema detect              # heuristic clustering on her actual shape
modusbrain schema suggest             # LLM-refined proposals
modusbrain schema review-candidates   # human gate on promotion
modusbrain schema review-candidates --apply Projects/   # accept

​

Authoring your own pack

modusbrain schema init my-pack            # scaffolds ~/.modusbrain/schema-packs/my-pack/pack.yaml
$EDITOR ~/.modusbrain/schema-packs/my-pack/pack.yaml
modusbrain schema validate my-pack        # check shape
modusbrain schema use my-pack             # activate
modusbrain schema active                  # confirm

api_version: modusbrain-schema-pack-v1
name: my-pack
version: 0.0.1
modusbrain_min_version: 0.39.0
extends: gbrain-base   # inherits everything from base; add overrides below
description: |
  My personal pack.

page_types:
  - name: project-x
    primitive: entity
    path_prefixes:
      - Projects/
    aliases: []
    extractable: false
    expert_routing: false

  # Add more types here. Each maps a path prefix to a primitive +
  # opt-in flags. See src/core/schema-pack/base/modusbrain-recommended.yaml
  # for a worked example.

link_types: []
takes_kinds: [fact, take, bet, hunch]
borrow_from: []
frontmatter_links: []
enrichable_types: []
filing_rules: []

​

Recovery + revert

modusbrain schema downgrade --to gbrain-base
# OR auto-detect previous from ~/.modusbrain/schema-pack-history.jsonl:
modusbrain schema downgrade

1. git revert <merge-commit> — restores the code.
2. modusbrain schema downgrade --to gbrain-base — restores config.
3. (Optional) modusbrain pages purge-deleted --older-than 0h — drops v0.39-typed pages that no longer have a matching type in the active pack.

​

Distribution

• modusbrain-schema-pack-v1 → schemapack
• gbrain-skillpack-v1 → skillpack

​

What’s deferred to v0.40+

• Per-source pack federation across mounts. A query crossing multiple sources currently rejects with permission_denied when those sources have divergent active packs (T19 + codex finding #2). The v0.40+ work computes a true per-source closure via the existing buildSourceClosureCte engine surface.
• extends chain semver compatibility checks between pack versions.
• skillpack ↔ schemapack cross-reference declarations — a skillpack can declare “I work best with these primitives present in your pack.”
• Live schema migration helpers — when you add a type, auto-suggest backfill of existing pages.
• Authoring vs derivation thesis reframe (D14). v0.39.0.0 ships the full 11-verb cathedral with 6 verbs marked experimental-tier. v0.40+ retro reads T23 usage telemetry to decide which to deprecate.