facts operations

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

facts.expire_by_adapter

Tombstone graph-level triples emitted by a specific extractor (e.g. a buggy adapter) without touching the parent memories.

POST /v1/facts.expire_by_adapter · MCP loom_facts_expire_by_adapter · role admin · 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.
adapter_name	str	required	Extractor adapter whose triples to delete (exact match on adapter_name).
max_confidence	float	1.0	Confidence ceiling: only expire triples with confidence < threshold. 1.0 = no ceiling.

Output field	Type	Meaning
expired_triples	int	Rows removed from loom.entity_triples; 0 when none matched.
expired_triple_memories	int	Rows removed from loom.entity_triple_memories (triple -> source key links).

facts.list

Subject-relation-object triples from the entity graph, filtered by subject / object / relation / entity; optional source keys.

POST /v1/facts.list · MCP loom_facts_list · 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.
subject	str \| None	None	Only triples with this subject, canonicalised like a write (or as given, lowered); subject/object/relation AND together, and unfiltered returns top triples by co_occur.
object	str \| None	None	Only triples with this object, canonicalised like a write (or as given, lowered); ignored when entity is set.
relation	str \| None	None	Only triples with this relation, normalised the way writes store it (works_at -> work_at).
entity	str \| None	None	Triples with this subject or object, canonicalised like a write (or as given, lowered).
limit	int	50	At most this many triples; the server caps it at 500.
sort_by	Literal['co_occur', 'recency']	'co_occur'	co_occur ranks by observation count, then recency; recency by last_seen first.
include_sources	bool	False	Fan out each triple to source memory_keys — extra CH round-trip, off by default.
include_source_status	bool	False	With the keys, read each source row's status (one more round-trip) and flag a triple that is open while every row behind it is superseded — the triple plane lagging a row update (writes close these at write time; this read shows any that…
min_co_occur	int	1	Drop triples observed fewer than this many times (summed over their rows).
as_of	datetime \| None	None	Only triples whose (valid_from, valid_to) interval contains this timestamp.
provenance	list[Literal['extracted', 'inferred', 'facet']] \| None	None	Provenance tiers to keep: any of "extracted", "inferred", "facet".

Output field	Type	Meaning
rows	list[FactRow]	The matching triples in sort_by order.
truncated	bool	True when more triples matched than limit.

facts.path

Find how two entities are connected: a bounded bidirectional breadth-first search over the same validity-filtered edge set facts.traverse walks, meeting in the middle.

POST /v1/facts.path · MCP loom_facts_path · 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.
entity_a	str	required	One end of the path; canonicalised like the write path before the search.
entity_b	str	required	The other end; canonicalised the same way.
max_hops	int	3	Longest path to look for, counted end to end (1–4).
top_k_per_hop	int	20	Neighbours each frontier entity keeps per hop, strongest first (1–100).
min_co_occur	int	1	Ignore edges whose summed observation count is below this.
as_of	datetime \| None	None	Only edges valid at this time; None keeps the edges still valid now.
relations	list[str]	(computed)	Typed graph (loom.entity_triples) instead of co-occurrence: relations restricts to those labels, labeled=True walks every typed edge.
labeled	bool	False	True walks every typed edge (see relations above); False walks co-occurrence.

Output field	Type	Meaning
entity_a	str	canonical form searched
entity_b	str	Canonical form searched for the other end.
found	bool	True when a path within max_hops exists; also True when both ends canonicalise alike.
path	list[str]	entity_a ... entity_b when found; [] otherwise
edges	list[_PathEdge]	len(path) - 1 when found
hops	int	len(edges) when found; hops explored when not
truncated	bool	True when the answer may be incomplete: the hop budget ran out with unexplored frontier, or per-hop top-k trimming dropped neighbours on the way.

facts.related

Return the entities that co-occur with input.entity via any relation, ranked by total co_occur (DESC).

POST /v1/facts.related · MCP loom_facts_related · 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.
entity	str	required	The entity whose neighbours to list, matched as subject or object: as the write path stores it (canonicalised) or as given, lowered.
top_k	int	20	At most this many neighbours; the server caps it at 200.
as_of	datetime \| None	None	Only edges valid at this time; None keeps the edges still valid now.

Output field	Type	Meaning
entity	str	entity canonicalised like a write, or "" when it has no canonical form.
related	list[_RelatedEntity]	Neighbours of entity over any relation, by summed co_occur descending.

facts.traverse

Walk the entity co-occurrence graph N hops out from a seed, one bounded query per hop.

POST /v1/facts.traverse · MCP loom_facts_traverse · 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.
seed_entity	str	required	Entity to walk from; canonicalised like the write path (articles, possessives, plurals) before the lookup.
max_hops	int	2	How many hops out from the seed to walk (1–4).
top_k_per_hop	int	20	Neighbours each frontier entity keeps per hop, strongest first (1–100).
min_co_occur	int	1	Ignore edges whose summed observation count is below this.
max_nodes	int	400	Hard ceiling on returned nodes across all hops.
as_of	datetime \| None	None	Only edges valid at this time; None keeps the edges still valid now.
relations	list[str]	(computed)	Walk the TYPED graph (loom.entity_triples: subject -relation-> object, with provenance in entity_triple_memories) instead of the co-occurrence table.
labeled	bool	False	True walks every typed edge (see relations above); False walks co-occurrence.
hub_degree	int \| None	None	Hub-expansion policy.
hub_share	float \| None	None	Relative hub rule: a reached node is a hub when the edge that reached it explains at most this share of the node's own degree — via_co_occur / degree, the probability of the parent given the node.
rank_by	Literal['co_occur', 'specificity', 'cosine'] \| None	None	What the per-hop trim ranks by.

Output field	Type	Meaning
seed	str	the entity actually walked from (canonicalised; see handler)
seed_community_id	int \| None	Community of the seed in the latest community pass; None when unclustered.
nodes	list[_TraversalNode]	ordered by hop ASC, then cumulative_weight DESC
truncated	bool	True when max_nodes cut the walk short.
hubs	list[str]	Entities the hub policy reported but did not expand, in the order the walk met them; empty when the policy is off or no node crossed the threshold.