Skip to content

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.

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

draft → published → (deprecated)
  • Draft schemas are not visible to projects.
  • Published schemas are project-scoped: a project’s available list 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_id NULL, source = "builtin") shared by every project that applies the blueprint claiming it.
  • Deprecated schemas remain installed on existing projects but cannot be newly assigned.

Terminal window
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.\"]}"
}
}
}'
Terminal window
curl https://api.example.com/api/schemas/<schemaId> \
-H "Authorization: Bearer <token>"
Terminal window
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"}'
Terminal window
curl -X DELETE https://api.example.com/api/schemas/<schemaId> \
-H "Authorization: Bearer <token>"

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

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 — absolute http/https URL with a host; stored trimmed.
  • sha256 (and md5, 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, or 02-01-2006; stored as RFC 3339.
  • time — 24-hour HH:MM (or HH:MM:SS, whose seconds are dropped); stored as HH: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 a country enum 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; integer also 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: Status

Label 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.


Terminal window
curl https://api.example.com/api/schemas/projects/<projectId>/available \
-H "Authorization: Bearer <token>"
Terminal window
curl https://api.example.com/api/schemas/projects/<projectId>/installed \
-H "Authorization: Bearer <token>"
Terminal window
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.

Terminal window
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.

Terminal window
curl -X DELETE https://api.example.com/api/schemas/projects/<projectId>/assignments/<assignmentId> \
-H "Authorization: Bearer <token>"

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.

Terminal window
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.


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.

Terminal window
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.


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.

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 [].

Terminal window
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" }
]
}
]

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.

name: legal-entities
version: "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_version
migrations:
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.
  1. You install the new schema version (memory schemas install --file schema-v2.yaml).
  2. If the schema has a migrations.from_version block, the server resolves a migration chain (walking backwards through from_version pointers, up to 10 hops).
  3. A preview runs synchronously on a sample of objects to assess risk (safe / cautious / risky / dangerous).
  4. If risk is dangerous and --force is not set, the assign returns migration_status: "blocked" — no job is enqueued.
  5. Otherwise an async background job is created. The job ID is returned in the assign response.
  6. The worker executes each hop sequentially, updating objects_migrated / objects_failed as 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:

Terminal window
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)”

Runs migration logic on all matching objects in dry-run mode and returns aggregated risk results without making any changes.

Terminal window
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>"}'
Terminal window
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
}'

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.

Terminal window
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}'

Strips archive entries up to and including through_version from all project objects, freeing storage.

Terminal window
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"}'
Terminal window
curl https://api.example.com/api/schemas/projects/<projectId>/migration-jobs/<jobId> \
-H "Authorization: Bearer <token>"

The memory schemas subcommands cover all schema management operations.

Schema files can be written in JSON or YAML. The CLI detects format by file extension (.yaml / .yml for YAML, otherwise JSON):

Terminal window
memory schemas create --file my-schema.yaml --project <projectId>
memory schemas create --file my-schema.json --project <projectId>

Compare two schema files (JSON or YAML) side-by-side without making any API calls:

Terminal window
memory schemas diff schema-v1.yaml schema-v2.yaml

The 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.

When the schema file contains a migrations block, the server automatically enqueues a background migration job after the assignment is created.

Terminal window
# 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 dangerous
memory schemas install --file schema-v2.yaml --project <projectId> --force
# Uninstall the from-version schema automatically after the migration chain completes
memory schemas install --file schema-v2.yaml --project <projectId> --auto-uninstall
# Dry run: preview migration without installing
memory schemas install --file schema-v2.yaml --project <projectId> --dry-run

If 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> --wait

Show the merged type registry for a project:

Terminal window
memory schemas compiled-types --project <projectId>
# Include schema source metadata and shadow warnings
memory 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).

List all schema assignments including uninstalled ones:

Terminal window
memory schemas history --project <projectId>

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:

Terminal window
# Dry run (preview only)
memory schemas migrate --project <projectId> \
--rename-type OldType=NewType \
--rename-prop "NewType.oldProp=newProp" \
--dry-run
# Apply
memory 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:

Terminal window
memory schemas migrate preview \
--project <projectId> \
--from <fromSchemaId> \
--to <toSchemaId>

Execute a migration (with TTY confirmation for risky/dangerous):

Terminal window
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):

Terminal window
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):

Terminal window
memory schemas migrate commit \
--project <projectId> \
--through-version 1.0.0

Poll a background migration job:

Terminal window
# Check status once
memory schemas migrate job --project <projectId> --job-id <jobId>
# Block until complete, streaming progress
memory schemas migrate job --project <projectId> --job-id <jobId> --wait
Terminal window
# 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 name
memory schemas uninstall --project <projectId> --keep-latest
# Preview what would be uninstalled (no changes made)
memory schemas uninstall --project <projectId> --all-except "core" --dry-run

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

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:

Terminal window
memory blueprints install ./my-schema-dir --project <projectId>