decision operations

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

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.