---
title: memory_schema operations
---

The exact fields each `memory_schema.*` operation takes and returns.

<!-- Generated by `python scripts/codegen/docs_reference.py` from the op registry; edit the models, not this page. -->

Every op is `POST /v1/<op>` over HTTP and the MCP tool `loom_<op>`. The identity fields (`org`, `namespace`, `agent`, `user_id`, `session_id`) are filled from the token and the MCP session when a transport can; for an HTTP call with no token on a single-user server, the install's org on every op but `code.*` and `tracker.*` (which keep their plane's), and on [some ops](/docs/reference/http-api#request) its namespace and agent; see [identities and namespaces](/docs/concepts/identities-and-namespaces). The [operations index](/docs/reference/operations) explains role, kind and the MCP `all` listing. Unknown input fields are served and named in `ignored_args`.

<!-- prettier-ignore-start -->

## `memory_schema.approve`

Approve (make active) or reject a proposed record schema.

`POST /v1/memory_schema.approve` · MCP `loom_memory_schema_approve` · role `admin` · write · audited · not listed under the MCP `all` toolset

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | required | The tenant (first element of the identity tuple). |
| `namespace` | `str` | required | The namespace the op reads or writes. |
| `name` | `str` | required | The schema to decide on, by name. |
| `decision` | `Literal['approve', 'reject']` | required | `approve` makes the schema `active`; `reject` marks it `rejected`. |
| `reviewed_by` | `str` | `''` | Reviewer fallback, stored only when the request has no principal to stamp. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `name` | `str` | The schema name, echoed. |
| `status` | `str` | The status now stored (`active` or `rejected`); empty when no schema has the name. |
| `updated` | `bool` | False when no schema has the name and nothing was written. |

## `memory_schema.list`

List a namespace's record schemas, active ones only unless `include_proposed`.

`POST /v1/memory_schema.list` · MCP `loom_memory_schema_list` · role `viewer` · read · not listed under the MCP `all` toolset

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | required | The tenant (first element of the identity tuple). |
| `namespace` | `str` | required | The namespace the op reads or writes. |
| `include_proposed` | `bool` | `False` | False lists `active` schemas only; True lists every non-tombstoned status. |
| `limit` | `int` | `100` | At most this many schemas (1–500), ordered by name. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `schemas` | `list[MemorySchemaSummary]` | The namespace's schemas with their fields, ordered by name. |

## `memory_schema.propose`

Register a record schema as `proposed`, for an admin to approve or reject.

`POST /v1/memory_schema.propose` · MCP `loom_memory_schema_propose` · role `writer` · write · audited · not listed under the MCP `all` toolset

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | required | The tenant (first element of the identity tuple). |
| `namespace` | `str` | required | The namespace the op reads or writes. |
| `name` | `str` | required | The schema's name; memory.record.write and queries address it by this name. |
| `description` | `str` | `''` | Free text stored with the schema and returned by memory_schema.list. |
| `fields` | `list[SchemaFieldInput]` | required | The field contracts (1–64); a bad type, constraint or pattern is rejected at register. |
| `created_by` | `str` | `''` | Author fallback, stored only when the request has no principal to stamp. |
| `status` | `Literal['active', 'proposed']` | `'active'` | For `memory_schema.register`, `active` is writable at once and `proposed` waits for approval; `memory_schema.propose` always stores `proposed`, regardless of this field. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `schema_id` | `str` | The new schema's id; every register call mints a fresh one. |
| `name` | `str` | The schema name, echoed. |
| `field_count` | `int` | How many fields the schema declares. |
| `status` | `str` | The stored status: `active` or `proposed` for `memory_schema.register`, always `proposed` for `memory_schema.propose`. |

## `memory_schema.register`

Register a typed-record schema (named fields) for a namespace; typed records are then written against it.

`POST /v1/memory_schema.register` · MCP `loom_memory_schema_register` · role `admin` · write · audited

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | required | The tenant (first element of the identity tuple). |
| `namespace` | `str` | required | The namespace the op reads or writes. |
| `name` | `str` | required | The schema's name; memory.record.write and queries address it by this name. |
| `description` | `str` | `''` | Free text stored with the schema and returned by memory_schema.list. |
| `fields` | `list[SchemaFieldInput]` | required | The field contracts (1–64); a bad type, constraint or pattern is rejected at register. |
| `created_by` | `str` | `''` | Author fallback, stored only when the request has no principal to stamp. |
| `status` | `Literal['active', 'proposed']` | `'active'` | For `memory_schema.register`, `active` is writable at once and `proposed` waits for approval; `memory_schema.propose` always stores `proposed`, regardless of this field. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `schema_id` | `str` | The new schema's id; every register call mints a fresh one. |
| `name` | `str` | The schema name, echoed. |
| `field_count` | `int` | How many fields the schema declares. |
| `status` | `str` | The stored status: `active` or `proposed` for `memory_schema.register`, always `proposed` for `memory_schema.propose`. |

<!-- prettier-ignore-end -->
