Configuration

Review every current MEMSEARCH setting, persisted UI settings, filesystem paths, and precedence rules.

The backend uses Pydantic settings with the MEMSEARCH_ prefix. Environment names below are the actual names read by the current source.

Environment settings

Variable	Default	Purpose
`MEMSEARCH_GEMINI_API_KEY`	empty	Google Gemini API key
`MEMSEARCH_CHROMA_DIR`	`~/Library/Application Support/MacMemorySearch/chroma`	ChromaDB persistence directory
`MEMSEARCH_THUMBNAIL_DIR`	`~/Library/Application Support/MacMemorySearch/thumbnails`	Cached `.jpg` thumbnails
`MEMSEARCH_PORT`	`7242`	FastAPI/Uvicorn port
`MEMSEARCH_HOST`	`127.0.0.1`	FastAPI/Uvicorn bind host
`MEMSEARCH_EMBEDDING_MODEL`	`gemini-embedding-2-preview`	Gemini embedding model
`MEMSEARCH_EMBEDDING_DIMENSIONS`	`768`	Requested vector dimensions
`MEMSEARCH_COLLECTION_NAME`	`mac_memory`	ChromaDB collection name
`MEMSEARCH_MAX_CONCURRENT_EMBEDS`	`5`	Async embedding semaphore size for the regular pipeline
`MEMSEARCH_MAX_FILE_SIZE_MB`	`50`	Maximum source-file size
`MEMSEARCH_AUTO_INDEX_ENABLED`	`false`	Start the filesystem watcher with the server
`MEMSEARCH_INDEX_PHOTOS_ENABLED`	`false`	Persisted Photos preference; does not itself start a run on every server start
`MEMSEARCH_PHOTOS_LIBRARY_PATH`	`~/Pictures/Photos Library.photoslibrary`	Photos library used for Photos.sqlite people data
`MEMSEARCH_WATCHED_FOLDERS`	Documents, Desktop, Downloads, Pictures	Folders for reindexing and automatic watching
`MEMSEARCH_EXCLUDE_PATTERNS`	hidden paths, `__pycache__`, `node_modules`, `.git`, `.DS_Store`, `Thumbs.db`	Path components excluded from file indexing

Model changes can require a fresh index

Query and document vectors must use compatible models and dimensions. If you change the embedding model or dimensions, clear and rebuild the index rather than mixing vectors created under different settings.

`.env` and shell examples

The CLI and server call load_dotenv() before importing backend settings, so a backend/.env file can provide the same names.

MEMSEARCH_GEMINI_API_KEY=your-key
MEMSEARCH_PORT=7242
MEMSEARCH_HOST=127.0.0.1
MEMSEARCH_MAX_FILE_SIZE_MB=50
MEMSEARCH_AUTO_INDEX_ENABLED=false

Shell variables work as well:

MEMSEARCH_GEMINI_API_KEY='your-key' \
MEMSEARCH_MAX_FILE_SIZE_MB=25 \
uv run memsearch serve

For list values, use the JSON representation accepted by Pydantic settings:

export MEMSEARCH_WATCHED_FOLDERS='["/Users/me/Documents","/Users/me/Projects"]'
export MEMSEARCH_EXCLUDE_PATTERNS='[".*","node_modules",".git","dist"]'

UI-managed persistent settings

The backend persists only these four fields in its own JSON configuration:

Field	Desktop control
`watched_folders`	Folder selection, add, and remove controls
`max_file_size_mb`	API-managed; no current desktop control
`auto_index_enabled`	Automatic-indexing toggle
`index_photos_enabled`	Onboarding Photos choice

They are written atomically to:

~/Library/Application Support/MacMemorySearch/config.json

PUT /config accepts the same four fields. The API cannot update host, port, model, dimensions, storage directories, collection name, concurrency, Photos library path, or exclusions.

API-key persistence in the desktop app

The desktop key is not stored in the backend JSON file. Electron stores it under the apiKey key in its electron-store configuration, normally:

~/Library/Application Support/MemSearch/config.json

When Electron starts the backend, it passes the value as MEMSEARCH_GEMINI_API_KEY in the child environment. Saving a new key restarts the backend.

Current key storage is plaintext

Current Electron code writes the API key as plaintext. It can decrypt a legacy safeStorage value once, but then rewrites that value as plaintext. Protect your macOS account and do not share the Electron Store file.

Precedence

For all settings, explicit environment values—including values loaded from backend/.env—are read when Settings is created.

For the four persistent UI fields, precedence is:

MEMSEARCH_* environment / .env
  > MacMemorySearch/config.json
  > source defaults

The disk value is applied only when the corresponding MEMSEARCH_* name is absent from os.environ.

For non-persistent fields, precedence is simply environment/.env over source defaults. When Electron supplies the stored key to the child process, that environment value is the backend key.

Data locations

Data	Default path
Backend persisted settings	`~/Library/Application Support/MacMemorySearch/config.json`
ChromaDB index	`~/Library/Application Support/MacMemorySearch/chroma`
Thumbnail cache	`~/Library/Application Support/MacMemorySearch/thumbnails`
Electron settings and API key	`~/Library/Application Support/MemSearch/config.json`
Electron-managed Python environment	`~/Library/Application Support/MemSearch/venv`
Backend log from desktop app	`~/Library/Application Support/MemSearch/logs/backend.log`
Default Photos library	`~/Pictures/Photos Library.photoslibrary`

The different MacMemorySearch and MemSearch directory names are intentional reflections of the current source, not aliases.

Inspect and update runtime configuration

curl http://127.0.0.1:7242/config

curl -X PUT http://127.0.0.1:7242/config \
  -H 'Content-Type: application/json' \
  -d '{"auto_index_enabled":true,"max_file_size_mb":25}'

The GET response intentionally exposes only watched folders, maximum file size, automatic/Photos flags, model, dimensions, and port. It does not return the Gemini key.