---
title: profile operations
---

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

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

## `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` | `''` | Require this content hash, or 'absent' for no unexpired section under the exact identity (concrete agent required); mismatch is 409, empty skips checking. |

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

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