working_memory operations

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

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.