Skip to content
Docs menu

The graph

Read the graph view, filter it, find a note in it, and what Notes draws it with.

View .md

The graph (⌘G, or Graph at the top) draws every note in the vault as a point, with its links as lines between points.

  • A point's colour is its top folder. Notes at the vault's root are grey. The legend in the corner names the colours.
  • A point's size grows with its number of links, so the hubs stand out.
  • Hover over a point to see the note's name, folder, link count and tags, with its links lit. Click it to open the note.
  • Drag the background to pan. Use the wheel or a pinch to zoom. Drag a point to pull it.
  • Find a note lights up the notes whose name or path matches and dims the rest. Enter opens the first match.
  • Filters show one folder (and the folders inside it) or one tag. They can also hide notes without links, hide stale notes, hide the structure lines (Show structure), and turn labels off.
  • The crosshair button fits the graph to the screen. The sparkle button shakes the layout loose again.
  • With the graph focused, + and − zoom, the arrow keys pan, and 0 fits.

A line joins two notes when one of these holds:

  • Written link. A [[wikilink]] or ![[embed]] in the body. Mentioning a page with @ writes a wikilink, so it counts.
  • Database. A row of a database, and the page that shows that database in a database block. A database no page shows has no lines: its rows stay apart.
  • Relation. A row and the notes its relation properties point at.
  • Sub-page. A note, and the page of the folder it sits in (a note beside a folder of the same name is that folder's page).

Database and sub-page lines are structure: they are drawn thinner and dimmer than written links, and Show structure turns them off. Every kind counts toward a note's link count, its size, and whether it is an orphan. When two notes are joined more than once, the line is drawn once. The local graph in the right panel uses the same lines.

For a very large vault, the graph shows the most-linked notes and says so. Filter by folder to see the rest.

If your system asks for reduced motion, the graph is laid out before it appears and nothing on it moves.

Show people

Open Filters and turn on Show people (it is off by default) to add the People contacts your notes mention. A mention is an @ of a contact in a note (Mentions). Each contact becomes a node in its own colour, with a line from every note that mentions them, and lines between two contacts you have linked. Click a contact to open their page in People.

You only see contacts you may see in People: a private contact of someone else never shows, even if a note mentions them, and links between people stay with the person who made them. With no mentions nothing is added. The same switch is GET /globe/api/graph?vault=me&people=1; the new edges have kind person. The People app has a graph of its own, your network as a graph, drawn by the same canvas.

Similar and topic lines

Some notes belong together and nobody linked them. Notes draws two more kinds of line for those, dashed and faint, so you can tell them from anything written or built into the vault:

  • Similar (on by default). A note's three nearest neighbours by meaning, if they are close enough. Each note has one vector (the average of its passages' embeddings), and two notes are similar when their vectors point the same way. Notes you already linked, or that structure already joins, get no second line. Similar lines never join two vaults, and a note you cannot read never shows up in yours. They need an embedding model; without one there are none.
  • Topics (off by default). Two notes that mention the same specific thing: a person, an organisation, a product, a place or a term such as "CPF" or "capital allowances". Notes asks the org's own model to list the named things in each note, a few notes per call, and joins two notes when they share one that is not on most pages. A thing on every page, such as "Singapore" in a Singapore vault, joins nothing: the rarer the thing, the more it counts. A People contact and an @ mention of them are one person. Without a model there are no topic lines, and nothing else changes.

Open Filters and use Similar and Topics to show or hide them. Both count toward a note's size and links in the picture, and the local graph in the right panel shows the similar lines of the open note.

Click a line to see why it exists: "Fines and Penalties and Medical expenses read alike (similarity 0.71). Nobody linked them", or "both mention CPF, Okta (weight 3.2)". The same pairs, with the same reasons, come back from globe_note_related (similar by meaning (0.71), shares a topic: CPF).

Behind the toggles: GET /globe/api/graph?vault=me returns similar lines (kind: "similar", score the cosine similarity) unless similar=0, and topic lines (kind: "topic", score the weight, why the shared things) only with topics=1. They are worked out after a note is embedded and by a cron every 10 minutes, so the graph reads a table.

What it costs

Similar lines cost no model call: they reuse the embeddings Ask already made. Topic lines call the org's model through the same door as the rest of Notes (the org's gear, the internal key of Notes, every call counted against the org's daily limit for AI in Notes, Notes settings). Notes go six to a call. A note whose text and model are unchanged is never sent again, and at most 300 notes an org are read a day. With no gear, no model or the daily limit reached, topic lines quietly stop being updated and the rest keeps working.

How well it works

test/db/globe-graph-eval.test.ts hides the real links of the 57-note vault used for Ask and sees whether the lines name them. Its 11 wikilinks are hidden in five folds of about 20%; a note's top 1, 3 or 5 neighbours count as a hit when either note of a hidden pair names the other. It is a small vault written by us: one link is 0.11 of recall, so read the differences as direction, not as proof. With mxbai-embed-large through Ollama, the link's name left in the text (an unlinked mention, which is what the suggestions below are for):

Ranking recall@1 recall@3 recall@5 precision@3
similar (average of passages, shipped) 0.67 0.89 1.00 0.24
similar (best pair of passages) 0.67 0.89 1.00 0.24
topic (a stand-in extractor) 0.33 0.33 0.33 0.09
random 0.11 0.22 0.33 0.04

With the name taken out of the text too, similar lines still find 0.44 at 1, 0.67 at 3 and 0.89 at 5 (topic 0.11). Precision is low because a note has two or three good neighbours, and only the pair someone happened to link is counted.

What is drawn (three neighbours, a floor, minus linked pairs) finds 7 of the 9 hidden pairs with the name in the text (0.78) and 5 of 9 without it (0.56). The floor trades coverage for noise:

Similar floor hidden pairs found edges drawn (57 notes)
0.5 0.89 120
0.55 0.89 102
0.6 (shipped for mxbai-embed-large) 0.78 89
0.65 0.56 76
0.7 0.33 62

Embedding models differ, so the floor does too: 0.6 for mxbai-embed-large (measured), 0.5 for bge-m3 and 0.55 for nomic-embed-text (not measured), 0.6 otherwise. The average of a note's passages and its best pair of passages scored the same here, because almost every note in the vault is one passage; the average is what ships because it is one vector per note that an index can search.

In CI the eval runs offline with a hashed embedder and a stand-in extractor that finds the vault's named things the way a good model would; how well a real model extracts is not measured. There, similar lines recover 0.56 of the hidden pairs at floor 0.3, topic lines 0.33.

Do they help Ask? The same 35 questions, following the extra lines from the top three answers as written links are:

Expansion recall@5 recall@10 MRR paraphrase R@5
written links only (shipped) 0.87 1.00 0.76 0.80
plus similar lines at 0.2 0.81 0.91 0.73 0.70
plus similar lines at 0.1 0.84 1.00 0.75 0.75
plus topic lines at 0.2 0.86 1.00 0.76 0.78
plus topic lines at 0.1 0.87 1.00 0.76 0.80
plus both at 0.1 0.84 1.00 0.74 0.75

None helped, and similar lines cost recall, as the structural lines did. So Ask does not follow them; they are for the graph, globe_note_related and the suggestions in the Inbox.

How it is drawn

The layout is a force simulation (d3-force) that runs in a Web Worker, so the page stays responsive while it settles. It starts from a disc with each folder in its own sector, which is close to where the simulation ends up.

Points and links are drawn with WebGL2: every link and every point take two draw calls. Points are flat discs with a thin dark rim and no glow, so dense clusters keep their colours. A 2D canvas on top draws the labels, the rings around the open and hovered notes, and the hovered note's links. Without WebGL2, the same picture is drawn on the 2D canvas alone.

We measured both renderers in Chrome on an Apple-silicon Mac at 1440×900, with a device pixel ratio of 2, on a graph of 5,000 notes and 20,000 links:

Renderer Main-thread time per frame (median) Frames
2D canvas, whole picture 8.6 ms (9.1 ms while hovering) 50–54 a second
WebGL2 with the 2D overlay (shipped) 0.9 ms (1.7 ms while hovering) 60 a second

The machine was busy with other builds during the run. The comparison holds; the absolute numbers will vary.