---
title: namespace operations
---

The exact fields each `namespace.*` 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](/reference/http-api#request) its namespace and agent; see [identities and namespaces](/concepts/identities-and-namespaces). The [operations index](/reference/operations) explains role, kind and the MCP `all` listing. Unknown input fields are served and named in `ignored_args`.

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

## `namespace.audit`

Usage report for one namespace: is it being used as a memory, or as an object store?

`POST /v1/namespace.audit` · MCP `loom_namespace_audit` · role `viewer` · read

| 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. |
| `window_seconds` | `int` | `604800` | Ledger window for the read/search counts and the hot-key join. |
| `sample_limit` | `int` | `5` | Sample rows per finding, 0 to 50; samples carry keys and counts, never values. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `org` | `str` | The tenant (first element of the identity tuple). |
| `namespace` | `str` | The namespace the op reads or writes. |
| `computed_at` | `datetime` | When the report started (UTC, to the second): a cited revision updated at or after it may have changed mid-report. |
| `window_seconds` | `int` | The ledger window the counts cover, in seconds (echoes the request). |
| `summary` | `NamespaceAuditSummary` | Size and access totals of the namespace the findings are measured against. |
| `findings` | `list[NamespaceAuditFinding]` | One entry per check that ran; a clean check is an `info` finding with count 0. |
| `skipped` | `list[str]` | Rules that could not run (checks, summary reads, the evidence read), as "name: reason". |
| `coverage` | `ReportCoverage` | Which rules ran and which were skipped: checks, summary reads, the evidence read. |
| `healthy` | `bool` | No critical finding. |
| `criticals` | `int` | Findings graded `critical`. |
| `warnings` | `int` | Findings graded `warning`. |
| `infos` | `int` | Findings graded `info`, clean checks included. |

## `namespace.browse`

Discover public namespaces in the org; anyone can join returned rows via namespace.join.

`POST /v1/namespace.browse` · MCP `loom_namespace_browse` · role `viewer` · read

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | required | The tenant (first element of the identity tuple). |
| `query` | `str` | `''` | Substring match on the namespace name or description, or on a public namespace's guide summary. |
| `limit` | `int` | `50` | At most this many rows, most members first; `closed` rows are dropped after the limit. |
| `include_closed` | `bool` | `False` | `closed` rows (bench/scratch) are omitted unless asked for; `kinds` narrows the directory (e.g. ["code"] for the Code view). |
| `kinds` | `list[str]` | *(computed)* | Only these kinds (`memory`, `code`, `bench`); empty lists every kind. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `rows` | `list[_BrowseEntry]` | Joinable namespaces (public rows and code namespaces), most members first, each with the caller's standing. |

## `namespace.cancel_request`

Withdraw the caller's own pending elevation request.

`POST /v1/namespace.cancel_request` · MCP `loom_namespace_cancel_request` · role `viewer` · idempotent · 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. |
| `subject` | `str \| None` | `None` | Whose request to withdraw, used only when the request carries no authenticated caller (dev mode). |

| Output field | Type | Meaning |
| --- | --- | --- |
| `cancelled` | `bool` | False if there was no pending request |
| `namespace` | `str` | The namespace the op reads or writes. |
| `cleared_role` | `Literal['viewer', 'writer', 'admin'] \| None` | The role the withdrawn request asked for; None when nothing was cancelled. |
| `cancelled_at` | `datetime \| None` | When the request was withdrawn (UTC); None when nothing was cancelled. |

## `namespace.delete`

Tombstone a namespace and stop accepting writes against it; the document sources it retires are named in `sources_retired`, also when `deleted` is false.

`POST /v1/namespace.delete` · MCP `loom_namespace_delete` · role `admin` · idempotent · 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. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `deleted` | `bool` | True if the row went from active=true → false |
| `namespace` | `str` | The namespace the op reads or writes. |
| `updated_at` | `datetime` | When the soft-delete was written, or the time of the call when nothing changed. |
| `sources_retired` | `list[str]` | The document sources this delete retired, also when `deleted` is false. |

## `namespace.get`

Fetch one namespace's metadata + settings (owner, visibility, feature flags, retention).

`POST /v1/namespace.get` · MCP `loom_namespace_get` · role `viewer` · read

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

| Output field | Type | Meaning |
| --- | --- | --- |
| `found` | `bool` | False when the namespace has no registry row; every other field is then None. |
| `namespace` | `str` | The namespace the op reads or writes. |
| `kind` | `str \| None` | `memory`, `code` (an indexed repository branch) or `bench` (a throwaway harness). |
| `owner_email` | `str \| None` | The subject named as owner when the namespace was registered. |
| `description` | `str \| None` | Free-text description; empty when none was set. |
| `tags` | `list[str] \| None` | The namespace's labels, including markers such as `auto-registered`. |
| `active` | `bool \| None` | False once the namespace is soft-deleted (its data stays in place). |
| `conversation_logging_enabled` | `bool \| None` | True when conversation transcripts are captured; false when off or never set. |
| `capture_generation_io` | `bool \| None` | Whether prompt/completion text goes to Langfuse; None inherits the server default. |
| `coverage_sweep` | `bool \| None` | Forces the extraction coverage sweep on or off; None lets the density gates decide. |
| `consolidation_enabled` | `bool \| None` | True when background `memory.consolidate` runs on this namespace. |
| `daily_cost_cap_usd` | `float \| None` | Upstream spend cap per rolling 24 hours, in USD; 0 inherits the global cap. |
| `daily_user_cost_cap_usd` | `float \| None` | Separate rolling-24h cap for each named user_id, USD; 0 inherits the server default. |
| `budget_alert_inbox` | `str \| None` | Task inbox owned by this namespace for budget warnings; empty disables them. |
| `conflict_threshold` | `float \| None` | Cosine at which a write is flagged `conflicted`; None inherits the server threshold. |
| `retention_days` | `int \| None` | Rows older than this many days are deleted, except memory, document and chunk rows under the Postgres authority; 0 inherits the global retention. |
| `warm_days` | `int \| None` | Rows older than this many days move to the warm tier; 0 inherits the global tiering. |
| `visibility` | `Literal['private', 'public'] \| None` | `private` (members only) or `public` (readable org-wide, listed by `namespace.browse`). |
| `requires_approval` | `bool \| None` | True when writer/admin self-joins wait for an admin's approval. |
| `join_policy` | `str \| None` | The stored word and the resolved one (inherit folded). |
| `effective_join_policy` | `str \| None` | `open`, `approval` or `closed`: the join rule in force once `inherit` is resolved. |
| `retrieval_defaults` | `dict[str, Any] \| None` | The set retrieval knobs; None when the namespace has none. |
| `rerank_endpoint` | `str \| None` | The reranker `memory.search` uses (a builtin or a configured endpoint's name); empty when none. |
| `classify_endpoint` | `str \| None` | URL `memory.set(classify=true)` calls to classify a write; empty when none. |
| `default_conflict_policy` | `str \| None` | How close writes are settled: `auto_reinforce` (the default when unset), `manual_review`, `newest_wins` or `append_only`. |
| `proposal_policy` | `ProposalPolicy \| None` | How proposals (`memory.set proposed=true`) are decided; the manual default when unset. |
| `code_change_policy` | `Literal['retire_removed', 'flag', 'revise'] \| None` | How reads treat the namespace's code-linked memories when their code changes: `retire_removed` (the default), `flag` or `revise`. |
| `tag_registry` | `list[dict[str, Any]] \| None` | Per-tag configuration rows (retention, dedup threshold, hot quota, conflict policy); empty when none are registered. |
| `classification` | `Literal['standard', 'restricted'] \| None` | `standard` or `restricted` (loom.namespaces.classification). |
| `guide_revision` | `int \| None` | The current revision of the namespace's guide, the `expected_revision` of its next `namespace.guide_set`; 0 when it never had one. |
| `guide_summary` | `str \| None` | The guide's one-line summary; empty when there is no guide or it was cleared. |
| `created_at` | `datetime \| None` | When the namespace was first registered (UTC). |
| `updated_at` | `datetime \| None` | When the registry row was last written (UTC). |

## `namespace.guide_get`

The namespace's guide: Markdown its writers keep on what it holds, its key layout and what its tags mean.

`POST /v1/namespace.guide_get` · MCP `loom_namespace_guide_get` · 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. |
| `revision` | `int` | `0` | A past revision to read; 0 (the default) reads the current guide. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `found` | `bool` | False when the revision read does not exist or cleared the guide. |
| `revision` | `int` | The revision read, the current one being what `namespace.guide_set` takes as `expected_revision`; 0 when that revision (or any guide) does not exist. |
| `content` | `str` | The guide in Markdown: what the namespace holds, its key layout, what its tags mean. |
| `summary` | `str` | One line for directories (`namespace.browse`) and the session-start pack. |
| `note` | `str` | The writer's note on what this revision changed. |
| `updated_by` | `str` | The actor (`human:<subject>` or `process:<subject>`) that wrote the revision. |
| `updated_at` | `datetime \| None` | When the revision was written (UTC); None when the namespace never had a guide. |

## `namespace.guide_history`

The guide's revisions, newest first, with summary, note, writer and length.

`POST /v1/namespace.guide_history` · MCP `loom_namespace_guide_history` · 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. |
| `limit` | `int` | `20` | Newest revisions to list, at most 200. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `revisions` | `list[_GuideRevision]` | Newest first; read one whole with `namespace.guide_get` and its `revision`. |

## `namespace.guide_set`

Save a new revision of the namespace's guide after you change one of its conventions: the whole text, a `note`, and `expected_revision` = the revision you read.

`POST /v1/namespace.guide_set` · MCP `loom_namespace_guide_set` · role `writer` · idempotent · 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. |
| `content` | `str` | required | The whole new guide in Markdown, at most 32,000 characters; "" clears it. |
| `summary` | `str \| None` | `None` | One line, at most 300 characters, that a directory shows for the namespace; left out, the current summary is kept, and "" removes it. |
| `expected_revision` | `int` | required | The revision this edit was made from (0 when there is no guide yet); a guide that has moved past it refuses the write and answers with its current text. |
| `note` | `str` | `''` | What this revision changes and why, at most 500 characters. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `written` | `bool` | True when this call wrote a new revision. |
| `conflict` | `bool` | True when the guide moved past `expected_revision` and this save's text differs from it: nothing was written, and `current` holds the guide to merge into. |
| `revision` | `int` | The current revision after the call (the one written, or the one that refused it), which the next edit passes as `expected_revision`. |
| `current` | `NamespaceGuideGetOutput \| None` | On a conflict, the current guide; otherwise None. |

## `namespace.inventory`

What one namespace holds and who appears in it, with what was not counted.

`POST /v1/namespace.inventory` · MCP `loom_namespace_inventory` · 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. |
| `read_scope` | `Literal['namespace', 'own_user', 'own_session']` | `'namespace'` | `own_user` / `own_session` bound the memory and run counts and the observed populations to `user_id` (and `session_id`); documents and members stay namespace-wide, records and integrations are not counted. |
| `user_id` | `str \| None` | `None` | The user `own_user` / `own_session` count; ignored under `namespace`. |
| `session_id` | `str \| None` | `None` | The session `own_session` counts; ignored under the other scopes. |
| `population_limit` | `int` | `20` | At most this many entries in each observed population (most rows first). |

| Output field | Type | Meaning |
| --- | --- | --- |
| `scope` | `InventoryScope` | The boundary every count was read under. |
| `sections` | `list[InventorySection]` | One per plane, in a fixed order: memories, records, documents, runs, integrations. |
| `populations` | `list[InventoryPopulation]` | Members, then the agents, authors and subjects observed on live memory rows. |
| `capabilities` | `list[InventoryCapability]` | Whether a real model and a real embedder serve this process (a keyed model without its key is served by the fake). |
| `computed_at` | `datetime` | When the reads started. |

## `namespace.join`

Self-add as a viewer on a public namespace.

`POST /v1/namespace.join` · MCP `loom_namespace_join` · role `viewer` · idempotent · 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. |
| `role` | `Literal['viewer', 'writer', 'admin']` | `'writer'` | Role to self-grant. viewer auto-activates; writer/admin ALWAYS land pending (regardless of requires_approval) — an existing admin approves via grants.approve. |
| `subject` | `str \| None` | `None` | Dev-mode override; ignored when a JWT is present. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `joined` | `bool` | True when this call granted access or recorded an elevation on an existing grant; false for a no-op or a request that left the caller with no access yet. |
| `namespace` | `str` | The namespace the op reads or writes. |
| `role` | `Literal['viewer', 'writer', 'admin']` | The role that actually took effect now. |
| `status` | `str` | `active` when the role took effect, `pending` while a request waits for an admin. |
| `requested_role` | `Literal['viewer', 'writer', 'admin'] \| None` | The role queued for, when a writer/admin request was gated. |
| `pending_admins` | `list[str]` | Active admins who can approve the pending request; empty when nothing is pending. |
| `joined_at` | `datetime` | When the grant row was written; for a no-op, the existing grant's time. |

## `namespace.leave`

Drop the caller's grant on a namespace.

`POST /v1/namespace.leave` · MCP `loom_namespace_leave` · role `viewer` · idempotent · 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. |
| `subject` | `str \| None` | `None` | Who leaves, used only when the request carries no authenticated caller (dev mode). |

| Output field | Type | Meaning |
| --- | --- | --- |
| `left` | `bool` | True when an active grant was revoked; false when the caller held none. |
| `namespace` | `str` | The namespace the op reads or writes. |
| `left_at` | `datetime \| None` | When the grant was revoked (UTC); None when nothing was revoked. |

## `namespace.list`

Enumerate every namespace the caller can see (own + granted + public).

`POST /v1/namespace.list` · MCP `loom_namespace_list` · role `org_admin` · idempotent · not listed under the MCP `all` toolset

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | required | The tenant (first element of the identity tuple). |
| `active_only` | `bool` | `True` | True lists active namespaces only; false includes soft-deleted ones. |
| `tags` | `list[str]` | *(computed)* | ANY-match filter |
| `limit` | `int` | `200` | At most this many rows, in namespace-name order; 1 to 2,000. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `rows` | `list[_NamespaceEntry]` | The org's registry rows matching the filters, in namespace-name order. |

## `namespace.list_categories`

Enumerate registered categories with item counts.

`POST /v1/namespace.list_categories` · MCP `loom_namespace_list_categories` · 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. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `categories` | `list[_CategoryEntry]` | Live categories, most linked memories first, then by name. |

## `namespace.list_mine`

List namespaces the caller is a member of (own + granted).

`POST /v1/namespace.list_mine` · MCP `loom_namespace_list_mine` · role `viewer` · read

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | required | The tenant (first element of the identity tuple). |
| `subject` | `str \| None` | `None` | Whose memberships to list, used only when the request carries no authenticated caller (dev mode). |

| Output field | Type | Meaning |
| --- | --- | --- |
| `rows` | `list[_MineEntry]` | The caller's grant rows (newest first), then namespaces named only by the token (role `jwt`), then those a client token reads through its creator. |

## `namespace.list_ontology`

List the ontology terms (entity and relation kinds) registered for a namespace.

`POST /v1/namespace.list_ontology` · MCP `loom_namespace_list_ontology` · 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. |
| `kind` | `Literal['entity_type', 'relation_verb', 'attribute'] \| None` | `None` | None = both |
| `status` | `Literal['accepted', 'pending', 'tombstoned'] \| None` | `'accepted'` | Only entries with this status; None lists every status. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `entries` | `list[_OntologyEntry]` | The matching entries, ordered by kind, then name. |
| `org` | `str` | The tenant (first element of the identity tuple). |
| `namespace` | `str` | The namespace the op reads or writes. |

## `namespace.mark_seen`

Acknowledge a new-invitation indicator on a namespace.

`POST /v1/namespace.mark_seen` · MCP `loom_namespace_mark_seen` · role `viewer` · idempotent · 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. |
| `subject` | `str \| None` | `None` | Dev-mode fallback; the JWT sub is authoritative in production. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `namespace` | `str` | The namespace the op reads or writes. |
| `seen_at` | `datetime` | When the visit was recorded (UTC). |

## `namespace.register`

Create a shared memory workspace within an org; caller becomes admin.

`POST /v1/namespace.register` · MCP `loom_namespace_register` · role `viewer` · idempotent · audited

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | required | The tenant (first element of the identity tuple). |
| `namespace` | `str` | required | Recommend kebab-case, e.g. eng-tooling |
| `owner_email` | `str` | required | The namespace's owner; an account with a login (an email, or an agent's claim code) keeps its stored owner exactly, so send that value back to update settings. |
| `description` | `str \| None` | `None` | Every setting left None (or omitted) keeps the stored value, and a fresh row takes the default named here, so a re-register that sends only what it changes resets nothing. |
| `kind` | `Literal['memory', 'code', 'bench'] \| None` | `None` | None = keep the existing row's kind (a fresh row is classified by name: `bench` under a bench prefix, else `memory`), so a settings-only re-register never demotes a code namespace to memory. |
| `tags` | `list[str]` | *(computed)* | Labels on the namespace; the list is replaced whole, so a register that omits it clears the stored tags. |
| `traffic_class` | `Literal['production', 'interactive', 'bench'] \| None` | `None` | The class requests into this namespace run as when the token carries no `traffic_class` claim. |
| `active` | `bool \| None` | `None` | fresh: True; True reactivates a soft-deleted row |
| `conversation_logging_enabled` | `bool \| None` | `None` | None = preserve the current value (a privacy toggle must not be silently re-enabled by a settings-form re-register that omits it), and False for a namespace that doesn't exist yet — transcript capture is opt-in. |
| `capture_generation_io` | `bool \| None` | `None` | Consent for sending this namespace's prompt/completion text to Langfuse. |
| `coverage_sweep` | `bool \| None` | `None` | The extraction coverage sweep per namespace. |
| `consolidation_enabled` | `bool \| None` | `None` | background memory.consolidate |
| `daily_cost_cap_usd` | `float \| None` | `None` | 0.0 inherits the global cap. |
| `daily_user_cost_cap_usd` | `float \| None` | `None` | Separate rolling-24h cap for each named user_id, USD; 0 inherits the server default. |
| `budget_alert_inbox` | `str \| None` | `None` | Existing task inbox owned by this namespace for budget warnings; empty disables them. |
| `conflict_threshold` | `float \| None` | `None` | Omitted keeps the stored threshold; an explicit null inherits LOOM_CONFLICT_THRESHOLD. |
| `retention_days` | `int \| None` | `None` | Days rows are kept, except memory, document and chunk rows under the Postgres authority; 0 inherits the global retention, a positive value overrides it per (org, namespace). |
| `warm_days` | `int \| None` | `None` | Rows older than this many days move to the warm storage tier; 0 inherits the global tiering setting. |
| `visibility` | `Literal['private', 'public'] \| None` | `None` | `private` = members-only; `public` = read-by-anyone-in-org + appears in namespace.browse. |
| `requires_approval` | `bool \| None` | `None` | When true, writer/admin self-joins go pending; viewer stays auto-approved. |
| `join_policy` | `Literal['inherit', 'open', 'approval', 'closed'] \| None` | `None` | How the namespace is joined. |
| `retrieval_defaults` | `NamespaceRetrievalDefaults \| None` | `None` | The retrieval knobs an unpinned memory.search on this namespace runs with (mode, k, auto_touch, include_tags, bodies, reinforcement_weight). |
| `rerank_endpoint` | `str \| None` | `None` | Optional reranker for memory.search: "builtin:openai[:<model>]", "builtin:cohere[:<model>]" or the name of an endpoint in LOOM_RERANK_ENDPOINTS_JSON (a URL is refused); empty ⇒ cosine + entity_boost. builtin:cohere is refused while the… |
| `rerank_prompt_template` | `str \| None` | `None` | Text forwarded as `prompt_template` in every call to `rerank_endpoint`. |
| `classify_endpoint` | `str \| None` | `None` | Classifier for memory.set(classify=True): https at a public address (or a host in LOOM_MEMORY_CLASSIFY_PRIVATE_HOSTS), no credentials; while the gateway is required its host must be in LOOM_INFERENCE_GATEWAY_HOSTS, and at a listed gateway… |
| `classify_prompt_template` | `str \| None` | `None` | Text forwarded as `prompt_template` in every call to `classify_endpoint`. |
| `tag_registry` | `list[NamespaceTypeConfig]` | *(computed)* | Per-tag TTL + dedup_threshold registry, matched on tags at memory.set time. |
| `default_conflict_policy` | `Literal['auto_reinforce', 'manual_review', 'newest_wins', 'append_only'] \| None` | `None` | fresh: auto_reinforce |
| `proposal_policy` | `ProposalPolicy \| None` | `None` | How proposals (facts written with memory.set proposed=true) are decided. |
| `code_change_policy` | `Literal['retire_removed', 'flag', 'revise'] \| None` | `None` | How reads treat this namespace's code-linked memories when their code changes: `retire_removed` (the default: search leaves out a memory whose code is all gone, and serves it again when the code returns), `flag` (only the links are marked)… |

| Output field | Type | Meaning |
| --- | --- | --- |
| `registered` | `bool` | False = no change; record already matched |
| `namespace` | `str` | The namespace the op reads or writes. |
| `updated_at` | `datetime` | When the registry row was written (UTC, whole seconds). |
| `visibility` | `Literal['private', 'public']` | The visibility stored by this write (`private` for a restricted namespace). |

## `namespace.register_category`

Register a category in a namespace.

`POST /v1/namespace.register_category` · MCP `loom_namespace_register_category` · 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 category's name; its id derives from it, so registering a name again updates it. |
| `description` | `str` | `''` | One line on what belongs in the category; embedded with the name and summary. |
| `summary` | `str` | `''` | Longer text embedded with the name; search hits show its first 280 characters. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `category_id` | `str` | Stable 32-hex id derived from org, namespace and name. |
| `embedded` | `bool` | False when the embedder failed: the category is stored but `search_categories` never returns it. |

## `namespace.register_ontology`

Register an entity type or relation verb for a namespace.

`POST /v1/namespace.register_ontology` · MCP `loom_namespace_register_ontology` · role `admin` · idempotent · 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. |
| `kind` | `Literal['entity_type', 'relation_verb', 'attribute']` | required | `entity_type`, `relation_verb` or `attribute` (a memory-key attribute). |
| `name` | `str` | required | The name the extractor should prefer; registering it again replaces the entry. |
| `description` | `str` | `''` | Free text on what the name means. |
| `status` | `Literal['accepted', 'pending', 'tombstoned']` | `'accepted'` | `accepted` names are read by the extractor; `pending` ones are on file only; `tombstoned` retires a name. |
| `cardinality` | `Literal['', 'one', 'many']` | `''` | relation_verb and attribute. "one": a subject holds ONE current object — a newer value closes the older interval on write (employer, location, status). "many": never auto-closed, even if the seed list would ("addresses" the verb vs the… |

| Output field | Type | Meaning |
| --- | --- | --- |
| `registered` | `bool` | Always true once the entry is written. |
| `org` | `str` | The tenant (first element of the identity tuple). |
| `namespace` | `str` | The namespace the op reads or writes. |
| `kind` | `str` | The kind registered (echoes the request). |
| `name` | `str` | The name registered (echoes the request). |
| `status` | `str` | The status stored (echoes the request). |

## `namespace.restore`

Restore a snapshot payload into a target namespace.

`POST /v1/namespace.restore` · MCP `loom_namespace_restore` · role `viewer` · idempotent · audited · not listed under the MCP `all` toolset

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | required | The tenant (first element of the identity tuple). |
| `target_namespace` | `str` | required | Where the payload is written, never a collection (`col-…`, `@me`) or a mirror's name (`acl-` and 24 hex digits); created (with the caller as admin) when absent, and reactivated when soft-deleted. |
| `payload` | `NamespaceSnapshotOutput` | required | A `namespace.snapshot` output, unchanged. |
| `rebind_agent` | `str \| None` | `None` | Rebind every memory row's `agent` to this when set; default preserves source. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `restored` | `bool` | False when this `snapshot_id` was already restored into the target (nothing written). |
| `publication_pending` | `bool` | Some memories this call wrote are committed but not yet searchable (Postgres authority): the delivery worker publishes them, and a search waits for it. |
| `target_namespace` | `str` | The namespace written to (echoes the request). |
| `snapshot_id` | `str` | The restored payload's id. |
| `counts` | `dict[str, int]` | `memories`, `types` and `grants` as the payload counted them, and `erased_skipped`, how many of its memories an erasure had removed from the target (always 0 under ClickHouse); on a replay, the counts its first restore recorded. |

## `namespace.rollback`

Return every memory head in a namespace to the version it had at `as_of`.

`POST /v1/namespace.rollback` · MCP `loom_namespace_rollback` · 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. |
| `as_of` | `datetime` | required | UTC instant to return to. |
| `dry_run` | `bool` | `True` | True reports the plan and writes nothing; false applies it. |
| `memory_keys` | `list[str] \| None` | `None` | Restrict to these keys; None = every key in the namespace. |
| `max_keys` | `int` | `5000` | Upper bound on keys changed per call; the output says when it was hit. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `dry_run` | `bool` | Echoes the request: true when nothing was written. |
| `as_of` | `datetime` | The instant rolled back to, as UTC. |
| `version_at` | `int` | `as_of` as an epoch-nanosecond version: the highest version a key may keep. |
| `reinstate` | `int` | Keys whose head was (or would be) replaced by an older version. |
| `remove` | `int` | Keys created after as_of that were (or would be) tombstoned. |
| `skipped_no_head` | `int` | Keys with history at as_of but no live row (hard-deleted): left alone. |
| `skipped_already_gone` | `int` | Keys created after as_of that are already tombstoned. |
| `truncated` | `bool` | More keys differ than max_keys; call again (or narrow memory_keys). |
| `sample` | `list[dict[str, Any]]` | Up to 20 planned moves (`memory_key`, `agent`, `action`, `version_from`, `version_to`). |
| `applied_at` | `datetime \| None` | When the rollback was written; None on a dry run or when no key differed. |

## `namespace.search_categories`

Cosine-rank the category registry against a query.

`POST /v1/namespace.search_categories` · MCP `loom_namespace_search_categories` · 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. |
| `query` | `str` | required | Text embedded and compared with each category's embedding. |
| `top_k` | `int` | `5` | At most this many categories, nearest first; 1 to 20. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `results` | `list[_CategoryHit]` | Embedded categories nearest to the query first; empty when the query could not be embedded. |

## `namespace.snapshot`

Freeze a namespace's curated state as a portable JSON payload.

`POST /v1/namespace.snapshot` · MCP `loom_namespace_snapshot` · role `admin` · idempotent · 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. |
| `include_embeddings` | `bool` | `False` | Recorded on the snapshot row; the payload carries no vectors either way, so the target re-embeds the restored rows. |
| `include_audit_tail_n` | `int` | `1000` | Recent audit rows to include for provenance; 0 skips. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `snapshot_id` | `str` | A fresh UUID; `namespace.restore` uses it to skip a payload already restored. |
| `org` | `str` | The tenant (first element of the identity tuple). |
| `source_namespace` | `str` | The namespace the payload was read from. |
| `created_at` | `datetime` | When the snapshot was taken (UTC, whole seconds). |
| `memory_count` | `int` | Number of rows in `memories`. |
| `type_count` | `int` | Number of rows in `types`. |
| `grant_count` | `int` | Number of rows in `grants`. |
| `audit_tail_count` | `int` | Number of rows in `audit_tail`. |
| `include_embeddings` | `bool` | Echoes the request; the payload carries no vectors either way. |
| `memories` | `list[_SnapshotMemoryRow]` | Every non-tombstoned memory row, oldest first, whatever its status. |
| `types` | `list[_SnapshotTypeRow]` | The namespace's per-tag configuration rows. |
| `grants` | `list[_SnapshotGrantRow]` | Active grants only; pending requests and revoked grants are left out. |
| `audit_tail` | `list[_SnapshotAuditRow]` | The newest audit rows of the namespace, newest first, at most `include_audit_tail_n`. |

## `namespace.summary`

Aggregated read-only metadata for one namespace, for a single-shot dashboard tile (category/memory counts, top entities, recent activity).

`POST /v1/namespace.summary` · MCP `loom_namespace_summary` · role `viewer` · read

| 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. |
| `top_entities_limit` | `int` | `10` | At most this many entities in `top_entities`; 0 skips the lookup. |
| `activity_seconds` | `int` | `86400` | The window the activity counts cover, in seconds; 1 minute to 30 days. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `org` | `str` | The tenant (first element of the identity tuple). |
| `namespace` | `str` | The namespace the op reads or writes. |
| `total_memories` | `int` | Live (non-tombstoned) rows in the namespace. |
| `type_counts` | `list[_NamespaceTypeCount]` | Live rows per memory type, most first. |
| `top_entities` | `list[_NamespaceTopEntity]` | Entities with the highest co-occurrence degree over live graph edges. |
| `recent_writes` | `int` | memory write calls in the activity window |
| `recent_recalls` | `int` | memory.search calls in the window |
| `distinct_agents` | `int` | Distinct agents with a ledger row in the activity window; the dashboard's and the assistant toolset's calls are left out, as they are of the recalls above, except a change to a memory (a set, a delete, a pin). |
| `last_activity_at` | `datetime \| None` | Time of the newest ledger row in the activity window, the same calls left out. |

## `namespace.taxonomy`

The de-facto taxonomy of a namespace — tags + entities across its memories.

`POST /v1/namespace.taxonomy` · MCP `loom_namespace_taxonomy` · role `viewer` · read

| 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. |
| `top_n_tags` | `int` | `50` | Top-N by frequency descending; rare values are cut. |
| `top_n_entities` | `int` | `50` | Most frequent entities to return; write-path sentinel values are left out. |
| `top_n_communities` | `int` | `12` | Largest entity communities to return (0 = skip the lookup). |

| Output field | Type | Meaning |
| --- | --- | --- |
| `tags` | `list[_TaxonomyEntry]` | The most frequent tags on live rows, most used first, at most `top_n_tags`. |
| `entities` | `list[_TaxonomyEntry]` | The most frequent entities on live rows, most used first, at most `top_n_entities`. |
| `memory_count` | `int` | Live (non-tombstoned) rows in the namespace. |
| `memory_types` | `list[_TaxonomyEntry]` | memory_types present in the namespace, with counts. |
| `communities` | `list[_TaxonomyCommunity]` | Topic clusters from the entity graph, largest first; [] until the entity_communities worker has run. |
| `communities_computed_at` | `str` | When the returned communities were computed; empty when none were returned. |

## `namespace.tune`

Draft changes to a namespace's extraction rules, categories and guide from what its rows and the audit show, and to the chunking and extractor settings from what its documents show.

`POST /v1/namespace.tune` · MCP `loom_namespace_tune` · 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. |
| `window_seconds` | `int` | `604800` | Ledger window the audit's usage checks cover, in seconds (default 7 days, 1 hour to 90 days). |
| `sample_limit` | `int` | `5` | Supporting rows cited per proposal, 1 to 20 (default 5). |
| `min_rows` | `int` | `5` | A tag or key prefix on at least this many live rows is drafted: a tag with no category of its name as a category, a prefix the guide does not name into the guide (default 5). |
| `max_category_proposals` | `int` | `5` | Category drafts returned, most used tags first, 0 to 20 (default 5). |

| Output field | Type | Meaning |
| --- | --- | --- |
| `org` | `str` | The tenant (first element of the identity tuple). |
| `namespace` | `str` | The namespace the op reads or writes. |
| `computed_at` | `datetime` | When the drafts were read (UTC). |
| `proposals` | `list[TuneProposal]` | The drafts, extraction instructions first, then categories, the guide, chunking and extractor routes. |
| `guide_revision` | `int \| None` | The guide's current revision (0: none written), which a guide draft's `expected_revision` carries; None when the guide could not be read. |
| `categories_registered` | `int \| None` | Categories registered in the namespace now; None when they could not be read. |
| `extraction_policy` | `str \| None` | The operator extraction policy the namespace's extractions run under (the org's, then the namespace's), for an org admin; None otherwise. |
| `extraction_policy_unavailable` | `str` | Why `extraction_policy` is None, or "". |
| `chunking` | `ChunkingSample \| None` | The namespace's documents re-chunked at the current values, the evidence a chunking draft is judged on; null when the namespace has no live document or the sample could not be read. |
| `skipped` | `list[str]` | Sections that drafted nothing, as "section: reason": a read that failed, or evidence that rules the draft out. |
| `model_used` | `bool` | Proposals use no model: every draft is built from the rows, the documents, the audit and the current settings. |

## `namespace.validate`

Integrity report for one namespace, in one call, shaped for the agent that just wrote to it.

`POST /v1/namespace.validate` · MCP `loom_namespace_validate` · role `viewer` · read

| 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. |
| `sample_limit` | `int` | `5` | Sample rows per finding, 0 to 50; 0 lists none and still counts every finding. |
| `conflict_age_seconds` | `int` | `604800` | A conflicted row older than this is a review that never happened. |
| `confidence_floor` | `float` | `0.5` | Rows below this confidence with no source pointer are the agent's own unqualified inferences — reported as info, not error. |
| `embed_grace_seconds` | `int` | `600` | A memory without a vector younger than this is the embedding worker's normal lag, not a finding. |
| `strict` | `bool` | `False` | True makes `healthy` require zero warnings as well as zero errors. |
| `keys` | `list[str]` | *(computed)* | Scope every check to these memory keys — the keys one session wrote — so a Stop hook can run the report per task at O(session) cost. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `org` | `str` | The tenant (first element of the identity tuple). |
| `namespace` | `str` | The namespace the op reads or writes. |
| `healthy` | `bool` | errors == 0 (and warnings == 0 when strict). |
| `errors` | `int` | Rows flagged by error-severity checks, summed across findings. |
| `warnings` | `int` | Rows flagged by warning-severity checks, summed across findings. |
| `infos` | `int` | Rows flagged by info-severity checks, summed across findings. |
| `findings` | `list[_NamespaceValidateFinding]` | One entry per check that ran, including checks whose count is 0. |
| `skipped` | `list[str]` | Rules that could not run (checks, the evidence read), as "name: reason". |
| `keys_scoped` | `int` | How many keys the report was scoped to (0 = whole namespace), so a caller can tell a per-task report from a full one. |
| `coverage` | `ReportCoverage` | Which rules ran and which were skipped: the checks and the evidence read. |
| `checked_at` | `datetime` | When the report started (UTC, to the second): a cited revision updated at or after it may have changed mid-report. |

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