---
title: procedure operations
---

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

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

## `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. |

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