namespace operations
The exact fields each namespace.* operation takes and returns.
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 its namespace and agent; see identities and namespaces. The operations index explains role, kind and the MCP all listing. Unknown input fields are served and named in ignored_args.
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. |
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. |
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[: |
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); 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. |