procedure operations

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

procedure.add

Register a procedural memory — a 'how to do X' recipe with structured (name, situation, steps) fields.

POST /v1/procedure.add · MCP loom_procedure_add · 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	'-'	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.
name	str	required	Procedure name; the memory key is procedure_<slug of name>, so the same name rewrites it.
situation	str	required	When the procedure applies (its precondition); this text drives procedure.match.
steps	list[str]	required	Two at least: a single step is a lesson, not a procedure (the miner holds the same line).
tags	list[str]	(computed)	Caller tags stored on the procedure; the row also gets the tag procedure.
metadata	dict[str, Any]	(computed)	Optional structured metadata (preconditions as key-value, expected outputs, ...).
graph	dict[str, Any] \| None	None	Optional executable graph (nodes = steps / memory / consolidation / decision, edges = dep / dataflow / branch).

Output field	Type	Meaning
memory_key	str	Key of the procedure row (procedure_<slug>).
memory_id	str	Id of the memory version written.
version	int	Version number of the written row.

procedure.evolve

Consolidate a procedure's accumulated run traces into an improved graph: rank the proven path by SUCCESSFUL traversals, flag steps no run ever used as dead ends, flag steps and transitions that sit…

POST /v1/procedure.evolve · MCP loom_procedure_evolve · 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	'-'	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.
memory_key	str	required	Key of the procedure to evolve (procedure_<slug>).
min_runs	int	3	Minimum folded-in runs before pruning acts on the evidence.
gate_mode	Literal['sprt', 'margin']	'sprt'	Acceptance gate for a pending revision.
gate_min_runs	int	3	Runs needed on the revision under test before any verdict.
gate_margin	float	0.05	margin mode: the success-rate drop that reverts.
gate_min_drop	float	0.15	sprt mode: the drop worth reverting over, error rates, and the run count past which the point estimate decides.
gate_alpha	float	0.05	sprt mode: false-revert error rate; lower needs more evidence before reverting.
gate_beta	float	0.2	sprt mode: missed-drop error rate; lower needs more evidence before accepting.
gate_max_runs	int	50	sprt mode: runs on the revision after which the point estimate decides.
strike_limit	int \| None	None	Consecutive failed runs that quarantine the procedure; None = LOOM_PROCEDURE_STRIKE_LIMIT (3), 0 = never.
gate_cost_tolerance	float	0.25	Cost tie-break on an accepted revision: revert when its successful runs cost more than this fraction above the prior revision's (first of duration, steps, tokens both reported); both sides need gate_cost_min_samples costed successes…
gate_cost_min_samples	int \| None	None	Costed successful runs each side needs for the cost check; None = gate_min_runs.

Output field	Type	Meaning
memory_key	str	Key of the evolved procedure.
version	int	Version of the procedure row this call wrote.
revision	int	The procedure's topology revision after this call (a revert opens a new one).
changed	bool	True when this call changed the graph's flags or quarantine state.
template	bool	True when the procedure is now a reusable template (stable, mostly succeeds, not quarantined).
folded_runs	int	Ledger rows folded into the graph by this call.
gate	Literal['none', 'undecided', 'accept', 'revert']	Acceptance gate on a pending revision: none (nothing pending), undecided (not enough runs yet), accept, revert.
gate_mode	str	The gate mode used (sprt or margin); "" when no revision was pending.
gate_llr	float	sprt: accumulated log-likelihood ratio (positive favours "the revision made things worse"); the verdict fires when it crosses a boundary.
gate_before	dict[str, int]	{total, ok} prior revision
gate_after	dict[str, int]	{total, ok} revision under test
gate_cost_before	dict[str, float]	Median cost of successful runs per side, and why a revision that passed the success gate was still reverted ("cost").
gate_cost_after	dict[str, float]	Median cost of the successful runs on the revision under test.
gate_reason	str	success or cost on a revert; "" otherwise.
dead_end_steps	list[str]	Step texts no folded run ever traversed (demoted from the linear steps).
fail_prone_steps	list[str]	Outcome contrast: steps / transitions disproportionately on failed runs (failure share >= procedure base failure rate + margin, enough runs).
fail_prone_transitions	list[str]	Transitions disproportionately on failed runs, as src -> dst node ids.
run_stats	dict[str, int]	The procedure's folded {total, ok} after this call.
strikes	int	Consecutive failed runs at the end of the trace log, and whether the procedure is struck out.
quarantined	bool	True when the procedure is struck out (see strike_limit).
retention	dict[str, float]	Success retention over the trace log: pairs of consecutive runs whose first succeeded, how many of their seconds did, and the rate.

procedure.fork

Copy a procedure from a namespace the caller can read into the request namespace, with its evidence reset.

POST /v1/procedure.fork · MCP loom_procedure_fork · role writer · write · audited · 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	target (the request namespace; WRITER enforced by the op)
agent	str	'-'	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.
from_namespace	str	required	Namespace to copy from; the caller needs read access to it.
from_org	str	''	defaults to org
memory_key	str	required	Key of the procedure to copy in from_namespace.
new_name	str	''	Rename on the way in (the memory key derives from the name).
reason	str	''	Why the procedure was adopted; kept in forked_from.

Output field	Type	Meaning
memory_key	str	Key of the new procedure in the target namespace.
version	int	Version of the row written.
name	str	Name of the new procedure (new_name or the source's).
steps	list[str]	The copied steps.
forked_from	dict[str, Any]	Lineage: source org, namespace, key, revision, digest, template flag, run stats, who forked it, why, and when.

procedure.list

Enumerate registered procedures in the namespace (optionally filtered by memory_key prefix or tags).

POST /v1/procedure.list · MCP loom_procedure_list · 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	'*'	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.
prefix	str	''	Only procedures whose key starts with procedure_ + this; "" lists all.
tags	list[str]	(computed)	Only procedures carrying at least one of these tags; empty = no tag filter.
limit	int	50	At most this many procedure rows are read (the server caps it at 500).

Output field	Type	Meaning
procedures	list[_ProcedureSummary]	The namespace's procedures (name, situation, tags, key, creation time).

procedure.locate

Where am I in this procedure, and what comes next?

POST /v1/procedure.locate · MCP loom_procedure_locate · 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	'*'	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.
memory_key	str	required	Key of the procedure the agent is following (procedure_<slug>).
at	str	''	Where the agent is: a node id or the tool name of its most recent call.
recent_path	list[str]	(computed)	The agent's recent node ids or tool names in this run, oldest first; feeds revisits and looping.
hops	int	2	How far ahead to expose. 2 is enough for the next decision; more is more tokens.
include_notes	bool	True	Attach recent failure notes from the ledger for transitions ahead.
max_notes	int	5	At most this many failure notes; 0 attaches none.

Output field	Type	Meaning
memory_key	str	Key of the procedure read.
name	str	The procedure's name.
status	Literal['template', 'exercised', 'authored', 'candidate', 'quarantined']	template, exercised, authored, candidate or quarantined.
matched	bool	True when at (or the last of recent_path) names a node of the graph.
active	dict[str, Any] \| None	The node the agent is at; None when not matched.
hops	list[list[dict[str, Any]]]	hops[0] = one step ahead, hops[1] = two ahead, ... (dead ends omitted).
entry_nodes	list[str]	When not matched: node ids with no incoming edge, where the procedure starts.
dominant_next	list[str]	Next node ids along the proven path from the active node.
revisits	dict[str, int]	Trajectory window: visits per node in this run, whether the active node is being revisited, and the untaken exits from it.
looping	bool	True when the active node already appears earlier in recent_path.
exits	list[str]	When looping: node ids reachable from the active node not yet visited in this run; empty otherwise.
failure_notes	list[dict[str, Any]]	Notes agents left on failed runs that died on a transition ahead.
rendered	str	Deterministic text of the above, ready to drop into a prompt.
run_stats	dict[str, int]	The procedure's folded {total, ok}.
for_agent	dict[str, int]	{total, ok} for the calling agent; empty for *, - or no runs.

procedure.match

Find procedures whose situation field is semantically closest to the caller's described situation.

POST /v1/procedure.match · MCP loom_procedure_match · 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	'*'	default fan-out — procedures from any agent in scope
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.
situation	str	required	The state the agent is in; compared against each procedure's stored situation.
top_k	int	5	At most this many candidates are searched (1–50); filters may return fewer.
tags	list[str]	(computed)	Only procedures carrying at least one of these tags; empty = no tag filter.
namespace_scope	Literal['this', 'all_mine']	'all_mine'	all_mine also searches the caller's own namespaces (up to the fan-out cap); this only namespace.
templates_only	bool	False	When true, only return procedures promoted to reusable templates (proven, well-exercised workflow topologies).
include_candidates	bool	True	Candidates are procedures nothing has exercised yet AND that no human authored.
include_quarantined	bool	False	A quarantined procedure (its last strike_limit runs all failed) is dropped unless asked for; returned last, labelled.
recent_tools	list[str]	(computed)	The tools the agent has called recently in this task.
tool_boost	float	0.2	Weight of tool_overlap in the fused score; 0 ignores recent_tools.
utility_weight	float \| None	None	Weight on the ledger-derived utility term of the fused score: score = similarity + tool_boost*overlap + weight * ((ok+1)/(total+2) - 0.5).
goal	str \| None	None	The objective the agent is pursuing, as distinct from the state it is in.

Output field	Type	Meaning
matches	list[_ProcedureMatch]	Matching procedures, by status tier (candidates and quarantined last), then score.
matched	int	The hit rate on the ledger — how many matched, the top procedure and its score (out_matched / out_procedure_key / out_score).
procedure_key	str	Memory key of the top match; "" when nothing matched.
score	float	Fused score of the top match; 0 when nothing matched.

procedure.record_run

Report one execution of a procedure so loom can learn which path actually works.

POST /v1/procedure.record_run · MCP loom_procedure_record_run · 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	'-'	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.
memory_key	str	required	Key of the procedure that was run (procedure_<slug>).
path	list[str]	(computed)	Ordered node ids the agent actually visited this run.
ok	bool	True	Whether the run succeeded.
note	str	''	Free-text note on the run (why it failed, …); procedure.locate shows failed runs' notes.
ts	str	''	Not stored: the ledger stamps each run with the server's time.
steps_taken	int \| None	None	What the run cost.
duration_ms	int	0	How long the run took, in milliseconds; 0 = unknown.
tokens	int	0	Tokens the run spent; 0 = unknown.

Output field	Type	Meaning
memory_key	str	Key of the procedure the run was recorded against.
version	int	Always 0: the run goes to the ledger, the procedure row is not rewritten.
run_stats	dict[str, int]	{total, ok, unfolded} including this run; unfolded counts ledger runs procedure.evolve has not folded yet.

procedure.revise

Propose an edited topology for a procedure — you are the refiner.

POST /v1/procedure.revise · MCP loom_procedure_revise · role writer · write · audited · 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	'-'	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.
memory_key	str	required	Key of the procedure to revise (procedure_<slug>).
graph	dict[str, Any]	required	The proposed topology (full graph; nodes keep their ids where unchanged so their statistics carry over).
reason	str	''	Why: what the failed runs showed and what this edit changes.
force	bool	False	Propose a topology the gate already rejected anyway.

Output field	Type	Meaning
memory_key	str	Key of the revised procedure.
version	int	Version of the procedure row this call wrote.
revision	int	The new revision number; runs recorded from now on count against it.
prior_revision	int	The revision it replaces (restored if the gate reverts).
digest	str	Hash of the proposed topology; the gate uses it to recognise a rejected one.
steps	list[str]	The linear step list derived from the new graph.