Zettelkasten

Luhmann's physical slip-box contained tens of thousands of index cards, each with a unique alphanumeric address. A new note was not filed by subject but placed wherever it could be cross-referenced to an existing note; the address was written at the top and outgoing references were written inline. Over time the collection self-organised into dense clusters of related ideas connected by an explicit link graph — something that no hierarchical filing system produces automatically.

The digital Zettelkasten community has translated these principles into plain-text formats: each note is a single file, the unique identifier is a UUID or timestamp, and links between files replace the handwritten references on cards. The emergent structure from following links reveals which ideas are central (high in-degree) and which are peripheral, without the author ever imposing a top-down taxonomy.

ORE Studio's documentation spans domain concepts (ORE instrument types, interest rate curves), architecture decisions (component split, CMake conventions), agile artefacts (stories, tasks, sprints), LLM instructions, recipes, and manuals. A hierarchical directory structure alone cannot represent the cross-cutting links: a concept defined in doc/knowledge/ is referenced from doc/agile/ tasks, from doc/recipes/, and from doc/manual/. Treating the documentation as a Zettelkasten graph means:

• Any page can link to any other page by UUID — location in the directory tree is not part of the link and files can be moved without breaking references.
• The knowledge graph visualisation (org-roam-ui) immediately reveals which concepts are central to the project and which are peripheral.
• LLMs can navigate the graph programmatically: compass show <UUID> prints a node's outgoing and incoming links, giving instant traversal without reading every file.

The most important constraint is the one hardest to maintain: each file should capture one idea, not a collection of loosely related ones. When a file grows, the right response is usually to extract a sub-topic into a new file and link to it, not to add another section. ORE Studio enforces this weakly — the document types (knowledge, recipe, component overview, task, story) are each scoped to a single subject — but within each type the author must resist the temptation to include tangential detail.

The atomic rule says how much a page holds. Three more rules, taken from Luhmann's practice rather than from the plain-text community's retelling of it, say what the page does with what it holds.

• Summarising a source instead of saying what it means here. A research-paper page is worth the commentary on what the result changes, not the abstract restated.
• Filing by tool decision. An agent that picks the thread has removed the exercise; it may propose, not choose.
• Only the near neighbours. The similar pages are the easy candidates, and the contradiction is the one that pays.
• A page holding several claims. Split it; a page with two theses cannot be contradicted cleanly by either.
• A hub that restates its cluster. The structure note gists and links; a second copy of the content drifts.
• A page with no way in. A page nothing links to is not in the graph, whatever directory it sits in.

Luhmann's slip-box contained a second kind of card. Alongside the atomic notes sat Überblicksnotizen — overview notes, usually rendered in English as structure notes — whose content was not an idea of their own but an ordering of other people's. A structure note names a cluster and lists its notes in an argued sequence, saying how each follows from the last and why the order is the one it is.

The distinction is between two kinds of address. An atomic note is addressable because it has an identifier; a structure note makes a cluster approachable, which is a different property. A reader who knows an identifier can reach any note directly, but a reader who knows only a subject has no way in. Search returns the notes that mention a term, ranked by resemblance; it cannot say which of them to read first, nor which three of forty are load-bearing. That judgement is authored, not computed, and the structure note is where it is written down.

The resulting shape is a hub with spokes. The hub carries no content that the spokes do not already hold, which is the discipline that keeps it honest: a structure note that restates its cluster becomes a second copy to maintain and drift away from. It gists and links, and the detail stays in exactly one place. The same rule governs any index in this graph, including this one.

Structure notes are also what make the collection navigable to an agent rather than merely searchable. An agent grounding itself in a domain before doing work has the reader's problem in an acute form: it knows the subject and not the identifiers, and the cost of reading the wrong five pages is paid in context it cannot recover.

ORE Studio holds them under the structure_note tag, and the knowledge index opens with the set. One exists per domain cluster: market data resolution, interest rate curves, volatility, identity and access, MASD, and the entity lifecycle.

Three conventions keep them honest. A structure note argues its order rather than listing one, saying what each page makes possible for the next; an order with no reason is a table of contents, which the index already provides. It gists and links, holding no content its cluster does not, so there is nothing in it to drift. And it says what it excludes, naming the neighbouring cluster and why the boundary falls where it does, because the reader who arrived at the wrong hub needs pointing at the right one more than the reader at the right hub needs reassurance.

A cluster earns a structure note when reading its pages in the wrong order costs something real. Where the order does not matter, the index entry is enough.

Some pages belong to a cluster without belonging to its sequence: a provenance note, a research paper, anything reached when the question changes rather than when the subject advances. A note holds these in a section marked # aside, and the marker is what the tooling reads. The alternative was to recognise such sections by their wording, which asks a script to interpret prose and gets it wrong the first time a note is phrased differently.