schema-author — evolve the brain's type taxonomy
Memrain uses OPEN page typing: a page's type lives in its frontmatter, filing
prefixes are conventions (see _brain-filing-rules.md), and typed links are
derived from page content. There is no mutable "pack" artifact — the taxonomy
is the set of conventions the ontology tracks plus the frontmatter discipline
this skill enforces. Authoring the taxonomy means: read the active ontology,
propose changes through it, record the convention, and backfill existing pages.
Non-goals (use these other skills instead)
This skill AUTHORS the taxonomy (adds page types, link verbs, filing prefixes, expert-routing decisions). For these adjacent jobs, route elsewhere:
- Filing one specific page →
skills/brain-taxonomist(viaget_skill brain-taxonomist). Brain-taxonomist routes at WRITE TIME ("where does this note go?"). schema-author changes the rules at AUTHORING TIME ("what types and prefixes exist?"). - Taxonomy-check as part of EIIRP iteration →
skills/eiirpalready has a schema-check phase. Don't duplicate. - Just looking up a type's settings →
ontology_get(orontology_dimensionsfor the dimension breakdown) directly. This skill is for CHANGING the taxonomy, not READING from it. - Querying who knows about X →
find_expertsdirectly (or the expert-routing conventions). schema-author decides that a type should be expert-routable; it does not run the query.
Convention
Convention: see
conventions/brain-first.md(viaget_skill conventions/brain-first) for the lookup chain (search → query → page_get → external).
Convention: see
conventions/schema-evolution.md(viaget_skill conventions/schema-evolution) for "when to add a type vs alias vs prefix" — the heuristic.
When to invoke
Invoke when the user (or a sibling skill) says any of:
- "Add a
researchertype to my taxonomy" - "I have 4000 untyped pages under
meetings/" - "My brain doesn't know that
journal-articleis a type" - "Treat
paperpages as fact-extractable" - "Propose types from what I've ingested"
- "Backfill the new types onto existing pages"
DON'T invoke for "where does THIS note go" (use brain-taxonomist) or
"who knows about X" (use find_experts).
Workflow
Phase 1 — Brain (know what the active ontology says)
ontology_get
Returns the brain's current ontology: known types, dimensions, and link
verbs in use. ontology_dimensions breaks down each dimension (type,
subtype, origin, format) with observed values. This is your baseline —
never propose a type without knowing whether an equivalent already exists.
Phase 2 — Assess (what does the current taxonomy cover?)
stats
Gives page/doc/chunk counts. Then measure type coverage directly:
get_recent_salience {"slug_prefix": "<candidate-prefix>"}
page_list {"type": "<candidate-type>"}
and inspect frontmatter on samples via page_get. Look for:
- untyped pages (no
typein frontmatter) - dead prefixes (a convention directory with zero matching pages — probable mis-declaration)
If coverage < 90%, there's untyped content worth typing.
For an untyped-pages drilldown, list the busiest prefixes and look
for shared path prefixes (e.g. "12 of these are under research/papers/") —
those are candidates for a new type.
Phase 3 — Propose (what types should the taxonomy add?)
Cluster candidates yourself from the Phase 2 scan (path-prefix clustering is a pure heuristic — no model call needed), then run the proposal through the brain:
ontology_propose {"entity": "concepts/types/researcher", "dimension": "prefix", "value": "people/researchers/", "source": "<an evidence page slug>"}
ontology_propose records one entity has dimension=value observation, so a
type is an entity (concepts/types/<name>) and each of its settings (prefix,
primitive, extractable, expert-routed) is one dimension on it. A novel
dimension lands quarantined; a different value on an existing one supersedes
it. Check ontology_conflicts
afterwards — a proposal that conflicts with an existing type/alias is a
signal to alias instead of add (see conventions/schema-evolution.md).
For LLM-refined candidates, use query over the untyped cluster and let the
brain's utility tier rank which clusters cohere as a type; promote only the
top candidates with clear prefix evidence.
Phase 4 — Apply (record the convention)
The taxonomy change becomes real in two places:
- The ontology — the accepted
ontology_proposeentry is the durable record of the decision. - The conventions page — update the filing rules so every writing skill picks it up:
page_append slug=concepts/type-conventions
"## researcher
- primitive: entity
- prefix: people/researchers/
- extractable: yes (facts pipeline may extract from these pages)
- expert-routed: yes (find_experts may surface these pages)"
For multi-part refactors (e.g. add a type AND the link verb that points to it), record both in the same pass so the taxonomy never half-describes itself:
ontology_propose {"entity": "concepts/types/paper", "dimension": "prefix", "value": "research/papers/"}
ontology_propose {"entity": "concepts/link-verbs/authored", "dimension": "from", "value": "researcher"}
ontology_propose {"entity": "concepts/link-verbs/authored", "dimension": "to", "value": "paper"}
Validate before backfill: re-run ontology_conflicts. It flags dangling
references and prefix collisions you'd otherwise discover only at runtime.
Phase 5 — Backfill (retype existing pages with the new types)
Dry-run first: enumerate what would change.
get_recent_salience {"slug_prefix": "people/researchers"}
Count the pages that would gain type: researcher. If the numbers look
right, backfill. For a handful of pages, edit frontmatter directly with
page_get + page_put. For large batches, the operator runs the retype on
the host — a dry run by default, --apply to write:
memrain page-retype --to researcher --path-prefix people/researchers/ --json
memrain page-retype --to researcher --path-prefix people/researchers/ --apply
Backfill must be idempotent: a second run finds nothing to update. Never rewrite page bodies during a retype — frontmatter only.
Phase 6 — Verify
Re-check coverage the same way as Phase 2. Coverage should be ≥95% now. Spot-check the new type:
find_experts "machine learning"
If researcher was declared expert-routed, results should include
researcher-typed pages. If they don't, the prefix convention and the actual
page slugs disagree — fix the convention or the filing, not the query.
Phase 7 — Record (preserve the change)
Write the decision as a brain page so future sessions inherit it:
page_put {"slug": "reports/taxonomy/{YYYY-MM-DD}-add-researcher", "type": "report", "allowAdHocType": true, "compiled_truth": {"category": "taxonomy"}, "markdown_body": "<what was added, why, evidence, backfill counts>"}
The background cycle picks up new conventions on its next pass — no manual reload step. Other agents see the change as soon as the pages are indexed.
Outputs
- Accepted ontology proposals recorded against the active ontology.
- Updated
concepts/type-conventionspage (the human-readable contract). typefrontmatter backfilled on matching pages after Phase 5.- Query paths (
find_experts, typed traversal viagraph_query) now route through the new expert types. - A
reports/taxonomy/...decision page.
Contract
- Inputs: a natural-language request that names a type / prefix / link verb / flag change, OR a Phase 2 scan showing untyped pages that need a new type.
- Outputs: ontology proposal entries + updated conventions page + (if backfill ran)
typefrontmatter set on matching pages + a decision report page. - Side effects: retyped pages bump their document generation, so the query cache invalidates itself; other agents pick the change up on next read.
- Idempotency: every step is idempotent. Re-proposing an existing type surfaces via
ontology_conflictsinstead of duplicating; a second backfill finds nothing to update. - Trust: taxonomy changes are internal-surface work — run them via the internal MCP surface or
memrain call; the public ingress does not expose destructive or taxonomy-shaping operations. - Atomicity: each page write is a single versioned
page_put; a failed batch leaves prior pages untouched andpage_versions/page_revertcan roll back any individual page.
Anti-Patterns
- Don't invent a parallel taxonomy record. The ontology (via
ontology_propose) plus the conventions page IS the taxonomy. A type that exists only in one agent's head — or only in one session's frontmatter — is not a convention. - Don't add a type for a directory you imported once for triage. Type
conventions are permanent decisions; one-time imports are not. See
conventions/schema-evolution.mdfor the <20-pages-don't-codify heuristic. - Don't declare a type expert-routed without a filing prefix. An
expert-routed type with no prefix convention never matches real pages, so
find_expertssilently never surfaces it. - Don't promote a proposal without verifying the prefix matches real
content. Run
ontology_conflictsand apage_listsample before recording the convention, to catch prefix collisions pre-write. - Don't conflate "filing one page" with "evolving the taxonomy." Filing
routes via
brain-taxonomist; schema-author is for authoring the type taxonomy itself. The Non-goals section above names the boundary. - Don't skip the dry-run before a large backfill. Always enumerate
would_applycounts + sample slugs first. A prefix that matches 50,000 pages is recoverable but slow; verifying first is cheap. - Don't remove a type without checking references. If another type's
aliases or link verbs reference it, break the references first. Check
ontology_conflictsandlist_link_sourcesbefore retiring anything.
Output Format
When invoked, this skill produces structured output suitable for both human and JSON consumption:
Per-proposal result: the ontology_propose response (accepted / conflict,
with the conflicting dimension named on conflict).
Coverage summary (the agent's final report):
- Total pages, typed %, untyped count, per-type breakdown, dead-prefix list
- Backfill: per-prefix
would_apply/appliedcount + sample slugs in dry-run mode - One line per taxonomy change: type name, prefix, flags (extractable / expert-routed), evidence count
On failure, tool errors come back in the standard MCP error envelope; read the message — it names the conflicting type, missing slug, or rejected parameter.
Failure modes
- Proposal conflicts →
ontology_conflictsnames the colliding type or alias. Alias instead of add, or pick a different name. - Backfill touches nothing → the prefix convention and the real slugs
disagree.
page_listthe prefix and compare against the convention. find_expertsmisses the new type → the pages carry the type but the filing prefix doesn't match the convention page. Reconcile them.- Permission denied (public surface) → taxonomy ops are internal-only.
Use the internal MCP surface or
memrain callfrom the host.