Registered by registerGraphSettings()
(src/services/settings/GraphSettings.ts) under the Note Graph section
of Joplin's Configuration screen. Registration itself is dynamic and re-runs on
every plugin start (Joplin doesn't persist section/setting definitions
across restarts), but the values a user sets are persisted by Joplin as
normal.
The section's description tells users how to open the graph in a popup (the graph icon in the note toolbar, or Note Graph Popup in the Command Palette) and how to close it. The popup has no menu item, so it has no keyboard shortcut: Joplin only lets users assign shortcuts to plugin commands that appear in a menu.
| Setting | Key | Type | Default | Effect |
|---|---|---|---|---|
| Enable AI-based semantic analysis | noteGraph.aiAnalysisEnabled |
Boolean | false |
Turns semantic edges on or off. Requires Joplin AI to be enabled with a ready embedding index (Configuration screen's AI page). |
| Similarity threshold (%) | noteGraph.similarityThreshold |
Integer, 0-100, step 5 | 70 |
Only the strongest (100 − value)% of candidate pairs become edges, ranked by how much closer two notes are than each usually is to its nearest notes. Lower = more edges. Only applies when AI analysis is enabled. |
| Max semantic edges per note (top-K) | noteGraph.maxEdgesPerNote |
Integer, 1-20, step 1 | 5 |
Caps how many of each note's strongest semantic connections are kept. Only applies when AI analysis is enabled. |
| Enable LLM analysis | noteGraph.llmEnrichmentEnabled |
Boolean | false |
Turns on Pass B: relationship explanations via Joplin AI chat. Requires AI-based semantic analysis to also be enabled. See LLM enrichment. |
| Retry AI embedding | noteGraph.retryEmbedding |
Boolean | false |
One-shot trigger, not a persistent toggle: ticking it immediately retries AI-based semantic analysis (for example, after cancelling it), then unticks itself. No-op if the graph panel hasn't been opened yet. |
| Retry AI labels | noteGraph.retryEnrichment |
Boolean | false |
One-shot trigger, not a persistent toggle: ticking it labels up to 200 more connections still missing a label straight away, and restarts background labeling if it stopped, then unticks itself. No-op if the graph panel hasn't been opened yet. |
Joplin's settings API has no float/slider type, only integer, so the
threshold is stored as a whole-number percentage and converted to the 0-1
scale SimilarityEngine expects by getSimilaritySettings(). A value
outside its valid range, or one that isn't a usable number at all, falls
back to the setting's default rather than being clamped to the nearest
valid value. See Similarity engine for what
threshold and top-K actually do in the scoring pipeline.
index.ts listens for joplin.settings.onChange and only acts if the
graph has already been built at least once (analysisController.hasNotes())
and the change touched one of the six keys above (NOTE_GRAPH_SETTING_KEYS):
- Ticking "Retry AI embedding" is handled first and separately from
everything else: the setting is immediately reset to
false(so it behaves like a button, not a checkbox that stays on) and AI analysis re-runs, reusing cached embeddings for unchanged notes and re-embedding only the ones that miss the cache. - Ticking "Retry AI labels" is handled next, the same way: reset to
false, then a Pass B retry pass runs. See LLM enrichment. - Choosing a different scope in the panel's notebook menu only changes which notes are drawn. Every note is already loaded, so nothing is read again; see Large vaults.
- Toggling AI analysis re-runs the full semantic analysis
(
runSemanticAnalysis), which re-embeds if turning on, or drops back to the structural graph if turning off. This also determines whether Pass B can do anything, since it depends on semantic edges existing. - Any other change (threshold, top-K, or toggling LLM analysis) is a
no-op if AI analysis is currently off, since none of them have an effect
without semantic edges. If AI analysis is on but notes haven't been
embedded yet, it falls back to a full
runSemanticAnalysis. Otherwise it recomputes edges from the already-embedded vectors and re-runs Pass B enrichment against the new edge set, reusing whatever is already cached.
If the panel hasn't been opened yet, a settings change is a no-op; the new values simply apply the next time the graph is built.