search operations

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

search.query

Search every plane of the caller's Loom content in one call.

POST /v1/search.query · MCP loom_search · 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	'-'	The writing or reading agent; '-' or '*' means any agent where the op allows it.
query	str	required	The question, searched in every plane at once.
top_k	int	5	At most this many hits per section (1-100); the tracker leg caps it at 10.
tags	list[str]	(computed)	Tag filter for the memory and knowledge legs; profile and conversations ignore it.
namespace_scope	Literal['this', 'all_mine']	'all_mine'	this searches namespace only; all_mine (the default) also reads the caller's own memory-kind namespaces.
recipe	Literal['', 'fast', 'balanced', 'quality', 'verbatim', 'code', 'temporal', 'graph']	''	Named memory.search preset for the memory leg (fast, balanced, quality, ...); empty = the server's defaults.
bodies	Literal['full', 'excerpt', 'none', 'unit']	'excerpt'	What each memory hit carries: excerpt (the first 200 characters; a decision or a constraint as stored), full (the stored clip), none (keys and scores only) or unit (whole values within a budget).
explain	bool	False	Every section unwithheld, and the ranking terms of each memory hit.
page	str	''	A memory.next_page handle from an earlier answer, to read the memory leg's next page; empty = the first page.

Output field	Type	Meaning
tracker	dict[str, Any] \| None	The duplicate-check verdict for a defect-shaped query under a code scope; absent otherwise, or when that leg failed or timed out.
memory	dict[str, Any]	The memory.search result plus the scoped repository's decisions, rendered as a reader block, without the hits the calibration flagged below its threshold (unless every hit is flagged).
knowledge	dict[str, Any]	The knowledge.search result plus the scoped repository's documents, hits below the knowledge similarity floor dropped.
profile	dict[str, Any]	Profile sections whose label or text matches the query words, then by meaning.
conversations	dict[str, Any]	The conversation.search hits under results.
withheld	dict[str, Any] \| None	Counts of hits held back per section by the answer-first rules, with reason; absent when nothing was withheld or explain is set.
namespaces_skipped	list[str]	The caller's namespaces no leg read because the fan-out stops at memory_search_fanout_max_namespaces; address one by name to search it.