Raycast extension
Install the current extension from source, configure its backend URL, search, inspect status, and troubleshoot connections.
The repository contains a Raycast extension with two commands: Memory Search and Index Status. It is not currently documented as a Raycast Store installation; run it from source.
Prerequisites
- Raycast installed on the Mac
- Node.js and npm
- A cloned copy of samuelmeseret/memsearch
- A running FastAPI backend with indexed content
Start the backend from source when the desktop app is not managing it:
cd memsearch/backend
uv sync
uv run memsearch serveInstall from source
In another terminal:
cd memsearch/raycast-extension
npm install
npm run devray develop opens the extension in Raycast’s development workflow. Keep the backend available while using either command.
Backend URL
Open the extension preferences in Raycast and set Backend URL. The default is:
http://localhost:7242The Electron client uses http://127.0.0.1:7242; both addresses normally reach the same loopback server. Do not add a trailing endpoint such as /search.
Do not expose an unauthenticated backend casually
The Memsearch API has no authentication and accepts broad CORS requests. Point Raycast at a non-loopback address only when the network and host are deliberately secured.
Memory Search
Type a natural-language query. Requests are debounced by 300 ms and ask for up to 20 results.
Use the search-bar menu to select:
- All Types
- Images
- PDFs
- Text Files
The grid displays a cached thumbnail when available, the filename, and a rounded score percentage.
Result actions
| Result | Actions |
|---|---|
| Regular file | Open File, Show in Finder, Copy Path, Copy Summary when present |
| Photos asset | Open in Photos, Copy Path, Copy Summary when present |
Copy Path on a Photos result copies its internal photos:// identifier rather than a filesystem path.
Index Status
The command refreshes status every three seconds and shows:
- total indexed items;
- last-indexed time;
- active indexing state and current progress;
- counts grouped by modality.
Its action panel includes:
| Action | Shortcut or behavior |
|---|---|
| Refresh | ⌘R |
| Reindex All | Starts saved watched folders when idle |
| Stop Indexing | Sends /index/stop when a run is active |
| Clear Index | ⌘⇧Delete; immediately sends the destructive request |
Raycast clear has no in-extension confirmation
The current Raycast command calls DELETE /index directly. Clearing removes all embeddings and cached thumbnails and requires a complete re-index.
Connection troubleshooting
Confirm backend health
curl http://127.0.0.1:7242/statusA JSON response means the backend is reachable. If it fails, start the backend or open the desktop app after onboarding.
Check the configured URL
Use http://localhost:7242 or http://127.0.0.1:7242 for a local backend. Confirm the scheme, host, and port; remove a trailing slash if a proxy treats it unexpectedly.
Avoid two owners of port 7242
Do not run uv run memsearch serve while launching the desktop app. The current Electron lifecycle treats port 7242 as its own and can terminate an existing listener before starting its managed backend.
Read the actual failure
The Raycast client reports HTTP status text, so a search-side Gemini failure may appear only as Service Unavailable. Reproduce the request with curl or inspect the desktop backend log for the detailed FastAPI error.
Rebuild after source changes
Run npm install after lockfile or dependency changes, then restart npm run dev. Use the extension’s npm run lint script when modifying its source.