Quick start

Install the macOS app, complete the current onboarding flow, index your first sources, and run a first search.

Download and install

Open Memsearch Releases.
Download the latest .dmg for your Mac.
Open the disk image and drag MemSearch into Applications.
Launch MemSearch from Applications.

You need macOS, an internet connection, and a Google Gemini API key. Photos integration is optional.

Current builds are not notarized

macOS may report that MemSearch “is damaged and can’t be opened.” This message is caused by the quarantine attribute on the current unsigned/notarized distribution; use the command below only for the MemSearch app you downloaded from the project’s Releases page.

Clear the quarantine attribute

Close the warning, open Terminal, and run:

xattr -cr /Applications/MemSearch.app

Open MemSearch again from Applications. If you installed it elsewhere, replace the path with the actual .app location.

Complete onboarding

The current onboarding flow has seven steps.

1. Welcome

Select Get Started. Memsearch explains that it searches images, PDFs, text, code, and other supported text formats by meaning.

2. Add a Gemini key

Paste a key from Google AI Studio and continue. The field must not be empty, but the key is not validated until the backend makes a Gemini request.

3. Let the backend prepare

Memsearch saves the key and starts its FastAPI backend. On a first run it:

looks for a usable uv binary;
attempts to install uv when it is missing;
creates a writable Python environment under the app’s user-data directory;
installs the backend dependencies; and
waits for http://127.0.0.1:7242/status to respond.

First-run setup can take up to two minutes before the app reports a timeout.

4. Choose folders

The folder list begins with the backend defaults:

~/Documents
~/Desktop
~/Downloads
~/Pictures

Remove folders you do not want indexed or select Add Folder to choose others. You may continue with no folders and add one later from the Status tab.

Folder access is recursive

Manual indexing walks supported files below each selected folder, excluding hidden paths and other configured exclusions. Review Indexing before selecting a very large home or project directory.

5. Choose automatic indexing

Enable Automatic Indexing if Memsearch should watch the selected folders for creates, edits, moves, and deletions. It is off by default and can be changed later.

6. Choose iCloud Photos

Enable Index iCloud Photos if you want photo-content and people search. macOS will request Photos access. You can leave this off and start Photos indexing later from Status.

7. Start or skip

Review the folder, automatic-indexing, and Photos choices.

Start Indexing saves the choices and starts selected sources.
Skip for Now saves the choices without starting an index run.

Only one indexing job should run at a time. If a Photos run does not begin while files are still indexing, wait for the file run to finish and select Index Photos from Status.

Watch initial progress

Open the Status tab. It reports the total indexed count, counts by modality, last-indexed time, current source, progress, current file or photo phase, and errors from the active run.

File indexing first scans folders, then processes eligible files one by one. Photos indexing may spend time scanning the library, checking existing entries, downloading iCloud assets, and embedding.

Run your first search

After at least one item is indexed:

Open the Search tab.
Enter a remembered detail, such as whiteboard diagram from standup.
Optionally choose Images, PDFs, or Text Files.
Double-click a file result to open it. A Photos result opens in Photos.

Try a few query styles:

signed apartment lease
notes about the embedding pipeline
rainy street photo at night
@Mira beach sunset

Searches require the Gemini key because the backend embeds each query before comparing it with the local index.