records

name	records
description	Define and use Mighty agent-defined records. Covers `record_type_def`, published versions, `mt record-type`, `mt record`, and the difference between system record types and agent-defined ones.

Mighty: Records

Use this skill when a repo needs to define new data primitives in Mighty or create records against published agent-defined schemas.

Core model

• System record types are built into the platform and keep record.type_def_id = NULL.
• Agent-defined record types are stored as data in record_type_def.
• Published agent-defined versions are immutable.
• Records that use agent-defined schemas pin the exact published version through record.type_def_id.

Upstream references:

• Agent-defined record types
• Primitive: Records
• Python SDK for Mighty primitives (HTTP-first)

What to use when

• Use mt record-type ... to define, publish, deprecate, and migrate schemas.
• Use mt record ... to create, list, and inspect record instances.
• Use the Python SDK when repo-owned scripts or services need HTTP-native record or record-type operations instead of shelling out to mt.

Practical rules

• Do not treat agent-defined types as a static Rust enum; discover them from record_type_def or from existing records.
• Draft definitions are editable. Published definitions require a new version for changes.
• Use explicit --space in automation.
• Choose replication_mode intentionally:
  • full for control-plane style data that should replicate broadly
  • on_demand for high-volume or selective-fetch records
• Do not create ordinary user data as a new system type just because the repo is first-party.

Authoring workflow

1. Design the schema, field requirements, and indexes.
2. Upsert the draft type with mt record-type upsert --file record_type.json.
3. Publish the version once the schema is ready.
4. Create records with mt record create --type <name> ....
5. If the schema changes later, publish a new version and run a migration instead of mutating the old published one.

Constraints

• Published versions are immutable.
• Agent-defined records must point at a published type version.
• Secret or large binary payloads should use the right Mighty primitive or file refs rather than being stuffed into arbitrary JSON fields.

Examples

• See record authoring patterns for minimal type and record payloads.