Soma

Private local document search

Private AI search for your local files.

Soma is a local knowledge-base search engine for Markdown, PDFs, images, audio, and video. Ask a natural-language question or use exact keywords, with indexing and retrieval on your own machine.

Install Soma Read the quick start

Soma does not require a hosted document index. The first sync may download managed models and runtimes; your indexed content stays in your local workspace.

Made for real folders

Find answers in the files you already have.

Keep your existing projects, notes, and recordings. Soma turns them into one searchable local knowledge base without asking you to migrate to a hosted service.

Developers and ops

Docs, code, and runbooks

Search API notes, deployment guides, incident response steps, and configuration details by meaning or by exact term.

Researchers and note-takers

Markdown, meetings, and journals

Point Soma at your notes vault or project folders, sync when files change, and retrieve the context behind an idea.

Scans and recordings

Search what text search misses

OCR, vision extraction, and transcription make screenshots, scanned pages, audio, and video searchable alongside text.

A simple local workflow

Add a folder. Sync it. Search naturally.

  1. 01 / ADD

    Choose a project

    Point Soma at a folder and optionally control its file scope.

    soma project add ~/notes --name notes
  2. 02 / SYNC

    Make it searchable

    Scan, extract, and embed the files. The first run may take longer while models download.

    soma sync
  3. 03 / SEARCH

    Ask or match exactly

    Use a natural-language question for semantic search or keywords and phrases for precision.

    soma search "how does auth work"

Search that meets you where you are

One local index, several ways to find the right file.

Hybrid keyword and semantic search

One query can combine lexical matching, vector retrieval, query expansion, and reranking for useful results when you remember the idea but not the exact phrase.

Local processing by default

Indexing, OCR, embeddings, and reranking run through a managed local runtime. There is no hosted index to upload your documents to.

Text, images, audio, and video

Search plain text and rich media together, including content recovered from scans, screenshots, recordings, and video files.

Native on Windows, macOS, and Linux

Use native executables for Windows x64, Linux x64, and macOS ARM64. The CLI starts quickly and does not require a separate app stack.

Multilingual and CJK-aware

Unicode-aware tokenization keeps short Chinese, Japanese, and other CJK queries retrievable alongside Latin text and code identifiers.

CLI, browser, and JSON API

Stay in the terminal, run the built-in local web interface, or automate searches through the HTTP endpoint that mirrors the CLI.

Private by design

Your documents stay in your workspace.

Local-first does not have to be vague. Soma keeps the searchable index and processed content on your machine, while being explicit that the first setup can fetch the models and runtimes it needs.

  • Local index and workspace storage
  • No hosted document search service required
  • Offline import is available for prepared artifacts

Get started

Install the native binary for your platform.

Choose a package manager or download the current executable from GitHub Releases.

Windows x64

winget install AwesomeDog.soma

Install from Windows Package Manager, then run Soma from PowerShell or your terminal.

View Windows releases

macOS ARM64

brew tap AwesomeDog/tap && brew trust AwesomeDog/tap && brew install AwesomeDog/tap/soma

Install with Homebrew on Apple Silicon, then add the folders you want to search.

View macOS releases

Linux x64

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

Download the single executable, make it runnable, and start indexing local projects.

View Linux releases

System requirements: 8 GB RAM for regular use; 24 GB recommended for OCR, vision, and transcription. GPU is optional.

Before you install

Questions about local search.

Does Soma upload my files?

Soma is designed around a local index and local processing. Your documents are not sent to a hosted search index; the first setup may download managed models and runtimes.

What can I search?

Search text files and rich media together, including Markdown, PDFs, screenshots, scanned pages, audio, and video when the relevant extraction step is available.

Can I search by exact words?

Yes. Hybrid search handles natural-language questions, while lexical search supports keywords, phrases, and exclusions.

Is Soma only a command-line tool?

No. The same search engine can run through the CLI, a local browser interface, or a JSON HTTP endpoint for automation.