context operations

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

context.fetch

Read back a parked result by key: a character slice (offset/limit) or only the lines matching a regex (pattern, with context_lines).

POST /v1/context.fetch · MCP loom_context_fetch · 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.
blob_key	str	required	The key context.offload returned.
offset	int	0	Character offset to start the slice at; with pattern, how many matches to skip.
limit	int	4000	At most this many characters of content per call (1-64000).
pattern	str	''	Regex (RE2 syntax, case-insensitive; no backreferences or lookaround).
context_lines	int	0	With pattern, lines of context shown around each match (0-10); context lines are numbered lineno- and matches lineno:.

Output field	Type	Meaning
found	bool	False when no live, unexpired blob has this key in the namespace.
blob_key	str	Echo of the input blob_key.
content	str	The character slice, or with pattern the matching lines as lineno: text.
content_type	str	Media type stored with the blob.
summary	str	The summary stored with the blob.
total_chars	int	Length of the whole stored content in characters.
total_lines	int	Line count of the whole stored content.
offset	int	Echo of the input offset.
next_offset	int	-1 when the slice (or the match list) is exhausted.
matched_lines	int	With pattern, how many lines of the whole content match; 0 otherwise.
expires_at	datetime \| None	When the blob stops being fetchable; None when not found.

context.offload

Park a large tool result (log, page, diff, query output) outside the model context.

POST /v1/context.offload · MCP loom_context_offload · 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.
content	str	required	The text to park; larger than LOOM_CONTEXT_OFFLOAD_MAX_BYTES (UTF-8 bytes) is a 413.
blob_key	str	''	Empty = content-addressed (blob/<sha256 prefix>): parking the same output twice yields the same key and one stored row.
content_type	str	'text/plain'	Media type stored with the content and returned by context.fetch.
summary	str	''	Caller-provided one-liner (the tool name and what it returned).
ttl_seconds	int	604800	How long the blob stays fetchable, in seconds (1 minute to 90 days).

Output field	Type	Meaning
blob_key	str	The key to fetch the content by: the one given, or blob/<sha256 prefix>.
content_bytes	int	Size of the stored content in UTF-8 bytes.
content_chars	int	Length of the stored content in characters.
sha256	str	SHA-256 hex digest of the content.
summary	str	The summary stored with the blob: the one given, or the content's first 200 characters.
expires_at	datetime	When the blob stops being fetchable.
pointer	str	Ready to stand in for the content in the transcript.

context.pack

A task's memories, decisions and procedures: call it first in each task, unless a Loom hook already put Loom's context in this session.

POST /v1/context.pack · MCP loom_context_pack · 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 user the pack reads for; "-" reads every user in the memories, profile, procedures and runs sections, and the rows filed under no user in the stack and working-memory sections.
session_id	str	'-'	The session the pack reads for; "-" reads every session in the memories section, and the rows filed under no session in the stack and working-memory sections.
run_id	str	'-'	The agent run (task scope) the call belongs to; '-' for none.
query	str	''	Optional task/question used to select relevant memories and docs.
situation	str	''	Optional situation description used to match procedures.
procedure_explore_rate	float \| None	None	Exploration rate for the procedures section; None = 0 (never).
token_budget	int	2000	Size cap of the whole rendered pack in tokens (about 4 characters each); a longer pack is cut and truncated is set.
top_k	int	5	How many hits each search-backed section asks for (procedures and the stack's knowledge layer cap it at 5).
read_scope	Literal['namespace', 'own_user', 'own_session']	'namespace'	Same semantics as memory.search.read_scope; binds to this op's user_id / session_id.
mode	Literal['startup', 'task', 'debug', 'handoff']	'task'	Section budgets and search recipe, with no LLM call in any mode: startup (fast recall; with no query it serves pins and recent memories), task and handoff (balanced), debug (quality).
include_knowledge	bool	False	Add a knowledge section of matching document chunks; needs a query.
include_conversations	bool	False	Add a conversations section of matching past messages; needs a query.
include_runs	bool	False	The runs manifest — one line per recent session of this identity (date, run status and goal, tool calls by kind with errors, files touched, digest), newest first, runs_limit rows.
runs_limit	int	12	How many recent sessions the runs manifest lists when include_runs is set (1-50).
include_chunks	bool	False	Widen the memories search's reranker pool with 20 recent candidates; no effect without a reranker.
section_token_budgets	dict[str, int]	(computed)	Per-section token budgets that override the mode's defaults, keyed by section name; a section never gets fewer than 80 tokens.
block_order	list[str]	(computed)	Optional caller-specified block ordering.
session_block	str	''	The caller's own session bookmark (session:<project>, the plugin's Stop-hook note).
only_sections	list[Literal['working_memory', 'memory_stack', 'profile', 'memories', 'procedures', 'decisions', 'knowledge', 'conversations', 'runs', 'namespace_health', 'namespace_guide', 'mentor']]	(computed)	Restrict the pack to these sections.
include_decisions	bool	True	Decision-typed hits leave the memories block and render as their own tagged section carrying the structured record (scenario, outcome, realized outcome).

Output field	Type	Meaning
rendered	str	The pack as one text: each non-empty section in a <name> tag, in block order, cut to token_budget.
sections	dict[str, str]	Each section's body by name, in block order; sections that rendered nothing are absent.
blocks	list[ContextBlock]	One entry per non-empty section: label, body, token estimate, citations, source count, and priority (its position in block order).
section_meta	dict[str, dict[str, Any]]	Per-section details by name: source count, citations, whether it was cut, its size, its token budget and fill ratio (above 1.0 means it was cut).
section_count	int	How many sections rendered something.
truncated	bool	True when any section, or the whole pack, was cut to its budget.
token_budget	int	Echo of the input token_budget.
mode	str	Echo of the input mode.
tokens_estimate	int	Budget pressure.
fill_ratio	float	tokens_estimate / token_budget, to three places.
stable_sections	list[str]	The leading run of rendered that does not depend on query or situation — the same bytes for every question this identity asks until its working memory, profile or pins change.
stable_prefix_chars	int	Length in characters of that prefix of rendered; 0 when the first section depends on the query.
stable_hash	str	SHA-256 of the stable prefix; empty when stable_prefix_chars is 0.
procedure_keys	list[str]	Procedures the pack put in front of the agent: the "shown" side of the ledger a utility needs.
procedure_keys_withheld	list[str]	Procedures the pack matched and deliberately withheld: the "not shown" side of the same ledger.