Memsearch manual
Search files and iCloud Photos on your Mac by meaning, using a local index and Google Gemini embeddings.
Memsearch is an open-source macOS app for semantic search. It indexes supported files and iCloud Photos, stores their vectors in a local ChromaDB collection, and lets you search with the details you remember instead of an exact filename.
Latest behavior only
This manual describes the current main branch and is maintained by hand. It has no version selector and does not fetch content from the application repository at build time.
Choose your path
Install the desktop app
Download the current macOS release and complete onboarding.
Learn search syntax
Use natural language, type filters, and @person filters.
Manage the index
Choose folders, track progress, enable watching, or clear data.
Use Raycast or the CLI
Search outside the Electron desktop window.
Requirements
| Use case | Required |
|---|---|
| Desktop app | macOS, a Gemini API key, and network access for Gemini calls |
| iCloud Photos | Photos permission; network access when an asset must be downloaded from iCloud |
| Backend or CLI from source | Python 3.12 or newer and uv |
| Electron app from source | Node.js and npm, in addition to the backend requirements |
| Raycast extension | Raycast, Node.js/npm for source installation, and a running Memsearch backend |
Get a Gemini key from Google AI Studio. The current packaged app can locate or install uv while preparing its backend on first launch.
Key concepts
Watched folders
Folders saved in Memsearch configuration and used by Reindex All or automatic file watching.
Embedding
A numeric representation created by Gemini for a file, image, PDF, photo, or search query.
Local index
A ChromaDB collection on your Mac containing vectors and result metadata.
Modality
The result type: image, PDF, or text.
What runs where
| Component | Role | Default connection |
|---|---|---|
| Electron desktop app | Onboarding, search UI, settings, backend lifecycle | http://127.0.0.1:7242 |
| FastAPI backend | Indexing, Photos access, embedding calls, vector search | Listens on 127.0.0.1:7242 |
| ChromaDB | Persistent vector index and result metadata | Local filesystem |
| Google Gemini | Creates document/image and query embeddings | Google API over the network |
| Raycast extension | Search and index-status commands | http://localhost:7242 by default |
memsearch CLI | Direct indexing, search, status, clear, and server commands | Runs backend modules locally |
The API has no authentication. Keep it bound to the loopback host unless you understand the exposure described in the API security note.
The basic workflow
- Add one or more folders, and optionally allow Photos access.
- Start indexing. Memsearch extracts or prepares content and asks Gemini for embeddings.
- Memsearch writes vectors, file metadata, and thumbnail references to local storage.
- Enter a natural-language query. The query is embedded and compared with the local vector index.
- Open a result in its native app, Photos, or Finder.
Local index does not mean offline indexing
ChromaDB and thumbnails remain on your Mac, but content used to create embeddings is sent to Google Gemini. Searches also send the query text to Gemini.
Manual map
| Page | What it covers |
|---|---|
| Quick start | Release installation, quarantine workaround, onboarding, and first search |
| Search | Query syntax, filters, scores, and result actions |
| Indexing | Folders, progress, cancellation, formats, exclusions, and clearing |
| Photos and people | PhotoKit permissions, iCloud assets, face-name data, and Photos actions |
| Raycast | Source installation, commands, filters, actions, and connection checks |
| CLI | Every current command, argument, and example |
| Configuration | Environment variables, persisted settings, paths, and precedence |
| API | Curated endpoint reference and errors |
| Privacy and architecture | Data flow, local storage, Gemini payloads, logs, and key storage |
| Troubleshooting | Startup, permissions, API-key, indexing, port, log, and reset fixes |
The project source and releases are available on GitHub and the Releases page.