`profile` operations

The exact fields each profile.* 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.

`profile.activity`

Recent profile reads per agent — "which AI client read my profile, when?".

POST /v1/profile.activity · MCP loom_profile_activity · 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.
`agent`	`str`	required	The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it.
`user_id`	`str`	`'-'`	The end user the row belongs to; `'-'` for none.
`session_id`	`str`	`'-'`	The session or conversation the row belongs to; `'-'` for none.
`run_id`	`str`	`'-'`	The agent run (task scope) the call belongs to; `'-'` for none.
`lookback_days`	`int`	`7`	capped at 30 server-side to bound the partition scan

Output field	Type	Meaning
`entries`	`list[ProfileActivityEntry]`	Agents that read the profile in the window (at most 20), most recent first; the dashboard's own reads are left out.

`profile.append`

WHAT: Atomic append to an existing profile section.

POST /v1/profile.append · MCP loom_profile_append · role writer · write · 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.
`agent`	`str`	required	The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it.
`user_id`	`str`	`'-'`	The end user the row belongs to; `'-'` for none.
`session_id`	`str`	`'-'`	The session or conversation the row belongs to; `'-'` for none.
`run_id`	`str`	`'-'`	The agent run (task scope) the call belongs to; `'-'` for none.
`label`	`str`	required	The section to append to; a missing section is created with the default size cap.
`addition`	`str`	required	Text added at the end of the section.
`separator`	`str`	`'\n'`	Put between the existing text and `addition`; unused when the section is new.

Output field	Type	Meaning
`version`	`int`	Version of the memory row this write created.
`memory_id`	`str`	Id of the memory row the section is stored in.
`content_sha256`	`str`	Content hash of the section after the write; pass it as `if_match_sha256` next time.
`namespace`	`str`	The namespace the op reads or writes.
`label`	`str`	The section that was written.
`char_limit`	`int \\| None`	The section's size cap after the write.
`value_length`	`int`	Length of the JSON-encoded value after the write, the size `char_limit` caps; the gap is the headroom left.

`profile.render`

Render every section in (org, namespace) into one prompt fragment.

POST /v1/profile.render · MCP loom_profile_render · 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.
`agent`	`str`	required	The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it.
`user_id`	`str`	`'-'`	The end user the row belongs to; `'-'` for none.
`session_id`	`str`	`'-'`	The session or conversation the row belongs to; `'-'` for none.
`run_id`	`str`	`'-'`	The agent run (task scope) the call belongs to; `'-'` for none.
`format`	`str`	`'xml'`	"xml" \| "markdown"
`labels`	`list[str] \\| None`	`None`	if set, render only these labels in this order
`scope`	`str`	`'namespace'`	"namespace" (default; fan-out) \| "this_agent"
`read_scope`	`Literal['namespace', 'own_user', 'own_session']`	`'namespace'`	How far the render reaches across USERS (same grammar as memory.search.read_scope, the token's claim is the ceiling).

Output field	Type	Meaning
`rendered`	`str`	The sections as one prompt fragment in the chosen `format`; empty when there are none.
`section_count`	`int`	How many sections were rendered.
`total_chars`	`int`	Length of `rendered` in characters, markup included.
`labels`	`list[str]`	The rendered sections' labels, in render order.

`profile.replace`

WHAT: Substring rewrite within a profile section.

POST /v1/profile.replace · MCP loom_profile_replace · role writer · 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.
`agent`	`str`	required	The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it.
`user_id`	`str`	`'-'`	The end user the row belongs to; `'-'` for none.
`session_id`	`str`	`'-'`	The session or conversation the row belongs to; `'-'` for none.
`run_id`	`str`	`'-'`	The agent run (task scope) the call belongs to; `'-'` for none.
`label`	`str`	required	The section to edit; a missing section is a 404.
`old`	`str`	required	Text to find; every occurrence is replaced, and absent text is a 422.
`new`	`str`	required	Replacement text; empty deletes the occurrences of `old`.

Output field	Type	Meaning
`version`	`int`	Version of the memory row this write created.
`memory_id`	`str`	Id of the memory row the section is stored in.
`content_sha256`	`str`	Content hash of the section after the write; pass it as `if_match_sha256` next time.
`namespace`	`str`	The namespace the op reads or writes.
`label`	`str`	The section that was written.
`char_limit`	`int \\| None`	The section's size cap after the write.
`value_length`	`int`	Length of the JSON-encoded value after the write, the size `char_limit` caps; the gap is the headroom left.

`profile.set`

WHAT: Create or replace a profile section at label.

POST /v1/profile.set · MCP loom_profile_set · role writer · 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.
`agent`	`str`	required	The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it.
`user_id`	`str`	`'-'`	The end user the row belongs to; `'-'` for none.
`session_id`	`str`	`'-'`	The session or conversation the row belongs to; `'-'` for none.
`run_id`	`str`	`'-'`	The agent run (task scope) the call belongs to; `'-'` for none.
`label`	`str`	required	The section's name (its memory key), e.g. `persona`; setting it again replaces its text.
`value`	`str`	required	The section's whole new text.
`char_limit`	`int`	`8192`	The section's size cap, measured on the JSON-encoded value; a longer value is a 422.
`source_trace`	`str`	`''`	Where the section came from; a trace starting with `memory.delete_version:` is refused (that op's tombstone marker).
`if_match_sha256`	`str`	`''`	Write only if the section's current content hash equals this (409 otherwise); empty = no check.

Output field	Type	Meaning
`version`	`int`	Version of the memory row this write created.
`memory_id`	`str`	Id of the memory row the section is stored in.
`content_sha256`	`str`	Content hash of the section after the write; pass it as `if_match_sha256` next time.
`namespace`	`str`	The namespace the op reads or writes.
`label`	`str`	The section that was written.
`char_limit`	`int \\| None`	The section's size cap after the write.
`value_length`	`int`	Length of the JSON-encoded value after the write, the size `char_limit` caps; the gap is the headroom left.

`profile.structured`

The user's structured profile and whether it is current.

POST /v1/profile.structured · MCP loom_profile_structured · 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.
`agent`	`str`	required	The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it.
`user_id`	`str`	`'-'`	The end user the row belongs to; `'-'` for none.
`session_id`	`str`	`'-'`	The session or conversation the row belongs to; `'-'` for none.
`run_id`	`str`	`'-'`	The agent run (task scope) the call belongs to; `'-'` for none.
`read_scope`	`Literal['namespace', 'own_user']`	`'namespace'`	The token's read_scope is the ceiling; the op always reads the one user_id named (or pinned), and own_session is refused.

Output field	Type	Meaning
`status`	`Literal['ready', 'stale', 'pending', 'no_schema']`	ready: current, or all null with no facts; stale: memories or schema changed, or a fact was not served at the build; pending: no live profile (unbuilt, expired, redacted or high); no_schema: none set or it no longer parses.
`profile`	`dict[str, Any]`	Every property of the schema, null where the memories do not settle it ({} under `no_schema`).
`built_at`	`datetime \\| None`	When the build read the profile's sources (a lock or unlock of the key keeps it); None when no row holds it (pending, or ready for a user with no facts).
`memory_id`	`str`	The memory row that holds the profile, whose history is the profile's history; empty when no row holds it (pending, or ready for a user with no facts).
`version`	`int`	The row's version, higher for each rebuild; 0 when no row holds it (pending, or ready for a user with no facts).
`version_text`	`str`	The same version as a decimal string, exact for a JavaScript caller (the number is above 2^53, which JSON.parse rounds): send this one to memory.delete_version.
`schema_sha256`	`str`	The hash of the schema the namespace has now.

profile operations

profile.activity

profile.append

profile.render

profile.replace

profile.set

profile.structured