---
title: working_memory operations
---

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

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

## `working_memory.append`

Append text to a working-memory block, creating it when missing.

`POST /v1/working_memory.append` · MCP `loom_working_memory_append` · role `writer` · write

| 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. |
| `block_key` | `str` | `'scratchpad'` | The block to append to; a missing block is created with the default size cap. |
| `addition` | `str` | required | Text added at the end of the block. |
| `separator` | `str` | `'\n'` | Put between the existing text and `addition`; unused when the block is new. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `block_key` | `str` | The block that was written. |
| `version` | `int` | Version of the row this write created (a nanosecond timestamp). |
| `char_limit` | `int` | The block's size cap in characters after the write. |
| `value_length` | `int` | Length of the block's content after the write, in characters. |
| `fill_ratio` | `float` | `value_length / char_limit`, to three places; a write that would pass 1.0 is refused. |

## `working_memory.delete`

Delete one working-memory block.

`POST /v1/working_memory.delete` · MCP `loom_working_memory_delete` · 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. |
| `block_key` | `str` | `'scratchpad'` | The block to delete. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `deleted` | `bool` | False when the scope held no live block under this key. |
| `block_key` | `str` | Echo of the input `block_key`. |

## `working_memory.get`

Fetch one working-memory block by key.

`POST /v1/working_memory.get` · MCP `loom_working_memory_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. |
| `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. |
| `block_key` | `str` | `'scratchpad'` | The block to read, within the caller's (agent, user, session, run) scope. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `found` | `bool` | False when the scope holds no live block under this key; the rest is then defaults. |
| `block_key` | `str` | Echo of the block's key. |
| `content` | `str` | The block's text; empty when not found. |
| `char_limit` | `int` | The block's size cap in characters; a write past it is refused with 422. |
| `version` | `int` | Version of the block's current row (a nanosecond timestamp); 0 when not found. |
| `updated_at` | `datetime \| None` | When the block was last written; None when not found. |
| `fill_ratio` | `float` | len(content) / char_limit. |

## `working_memory.render`

Render working-memory blocks as XML or markdown. context.pack already includes this section; direct render is mainly for SDK or custom orchestration code.

`POST /v1/working_memory.render` · MCP `loom_working_memory_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. |
| `block_keys` | `list[str]` | *(computed)* | Only these blocks (at most 20); empty = every live block in the scope. |
| `format` | `Literal['xml', 'markdown']` | `'xml'` | `xml` wraps each block in a `<working-memory block=...>` tag; `markdown` puts it under a `## <block_key>` heading. |
| `limit` | `int` | `20` | At most this many blocks, in `block_key` order (1-100). |

| Output field | Type | Meaning |
| --- | --- | --- |
| `rendered` | `str` | The blocks as one text in the chosen `format`; empty when the scope has none. |
| `blocks` | `list[WorkingMemoryBlock]` | The rendered blocks with their size caps and versions, in `block_key` order. |
| `block_count` | `int` | How many blocks were rendered. |
| `total_chars` | `int` | Sum of the blocks' content lengths, in characters. |

## `working_memory.replace`

Replace exact text inside a working-memory block.

`POST /v1/working_memory.replace` · MCP `loom_working_memory_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. |
| `block_key` | `str` | `'scratchpad'` | The block to edit; a missing block is a 404. |
| `old` | `str` | required | Text to find; every occurrence is replaced, and absent text is a 422. |
| `new` | `str` | `''` | Replacement text; empty deletes the occurrences of `old`. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `block_key` | `str` | The block that was written. |
| `version` | `int` | Version of the row this write created (a nanosecond timestamp). |
| `char_limit` | `int` | The block's size cap in characters after the write. |
| `value_length` | `int` | Length of the block's content after the write, in characters. |
| `fill_ratio` | `float` | `value_length / char_limit`, to three places; a write that would pass 1.0 is refused. |

## `working_memory.set`

Overwrite one working-memory block.

`POST /v1/working_memory.set` · MCP `loom_working_memory_set` · role `writer` · idempotent

| 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. |
| `block_key` | `str` | `'scratchpad'` | The block to write, within the caller's (agent, user, session, run) scope. |
| `content` | `str` | `''` | The block's whole new text, replacing what it held; empty stores an empty block. |
| `char_limit` | `int` | `4096` | The block's size cap in characters; `content` longer than it is refused with 422. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `block_key` | `str` | The block that was written. |
| `version` | `int` | Version of the row this write created (a nanosecond timestamp). |
| `char_limit` | `int` | The block's size cap in characters after the write. |
| `value_length` | `int` | Length of the block's content after the write, in characters. |
| `fill_ratio` | `float` | `value_length / char_limit`, to three places; a write that would pass 1.0 is refused. |

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