Obsidian Smart Connections: local embeddings for related-note search

The unlinked-notes problem Smart Connections targets

The README frames the problem through the author's own history: a forgotten 20-page Google Doc, and the note that it hit "like a punch." The stated audience is narrow and specific. Obsidian power users, researchers, writers and lifelong learners who already have hundreds or thousands of notes. That is the person this plugin is built for, and it is also the person most likely to be disappointed by a keyword search box.

The failure mode the README describes is not capture, it is retrieval. Ideas get written down quickly and then never resurface, so the vault grows into what the README calls a maze. The cost is duplicated work and rereading. Smart Connections answers that by ranking existing notes against whatever you are currently writing, rather than waiting for you to remember the right search term. If you have fifty notes and remember all of them, the plugin has nothing to add.

How local embeddings and the Smart Environment produce connections

The mechanism, as the README describes it, is semantic: a local embedding model turns note content into vectors, and the plugin compares those vectors to surface notes that are semantically related to the current one. The README says the model ships with the plugin and "just works," with zero setup and no API key. The repository layout backs up the local-first claim. The top level contains smart_env.config.js, which is the configuration surface for the Smart Environment, and package.json lists a set of internal packages including smart-embed-model, smart-entities, smart-collections and smart-file-system, all resolved as local file paths rather than published dependencies.

That dependency structure matters for anyone judging the project's auditability. The README claims the bundle is ultra-lightweight with minimal third party dependencies and that the codebase can be audited more than three times faster than comparable AI plugins. The package.json is more complicated than that pitch suggests: several runtime dependencies point at sibling directories (file:../jsbrains/...) plus obsidian-smart-env, and jsbrains itself is pinned as a git dependency at a specific commit in devDependencies. So the shipped plugin has a small dependency surface, but building it from source requires those sibling repositories to be present. The README also mentions a Smart Environment that the plugin uses, and the settings guide covers indexing, filters and ranking defaults.

Installing Smart Connections from Obsidian Community plugins

The README's three-step plan is the official install path, and it does not involve a terminal. Install and enable Smart Connections from Obsidian Community plugins, keep writing so the built-in local model indexes the vault, then open the Connections view to see relevant notes and drag links into the current note.

There is no CLI install command in the README, so nothing to show in a shell block. What the repository does document is the development path, which is what you would use if you wanted to build the plugin yourself rather than take the Community plugins release. The package.json defines these scripts, and they are the only build entry points given:

npm run build
npm run build-dev
npm run test

The build script runs node esbuild.js; build-dev runs the same esbuild.js with a .env file loaded via --env-file=.env; and test runs npx ava --verbose. Because several dependencies are declared as file: paths into sibling directories, a fresh clone will not build until those directories exist, which the README does not walk through. For normal users the Community plugins route is the intended one, and the README points to the Getting Started guide for reaching a first successful workflow.

Where Smart Connections stops short

The README is a marketing document, and the gaps show. It does not document rollback, index invalidation, or what happens when the local embedding model is unavailable or fails mid-scan. For a plugin whose entire value depends on a persistent vector index over your vault, that is a real omission. If the index corrupts or a model update changes vector dimensions, the README gives you no recovery procedure.

The licence is the second limitation. The repository reports NOASSERTION, and package.json declares "license": "SEE LICENSE IN LICENSE". That is not a recognised SPDX identifier, so you cannot assume MIT or Apache terms from the metadata alone. The README describes the core as "source available," which is a different posture from open source. For an individual installing into a personal vault this is mostly academic. For anyone redistributing the plugin or embedding it in a product, it is the first thing to resolve.

Third, the Pro surfaces are explicitly separated. Inline connections and the Bases integration are listed under Pro, so the free path covers the Connections view and Lookup but not in-editor suggestions. The README does not state pricing for those Pro plugins, and it should not be inferred from the repository.

Smart Connections compared with Obsidian Copilot

The most common comparison is with Obsidian Copilot, and the difference is architectural rather than cosmetic. Smart Connections is built around a local embedding model that ships with the plugin and runs offline by default, with no API key required. That is the README's central claim, and it is why the plugin can index a vault without sending note content to a provider.

Copilot, by contrast, is oriented around chat with hosted models. The README for Smart Connections pairs it with Smart Chat and mentions ChatGPT, Claude and Gemini in the repository topics, but the Connections feature itself is the local semantic layer. If your goal is a conversational assistant over your notes backed by a hosted model, Copilot is the closer fit. If your goal is a ranked list of related notes that appears while you write, without a key or a network call, Smart Connections is aimed squarely at that. The two can coexist, and the README's own walkthrough video shows Smart Connections alongside Smart Chat rather than replacing it.

Maintenance, releases and what upgrades cost you

The repository is not archived, and the last push was on 2026-09-13, four days before this writing. Recent releases are 4.7.0, 4.7.1 and 4.7.2, all published on 2026-08-05 and 2026-08-06. So the project is releasing frequently enough that version drift is a real consideration, and the version in package.json (4.7.2) matches the latest tagged release.

Upgrade cost is dominated by reindexing. The README's design means embeddings are computed locally, and a model change or a settings change to indexing and filters can invalidate existing vectors. The settings guide is the place the README points for configuring indexing, filters, ranking and UI defaults, which is also where you would go after an upgrade that changes ranking behaviour. The migrations/ directory at the repository root suggests schema changes are handled in-tree, but the README does not describe a migration procedure for users. Budget time for a reindex after major version bumps, and treat the Pro surfaces as a separate upgrade track since inline connections and Bases are documented under Pro rather than core.

What to check before you commit your vault to it

Three things are worth verifying on your own machine before you rely on Smart Connections. First, that the local embedding model runs acceptably on your hardware, particularly on mobile, where the README claims support but where local inference is the hardest constraint. Second, that your vault's size and file mix match the settings guide's indexing and filter controls, because a vault with large attachments or generated files will behave differently from one with plain markdown. Third, the LICENSE file itself, since NOASSERTION in the repository metadata tells you nothing about redistribution rights.

The README is honest about the intended user and thin about the edge cases. Read the Getting Started and settings guides before you enable it on a vault you care about, and keep a backup of the vault outside Obsidian's sync so that an index problem is never a data problem.

Editorial conclusion

Adopt it if you already run Obsidian with hundreds or thousands of notes and want semantic related-note surfacing without an API key or a cloud round trip; the README's three-step plan (install from Community plugins, keep writing, open the Connections view) is the whole onboarding. Do not adopt it if you need a permissively licensed codebase, since the repository declares NOASSERTION and package.json points to SEE LICENSE IN LICENSE, or if you need documented index rollback, which the README does not cover. Verify first that a local embedding model actually runs on your hardware, especially on mobile, and read the LICENSE file before shipping the plugin inside a distributed vault.

Frequently asked questions

Official sources

1. brianpetro/obsidian-smart-connections on GitHub
2. Issues
3. Project website
4. README
5. Releases