crystalline-schema

Crystalline Schema

A domain's engrams need no schema by default - type and status are free-form strings. Reach for a schema engram once a domain wants a given type to carry a consistent shape: required observation categories, required relations, or expected frontmatter fields.

Authoring a schema engram

A schema is itself an engram, type: schema, whose frontmatter declares the shape for another type via entity. Body content is optional prose describing the schema; the shape lives entirely in frontmatter.

Before deciding which categories and relations to require, call vocabulary for the domain to see what its engrams already use - it complements infer_schema by grounding the shape in real terms.

---
type: schema
title: Decision Schema
tags:
  - schema
  - engineering
status: stable
entity: decision
version: 1
schema:
  summary: string, one line summary of the decision
  rationale?: string
  priority(enum):
    - low
    - medium
    - high
  alternative?(array): string
  supersedes?: Decision
settings:
  validation: warn
  frontmatter:
    status(enum):
      - stable
      - proposed
      - superseded
    owner: string
---

# Decision Schema

Engrams of type `decision` in the engineering domain follow this shape.

That is the on-disk shape. Through the MCP write tool none of that frontmatter goes into content - write_engram builds the frontmatter itself from its arguments, and entity, version, schema and settings travel through metadata as an object:

{
  "tool": "write_engram",
  "arguments": {
    "domain": "engineering",
    "title": "Decision Schema",
    "type": "schema",
    "tags": ["schema", "engineering"],
    "metadata": {
      "entity": "decision",
      "version": 1,
      "schema": {
        "summary": "string, one line summary of the decision",
        "priority(enum)": ["low", "medium", "high"]
      },
      "settings": { "validation": "warn" }
    },
    "content": "The shape for decision engrams.\n\n- [convention] Decisions carry a summary and a priority #schema\n- [convention] Adopted in warn mode first #schema"
  }
}