---
title: decision operations
---

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

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

## `decision.chain`

Trace a decision's causal chain: upstream (what caused or influenced it) and/or downstream (what it went on to cause), up to 4 hops over the authored graph.

`POST /v1/decision.chain` · MCP `loom_decision_chain` · 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. |
| `memory_key` | `str` | required | The key to start the walk from, usually a decision's. |
| `direction` | `Literal['upstream', 'downstream', 'both']` | `'both'` | `upstream` follows what led here, `downstream` what it led to, `both` walks each. |
| `max_hops` | `int` | `3` | How many edges away to walk, 1-4. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `seed` | `str` | The starting key, echoed. |
| `seed_decision` | `DecisionRow \| None` | The seed's decision record; null when the seed is not an active decision. |
| `nodes` | `list[ChainNodeRow]` | Every key reached over `caused`, `influenced` or `derived_from` edges, each once, nearest hop first. |

## `decision.outcome`

Close the loop on a decision once reality has answered: record what actually happened and whether it worked (success).

`POST /v1/decision.outcome` · MCP `loom_decision_outcome` · 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. |
| `memory_key` | `str` | required | The active decision to update; answers 404 when there is none, or when the record's writer has no live decision row under the key. |
| `realized_outcome` | `str` | required | What actually happened, stored on the decision record. |
| `success` | `bool \| None` | `None` | None keeps the record's verdict; True/False sets it and credits (or marks) the deciding run's memories. |
| `agent` | `str` | `'*'` | The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `memory_key` | `str` | The decision's key, echoed. |
| `updated` | `bool` | Always true: a missing decision answers 404 instead. |
| `memories_credited` | `int` | memories credited through the run ledger (run.complete memories_used). |

## `decision.precedents`

BEFORE deciding, ask what was decided in similar situations: semantic search over past decisions (optionally within a category), each with its reasoning, rejected alternatives, and — when known…

`POST /v1/decision.precedents` · MCP `loom_decision_precedents` · 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. |
| `query` | `str` | required | The scenario at hand, phrased as the deciding agent sees it. |
| `category` | `str` | `''` | Only decisions in this category (case-insensitive); "" searches every category. |
| `top_k` | `int` | `5` | At most this many precedents, 1-25. |
| `with_outcome_only` | `bool` | `False` | Only decisions whose realized outcome is known (decision.outcome called). |

| Output field | Type | Meaning |
| --- | --- | --- |
| `precedents` | `list[DecisionRow]` | Active past decisions, the most similar decision statement first. |
| `embedding_model` | `str` | The embedder the underlying memory search used. |

## `decision.record`

Record a DECISION as a first-class object — call it whenever you choose between options that matter later (a vendor, a design, a fix, a rollback).

`POST /v1/decision.record` · MCP `loom_decision_record` · role `writer` · idempotent · 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` | 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 run this decision was made in (run.begin). |
| `category` | `str` | required | category + scenario identify the decision: re-deciding the same scenario supersedes the earlier record (history keeps it). |
| `scenario` | `str` | required | The situation that needed deciding; `decision.precedents` matches a query against the decision's statement, which opens with the scenario. |
| `reasoning` | `str` | required | Why this outcome was chosen. |
| `outcome` | `str` | required | What was decided. |
| `alternatives` | `list[str]` | *(computed)* | What was considered and not chosen — the field every "why not X" question needs and most decision logs omit. |
| `confidence` | `float` | `0.0` | The decider's confidence, 0-1; 0 records none (the memory row and edges then carry 1.0). |
| `stage` | `Literal['decided', 'proposed']` | `'decided'` | "decided" (default), or "proposed" for an option put forward and not yet chosen or built (a proposal, a plan, an action item); unrelated to memory.set's `proposed`, a fact on trial. |
| `decision_maker` | `str` | `''` | Who decided, a person or an agent; "" records the calling `agent`. |
| `caused_by` | `list[str]` | *(computed)* | memory_keys (decisions, facts, procedures) that CAUSED or INFLUENCED this decision; each becomes an authored edge (memory.link) with this call as its evidence. |
| `influenced_by` | `list[str]` | *(computed)* | Keys that shaped the decision without causing it; each becomes an `influenced` edge. |
| `tags` | `list[str]` | *(computed)* | Extra tags on the memory row, beside `decision` and `decision:category:<category>`; a `decision:proposed` tag here is dropped (set it with `stage`). |
| `valid_at` | `datetime \| None` | `None` | Real-world time the decision took effect; None = now. |
| `files` | `list[str] \| None` | `None` | The repo files this decision governs (repo-relative path or bare filename); memory.for_file serves it before an edit of them. |
| `source_class` | `Literal['derived', 'external', 'imported'] \| None` | `None` | Declare that this decision was derived from other content (`derived`) or came from outside (`external`, `imported`). |
| `source_resource_id` | `str` | `''` | The file path, document id or URL this decision was taken from, cited on its hits. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `memory_key` | `str` | The decision's key, derived from category + scenario; pass it to `decision.outcome` and `decision.chain`. |
| `record_id` | `str` | The id of the `decision` record version written. |
| `superseded_prior` | `bool` | True when an active decision for the same category + scenario existed and is now superseded by this one. |
| `edges_written` | `int` | How many `caused` / `influenced` edges were written; a failed link is skipped. |
| `next` | `str` | Plain-text hint naming the follow-up operations. |

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