How Nodez works

Nodez sits on top of a folder of Markdown files. It does not import them, convert them, or move them into a database. Everything you write stays a plain .md file in a folder you chose, which means you can open the same folder in any other editor - or in Finder - and nothing is missing.

That single decision explains most of the rest of the app.

Your files come first#

When you open a vault, you are pointing Nodez at a folder. It reads what is there and writes back plain Markdown. Close Nodez and the folder is still a perfectly ordinary set of text files.

The practical consequence: your notes outlive the app. If Nodez stopped being developed tomorrow, you would lose an interface, not your writing.

The index: what Nodez remembers#

As you write, Nodez keeps a quiet running list of what is in your vault - note titles, headings, tags, and which notes link to which. This is the index, and it is what makes search feel instant and backlinks appear without you doing anything.

The index is rebuilt from your files, never the other way round. It is a convenience, not a source of truth. Delete it and Nodez rebuilds it.

The graph: your notes as a map#

Every link you write is a connection between two notes. Collect enough of them and you have a map of how your thinking is organised - which ideas are central, which notes are isolated, which clusters have formed without you planning them.

The graph view draws that map. You can:

• See the whole vault at once, or just the neighbourhood around one note
• Trace a path between two notes to find out how they are related
• Filter to particular kinds of note or connection
• Group by community - clusters Nodez detects from the shape of your links

There are two ways of drawing it. The 2D view is the default and is the faster, calmer one. The 3D view puts the same graph in space, which makes dense clusters easier to pull apart. Both are drawing the same underlying data.

Your code, in the same picture#

You can also point Nodez at a code project. It reads that folder the same way it reads your notes - what imports what, what calls what, which files depend on which - and adds it to the same graph.

The payoff is being able to see notes and code together: the design note that explains a module sitting next to the module. See Indexing a repository.

Nodez only ever reads your code. It does not edit it.

Sync is just git#

Nodez does not run a sync service, and there is no Nodez account. If your vault is a git repository, Nodez can pull, commit, and push it for you, and it shows you when your local copy has fallen behind.

When something conflicts, it stops and tells you rather than guessing. Nothing is committed or pushed unless you ask. See Syncing with GitHub.

Talking to AI agents#

This is the part that is unusual. Nodez can serve your notes-and-code graph to an AI assistant - Claude, Cursor, and anything else that speaks MCP, the standard protocol for connecting tools to assistants.

The difference this makes: instead of pasting files into a chat window and hoping the assistant guesses the context, it can query the map. It can ask which notes mention a topic, what a particular file depends on, or what would be affected by changing something - and then read only the handful of files that actually matter.

This runs on your machine and reads the vault you opened. Nodez needs Node.js installed for this feature; the app tells you if it cannot find it.

What Nodez deliberately is not#

• Not a cloud service. There is no server holding your notes, and no account.
• Not a database. The files are the truth. Everything else is derived.
• Not a code editor replacement. It reads your code to map it; it does not try to be your IDE.
• Not collaborative - no live multi-person editing. Sharing is git.