---
title: facts operations
---

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

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

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

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