CLI reference

Install the backend from source and use every supported memsearch command, argument, filter, and example.

The Python package installs a memsearch console entry point. Run it through uv from the repository’s backend directory.

Source prerequisites

macOS for Photos and people features
Python 3.12 or newer
uv
A Gemini API key

git clone https://github.com/samuelmeseret/memsearch.git
cd memsearch/backend
uv sync

Set the key with the actual prefixed environment name:

export MEMSEARCH_GEMINI_API_KEY='your-key'

You can instead put MEMSEARCH_GEMINI_API_KEY=your-key in backend/.env. Do not commit that file.

Command summary

Command	Purpose
`index FOLDER [--limit N]`	Index supported files below one folder
`index-photos [--limit N] [--favorites]`	Index image assets through PhotoKit
`update-people`	Backfill Photos person names without re-embedding
`search QUERY [-n N] [-m TYPE]`	Search the local vector index
`status`	Print index totals and last-indexed time
`clear`	Delete all embeddings and cached thumbnails
`serve`	Start the FastAPI server

`index`

memsearch index FOLDER [--limit N]

Argument	Required	Meaning
`FOLDER`	Yes	Folder to resolve and scan recursively
`--limit N`	No	Maximum eligible files selected for this run

uv run memsearch index ~/Documents
uv run memsearch index ~/Projects --limit 250

The command exits with an error if the path is not a directory or the Gemini key is empty. The completion summary reports indexed, error, and skipped counts.

`index-photos`

memsearch index-photos [--limit N] [--favorites]

Option	Meaning
`--limit N`	Limit the PhotoKit fetch to the newest N image assets
`--favorites`	Index only favorite assets within the fetched set

uv run memsearch index-photos
uv run memsearch index-photos --limit 100
uv run memsearch index-photos --favorites
uv run memsearch index-photos --limit 100 --favorites

This command needs Photos permission. It runs synchronously so PhotoKit callbacks can use the main run loop.

`update-people`

uv run memsearch update-people

The command reads the configured Photos.sqlite database, finds indexed photos:// image entries, and updates their person_names metadata. It does not call Gemini or rebuild embeddings.

It exits with an error when the Photos database cannot be read. If no images are indexed, it reports that state and returns.

`search`

memsearch search QUERY [-n N] [-m {image,pdf,text}]

Argument	Default	Meaning
`QUERY`	required	Natural-language query string
`-n N`, `--num N`	`10`	Maximum results
`-m TYPE`, `--modality TYPE`	none	`image`, `pdf`, or `text`

uv run memsearch search "notes about machine learning"
uv run memsearch search "family vacation" -m image
uv run memsearch search "quarterly roadmap" --modality pdf --num 5
uv run memsearch search "build pipeline" -m text -n 20

The direct CLI search does not parse @person syntax. Person parsing is implemented in the FastAPI /search route used by the desktop app and Raycast. For people queries from a terminal, call the HTTP API:

curl -X POST http://127.0.0.1:7242/search \
  -H 'Content-Type: application/json' \
  -d '{"query":"@Mira beach sunset","n_results":10}'

`status`

uv run memsearch status

Prints total indexed files, modality counts, and the last-indexed timestamp. This command reads ChromaDB directly; it does not report the richer live pipeline fields exposed by the server’s /status endpoint.

`clear`

uv run memsearch clear

Deletes the entire ChromaDB collection and cached .jpg thumbnails. It prints the number of cleared embeddings and thumbnails. It does not ask for confirmation.

Destructive command

clear cannot be undone. Watched-folder configuration remains, but search stays empty until sources are indexed again.

`serve`

uv run memsearch serve

Starts Uvicorn with the configured host and port, by default:

127.0.0.1:7242

Keep this process running for the Raycast extension or direct HTTP clients. Avoid launching the Electron app at the same time because it manages the same default port.

Help and exit behavior

Run without a command to print argparse help; the process exits with status 1. Use command-level help for generated argument details:

uv run memsearch --help
uv run memsearch index --help
uv run memsearch search --help

Configuration for all commands is documented under Configuration.

On this page