LiveRecall

LiveRecall secures captured screenshots using a local encryption mechanism:

1. Encryption: Screenshots are encrypted using a password provided by the user.
2. Password Management: The password is not stored by the application; you must remember it to access your data.
3. Decryption: Images are only decrypted temporarily during retrieval for viewing.
4. Secure Deletion: Decrypted images are promptly deleted after use to prevent unauthorized access.

LiveRecall uses a multi-modal approach to find screenshots. You can specify the following search modes:

• Auto (Hybrid): The default mode. It combines all search methods using Reciprocal Rank Fusion (RRF) for the best results.
• Image: Performs visual similarity search (e.g., searching for "cat on a keyboard").
• Text Fuzzy: Performs fast text matching with typo tolerance using trigram search.
• Text Semantic: Uses embeddings to find screenshots containing text with similar meaning to your query.

Use the provided build scripts to create .dmg (macOS) or .exe (Windows) installers. The output is placed in the dist/ directory.

# One-command build (installs deps, builds web, creates package)
uv run python scripts/build_release.py

# Quick build (skip web rebuild if exists)
uv run python scripts/build_release.py --quick

To run LiveRecall from source, ensure you have Python 3.10+, Node.js 18+, and uv installed. Follow these steps:

1. Clone the repository and enter the directory.
2. Use uv sync to install Python dependencies and create a virtual environment (.venv).
3. Navigate to the web directory and run npm install to set up the web UI.

# Clone the repository
git clone https://github.com/VedankPurohit/LiveRecall.git
cd LiveRecall

# Install Python dependencies (creates .venv automatically)
uv sync

# Install web UI dependencies
cd web && npm install && cd ..

Depending on your needs, you can run the application in three different modes:

• System Tray App (Recommended): Launches the full menu bar application.
• API Server Only: Runs only the backend service.
• Web UI Development: Runs the API in one terminal and the Next.js web interface in another.

# Option 1: System Tray App
uv run python main.py

# Option 2: API Server Only
uv run python main.py --api-only

# Option 3: Web UI Development
# Terminal 1: Start API
uv run python main.py --api-only

# Terminal 2: Start web UI
cd web && npm run dev

If running in development mode, the web UI is accessible at http://localhost:3000.

To use the pre-built application on macOS:

1. Download the latest DMG from the Releases page.
2. Open the DMG and drag LiveRecall to your Applications folder.
3. Launch the app from your Applications.
4. Important: You must grant Screen Recording permission in System Settings > Privacy & Security > Screen Recording.

Note: On the first launch, the app will automatically download approximately 530MB of AI models (Image embedding ~400MB and Text embedding ~130MB).

Settings can be adjusted via the Web UI or through the API. Available configuration keys include:

• Capture Mode: normal, games, fast, coding, video, presentation
• Capture Interval: 1-10 seconds
• Quality: 50-100%
• Safe Mode: Filter sensitive content from search
• Auto-compress: Compress old screenshots
• OCR Enabled: Enable/disable text extraction (enabled by default)
• Search Mode: auto (hybrid), image, text_fuzzy, text_semantic

Upon startup, TrayApp performs an enhanced setup check by querying the /setup/enhanced-status endpoint. It automatically opens the web UI setup page ({WEB_UI_URL}/setup) if any of the following conditions are met:

1. Version Change: The needs_setup flag is true, indicating a version change was detected (e.g., last_seen_version != current_version).
2. Missing CLIP Model: The clip_status is reported as not_downloaded, which is required for search functionality.
3. OCR Migration: The migration_status indicates needs_migration is true (e.g., there are screenshots without OCR that need processing).

You can run the FastAPI application directly using uvicorn. By default, it runs on 127.0.0.1:8742 with reload enabled and warning-level logging to reduce noise.

uvicorn api.main:app --reload --port 8742

The backend provides a FastAPI-based REST API. The full interactive documentation is available at http://localhost:8742/docs when the server is running.