With BRAT — installs and keeps updating itself

1. Install Obsidian42 - BRAT from the community plugins.
2. Command palette → BRAT: Add a beta plugin for testing.
3. Paste DBB-FC/why-graph.

BRAT installs it, enables it, and updates it on every release.

By hand

Download main.js, manifest.json and styles.css from the latest release into <vault>/.obsidian/plugins/mapa-neuronal/, then enable it in Settings → Community plugins. Nothing else is needed: those three files are the whole plugin.

Everything else lives in the tools menu — the ⋯ tools chip on the map, or the tab's own ··· menu:

This plugin grew inside a vault built on the LLM wiki pattern — Andrej Karpathy's original design: immutable raw sources on one side, a curated wiki the LLM maintains on the other, and a written contract between them. It does not require that pattern, and it names no folder of its own — but that is the shape it was designed against. Any vault with a deliberate structure (PARA, Zettelkasten with MOCs, a digital garden with topic hubs) gets the same benefit.

If you run an LLM wiki, the map does something specific for you: the raw layer becomes the first column, the curated wiki the middle ones, and the syntheses the last — so you can see at a glance whether your sources are actually being distilled, or just piling up.

If your vault is flat today, the map is still useful as a diagnosis: it shows you exactly how much of your thinking is sitting in one undifferentiated pile.

No, and no plugin can. Subscriptions (Claude Pro/Max, ChatGPT Plus) pay for the vendor's own apps; there is no public API you can authenticate with a subscription. The API is a separate product, billed per token with prepaid credit.

Three ways to deal with that:

• Local AI — free. Ollama or LM Studio on your own machine: no key, no cost, and your notes never leave the computer. This is the answer if you do not want to pay per use.
• Your own key. A few cents per suggestion — roughly $0.04 with Claude Opus 5. New API accounts get free credit to try it.
• No AI at all. The AI only proposes reasons for links that do not have one; everything else — layers, paths, gaps, radial, export — never makes a network call.

Plugins that appear to run on "one subscription" are doing one of two things: using a local model (free, like the option above), or paying the API with the developer's own key and charging you a subscription for it — which means your notes pass through their server. This plugin has no server, so that trade is not on the table.

Four fields: pick the provider, paste your key, choose the model, and press Test the connection — one tiny call that tells you whether it answers, without sending any note. The key is stored on this device only.

Every approval is logged (date, model, quotes, resulting text) in a note under the audit folder, so you can audit or undo later.

Measured accuracy

On a real vault of 254 notes and 916 links, over a reproducible sample of 44 links reviewed blind against the source notes:

That measurement was made with Claude Opus 5. With other models the locks still apply — a proposal without verifiable quotes still cannot be approved — but the hit rate is untested; treat it as unknown until you measure it on your own vault.

Everything above the dashed AI box happens inside your computer, with no network call at all. The AI is reached only when you ask for a suggestion, with your key; whatever it proposes has to survive a code check of its quotes and your approval before a single line is written back to your note. The interactive version of this diagram is in docs/diagramas/mapa-neuronal.html — download it and open it in a browser.

A user reimplemented the engine in Python to predict the counts before touching their vault, and they matched. These are the rules, written once (they also ship inside the exported JSON):

• Node: every .md file inside a folder assigned to a layer, minus the excluded ones. The most specific folder wins. Sources cited by path do not count as notes.
• Link: an undirected pair of notes on the map joined by at least one resolved [[wikilink]]. A→B and B→A are one link. Self-links and links to notes off the map are ignored.
• Reason: the text of - [[note]] — reason in the connections section; failing that, the first body line where the link appears.
• Topic: the topic frontmatter property; if missing, the most frequent topic among its neighbours.
• Hub: per topic, the last-layer note with hub: true; if none has it, the first one in that layer with the topic declared.
• Order within a layer: by topic, then by the weighted barycentre of its neighbours (adjacent layers weigh 1, distant ones 1/distance), six passes.
• Off the map: notes that fall in no folder with a layer are counted in the header and flagged on load, as are configured folders that hold no notes.

• Your notes go to the provider you choose, with your key, at your cost. The plugin has no server. The author never sees your notes, your keys or your queries.
• Keys are stored per device in Obsidian's local storage — never in data.json, so they never travel through git, Obsidian Sync or a backup.
• Nothing is sent until you ask for a suggestion. Opening the map, browsing, paths and gaps make zero network calls.
• Rough cost per suggestion with Claude Opus 5: two notes of context plus the review pass. A vault with a hundred reason-less links costs single-digit dollars to work through — and you never have to do it in one go.
• The local provider (Ollama) sends nothing anywhere: no key, no internet, no cost.

The plugin does not save tokens by itself — the structure does, and the plugin is what makes the missing pieces impossible to ignore. Its own AI feature spends tokens: about 3,900 of input per suggestion, roughly $0.04 with Claude Opus 5.

What pays off is the other direction. A reason is written once and read many times: by you, and by any agent that works against your vault. The three rows above were measured on the author's vault — 254 notes, 916 links, ~147,800 tokens of wiki — by counting characters ÷ 3.7 and comparing what each question costs to answer with and without the written structure. Your numbers will differ; the ratios are what travel.

The honest caveat is in the figure: nobody dumps a whole wiki on every question — an agent greps. The defensible comparison is the first row, reading the reason instead of opening both notes, and that one is 115×.

Only when you press Approve on an AI suggestion, and only as an appended line in the connections section of that one note. Existing text is never rewritten or reordered, and your frontmatter is not touched unless you fill in the Last-modified property setting, which is empty by default.

Everything else — layers, colours, paths, gaps, exports — is read-only. Exports are the one other write: a PNG into the folder you choose.

There is no telemetry, no analytics and no server: the plugin makes no network request except the AI call you ask for, to the provider you configured.

It does read the list of every note in your vault — a map cannot be drawn from a subset — and the release assets carry GitHub attestations, so you can verify they were built from this source:

gh attestation verify main.js --repo DBB-FC/why-graph

With any vault you see the map. If your notes also cite their sources by path — as an LLM wiki does, with its raw sources in a folder — the map also shows where each thing came from:

• On demand. Tap a note and the files it cites appear next to it; tap another and they change. The first layer stops growing with every clipping.
• A source's card opens the original file, lists which notes cite it, and jumps to the exact line of the citation.
• Broken reference. A note citing a file that does not exist shows in red in health mode.
• Unlinked sources. Under "⋯ tools", a list of the files in your source folders that no note on the map cites, with the counter "cited: X of Y" and its scope. It says only that: not whether you processed them. Your workflow gives it meaning, not the plugin.
• Search finds sources, hidden notes and members of collapsed topics.

A citation is an explicit path: in backticks, in a [[wikilink]], in a link, or bare up to the first space. Citing a folder is not the same as citing every file inside it.

Tested on a vault with 5,043 notes and 17,526 links. Each layer draws its most connected notes (default 150) and reveals the rest on demand, so the map stays interactive instead of drawing a grey rectangle. Radial view caps each ring at 80.

The map draws on a dark canvas in both light and dark Obsidian themes — like a night sky, so the topic colours and the light pulses along the links stay readable. The panel, the chips and the settings follow your theme.

Everything runs from src/; the release is one esbuild pass, unminified.

npm install
npm test        # builds src/main.js → main.js and checks the translations
npx eslint src/ # the official Obsidian plugin linter
./instalar-en-vault.sh /path/to/your/vault

src/main.js is the source. main.js in the repository root is the build output and is not committed — releases carry it. The build is a single esbuild pass, no minification, so the released file stays readable.

The README animation is generated the same way, from the real plugin over a demo vault: ./pruebas/mirador/demo.sh.

MIT. Free for anything — personal or commercial — and you may fork it, change it and redistribute it, keeping the copyright notice.

The plugin itself charges nothing and has no paid tier. The Obsidian directory still labels it optional payments, because it can connect to AI services that charge you directly with your own key; the local provider (Ollama, LM Studio) costs nothing at all.