Soma Search

Soma Search is an Obsidian plugin that adds private, offline, local-first search to your vault. It brings the Soma search engine into a familiar Obsidian sidebar and manages a dedicated Soma instance for the current vault.

Search Markdown notes, PDF documents, scanned pages, images, and recorded audio with semantic (vector), keyword (lexical), or hybrid search — without sending a single byte to the cloud.

[!WARNING] Memory-hungry by nature. Processing multimedia files — images, scanned pages/PDFs, and audio (OCR, vision, speech-to-text) can need up to 24 GB of RAM while extraction is active. On machines with less memory, multimedia files may fail to index or never show up in results. Markdown and text-based PDFs need far less. See Requirements.

Folders are not memory. Memory returns as a phrase, an image, or a half-formed question — rarely as a file path. Soma Search gives every fragment an honest way back.

Table of contents

• Why Soma Search
• Features
• Soma Search vs. Obsidian built-in search
• Requirements
• Installation
• Getting started: index your vault
• Usage
• How it works
• Privacy and disclosures
• FAQ
• Troubleshooting
• Development
• Release
• Related projects

Why Soma Search

Obsidian's built-in search is fast, but it only matches literal text in Markdown. Everything else in a real vault — a scanned contract, a whiteboard photo, a research PDF, a meeting recording — is invisible to it. And if you can't remember the exact wording, keyword search can't help you either.

Soma Search fixes both problems:

1. It makes non-text files searchable through text extraction, OCR, vision, and speech-to-text.
2. It understands meaning, so "how do I cancel a subscription" can find a note titled "unsubscribe flow".

All of it runs locally on your machine.

Features

🔎 Three search modes

Semantic search is the default. Your mode and result limit are remembered between sessions.

📄 Search more than Markdown

Soma indexes far more than plain text — everything lands in the same index and is reachable with any search mode:

• PDF documents — extracts embedded text
• Scanned or image-based content — reads text with OCR
• Images and visual content — understands content through vision extraction
• Recorded media — turns speech into searchable text

⚠️ Up to 24 GB of RAM may be needed while multimedia extraction (OCR, vision, speech-to-text) is running.

🔒 Private by design

• Extraction, indexing, and inference all happen on your machine
• The plugin talks only to a local Soma instance on 127.0.0.1 over loopback HTTP
• No cloud search service, no telemetry, no accounts, no ads, no payments

⚡ Built for the Obsidian workflow

• Native search sidebar, opened from the ribbon or command palette
• Debounced search (450 ms) or instant search with Enter
• Results show file title, preview snippet, and line number when available
• Keyboard accessible: focus a result and press Enter or Space
• Markdown files open at the matching line
• Automatic sync on startup, then hourly

Soma Search vs. Obsidian built-in search

Requirements

• Obsidian desktop 1.13.0 or later with a local filesystem vault (mobile is not supported)
• Soma installed locally — when no full path is configured, the plugin tries common locations
• At least 8 GB of RAM; multimedia extraction may require 24 GB while active
• Network access only when Soma needs to download models or helper programs

Installation

1. Install Soma (the local search engine)

# Windows
winget install AwesomeDog.soma

# macOS
brew install AwesomeDog/tap/soma

# Linux
curl -fsSL https://github.com/AwesomeDog/soma/releases/latest/download/soma-linux-x64 -o soma
chmod +x soma && sudo mv soma /usr/local/bin/

Verify the installation before continuing:

soma sync

2. Install the Soma Search plugin

From Obsidian (recommended)

Settings → Community plugins → Browse → search "Soma Search" → Install → Enable

Manual install

1. Download main.js, manifest.json, and styles.css from the latest release.
2. Copy them into <your-vault>/.obsidian/plugins/soma-search/.
3. Reload Obsidian and enable Soma Search under community plugins.

If Soma isn't found automatically, set the full path to the soma executable in the plugin settings.

Getting started: index your vault

1. Open Soma Search from the ribbon icon or the command palette.
2. If the vault is not yet part of its directory-local Soma workspace, click Initialize in the sidebar.
3. Wait for indexing to finish.

The first initialization indexes the whole vault and may take a while on large vaults or vaults with many media files. The sidebar can stay on Initializing... during this process — let it complete before searching.

Under the hood the plugin runs:

soma init --no-color
soma project add --exclude=.obsidian/** --no-color .

Usage

1. Open the Soma Search sidebar.
2. Pick a mode: Semantic, Keyword, or Hybrid.
3. Type your query.

• Search runs 450 ms after you stop typing, or immediately when you press Enter.
• The result limit defaults to 20 and can be set anywhere from 5 to 100.
• Each result shows the file title, a preview, and a line number when available.
• Click a result — or focus it and press Enter / Space — to open it in a new tab.
• When Soma returns a matching line, Markdown files open directly at that location.

Mode and result limit are saved as preferences.

How it works

The plugin starts a dedicated Soma server for the vault when you initialize Soma, or on the first search in an already-initialized vault:

soma server --port=<available-port> --auto-sync --no-color

That instance:

• Listens only on 127.0.0.1 on a dynamically selected port
• Synchronizes immediately, then hourly
• Stops when the plugin is unloaded

All search requests go directly to this local instance over loopback HTTP.

Privacy and disclosures

• Plugin network use: the plugin communicates only with the local Soma instance over loopback HTTP at 127.0.0.1. It does not upload vault content or search queries.
• Plugin data and access: the plugin runs the user-installed Soma executable and saves its configured path in Obsidian plugin data. It includes no telemetry, accounts, payments, or advertising.
• Plugin storage: initialization creates .soma/local.yml and .soma/local.sqlite inside the vault. These hold Soma configuration and a plaintext search index, and are not removed when the plugin is disabled or uninstalled.
• Soma itself: the open-source Soma engine may download local models and helper programs from GitHub and Hugging Face, keep cache and log data outside the vault, and follow linked files outside the vault.

FAQ

Troubleshooting

Development

npm install
npm run build
npm run deploy -- "/path/to/vault"

After deployment, enable Soma Search under Obsidian's community plugins. Restart Obsidian after changing manifest.json; for source-only changes, rebuild and reload the plugin.

Release

npm version patch
git push origin main --follow-tags

npm version patch bumps package.json, syncs manifest.json and versions.json, and commits all three. Pushing with --follow-tags pushes that commit together with the new tag. Use minor or major instead of patch when appropriate.

The working tree must be clean, and the release flow requires no manual version edits — the version in manifest.json is what the workflow checks against the tag name.

The release workflow builds the plugin, attaches main.js, manifest.json, and styles.css, and creates a draft GitHub release. Review it, add release notes, then publish it manually.

Related projects

• Soma — the local-first search engine powering this plugin (semantic, lexical, and hybrid search with OCR, vision, and speech extraction)

License

See LICENSE.

_{Keywords: Obsidian plugin · Obsidian semantic search · Obsidian local search · Obsidian offline search · Obsidian AI search · vector search · hybrid search · full-text search · search PDF in Obsidian · OCR Obsidian · image search · audio transcription search · embeddings · RAG · local-first · privacy-first · personal knowledge management (PKM) · note-taking}