Search

Return has two layers of search that work together: keyword search finds exact words, and semantic search finds content by meaning — even when the words don’t match.

Keyword search is always available and works instantly. Type in the Explorer search box and Return searches through your document text.

It handles partial matches and basic word variations, so searching for “contract” will also find “contracts” and “contracting”. Results are ranked by relevance using BM25 scoring — the same algorithm used by search engines.

Keyword search works offline, requires no setup, and has zero performance cost.

Semantic search understands meaning. Searching for “payment deadlines” can find a paragraph about “invoices are due within 30 days” — even though the words don’t overlap. It works across all your documents at once.

This is powered by an AI embedding model (nomic-embed-text) running locally through Ollama. Each document is split into small fragments and converted into numerical vectors that capture meaning. When you search, your query is converted the same way and matched against all fragments.

  1. Install Ollama from ollama.com if you haven’t already
  2. Pull the embedding model: ollama pull nomic-embed-text
  3. In Settings → Semantic Search, enable Semantic Indexing

Return indexes your documents in the background. For a typical workspace (100–500 documents), this takes under a minute. New and edited documents are re-indexed automatically as you work.

How results are ranked

When you type a query, Return runs both keyword and semantic search simultaneously and merges the results using Reciprocal Rank Fusion. Short queries (one or two words) lean more on keyword matching, while longer, question-style queries lean more on semantic matching. You don’t need to think about this — it happens automatically.

Search results show the matching fragment, which document it came from, and its section path (e.g., “Contract → §5 Payment Terms”). Click a result to open the document.

What gets indexed

Only your markdown documents (.md files) are indexed for search. Configuration files, templates, and other non-document files in the .config folder are excluded.

The search index is stored locally in Return’s database alongside your files. If you delete the database, the index rebuilds automatically from your files on next launch. Your files are always the source of truth.

How indexing changes your files

When you enable semantic search for a folder, Return adds a small metadata block to the top of each markdown file. This block holds a stable identifier and a few timestamps — it’s what lets chat history, annotations, and renames stay connected to the right document even if you move or rename files later.

The metadata block looks like this:

---
id: doc_a1b2c3d4e5f6
created: 2026-05-13T10:00:00Z
modified: 2026-05-13T10:00:00Z
---

Files in folders without semantic search remain untouched. Return adds metadata to a file only when:

Until then, opening a file just to read it never modifies the file on disk. Behind the scenes Return assigns the file a temporary identifier in memory so chat, annotations, and other tools all “see” the same document — but nothing is written to your file until you actually do one of the actions above. If you close the file without acting, the temporary identifier is discarded.

If you turn semantic search off later, the metadata stays in place — re-enabling later then skips files that already have it and only adds it to new ones.

Privacy

All search processing happens on your machine:

Enabling semantic search does not send your documents to any server. The embedding model downloads once (274 MB) and runs entirely on your hardware.

Tips for better results