Brain Graph

An Obsidian plugin that draws your vault as a brain, in 2D or 3D. It's a lightweight alternative to the core graph view.

• Neurons: each note is a point on the cortex. The 10 most connected notes always show their names.
• Regions: each community of notes (detected from links) or each top-level folder becomes a region of the cortex. Tightly connected groups sit next to each other.
• Orphans: notes without links live in the cerebellum.
• Fibers: the links. With the surface off (default), they dive toward the center like white matter. With the surface on, they arch over the outside.
• Stable map: positions are saved, so the brain always opens the same way. New notes land near their neighbors without shuffling the rest.
• Fits your theme: light and dark modes follow Obsidian, using your theme's background and interface colors.

Installation

From Community plugins

1. Open Settings → Community plugins → Browse and search for Brain Graph.
2. Select Install, then Enable.

Manual

1. Download main.js, manifest.json and styles.css from the latest release.
2. Put them in <vault>/.obsidian/plugins/brain-graph/ (create the folder if needed).
3. In Settings → Community plugins, reload the list and enable Brain Graph.

Open it from the brain icon in the ribbon or with Ctrl/Cmd+P → "Brain Graph: Open graph view".

On first open, the plugin computes the layout (a few seconds, depending on vault size) and writes layout.json to the plugin folder. Later opens are instant.

When updating manually, replace the files and restart Obsidian. Toggling the plugin off and on with the new version may fail to load.

Usage

• Navigate: drag to orbit (3D) or pan (2D), scroll to zoom. Click a note to open it; Ctrl/Cmd+click opens it in a new tab.
• Graph toolbar: switches 2D/3D, jumps to side, top and front views, toggles cortex, surface, depth of field, glow and ambient pulses, and has a search by note name.
• Commands: "Open graph view", "Recalculate layout" and "Toggle 2D/3D".

Settings

Performance

The plugin is built to run at 20 fps or more on integrated GPUs.

• On-demand rendering: it only redraws when something changes. For zero cost while the brain is still, turn off ambient pulses and idle animation. With either one on, the loop runs at about 30 fps.
• Auto pause: rendering stops when the tab is hidden.
• Finite layout: the layout converges and stops, with O(n) repulsion via a spatial hash. The result is stored in layout.json.
• LOD: depth of field reduces detail in the background.

Privacy

Brain Graph works fully offline. It lists the Markdown files in your vault and reads their links through Obsidian's metadata cache to build the graph; note contents never leave your machine. It makes no network requests, and only writes data.json (settings) and layout.json (positions) inside its own plugin folder.

Development

Requires Node.js 22 and npm.

npm install
npm run dev      # watch → main.js with sourcemap
npm run build    # type-check (tsc) + minified build
npm run deploy   # build + copy to a test vault

deploy uses the path given as an argument, or the BRAIN_GRAPH_VAULT variable, or ~/Documents/BrainGraph-Teste. For a path with spaces, call node dev/deploy.mjs "<vault>" directly.

Preview outside Obsidian

dev/preview.ts renders the brain with a fake vault in the browser:

npx esbuild dev/preview.ts --bundle --format=iife --outfile=dev/preview.js
python -m http.server 5178   # open http://localhost:5178/dev/index.html

URL parameters:

• n: number of notes (default 1500).
• clusters: number of groups.
• orphans: fraction of orphan notes.
• mode=2d.
• view=superior|frontal.
• cloud: no surface.
• Effects to turn off: nodof, noglow, noambient, noidle.

Measurement scripts

Bundle with npx esbuild dev/<script>.ts --bundle --platform=node --outfile=dev/<script>.js and run with node:

• dev/bench.ts: graph and layout time with 1.5k, 8k and 20k synthetic notes.
• dev/quality.ts [vault]: on a real vault, measures link length, reopening, new notes and distribution per lobe.
• dev/affinity.ts: checks that connected communities end up as neighbors.

Structure

Release

Releases are published by GitHub Actions (.github/workflows/release.yml):

1. Update version in manifest.json and package.json, and add the version to versions.json.
2. Commit, create an annotated tag without a v prefix (Obsidian requires the tag to match the manifest version exactly) and push: git tag -a 1.0.1 -m "Brain Graph 1.0.1" && git push origin main 1.0.1.
3. The workflow checks that the tag matches manifest.json, builds, attests the build provenance, and publishes main.js, manifest.json and styles.css.

To republish an existing tag, use Actions → Release → Run workflow and enter the tag.

License

MIT