Schema
Schemas are versioned bundles of object type schemas, relationship type schemas, UI configurations, and extraction prompts. They let you define a domain model once and apply it to many projects.
Concepts
Section titled “Concepts”| Concept | Description |
|---|---|
| Schema | A versioned bundle: type schemas, relationship schemas, UI configs, extraction prompts |
| Schema pack | One schema as it appears inside a project: the unit the Schema packs page, compilation, and blueprint provenance work with |
| Assignment | A link between a schema and a project |
| Compiled types | The merged schema registry view for a project, combining all active schemas |
| Blueprint | A versioned bundle of packs, agents, skills, and seed data; applying it assigns its packs. See Blueprints |
Schema lifecycle
Section titled “Schema lifecycle”draft → published → (deprecated)- Draft schemas are not visible to projects.
- Published schemas are project-scoped: a project’s
availablelist shows only schemas it owns, and global-registry rows surface only after being installed. The exception is a built-in pack, which is a single global row (project_idNULL,source = "builtin") shared by every project that applies the blueprint claiming it. - Deprecated schemas remain installed on existing projects but cannot be newly assigned.
Managing schemas (admin)
Section titled “Managing schemas (admin)”Create a schema
Section titled “Create a schema”curl -X POST https://api.example.com/api/schemas \ -H "Authorization: Bearer <token>" \ -H "Content-Type: application/json" \ -d '{ "name": "legal-entities", "version": "1.0.0", "description": "Object types for legal entity extraction", "author": "Emergent Company", "source": "official", "license": "MIT", "draft": false, "objectTypeSchemas": { "Contract": { "type": "object", "properties": { "title": { "type": "string" }, "parties": { "type": "array", "items": { "type": "string" } }, "signedDate": { "type": "string", "format": "date" }, "jurisdiction":{ "type": "string" } }, "required": ["title"] }, "Clause": { "type": "object", "properties": { "clauseType": { "type": "string" }, "text": { "type": "string" } } } }, "relationshipTypeSchemas": { "CONTAINS_CLAUSE": { "from": "Contract", "to": "Clause" } }, "uiConfigs": { "Contract": { "icon": "file-text", "color": "#0ea5e9", "displayProperty": "title" }, "Clause": { "icon": "paragraph", "color": "#8b5cf6", "displayProperty": "clauseType" } }, "extractionPrompts": { "Contract": { "systemPrompt": "Extract contract entities from the document.", "exampleJson": "{\"title\": \"Service Agreement\", \"parties\": [\"Acme\", \"Widgets Inc.\"]}" } } }'Get a schema
Section titled “Get a schema”curl https://api.example.com/api/schemas/<schemaId> \ -H "Authorization: Bearer <token>"Update a schema
Section titled “Update a schema”curl -X PUT https://api.example.com/api/schemas/<schemaId> \ -H "Authorization: Bearer <token>" \ -H "Content-Type: application/json" \ -d '{"version": "1.0.1", "description": "Updated description"}'Delete a schema
Section titled “Delete a schema”curl -X DELETE https://api.example.com/api/schemas/<schemaId> \ -H "Authorization: Bearer <token>"Schema field reference
Section titled “Schema field reference”| Field | Type | Description |
|---|---|---|
name |
string | Unique identifier name |
version |
string | Semver string, e.g. 1.0.0 |
description |
string | Human-readable description |
author |
string | Schema author |
source |
string | official, community, or custom label |
license |
string | SPDX license ID, e.g. MIT |
repositoryUrl |
string | Source repository URL |
documentationUrl |
string | Docs URL |
objectTypeSchemas |
object | Map of type name → JSON Schema |
relationshipTypeSchemas |
object | Map of relationship type → schema |
uiConfigs |
object | Map of type name → UI config |
extractionPrompts |
object | Map of type name → prompt config |
migrations |
object | Optional migration hints block (see Schema migrations) |
checksum |
string | md5 of canonical content (32 hex characters) |
draft |
bool | true = not visible to projects |
publishedAt |
timestamp | When the schema was published |
deprecatedAt |
timestamp | When the schema was deprecated |
Property definitions
Section titled “Property definitions”Each property in an objectTypeSchemas entry is a JSON-Schema fragment. The
registry understands these keywords; unknown keys pass through untouched, so
behavioural blocks such as embedding and extraction survive a blueprints
round-trip.
| Keyword | Behaviour |
|---|---|
type |
Coerced on write for number, integer, boolean, date, time, url, email, phone, country, currency, md5/sha1/sha256/sha512, array (see below). string is stored as sent unless format names a semantic format; object is type-checked but not converted. An unknown type is stored as-is |
title |
Display label. The UI shows it in place of the key, which stays visible beneath it |
description |
Help text shown with the field |
items |
Element schema for array, declared as an object such as {"type": "string"}; every element is coerced (a wrong element fails with its index). A bare scalar ("items": "string") is rejected when the schema is created or updated, over REST and MCP alike |
enum |
Allowed values for a primitive property (string-backed, number, integer, boolean), enforced on object and relationship writes after coercion. An array’s items.enum constrains every element. On array/object itself it is documentation only |
format |
On a string property, validates like the matching type for email, phone, country, currency and time. Any other format is documentation only, except markdown: it declares the value as prose, so the object preview, the object page and the card API render it as sanitized Markdown (the value is still a string and is not validated) |
minimum / maximum |
Enforced on number and integer: a value outside the bound fails the write |
required |
Type-level list of property names that must be present on a write |
Type-specific validation:
url— absolutehttp/httpsURL with a host; stored trimmed.sha256(andmd5,sha1,sha512) — hex digest of exactly the right length; stored lower-case.date— RFC 3339,2006-01-02,2006-01-02 15:04:05,2006-01-02T15:04:05,01/02/2006, or02-01-2006; stored as RFC 3339.time— 24-hourHH:MM(orHH:MM:SS, whose seconds are dropped); stored asHH:MM.email— one bare RFC 5322 address; a display form (Alice <alice@example.com>) is rejected. Stored lower-case.phone— an optional leading+, then digits with spaces, dashes, dots or parentheses; 7–15 digits in total. Stored as typed.country— ISO 3166-1 alpha-2 or alpha-3 country code; stored as the canonical two-letter upper-case code.currency— ISO 4217 currency code; stored upper-case.enum— the supplied value must be one of the declared values. Matching runs after coercion, so"de"passes acountryenum of["DE"]and stores"DE". A value outside the list fails the whole write with the allowed values named. Enum is supported on primitive types only; an empty enum list on a primitive property is rejected when the schema is created or updated.number/integer—minimum/maximum, when declared, are enforced;integeralso rejects a fractional value.
properties: tokensUsed: type: integer title: Tokens used homepage: type: url title: Homepage contentHash: type: sha256 title: Content hash tags: type: array items: { type: string } contact_email: type: email title: Contact email home_country: type: country title: Home country latitude: type: number minimum: -90 maximum: 90 title: Latitude status: type: string enum: [draft, published, archived] title: StatusLabel every key a reader cannot scan at a glance — any snake_case key, or one
with an internal capital. event_time → Event time, tokensUsed →
Tokens used. Keys stay visible beneath the label, so a good title is a
rendering choice, not a rename.
Assigning schemas to projects
Section titled “Assigning schemas to projects”Browse available schemas
Section titled “Browse available schemas”curl https://api.example.com/api/schemas/projects/<projectId>/available \ -H "Authorization: Bearer <token>"List installed schemas
Section titled “List installed schemas”curl https://api.example.com/api/schemas/projects/<projectId>/installed \ -H "Authorization: Bearer <token>"Assign a schema
Section titled “Assign a schema”curl -X POST https://api.example.com/api/schemas/projects/<projectId>/assign \ -H "Authorization: Bearer <token>" \ -H "Content-Type: application/json" \ -d '{"schemaId": "<schemaId>"}'This creates an assignment with active: true by default.
Enable / disable an assignment
Section titled “Enable / disable an assignment”curl -X PATCH https://api.example.com/api/schemas/projects/<projectId>/assignments/<assignmentId> \ -H "Authorization: Bearer <token>" \ -H "Content-Type: application/json" \ -d '{"active": false}'Inactive assignments do not contribute types to the compiled registry.
Remove an assignment
Section titled “Remove an assignment”curl -X DELETE https://api.example.com/api/schemas/projects/<projectId>/assignments/<assignmentId> \ -H "Authorization: Bearer <token>"Compiled types
Section titled “Compiled types”The compiled types endpoint merges all active schema assignments for a project into a single flat type map. Later-assigned schemas override earlier ones for the same type name.
curl https://api.example.com/api/schemas/projects/<projectId>/compiled-types \ -H "Authorization: Bearer <token>"This is the schema registry the extraction pipeline uses. Types registered here that are not yet in the project’s schema registry table are automatically added with source = "template" on the next extraction run.
Schema history
Section titled “Schema history”The history endpoint returns all schema assignments for a project including ones that have been uninstalled (soft-deleted). Useful for auditing which schemas were used over time.
curl https://api.example.com/api/schemas/projects/<projectId>/history \ -H "Authorization: Bearer <token>"Each item includes status: "installed" or status: "uninstalled" and an optional removed_at timestamp.
Schema packs
Section titled “Schema packs”A schema pack is one schema as it exists in a project. The Schema area’s
Schema packs page (/schema/packs) is the pack-level view: every active pack
with its name, version, owner badge, and the object/relationship types it
contributes. Object types are chips that open the type page, and each row links
to the pack’s read-only detail.
The page groups packs into four fixed sections, in this order:
| Section | What it holds | Heading / title link |
|---|---|---|
| Manual | Add schema installs and project-authored or override packs | No link |
| Blueprints | Packs an applied blueprint declares, grouped per blueprint | Heading links to the blueprint |
| Data Sources | Packs a data-source provider installs on connect (e.g. github-app-workflow for the GitHub App / Bot, email-core for Gmail), one row per installed app |
Row links to that data source |
| Built-in | Global source="builtin" platform packs that no applied blueprint claims |
No link |
A global built-in pack that an applied blueprint claims is listed under Blueprints (blueprint provenance wins), matching the pack detail’s owning-blueprint link.
A pack row’s title is only a link where the section gives it a destination; its object types and the explicit Details link are always navigable.
Packs arrive in a project one of these ways:
| Source | Owner badge | How it gets there |
|---|---|---|
| Applied blueprint (built-in) | Global | Shared source="builtin" row, one for all projects |
| Applied blueprint (user/import) | Project | A project-scoped pack created on apply |
| Data-source provider | Project | Installed by the provider on connect (source="provider:<type>"), then reconciled in place on re-connect, webhook or issue sync |
| Manual install or project-authored schema | Project | Add schema, or a manual/override pack (source="manual") |
Provider packs are code-owned: their types, icons/colours and provenance token come from the provider, and a reconcile updates the project’s existing pack rather than creating a second version. Their types render with the declared accent (for the GitHub App pack: a pull request, an issue and a review lane).
There is no read-time “system pack”: a project’s packs are only what has been assigned to it.
The pack list is derived, not stored: it groups the project’s compiled types
by their schemaId and joins pack metadata from the schema catalog. Types with
no schemaId cannot be attributed to a pack and are omitted, as are shadowed
(losing) duplicates — so an override pack never resurfaces the type it
supersedes, and a fully-shadowed pack does not appear at all.
Pack blueprint claims
Section titled “Pack blueprint claims”Returns compiled schema packs claimed by at least one applied blueprint (status = "applied"). Packs claimed only by unapplied or superseded blueprints are omitted. An empty result is [].
curl https://api.example.com/api/schemas/projects/<projectId>/pack-claims \ -H "Authorization: Bearer <token>"The response is pack-centric:
[ { "schemaId": "<schemaId>", "name": "legal-entities", "version": "1.0.0", "blueprints": [ { "blueprintId": "<blueprintId>", "name": "legal", "version": "2.0.0" } ] }]Schema migrations
Section titled “Schema migrations”Schemas can carry an optional migrations block that declares how to migrate live graph data when upgrading from a previous version. The server uses this block to run an async background migration job automatically when you install the new schema version.
migrations block (YAML)
Section titled “migrations block (YAML)”name: legal-entitiesversion: "2.0.0"description: Legal entity schema v2
objectTypeSchemas: Agreement: type: object properties: title: { type: string } parties: { type: array, items: { type: string } } signed_at: { type: string, format: date } # renamed from signedDate jurisdiction: { type: string } required: [title]
# Optional migrations block — describes what changed since from_versionmigrations: from_version: "1.0.0" # previous version this schema upgrades from type_renames: - from: Contract to: Agreement property_renames: - type_name: Agreement from: signedDate to: signed_at removed_properties: - type_name: Agreement name: legacyId| Field | Description |
|---|---|
from_version |
Required. The schema version this migration upgrades from. Must match an installed schema with that name and version. |
type_renames |
List of {from, to} type-name renames to apply to live data. |
property_renames |
List of {type_name, from, to} property-key renames. |
removed_properties |
List of {type_name, name} properties that are intentionally removed. Data is archived, not warned. |
How auto-migration works
Section titled “How auto-migration works”- You install the new schema version (
memory schemas install --file schema-v2.yaml). - If the schema has a
migrations.from_versionblock, the server resolves a migration chain (walking backwards throughfrom_versionpointers, up to 10 hops). - A preview runs synchronously on a sample of objects to assess risk (
safe/cautious/risky/dangerous). - If risk is
dangerousand--forceis not set, the assign returnsmigration_status: "blocked"— no job is enqueued. - Otherwise an async background job is created. The job ID is returned in the assign response.
- The worker executes each hop sequentially, updating
objects_migrated/objects_failedas it goes.
Risk levels:
| Level | Meaning |
|---|---|
safe |
No data loss; only renames and additions. |
cautious |
Minor type coercions that could lose precision. |
risky |
1–2 properties will be dropped (not in removed_properties). Use --force. |
dangerous |
3+ properties will be dropped. Use --force. |
Migrating types (System B — SQL renames)
Section titled “Migrating types (System B — SQL renames)”The original migrate endpoint performs direct SQL renames on graph data without schema-version tracking. Use this for quick, low-risk renames when you don’t have schema version metadata:
curl -X POST https://api.example.com/api/schemas/projects/<projectId>/migrate \ -H "Authorization: Bearer <token>" \ -H "Content-Type: application/json" \ -d '{ "type_renames": [ {"from": "OldType", "to": "NewType"} ], "property_renames": [ {"type_name": "NewType", "from": "oldProp", "to": "newProp"} ], "dry_run": true }'Migration REST API (System A — async, schema-version aware)
Section titled “Migration REST API (System A — async, schema-version aware)”Preview a migration
Section titled “Preview a migration”Runs migration logic on all matching objects in dry-run mode and returns aggregated risk results without making any changes.
curl -X POST https://api.example.com/api/schemas/projects/<projectId>/migrate/preview \ -H "Authorization: Bearer <token>" \ -H "Content-Type: application/json" \ -d '{"from_schema_id": "<fromId>", "to_schema_id": "<toId>"}'Execute a migration
Section titled “Execute a migration”curl -X POST https://api.example.com/api/schemas/projects/<projectId>/migrate/execute \ -H "Authorization: Bearer <token>" \ -H "Content-Type: application/json" \ -d '{ "from_schema_id": "<fromId>", "to_schema_id": "<toId>", "force": false, "max_objects": 0 }'Rollback a migration
Section titled “Rollback a migration”Restores property data from migration_archive and, optionally, the type registry.
to_version names the target version of the migration being undone — it must
match an archive entry’s to_version (the version the objects were migrated to),
not the version to roll back to. The objects are restored to that archive’s
from_version. A request whose to_version matches no migration archive returns
a 404.
curl -X POST https://api.example.com/api/schemas/projects/<projectId>/migrate/rollback \ -H "Authorization: Bearer <token>" \ -H "Content-Type: application/json" \ -d '{"to_version": "2.0.0", "restore_type_registry": false}'Commit (prune) migration archive
Section titled “Commit (prune) migration archive”Strips archive entries up to and including through_version from all project objects, freeing storage.
curl -X POST https://api.example.com/api/schemas/projects/<projectId>/migrate/commit \ -H "Authorization: Bearer <token>" \ -H "Content-Type: application/json" \ -d '{"through_version": "1.0.0"}'Get migration job status
Section titled “Get migration job status”curl https://api.example.com/api/schemas/projects/<projectId>/migration-jobs/<jobId> \ -H "Authorization: Bearer <token>"CLI reference
Section titled “CLI reference”The memory schemas subcommands cover all schema management operations.
YAML support
Section titled “YAML support”Schema files can be written in JSON or YAML. The CLI detects format by file extension (.yaml / .yml for YAML, otherwise JSON):
memory schemas create --file my-schema.yaml --project <projectId>memory schemas create --file my-schema.json --project <projectId>Diff two schemas
Section titled “Diff two schemas”Compare two schema files (JSON or YAML) side-by-side without making any API calls:
memory schemas diff schema-v1.yaml schema-v2.yamlThe diff output includes a property-level breakdown (added/removed/type-changed properties per type) and a suggested migrations: YAML block auto-populated from the detected differences. Copy this block into your new schema file as a starting point.
Install a schema (with auto-migration)
Section titled “Install a schema (with auto-migration)”When the schema file contains a migrations block, the server automatically enqueues a background migration job after the assignment is created.
# Install and auto-migrate (job ID printed; TTY streams progress)memory schemas install --file schema-v2.yaml --project <projectId>
# Force migration even if risk level is dangerousmemory schemas install --file schema-v2.yaml --project <projectId> --force
# Uninstall the from-version schema automatically after the migration chain completesmemory schemas install --file schema-v2.yaml --project <projectId> --auto-uninstall
# Dry run: preview migration without installingmemory schemas install --file schema-v2.yaml --project <projectId> --dry-runIf a migration job is started and stdout is a TTY, the CLI automatically polls and streams progress until the job completes. In non-TTY mode it prints:
Migration job started: <jobId>Run: memory schemas migrate job --job-id <jobId> --waitShow the merged type registry for a project:
memory schemas compiled-types --project <projectId>
# Include schema source metadata and shadow warningsmemory schemas compiled-types --project <projectId> --verbose--verbose adds schema_id, schema_name, schema_version, and a shadowed flag (true when two installed schemas define the same type name).
Schema history
Section titled “Schema history”List all schema assignments including uninstalled ones:
memory schemas history --project <projectId>Migrate types
Section titled “Migrate types”System B — SQL renames (no version tracking)
Section titled “System B — SQL renames (no version tracking)”Rename types or property keys across live data in a single transaction:
# Dry run (preview only)memory schemas migrate --project <projectId> \ --rename-type OldType=NewType \ --rename-prop "NewType.oldProp=newProp" \ --dry-run
# Applymemory schemas migrate --project <projectId> \ --rename-type OldType=NewType \ --rename-prop "NewType.oldProp=newProp"System A — Schema-version-aware migration subcommands
Section titled “System A — Schema-version-aware migration subcommands”Preview risk before migrating:
memory schemas migrate preview \ --project <projectId> \ --from <fromSchemaId> \ --to <toSchemaId>Execute a migration (with TTY confirmation for risky/dangerous):
memory schemas migrate execute \ --project <projectId> \ --from <fromSchemaId> \ --to <toSchemaId> \ --force # skip confirmation for risky/dangerous --max-objects 500 # limit batch size (0 = no limit)Rollback a migration (undo the migration whose target version is 2.0.0):
memory schemas migrate rollback \ --project <projectId> \ --to-version 2.0.0 \ --restore-registry # also reinstall old schema types--to-version names the migration’s target version (the archive’s to_version),
not the version to return to; objects are restored to the archive’s from_version.
Prune migration archive entries (commit):
memory schemas migrate commit \ --project <projectId> \ --through-version 1.0.0Poll a background migration job:
# Check status oncememory schemas migrate job --project <projectId> --job-id <jobId>
# Block until complete, streaming progressmemory schemas migrate job --project <projectId> --job-id <jobId> --waitBulk uninstall
Section titled “Bulk uninstall”# Uninstall all schemas except named ones (comma-separated)memory schemas uninstall --project <projectId> --all-except "core,legal-entities"
# Keep only the most recent version of each schema namememory schemas uninstall --project <projectId> --keep-latest
# Preview what would be uninstalled (no changes made)memory schemas uninstall --project <projectId> --all-except "core" --dry-runMCP tools
Section titled “MCP tools”The following MCP tools are available for schema management:
| Tool | Description |
|---|---|
schema-list |
List schemas owned by the project (search, paging, include_deprecated) |
schema-get |
Get one schema with its type definitions, UI configs, extraction prompts |
schema-list-available |
Browse schemas available to install |
schema-list-installed |
List installed schemas (excludes uninstalled) |
schema-assign |
Install a schema into the project |
schema-assignment-update |
Enable/disable an assignment |
schema-uninstall |
Uninstall a schema assignment |
schema-create |
Create a new schema (pack) in the registry; runs the same schema-definition guard as the REST create/update endpoints |
schema-delete |
Delete a project-owned schema from the registry |
schema-history |
Full installation history including uninstalled schemas |
schema-compiled-types |
Merged type registry; use verbose: true for shadow metadata |
schema-version |
Current schema version plus type and relationship counts |
schema-icon-list |
Valid Lucide icon names for ui_configs.<type>.icon |
schema-migrate-preview |
Preview migration risk across all objects (dry-run) |
schema-migrate-execute |
Execute a schema-version-aware migration |
schema-migrate-rollback |
Rollback live data to a previous schema version |
schema-migrate-commit |
Prune migration archive entries up to a given version |
schema-migration-job-status |
Get the status of an async migration job |
migration-archive-list |
List migration archive entries for a project |
migration-archive-get |
Get one archived migration entry |
schema-migration-preview |
Legacy preview by from_version/to_version; prefer schema-migrate-preview |
Blueprints
Section titled “Blueprints”A blueprint bundles schema packs, agent definitions, skills, and seed data so a project can apply them as a versioned unit. Applying a blueprint is the normal way to install a built-in pack; the registry (browse, draft, publish, version, apply, unapply) is reachable over MCP and REST, and a directory or GitHub repo can be applied with the CLI.
See Blueprints for the lifecycle, manifest shape, the MCP tool table, and the CLI reference. To install a local directory:
memory blueprints install ./my-schema-dir --project <projectId>