Lenses, nodes and links

Three words carry the whole app. Everything else you can learn later, or never.

The problem folders have

Put a note about the Treaty of Versailles in a folder and the folder has recorded one thing: where you put it. It does not know that Versailles is a treaty rather than a person, that it ended a war and set terms for a country, or that three of your other notes are the terms it set. You know all of that. The folder is not built to hold any of it.

So the structure stays in your head, and everything a tool could do with it — draw it, count it, check it, find the gap in it — is off the table. Search gets you back to a note you half remember. It cannot answer “what did this cause”, because nothing ever wrote down that anything caused anything.

A lens is where you write that down. You decide what counts as a thing and what counts as a link, and the graph is what your vocabulary makes visible. The three words below are what that takes.

A node is one idea

Small enough to hold in your head. It has a title, a one-line definition, a body as long as you want, and links out to other nodes.

The size is the discipline. If a node needs three definitions it is three nodes, and splitting it is not busywork — the links you have to draw between the pieces are the part you would otherwise have left implicit in a paragraph.

The definition earns its own line because it travels. It is what shows in graph labels, tooltips and list views, so it wants to be a sentence that stands alone — what the thing is and why it matters, rather than a restatement of the title.

Every node has a permanent name

That name is its slug: lowercase, dash-separated, derived from the title unless you set one. Sam Dash becomes sam-dash.

The slug is what links point at, which makes it identity rather than decoration. Two nodes with the same slug are the same node. Two slugs for the same subject are two nodes, permanently, with your graph split between them.

And slugs are unique across your whole palace, not per lens — so the-supreme-court can only exist once, however many lenses would like to have it. That is why most lenses give their slugs a short prefix: wg-nixon, got-jon-snow. The prefix is a convention you pick, not a setting the app enforces, and it is worth picking before the tenth node rather than the hundredth.

A link is a claim about two ideas

Write [[another-node]] in a body and you have drawn an edge. That edge appears on the graph immediately, and on the other node as an incoming link, so connection is never one-directional bookkeeping you have to remember to repeat.

Links can be typed — derives from, contradicts, precedes — and a lens decides which types it recognises. That is the first hint that a lens is more than a folder. Typed relations covers it properly.

A lens is a reading

A lens is a set of nodes and its own vocabulary for them. Its own groups, its own relation types, its own sense of what connects to what. Two lenses over overlapping material can disagree completely about how that material is organised, and neither is wrong — they are different readings, which is the entire point.

This is why a lens is not a tag and not a folder. A tag adds a word to a note. A lens brings a whole apparatus with it.

Groups are declared. Kinds are not.

A group is a category a lens sorts its nodes into, and it carries a colour — Congress, The White House, The Press. You create groups in lens settings, and a node can only be in a group the lens has declared. Given enough of them, groups nest into families.

A kind looks similar and works the opposite way round. person, event, document, org, place — the sort of thing a node is. There is no list of kinds anywhere, because kinds are not declared: they are simply whatever the nodes in your lens already use. Write kind: treaty on a node and that lens now has treaties in it.

One node in two lenses

A node can appear in more than one lens. Refraction makes one visible in another lens without copying it — edit it anywhere, it changes everywhere, because there is still only one node.

If the two lenses need to say different things about it, that is a facet: a per-lens version of the title and body, sitting on the same node, neither overwriting the other.

Why the graph is the main view

A folder tree can only show you what you already decided. It answers “where did I put that” and nothing else. The graph answers the questions you did not know to ask: what sits between these two ideas, what is unexpectedly central, what you have written eleven notes around and never named.

There is a Library view when you just want a list, and it is a good list. But the default is the graph, because the structure is the thing you are building — the notes are how you build it.

One consequence catches people out: where a node sits on screen is not part of your notes. The layout is drawn by a simulation and remembered by your browser, so it can shift when the links change and it does not follow you to another machine. Nothing is lost when it moves — My graph rearranged itself explains why, and why that is the right trade.

Macro lenses

When you have a lot of lenses, one can hold others: a macro lens. Science holding Physics and Chemistry; Investigation holding several cases.

You never flag a lens as a macro lens. It becomes one the moment another lens names it as its parent — the status is derived from the arrangement rather than set by a switch, so it cannot fall out of step with reality. Remove the last child and it is an ordinary lens again.

Two consequences worth knowing before they surprise you:

One node can be private inside a shared lens

Sharing is a property of a lens: private, friends, or public. But a single node can be marked restricted, and that mark outranks the lens it is sitting in — in every lens it is sitting in. A restricted node stays yours in a public lens, and it is never sent to a hosted model, whatever your AI settings say.

The full picture is in Sharing a lens and What leaves this app. It is named here because a bit you don't know exists is a bit you will never go looking for.

The words, in one place

Including four this page has deliberately not taught you. They are here so that meeting one later is a lookup rather than a surprise.

Next

• Add your first nodes — the four ways content gets in, and which to reach for first.
• What you started with — the example lenses in your account, and why they are yours to delete.
• Groups and families — building the categories a lens sorts by.