Skip to content
Smart Plugins

Official Smart Plugins site

Smart Plugins are independent third-party plugins for Obsidian. Smart Connections is the flagship plugin.

Tune Smart Connections scoring and ranking algorithms

Connections Pro exposes score and ranking controls so you can tune signal, not just change algorithms.

Use this page when results are close, noisy, under-weighted, or out of order.

Start with the symptom:

Symptom Tune first Why
Results are too broad Results type, limits, filters The candidate pool is probably too wide.
Results are relevant but ordered poorly Ranking algorithm The score is acceptable, but final order needs shaping.
Valuable project/tag/frontmatter notes are under-ranked Score algorithm weights The relevance signal needs metadata or path emphasis.
Same low-value notes keep returning Feedback-aware scoring or filters You need to steer recurring noise.
Similar notes are actually repeated work Smart Dedupe Cleanup is a review decision, not a ranking tweak.

Setup flow

Recommended order:

  1. Choose the candidate pool.
  2. Adjust filters and limits.
  3. Select a score algorithm.
  4. Add ranking only when you need extra shaping.
  5. Use Dedupe when repeated material needs review, not when the list merely needs tuning.

Candidate pool

Choose a results collection key.

Use Sources when you want broader overview.
Use Blocks when long notes hide the useful section and you need finer-grained matches.

Filters before algorithms

Filters decide what is allowed into the list.

Use them before advanced scoring when the problem is scope.

Good filter use cases:

If you want notes excluded from indexing entirely, use Smart Environment exclusions instead.
Connections filters affect what is shown after Smart Environment has prepared the data.

Related:
Smart Connections settings
Smart Environment settings

Score algorithms

Score algorithms decide the primary relevance score for each candidate.

Start with Cosine Similarity as the baseline.

Move to feedback or metadata weighting after you observe noisy, under-weighted, or over-weighted results.

Algorithm What it does When to use
Cosine Similarity Ranks by embedding similarity between the current note and candidates. Default when you want stable, feedback-free results.
Similarity Adjusted by Feedback Penalizes candidates similar to hidden notes. When you want to reduce recurring noise.
Similarity Weighted by Feedback Boosts candidates similar to pinned notes and dampens hidden notes. When you actively pin or hide to steer results.
Similarity Weighted by Key + Frontmatter Multiplies similarity based on key fragments and frontmatter matches. When metadata should emphasize or de-emphasize results.

Ranking algorithms

Ranking algorithms reorder already-scored candidates.

Use ranking when results are relevant but the final order feels wrong.

Algorithm What it does Notes
None Keeps the original score order. Fastest option.
Re-ranking model Applies Smart Rank to reorder the scored list. Requires a Smart Rank model in Smart Environment Pro settings.
Recency rank Orders results by most recently modified items. Useful when freshness should dominate final order.

Score vs ranking boundary

Keep the boundary simple:

If you change too many layers at once, it becomes hard to know what helped.

A practical rule:

Fix scope first. Tune relevance second. Reorder third. Clean up repeated work only after review.

Controls at a glance

Practical presets

Default, low-maintenance

Use this when you want stable, broad note-level discovery.

Reduce recurring noise

Use this after hiding notes that keep polluting useful results.

Leverage explicit curation

Use this when pinned and hidden signals represent real preference.

Metadata-driven retrieval

Use this when folders, keys, headings, or frontmatter should shape relevance.

Example weighting config

Use JSON in the score algorithm settings:

{
	"key_weights": {
		"Projects/": 1.2,
		"Readwise/": 0.8,
		"#High-value heading": 1.3
	},
	"meta_weights": {
		"status:evergreen": 1.15,
		"type=spec": 1.1,
		"reviewed": 1.05
	}
}

This is best for structural intent.

Use recency ranking for freshness intent.

Tuning workflow

1. Establish a baseline

Start with:

Open one real note and write down what feels wrong.

2. Fix scope

If results come from the wrong part of the vault, use filters first.

Do not use a ranking model to solve a scope problem.

3. Fix granularity

If whole notes are too broad, test Smart Blocks.

If blocks are too noisy or heavy, return to Sources or tune block settings in Smart Environment.

4. Fix signal

If the right notes exist but are consistently under-weighted, add metadata or feedback weighting.

5. Fix final order

If the right candidates are present but poorly ordered, add ranking.

6. Use Dedupe for repeated work

If the problem is that similar blocks should be compared, merged manually, archived, or ignored, use Smart Dedupe.

Similarity creates the question.
Dedupe review turns it into a decision.

Troubleshooting quick checks

Results feel too broad

Try:

Same low-value notes keep returning

Try:

Valuable tagged or foldered notes are under-ranked

Try:

Results are relevant but ordering feels off

Try:

Similar results look like duplicates

Use Dedupe, not ranking.

Connections algorithms decide retrieval order.
Dedupe helps review likely repeated blocks or notes side by side.

Related pages