Features

Canvas

Infinite Canvas

Pan and zoom freely across an infinite workspace. Semantic zooming adjusts detail level:

• Zoomed in: Full content, edit handles, detailed view
• Zoomed out: Titles only, collapsed cards for performance

Edge labels have their own zoom threshold (Settings > Appearance): below it, labels are hidden to reduce clutter in the zoomed-out view.

Node Types

Tags

Hashtags in node content become node tags:

• #tag tokens are extracted whenever content is set: on node creation and on every content edit, from any interface (canvas editor, MCP tools, LLM agent)
• Loading a workspace scans every node's body as well, so content that arrived before tags were extracted, or that another editor wrote into the vault, is tagged like anything else. The pass writes only the nodes whose tags changed, so a workspace already current costs no writes
• A #tag in the text always creates its tag node and the edge to it. Whether those are drawn is a separate, view-only question answered by the tag filter, which never creates or destroys anything
• Text inside code is not read for tags: a fenced code block (`` or ~~~) and an inline code span hold literal text. Read as tags, the colour codes of a Mermaid diagram (fill:#f3e5f5`) became tags, tag nodes and edges between every note with a diagram. Loading a workspace withdraws any recorded tag that its note's text holds only inside code, with its edge and the tag node it leaves empty
• Deleting a #tag from the text withdraws it: the tag leaves the node, its edge is deleted, and the tag node goes too once the last note using it lets go
• Deleting a note withdraws its tags the same way: a tag node that the deleted notes were the last to use is deleted with them. It stayed behind as an unconnected node. Undoing the deletion brings the note back and reconnects its tags, which draws the tag node again once two notes share the tag
• Settings > Canvas > Repair Tag Nodes also deletes tag nodes that no note is connected to, left behind by deletions made before this rule
• A tag added by hand from a card's chips was never in the text, so an edit never withdraws it. Only a tag the previous body carried and the new one does not is taken away
• Tags are how nodes are grouped. Frames were removed: upgrading gives each node that was in a titled frame that title as a tag, shown as a chip on the card ("Kapitel 1-30" becomes kapitel-1-30). The tag is stored with the node, not written into its text; like any tag shared by two or more notes, it is drawn as a tag node connected to them when the workspace loads
• The node preview panel lists the tags as chips beside the date chip, each with its remove button inside the chip, and the row wraps when they do not fit on one line
• A node's tags appear as chips at the bottom of its card; on a selected node, chips gain a remove button and a "+ #" chip adds tags directly
• Whether tag nodes are drawn is remembered between sessions. Hiding them is a view choice, so it neither creates nor deletes anything, and it holds across a restart
• Tag nodes and their edges are a toggleable canvas layer: the edge-filter cluster on the canvas (bottom left, beside the content it filters) switches manual, storyline, wikilink, and tag layers
• A tag becomes a tag node once at least two notes share it. One node per distinct tag put 606 tag nodes into a workspace holding 360 real ones, and 542 of them - 89% - were reachable from a single note or none: a tag used once labels that note rather than linking it to anything, and its card already shows it as a chip. What earns a node is a tag that joins notes together
• Loading a workspace connects any node whose tags have no edges, so tags that arrived without them - from the body scan, or from an agent setting a node's tags over MCP - are shown like any other. An existing connection is never duplicated, so a connected workspace costs nothing
• Settings > Canvas > Repair Tag Nodes merges tag nodes that duplicate each other and restores a missing # prefix, left behind by an earlier lookup that compared a bare name against a title stored with its hash

YAML frontmatter at the top of a note (Open Knowledge Format metadata) is treated as structured node metadata, never as text:

• The block is hidden from rendered cards, and all editors (inline, fullscreen, preview panel) show only the body — the metadata header survives every edit untouched
• Its fields surface as chips on the node card: tags, the date (or date range), and the OKF lifecycle status when it is draft or deprecated (stable is the silent default)
• Click the date chip (or the "+ Set date" chip on a selected node) to set or change the node's date and date_end in place — no YAML editing needed
• Title and tags from frontmatter also feed the node record during vault sync

Selection & Multi-Select

• Click to select single node
• Shift+Click to add to selection
• Lasso selection for multiple nodes
• Bulk operations on selection

Fullscreen Editor

Open any node in a fullscreen split-view editor for focused writing:

• Trigger: Cmd+Click (Mac) or Ctrl+Click (Windows/Linux) on any node
• Fills the window: The view covers the whole application window, edge to edge. The canvas, toolbar and panels are hidden until it is closed; it is not a dialog over the canvas, and there is no area outside it to click to close it
• Split view: Markdown editor on left, live preview on right
• Auto-save: Changes save automatically with 500ms debounce
• Keyboard shortcuts:
• Escape - Save and close
• Cmd/Ctrl+S - Save immediately
• Features:
• Title editing in header
• Wikilink autocomplete (type [[ to trigger)
• Mermaid diagram preview
• "Zoom to Node" button to locate node on canvas

Connections

Edge Types

Wikilink Edges

Writing [[link]] in a node's content creates a wikilink edge to the referenced node:

• Edges are created whenever content is set: on node creation and on every content edit, from any interface (canvas editor, MCP tools, LLM agent, vault import)
• Links resolve by note title, by relative path ([[folder/note]]), and with section anchors ([[note#section]])
• A pair already connected by a manual edge does not receive a parallel wikilink edge
• Removing the link removes the wikilink edge; manual edges are kept

Edge Routing

Multiple routing styles for visual clarity:

• Orthogonal - 90-degree angles, clean diagrams
• Curved - Bezier curves, organic flow
• Straight - Direct lines
• Hyperbolic - Smooth curves avoiding nodes

Neighbor Highlighting

When selecting a node, connected neighbors are highlighted for context. The highlight holds in every theme and at every zoom level, including the collapsed cards shown when zoomed out; above the LOD threshold, where cards are drawn as circles, neighbors carry the same highlight as a ring.

Neighborhood View

Focus on a specific node and its connections: - Toggle neighborhood mode to hide unrelated nodes - Adjust depth (1-5 hops) to control how far connections extend - The subgraph is arranged radially around the focus node; the layout controls rearrange it without changing stored positions - Double-click any neighbour, on its title or its body, to make it the new focus - Useful for exploring dense graphs

Physics Mode

Let the graph arrange itself while you pull on it. Press P or use the atom button in the canvas controls.

Prerequisite: the canvas is in bubble mode (zoomed out, or bubble mode switched on in the canvas controls). Physics mode is not available with cards.

1. Zoom so the part of the graph you want to arrange is on screen (up to 2000 nodes).
2. Press P. Connected nodes pull together, the others make room, and nodes stop overlapping.
3. Drag a node: its connections follow, and the graph settles again when you let go.
4. Press P again to stop. The positions are saved when the graph comes to rest, when you stop, or when you leave bubble mode.

Nodes off screen stay where they are. One Undo restores every position from before you switched the mode on. Running a layout command or Undo switches the mode off. The mode is not available in the neighborhood view. While nodes are moving, edges are drawn as straight lines between the bubbles; they are routed in their style again when the motion stops.

Storylines

Create linear narratives through your knowledge graph:

• Order nodes into a sequence
• Navigate through storyline in reader mode
• Edit a section where you read it: double-click its text or its title, then save with Cmd/Ctrl+Enter or by clicking away, or cancel with Escape
• Export storylines as documents
• Color-code storyline edges

Anchored notes and comments

A note about a passage sits at that passage. Write a [[wikilink]] where it belongs; the reader shows it as an inline link, and the links sidebar (link icon in the reader header, "Show references") shows the linked note beside it.

• A link to a node that does not exist is marked as missing.
• Creating a comment writes such a link into the text it comments on, so the comment travels with the passage rather than with a position in the sequence.

To read one node on its own, right-click it on the canvas and choose Read node. It opens in the same reader the storylines use, at full width.

Agent log

The chat panel shows the conversation; the log shows what the agent did and anything that failed. Open it with the Log button in the status bar at the bottom of the canvas, next to the node and edge counts. The button is present whenever the AI is enabled, so errors have a known place to be even before anything goes wrong.

Watching a PDF import work

Dropping a PDF creates its node immediately, and the AI cleanup that follows is visible rather than opaque:

• The cleaned text streams into the node as it is generated. With the Ollama provider each token appears as the model produces it (updates are throttled to keep the canvas smooth); providers without streaming support fall back to updating the node as each section completes.
• The node currently being written carries a pulsing outline so it is findable on a busy canvas. The pulse stops and the outline disappears the moment processing ends, whether it finished or was aborted.
• The status line still names the section being cleaned, which remains the only progress signal for multi-section documents on non-streaming providers.

Reading a long node

A node card shows the beginning of its content and marks where the text continues. Cards are a few hundred pixels tall, and a node holding an imported paper can carry tens of kilobytes, so rendering all of it into the card would cost several dropped frames on every click.

To read the whole document, open the node: Cmd/Ctrl+click for the fullscreen view, or right-click and choose Read node for the reader. Both render the full text.

Bringing a vault to OKF

Nodus stores notes in Open Knowledge Format (OKF v0.2): Markdown with YAML frontmatter, readable by Obsidian. Files Nodus creates carry that frontmatter already; files that predate Nodus usually do not.

To add it to an existing vault, open Settings > Workspaces, select the workspace, and choose Check files under OKF frontmatter. Nodus reports how many files would gain frontmatter, how many already have it, and how many nodes have no file, and writes nothing until you confirm.

The backfill only adds a frontmatter block above the existing text. Bodies, [[wikilinks]] and #tags are untouched, and a file that already has frontmatter is left alone rather than merged into, so fields you set by hand cannot be lost.

Expanding a PDF into a graph

When a dropped PDF has structure - several sections or a bibliography - Nodus offers to expand it after the document imports. The single node stays either way; the dialog chooses what is added:

• Sections as nodes. One node per heading, connected along the document outline, tagged with the paper's title.
• References as citation nodes. Each bibliography entry becomes a citation node, cited by the paper.
• Verify against Semantic Scholar. Each reference is marked verified, not_found, or not_checked in its frontmatter. A reference is only marked not found when the service answered; if the service is unreachable, the state is not checked - an outage never invalidates your bibliography.
• Add references to Zotero. Shown when the Zotero integration is configured; nothing is written to Zotero without this choice.
• Extract claims with the AI. One model pass per section; claims become nodes linked to their section as supporting or contradicting. Sections the model fails on are skipped and counted, and the structural graph is never held up by the model.

Importing PDF highlights

Drop a PDF that you have already annotated and Nodus offers its highlights for import.

1. Drop the PDF onto the canvas. The document is imported as a node as usual.
2. If the file carries highlights, a picker lists them with their page number, colour and any comment you wrote.
3. Choose the ones worth keeping and confirm. Each becomes a node holding the passage and your comment, linked back to the document node.

Highlights already imported from that file are marked as such and are not imported again, so re-dropping an updated PDF brings in only what is new.

A highlight can only be imported when the PDF stores the highlighted text alongside the annotation. Zotero and Adobe Acrobat do this; macOS Preview records only the marked region, so highlights made there appear in the picker as unavailable. This is a limitation of what the file contains, not of the file being unreadable.

Exporting a document

Turn work on the canvas into a document in two formats:

• PDF - compiled in the application, ready to send
• Typst source - to keep editing outside Nodus

Two ways in:

1. In the storyline reader, choose Export. The document follows the storyline order, so the sequence you arranged is the sequence in the document.
2. Select nodes on the canvas, right-click, and choose Export selection. Nodes are ordered top to bottom, left to right.

The dialog collects a title, an optional author, the paper size, and whether to append a list of the connections between the exported nodes. Choose where to save with the system dialog. If a PDF fails to compile, the dialog says so and writes nothing, so a broken file never lands on disk.

Nodes with Typst math export as math, not as source text, since the same engine renders both on the canvas and in the document.

Learning the edge gestures

The edge gestures are not visible on screen, so a short coach runs once after onboarding. It teaches three of them in turn - the right edge for storylines, a dwell at the bottom edge for timelines, the left edge for the agent - and moves on only when you actually perform the gesture it is asking for. Skip it at any time; it does not come back.

To see it again, open Settings > General and choose "Replay gesture tour".

Storyline Panel

Moving between graph and storylines works in steps along the screen edges: each push of the pointer against the right edge goes one step deeper into storylines, each push against the left edge steps back toward the graph.

Each edge is active only at a handle in the middle of that edge, marked on screen. Pushing the border anywhere else - reaching for another window, the dock or the desktop - does nothing, so panels open when you aim for them and not while you work.

• Push right once: the storyline overview slides open on the right
• Push right again: the reader opens at half the window, keeping the graph visible, with the last-read storyline (the first storyline initially)
• Push right a third time: the reader expands to the full window, and the text spans its whole width instead of a centred column
• The text pane scrolls vertically only; a wide table, formula or diagram scrolls inside its own box, so a sideways swipe does not shift the text
• Push left: each push steps back down — full reader to half, half to the overview (or the timelines view, if the reader was opened from there), overview to the plain graph
• Open layers stay open while you work in them; only a left-edge push or the toolbar book button steps back
• While a layer is open, stepping deeper requires pressing the pointer against the very edge of the window, so using the panel near the border does not skip ahead
• The reader's left handle still resizes it freely between steps

In the overview:

• Clicking a storyline row opens it in reader mode; the chevron on the row expands its ordered nodes inline instead
• Drag a storyline row to reorder storylines — the same drag used for reordering nodes within a storyline; the order persists and the timelines lanes follow it
• Several storylines can have their item lists expanded at once
• The overview shortens above an open timelines sheet instead of overlapping it
• Storyline titles wrap to at most two lines instead of being truncated
• Drag the separator between panel and canvas to set the panel width; the width persists across sessions
• Drag nodes from the canvas onto a storyline section to add them to that storyline

Timelines

Timelines live along the bottom of the window: dwelling the pointer at the bottom edge for a second (or the timelines button in the storyline overview) slides up a sheet showing all storylines; the graph stays visible above it, and it can be open alongside the overview and beneath a shortened reader:

• Every storyline is a horizontal lane in its color; its nodes are beads in order
• A node states its point in time with a date: frontmatter field — date: 20 BC, date: 1969-07-20, date: 1969-07-20 14:30, date: 1500. Only dated nodes are placed (BC dates and minute-precision timestamps supported); nodes without a date do not appear on the axis
• Large empty stretches between clusters of events are abbreviated: the axis breaks (marked with a double slash) instead of wasting space, and each segment labels itself at its own level of detail
• A node spanning time (an era, a long work) adds date_end: and is drawn as a bar from start to end instead of a bead
• The from/to fields in the sheet's header fix the axis range (same date formats); either side left empty fits automatically, and the chosen range persists. Axis labels adapt to the span: years, months, days, or clock times for narratives playing out within hours
• Nodes shared between storylines are joined by dashed connectors, and graph edges between timeline nodes are drawn as arcs
• Dated nodes outside every storyline appear in a gray "Unassigned" lane, so the timeline covers every dated node in the workspace
• Marks carry the node's own color when set, falling back to the lane's storyline color
• Hovering a bead or bar shows the same hover preview as the canvas
• The sheet stays open alongside the storyline overview and the reader (the reader sits above it)
• Clicking a lane or bead opens that storyline in the reader; a left-edge push or the close button slides the sheet away

Importing an ontology

Drop an ontology file (.ttl, .rdf, .owl, .jsonld) on the canvas to import its classes and, optionally, its individuals as nodes, with their relations as edges.

An ontology published as several files (for example OBOE's oboe-core, oboe-characteristics and oboe-standards) can be imported one file at a time, in any order: a class that refers to a class from another file is linked once both are in the workspace.

To add the links missing from an ontology imported before this worked:

1. Open the workspace that holds the ontology.
2. Drop the ontology's files on the canvas again.

Classes already in the workspace are not created again and existing edges are not duplicated, so only the missing links are added.

Math with Typst

Native Typst integration for fast mathematical typesetting:

• Sub-second rendering - No LaTeX compile times
• Modern syntax - Cleaner than LaTeX
• Inline and block - Both supported

Examples

Inline math: $x^2 + y^2 = z^2$

Block math:

$$
integral_0^infinity e^(-x^2) dif x = sqrt(pi)/2
$$

See Typst Math Reference for complete syntax.

Obsidian Integration

Vault Import

Import existing Obsidian vaults:

• Markdown content preserved
• Wiki-links [[link]] converted to edges
• Folder structure respected
• Automatic force-directed layout

Bi-directional Sync

Changes sync between Nodus and your vault folder:

• Edit in Nodus → updates Obsidian vault
• Edit in Obsidian → updates Nodus canvas
• File watcher detects external changes
• Renaming a node in Nodus renames its vault file to the new title, with the same character substitutions Nodus applies when it creates a file; the file's content, frontmatter included, is left as it is. If another file already carries the target name, the node keeps its current file name. The rename is invisible to the watcher, so it is never read back as a deleted note and a new one
• With sync disabled, edits change only the Nodus database; vault files are never written or renamed

Workspace Separation

Each imported vault becomes a separate workspace, keeping projects organized.

Citation Management

Zotero Integration

Nodus exchanges references with a Zotero library through the Zotero Web API. Each direction is a single action you start; nothing is synchronised afterwards, so a later change on one side does not reach the other.

Nodus reads the library as it is stored on zotero.org, not the local Zotero database: items and collections that the Zotero desktop application has not yet synced are not visible. It reaches your personal library only, not group libraries, and the same account serves every workspace.

Connect to Zotero

Prerequisite: a Zotero account whose library is synced to zotero.org.

1. Open zotero.org/settings/keys and create a private API key. Allow library access; allow write access only if you want to add references from Nodus.
2. Note the numeric user ID shown on the same page.
3. In Nodus, open Settings > Zotero.
4. Enter the user ID and the API key under "Zotero Cloud".
5. Select "Test connection".

Result: the status shows "Connected" and the collections of the library are listed. A library without collections lists none; its items can still be imported.

A key without write access is enough for importing and makes "Add to Zotero" fail without changing the library.

Import references

1. Open the workspace that should receive the references.
2. Open Settings > Zotero.
3. Select "Import" beside a collection, or "Import All Items" for the whole library.

Result: each top-level item becomes a citation node in the open workspace, with its title, authors, date, journal, DOI and abstract, and the Zotero item key in its frontmatter (zotero_key). Attachments and notes are not imported. The nodes are laid out in a grid and are not connected; see Citation Graph below for connecting them. Importing the same items again creates the nodes again.

Add references to Zotero

Prerequisite: the API key has write access.

1. Select one or more citation nodes on the canvas.
2. Right-click and select "Add to Zotero".

The action is offered when the selection holds a citation node or a citation stub, and adds only those: notes in the same selection are left out.

Result: each selected node becomes a new item at the top level of the library. A node whose DOI already exists in the library is skipped and counted as a duplicate; a node without content is skipped. An existing Zotero item is never changed or deleted. If the library cannot be read, nothing is added, because duplicates could not be checked.

Dropping a PDF offers the same step for its extracted references ("Add references to Zotero").

An agent can take the same step: the add_to_zotero tool, available to MCP clients and to the in-app agent, takes the ids of the nodes to add and follows the same rules.

Semantic Scholar Integration

Fetch citations for papers with DOIs:

• Right-click citation nodes and select "Fetch Citations"
• Creates a citation node for each referenced or citing paper that is not on the canvas yet
• Builds citation network on your canvas

Citation Graph

Connect the papers on the canvas by who cites whom.

Prerequisite: the open workspace holds citation nodes with a DOI or a Semantic Scholar id, for example from a Zotero or BibTeX import. Papers without either are skipped.

1. Open Settings > Zotero > Citation Graph.
2. Leave "Create stub nodes for missing papers" on to add a stub node for a cited paper that is not on the canvas, at most 10 per paper; switch it off to connect only the papers already there.
3. Select "Build Citation Graph".
4. To end the build early, select "Stop". The build ends before the next paper, and the edges and stub nodes created so far are kept.

Result: a cites edge joins each pair of papers on the canvas where one cites the other, and the panel reports the number of edges and stub nodes created.

The build asks Semantic Scholar for each paper, its references and its citations: at least three requests per paper, at least 3 seconds apart, and longer when the service limits the rate, so 100 papers take 15 minutes or more. The progress line shows the paper being processed and its position (12 of 130). Answers are kept for 24 hours, so a build that was stopped and started again does not repeat the requests it already made.

BibTeX Import

Import .bib files directly to create citation nodes with:

• Author, title, year
• DOI links
• Journal/conference info

LLM Integration

Connect AI assistants for research help:

Supported Providers

Agent Features

• Research assistance
• Content summarization
• Smart node connections
• Task automation

Ask AI on the canvas vs. on a node

Two scopes keep AI actions predictable:

• Agent panel on the canvas's left edge runs the graph agent, which can create and edit nodes, add edges, and lay out the graph. It is a chat: prompts and full answers stay in a transcript, each answer listing the tools it used, and a line above the input names the nodes going into the context (the current selection, or the whole graph when nothing is selected). Fold it away with the toggle in the canvas's top-left corner, or reveal it with a left-edge push; drag its inner edge to resize it.
• Node "Ask" bar (in the node preview) runs the node agent, which only edits the current note. It never creates new nodes.

Plan-first approval

The graph agent always works in two phases:

1. Plan. It researches and reads the graph only; it cannot create, edit, delete, or connect nodes in this phase. It then proposes a plan.
2. Execute. The plan opens in an approval dialog that states, up front, what it will create versus edit (for example, "create 7 new nodes, edit 2"). Each step is labeled with its action and lists the affected node titles. Nothing is written to the graph until you approve.

This makes node creation predictable: the agent never adds a node you did not see listed and approve.

Layout Algorithms

Automatic arrangement of nodes:

Export Options

Typst Export

Export canvas as Typst document for further editing.

PDF Generation

Generate PDFs directly using Typst compilation.

Print to PDF

Save the canvas as a picture on one PDF page.

1. Select the nodes to print, or select none to print every node of the workspace.
2. Select "Print to PDF" in the canvas controls, or right-click a node and select "Print to PDF".
3. Choose where to save the file.

Result: a single vector page as large as the printed nodes, showing each as a card with its title and content, joined by the edges that run between them. Selection and hover highlights are not printed, and the light theme's colours are used. Math, images and diagrams are printed as their source text.

Markdown Export

Export nodes as standard Markdown files.

Open Knowledge Format Export

Export a workspace as an Open Knowledge Format (OKF v0.2) bundle so AI agents and other OKF consumers can read it without Nodus:

• Every node with content becomes a Markdown concept document with YAML frontmatter: type (from the node type), title, tags, and generated provenance
• Documents are grouped into subdirectories by node type (notes/, citations/, ...)
• A root index.md declares okf_version: "0.2" and lists all documents by section with descriptions
• Wikilinks are rewritten to bundle-relative Markdown links in the exported copy; unresolvable links are left unchanged
• The export writes to a folder you choose; the workspace and its vault files are not modified

Files that Nodus itself creates in a vault (via "create file for node" or the export-to-files action) also carry OKF frontmatter, unless the content already starts with its own frontmatter block. Existing vault files are never rewritten to add frontmatter.

Data Storage

Local-First Architecture

All data stored on your device:

• SQLite - Metadata, positions, connections
• Markdown files - Content (Obsidian-compatible)
• No cloud required - Works fully offline

Privacy

• No telemetry
• No data collection
• Your data stays yours

Keyboard Shortcuts

Press ? on the canvas for the full list.

Themes

Node colors can be customized individually.