Skip to content

Latest commit

 

History

History
62 lines (54 loc) · 4.52 KB

settings.md

File metadata and controls

62 lines (54 loc) · 4.52 KB

Settings reference

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.

Reacting to changes

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.