I keep my notes in plain Markdown files. Someone out there has a graph view for them — of course they do — but it lives in a GUI editor, and I'm at the terminal. I wanted to see how my notes connect without switching surfaces. So I built graffa — a terminal interface that reads a Markdown vault and shows the graph alongside the notes, right where I already am.
┌──────────────────────────────────────────────────────────┐
│ graffa 229 notes / 173 edges │ all domains │ norm │
├──────────────┬───────────────────┬───────────────────────┤
│ Notes [/] │ Map · 7 direct · │ Reader │
│ │ 12 two-hop │ │
│ > Project A │ ops │ Project A │
│ dev │ ○ ○ │ development/planning │
│ │ ○ ○ │ notes/project-a.md │
│ Project B │ ○ ○ ○ │ │
│ design │ ○ ○ ○ │ A proposal for │
│ │ ○ ○ ● ○ ○ │ the next iteration │
│ Proposal │ ○ │ of the platform │
│ dev │ ○ ○ │ architecture... │
│ │ design │ │
│ │ │ ## Scope │
│ │ │ The refactoring │
│ │ │ focuses on three │
│ │ │ modules... │
├──────────────┴───────────────────┴───────────────────────┤
│ loaded demo vault j/k sel / filter d dom t tag ... │
└──────────────────────────────────────────────────────────┘
The note list stays on the left, filterable by text, domain, or tag. The document reader fills the right panel with the full note body. And the middle panel shows an ego map — the selected note at the center, its direct links in an inner ring, and two-hop connections in an outer ring — organized so that notes from the same domain share the same wedge of the circle.
The domain alignment is what keeps the map readable without a physics engine. Force-directed layouts shift everything when you add a note. Ring layouts avoid the jitter but scatter related notes around the circle. By assigning each domain its own sector and placing notes within that sector across both rings, related notes stay together whether they're one hop or two hops away. The map answers the nearby question without needing to redraw the universe.
Everything about graffa follows from the same motivation — the graph should serve the reading, not take over the screen. It works on plain Markdown files, offline, without an account. The native backend scans YAML frontmatter, Markdown links, and [[wikilinks]] directly from the filesystem. There's a zk backend if you already have an indexed notebook. Navigation is keyboard-driven — j/k to move through the list, d/t to cycle domain and tag filters, Tab to switch panes. No mouse, no GUI, no reason to leave the terminal.
The files don't change. No import, no migration, no lock-in. Point it at a directory of Markdown files and it builds the graph from what it finds.
graffa is on Codeberg — clone it, point --notebook-root at your vault, and see if the graph stays in its lane.