# LoomThread

A thread: one memory. Weak alone, powerful when woven.

Its standing in the loom is its `salience`, `weight × (1 − fray)`. Time alone never changes it: a thread frays only when it is put in front of an agent and goes unused, and tightens again when it is used. A thread accessed yesterday and one accessed five years ago stand equal if both still matter. The one exception is a thread that says when it stops holding (`until`): after that it is no longer woken into or offered.

Threads are never deleted by forgetting. A cut releases the words and leaves a knot (`knot`); a reframe leaves a seam (`seams`). Only a tenant admin's erasure removes a thread, and that exists for data-subject erasure, not for memory.

**Kind:** an object, used in responses.

## Fields

Every field is present in a response; empty ones are `null`.

| Field | Type | Description |
|---|---|---|
| `loomId` | `uuid` | The loom that holds the thread. |
| `content` | `string` | The thread's words. Empty once cut; the knot keeps the essence. |
| `kind` | [`ThreadKind`](https://docs.maitento.com/reference/types/thread-kind.md) | What kind of memory it is. |
| `strand` | [`ThreadStrand`](https://docs.maitento.com/reference/types/thread-strand.md) | Warp (foundational, never frays) or weft (contextual, can fray). |
| `weight` | `number` | 0..1: emotional significance, importance, meaning. |
| `fray` | `number` | 0..1: how loose the thread has worked through disuse. Warp never frays. |
| `decayRate` | [`DecayRate`](https://docs.maitento.com/reference/types/decay-rate.md) | How quickly it frays when it is offered and goes unused. |
| `subjects` | `string[]` | Who or what the thread is about, as named in conversation ("Ada", "the billing service"). |
| `subjectKeys` | `string[]` | The `subjects`, normalised (lowercase, single-spaced) for matching. |
| `tags` | `string[]` | Free-form tags. |
| `cues` | `string[]` | Words the thread waits for (normalised: lowercase, single-spaced). When someone says one, the thread comes back to the agent that holds it: "remind me when the cello comes up". |
| `visibility` | [`ThreadVisibility`](https://docs.maitento.com/reference/types/thread-visibility.md) | Whether every agent bound to the loom may see it, or only the agent that wove it. |
| `until` | `datetime \| null` | When this stops holding, if it says: the day a reminder no longer matters ("the entry closes on Friday 30 October 2026"), or a plan has passed. After it, the thread is no longer woken into or offered; recall still finds it, marked as past. Null: it holds until it is let go. |
| `basis` | [`ThreadBasis`](https://docs.maitento.com/reference/types/thread-basis.md) | What it rests on: said, the agent's own impression, or read somewhere (see `ThreadBasis`). |
| `pinned` | `boolean` | Held close: always part of what the agent wakes up knowing. |
| `origin` | [`ThreadOrigin`](https://docs.maitento.com/reference/types/thread-origin.md) | Who wove the thread, and from where. |
| `companions` | [`ThreadCompanion`](https://docs.maitento.com/reference/types/thread-companion.md)`[]` | Threads this one has been used together with (see `ThreadCompanion`). |
| `provenance` | [`ThreadProvenance`](https://docs.maitento.com/reference/types/thread-provenance.md)`\| null` | Set when the thread came from another loom (a gift, or inheritance when the loom was seeded). Null for a thread woven here, which is almost all of them. |
| `canTravel` | `boolean` | Whether this thread may be copied to another loom. Only shared knowledge travels: never a knot, a private note, a reflection (another agent's inner voice), an episode (a moment the recipient did not live, which would be a fabricated memory rather than knowledge), or an intention (a promise made to someone else). Set by Maitento. |
| `accessCount` | `integer` | Times recalled or used. |
| `lastAccessedAt` | `datetime \| null` | When the thread was last recalled or used (UTC). Null if it never has been. |
| `surfacedCount` | `integer` | Times put in front of an agent (tapestry, suggestion, recall result). |
| `lastSurfacedAt` | `datetime \| null` | When the thread was last put in front of an agent (UTC). Null if it never has been. |
| `reinforcements` | `integer` | Times the same thread was woven again and reinforced instead of duplicated. |
| `knot` | [`ThreadKnot`](https://docs.maitento.com/reference/types/thread-knot.md)`\| null` | What remains of a cut thread: when and why it was let go, and its essence. Null on a living thread. |
| `seams` | [`ThreadSeam`](https://docs.maitento.com/reference/types/thread-seam.md)`[]` | The seams its reframes left, oldest first: what it said before each change, and why it changed. |
| `revision` | `integer` | Goes up by one every time the thread is reframed, cut or pinned. |
| `isKnot` | `boolean` | True when the thread has been cut and only its knot remains. Set by Maitento. |
| `isWarp` | `boolean` | True when the thread is warp: foundational, and never frays. Set by Maitento. |
| `isIntention` | `boolean` | True when the thread is an intention: something to do when its moment comes. Set by Maitento. |
| `isLoose` | `boolean` | Held loosely: an impression, or something read rather than said. Lighter, and never built on. Set by Maitento. |
| `salience` | `number` | Standing in the loom: weight, loosened by fraying. Warp never frays. Set by Maitento. |
| `shortId` | `string` | The 8-character id agents see and can refer back to. Set by Maitento. |
| `tenantId` | `uuid` | The id of the tenant it belongs to. |
| `id` | `uuid` | The unique id. Use it in `by-id` routes and wherever another object refers to this one. |
| `dateCreated` | `datetime` | When it was created, in UTC. |
| `dateUpdated` | `datetime` | When it was last changed, in UTC. |

## Example

```json
{
  "loomId": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
  "content": "...",
  "kind": "Semantic",
  "strand": "Weft",
  "weight": 0,
  "fray": 0,
  "decayRate": "Normal",
  "subjects": [
    "..."
  ],
  "subjectKeys": [
    "..."
  ],
  "tags": [
    "..."
  ],
  "cues": [
    "..."
  ],
  "visibility": "Shared",
  "until": "2026-10-26T12:00:00.0000000Z",
  "basis": "Said",
  "pinned": false,
  "origin": {
    "kind": "Manual",
    "interactionProcessId": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
    "appProcessId": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
    "agentId": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
    "agentName": "...",
    "userId": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
    "nightWeavingId": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f"
  },
  "companions": [
    {
      "threadId": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
      "times": 0,
      "lastAt": "2026-10-26T12:00:00.0000000Z"
    }
  ],
  "provenance": {
    "kind": "Gift",
    "sourceLoomId": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
    "sourceLoomName": "...",
    "sourceThreadId": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
    "givenBy": "...",
    "note": "...",
    "date": "2026-10-26T12:00:00.0000000Z",
    "ownedAt": "2026-10-26T12:00:00.0000000Z",
    "isOwned": false
  },
  "canTravel": false,
  "accessCount": 0,
  "lastAccessedAt": "2026-10-26T12:00:00.0000000Z",
  "surfacedCount": 0,
  "lastSurfacedAt": "2026-10-26T12:00:00.0000000Z",
  "reinforcements": 0,
  "knot": {
    "dateCut": "2026-10-26T12:00:00.0000000Z",
    "acknowledgment": "...",
    "essence": "...",
    "wovenIntoThreadId": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
    "supersededByThreadId": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
    "cutBy": {
      "kind": "Manual",
      "interactionProcessId": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
      "appProcessId": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
      "agentId": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
      "agentName": "...",
      "userId": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
      "nightWeavingId": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f"
    }
  },
  "seams": [
    {
      "date": "2026-10-26T12:00:00.0000000Z",
      "previousContent": "...",
      "previousWeight": 0,
      "previousStrand": "Weft",
      "reason": "...",
      "acknowledgment": "...",
      "by": {}
    }
  ],
  "revision": 0,
  "isKnot": false,
  "isWarp": false,
  "isIntention": false,
  "isLoose": false,
  "salience": 0,
  "shortId": "...",
  "tenantId": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
  "id": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
  "dateCreated": "2026-10-26T12:00:00.0000000Z",
  "dateUpdated": "2026-10-26T12:00:00.0000000Z"
}
```

## Where it's used

- [`looms.cut`](https://docs.maitento.com/reference/api/looms.md) (`PUT /looms/by-id/{id}/threads/by-id/{threadId}/cut`)
- [`looms.pin`](https://docs.maitento.com/reference/api/looms.md) (`PUT /looms/by-id/{id}/threads/by-id/{threadId}/pin`)
- [`looms.reframe`](https://docs.maitento.com/reference/api/looms.md) (`PUT /looms/by-id/{id}/threads/by-id/{threadId}/reframe`)
- [`looms.thread`](https://docs.maitento.com/reference/api/looms.md) (`GET /looms/by-id/{id}/threads/by-id/{threadId}`)
- [`looms.threads`](https://docs.maitento.com/reference/api/looms.md) (`GET /looms/by-id/{id}/threads`)
- Inside [`LoomInspection`](https://docs.maitento.com/reference/types/loom-inspection.md)
- Inside [`LoomReflection`](https://docs.maitento.com/reference/types/loom-reflection.md)
- Inside [`LoomTensionView`](https://docs.maitento.com/reference/types/loom-tension-view.md)
- Inside [`ThreadRecollection`](https://docs.maitento.com/reference/types/thread-recollection.md)
- Inside [`WeaveResult`](https://docs.maitento.com/reference/types/weave-result.md)