# Relationships

> Typed, directional links between documents and folders, drawn by people or suggested by AI.

Folders say where something lives. Relationships say how it connects to things that live
elsewhere: the implementation that answers a requirement, the version that replaced a draft, the
feedback on a release.

## Four types

Every relationship has one of four types and a required reason.

| Type            | Read as                    | Use it when                                                                                                  |
| --------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------ |
| **references**  | references / referenced by | It mentions or points at the other, without depending on it                                                  |
| **responds to** | responds to / answered by  | It addresses, implements or answers the other                                                                |
| **supersedes**  | supersedes / superseded by | It replaces the other; this is the version that counts now                                                   |
| **related to**  | related to                 | They are connected, but not in one of the specific ways above (drawn by people; the AI uses threads instead) |

Relationships have a direction. "Requirements V2 _supersedes_ Requirements" shows on V2 as
_supersedes_ and on the original as _superseded by_.

Either end can be a document or a folder, so "Client feedback _responds to_ the Release 1 folder"
works too.

## Drawing one

- **Drag** a document or folder onto another document.
- Or use **Connect to…** on either item.

Pick the type, write the reason, save. Dropping onto a _folder_ moves the item instead; dropping
onto a _document_ relates them.

## AI-suggested relationships

When you add or change a document, Filement compares it with the rest of the workspace and
suggests the specific connections it finds: a newer version, a reply, a citation. Suggestions are
marked as AI-suggested, sit in their own section of a document's insights, show dashed in the
knowledge graph, and carry a confidence score. Hover a suggestion to see the score, or read it
under the suggestion on a touch screen. Filement learns the score from what people in your
workspace kept and turned down before, not only from the model's own guess.

The AI doesn't suggest plain **related to** links. Documents from the same piece of work go into
the same **thread** instead (below), which says it once for all of them.

For each suggestion you can:

- **Keep this connection**, which makes it your relationship. It remembers it began as a
  suggestion.
- **Dismiss** it, which removes it and stops the same pair being suggested again.
- **Leave it.** It stays a suggestion until later reading contradicts it.

Relationships that AI tools create over MCP count as AI-suggested too, even though they arrive
under your account, because a model decided them.

## Threads, versions and Activity

Filement keeps three things up to date on its own, so a workspace gets easier to read as it
grows.

**Versions.** Copies, re-downloads such as `plan(1).md`, drafts, and v1/v2 of one document form a
family with one current version. When the text proves it, the family shows as one card on the
board ("3 versions") with the older ones tucked behind it. When it's only the AI's reading, older
versions stay visible, greyed, with "Newer: …". **Versions…** in an item's menu lists them, and
**Not the same document** separates one for good.

**Threads.** A thread is one piece of work across documents and folders: the request, the spec,
the status reports, the reply, the decisions, the plan. It has its own page with a dated timeline,
where the work stands, what was decided and what is still open. On that page, hover a document to
see what it's connected to, and click "answers …" to jump to the document it names. Click a
decision or an open question to go to the document it came from. Hovering a card anywhere outlines
everything in its thread and family. A folder's **Brief** lists the threads in it. A thread never
mixes documents from areas with different access.

**Activity.** Activity lists every change the AI makes, and every change something makes on your
behalf, in plain words and in groups. A group is one connected agent's working session (its
changes until it has been idle for half an hour), one conversation with the assistant, one upload
or file saved from chat, or one reading of a document. **Undo all** (just **Undo** on a group of one) takes a whole group back,
newest change first, so a chain unwinds in order. Say an agent made a folder, moved files into it
and edited one: the edit is reverted, the files move back, and the folder goes to Trash. You can
undo any single change on its own too. A change someone has touched since stays as it is, and the
list says so. Undoing never loses anything: created items go to Trash, and edits come back as a
new version.

## Connected items stack together

When you connect two things that sit in the same folder, they collapse onto one card there: a
small pile with a count, so you can see the connection while you're just browsing.

**Click the pile** to open its route view. The pile lifts into a panel where it stands and reads
top to bottom. Each connection gets its own line with the type in its colour, the reason whoever
drew it wrote, and the item it leads to. It reads oldest first: the original document, then what
superseded or answered it, then whatever came from _that_. So each line is labelled the way you
read it. The spec is "answered by" the implementation, even if you drew the connection as
"responds to" from the other end.

Connections chain, and they branch. A line runs from each item to the one it leads to, in the
relationship's colour, with the label hanging off it. A chain runs straight down one column; where
two things came out of the same item, each branch is indented under it. The route view is the only
way a stack is shown, because it's the only view that shows both the shape and the reasons.

The page behind dims while the panel is open. A press anywhere outside closes it, and so does
Escape. From the panel you can open any item or use its menu as anywhere else, and **Open in the
graph** hands a tangled one to the knowledge graph, which has pan, zoom and filters. Drag a member
out onto an empty slot on the board to separate it again; the connection stays.

### Connecting to something inside a stack

Drag a file onto a stack and **hold for a moment**. The route view opens while you're still
dragging, and dropping on any row connects to that item. That's how you link to something in the
middle of a chain, not just to the card on top.

## Where you see them

- **In the folder itself.** Connected items stack onto one card that opens to the route view.
- **In a document's insights.** Relationships people added come first, with AI suggestions in a
  separate section below.
- **In the knowledge graph.** Every connection in the workspace or one project, solid for people
  and dashed for AI. See below.
- **For agents.** MCP tools return the two groups separately. See [Tools](https://filement.app/docs/agents/tools.md).

## The knowledge graph

Open it from the sidebar. It draws the connections in the workspace, solid for connections people
added and dashed for ones Filement suggested, with an arrowhead for the directional ones. Lines
are grey until you point at or select an item. Then that item's lines show in the colour of their
relationship type.

Filement groups what it already knows belongs together, so the graph stays readable as it adds
connections:

- **Versions of one document are one card.** Drafts, copies and earlier versions stack behind
  the newest one, and the card says how many there are ("3 versions"). Connections to any of them
  are drawn to that card. Select it to see the versions and how each connection reached it. To see
  every version as its own card, switch **Current** to **All versions**.
- **A thread is a shaded area.** The documents in one thread sit together inside an area
  labelled with the thread's name. Click the name to see where the thread stands, what's open
  and what was decided. Double-click it to open the thread. Drag the name to move the whole
  thread.
- **Zoom out and the threads take over.** When cards get too small to read, each thread shows
  its name in large type and a single line joins two threads, labelled with how many connections
  run between them.
- **Lines that repeat something are hidden until you look.** A "related to" link between two
  documents in the same thread says the same thing as the thread. A chain of "supersedes" links
  already says the oldest version was replaced. Those lines appear when you point at or select
  one of their items.

Filement works the layout out from the connections themselves, and it's the same every time you
open the same workspace, so you can find things where they were last time. **Re-arrange** moves
everything, and so does switching between **Current** and **All versions**. Dragging a card
moves just that card. Filtering never moves anything.

To narrow it down:

- **Find in graph** (or press `/`) lights up items whose name matches and fades the rest.
- **Types** and **People / Suggested** take whole classes of connection off the canvas.
- **Projects** appears when the workspace has more than one. A connection stays on screen if
  either end is in the project you picked, so links that leave the project stay visible.

**Click an item to focus it.** Everything more than one hop away fades, and the canvas frames the
neighbourhood. The panel on the right lists that item's connections with the reason someone gave
for each, who added it, and, for suggestions, how confident Filement is. Accept or dismiss a
suggestion right there. Use the **1 / 2 / 3** control to widen the focus to two or three hops.

Double-click an item, press `Enter`, or use **Open** to go to it. `Esc` clears the focus.
Right-click any item for the usual Rename, Move, Connect and Trash.