🧠 MemoryMind AI

An AI-powered companion dashboard for Immich, supercharged by Google Gemini 2.5 Flash.

MemoryMind AI is a modern Next.js companion application that integrates seamlessly with your self-hosted Immich photo and video library. By leveraging Google Gemini 2.5 Flash's multimodal capabilities, it transforms your library management with semantic search, automated screenshot sorting, and intelligent album curation.

---

🚀 Key Features

• 🔍 Smart Semantic Search

  Go beyond simple keywords. Enter queries like "dog running in the park" or "sunsets at the beach". MemoryMind AI parses search intent using Gemini to translate natural language queries into a combination of Immich's vector search (CLIP) and exact metadata filters (location, date range, media types, favorites).

• 📂 Screenshot Organizer

  Clean up your camera roll clutter. Scan your photo library for screenshots, extract their text content via Immich OCR, and run them through Gemini to automatically categorize them into dedicated albums:

  *🏦 Banking: Receipts, UPI slips, transaction confirmations, bank statements. *🛒 Shopping: Amazon orders, cart checkouts, invoices, delivery tracking. *🎓 Certificates: Degrees, diplomas, ID cards (Aadhaar/PAN), driver licenses, credentials. *💼 Job Applications: Portals, resumes, confirmation emails. *📞 Interview Calls: Zoom/Meet links, HR chats, calendar invites, assessment requests. *📚 Study Material: Lecture slides, code snippets, diagrams, textbooks.

• 🪄 Natural Language Album Creator

  Build thematic albums effortlessly. Simply instruct the AI in plain English (e.g., "Create an album for my trip to Goa last summer"), and Gemini will scan your assets, match them by location, filenames, or timestamps, and group them into a brand-new Immich album automatically.

• 📊 Stunning Management Dashboard
  A sleek, responsive dark-mode dashboard built with TailwindCSS v4 and shadcn/ui. View real-time library statistics (total assets, albums, and screenshot count), upload new photos instantly, and execute quick tasks.

---

🏗️ Project Architecture

memorymind-ai/
├── docker/                  # Local Immich deployment configurations
│   └── immich/
│       ├── .env             # Docker compose environment variables
│       └── docker-compose.yml # Immich standalone docker setup
├── public/                  # Static assets and icons
├── src/
│   ├── actions/             # Next.js Server Actions (bridge to service layer)
│   │   ├── album.action.ts
│   │   ├── organizer.action.ts
│   │   ├── search.action.ts
│   │   └── settings.action.ts
│   ├── app/                 # Next.js App Router (pages and API proxy routes)
│   │   ├── (dashboard)/     # Main dashboard interface layout & routes
│   │   │   ├── albums/      # Smart Album Creator view
│   │   │   ├── organizer/   # Screenshot Organizer dashboard
│   │   │   ├── photos/      # Library photo stream
│   │   │   ├── search/      # Smart AI Search interface
│   │   │   ├── settings/    # API connection console
│   │   │   └── page.tsx     # Welcome homepage
│   │   ├── api/             # Backend API proxy endpoints (prevents CORS issues)
│   │   │   ├── ai-search/   # API route for query parsing & semantic search
│   │   │   ├── assets/      # Stream binary data & retrieve library statistics
│   │   │   ├── create-album/# API route for smart album creation
│   │   │   └── organize/    # API route for screenshot categorization
│   │   ├── globals.css      # Core Tailwind styling & tokens
│   │   └── layout.tsx       # Core HTML root shell
│   ├── components/          # Reusable React components
│   │   ├── dashboard/       # Stats cards, direct uploaders & quick actions
│   │   ├── organizer/       # Screenshot scanning & classification grids
│   │   ├── search/          # Search bar, intent visualizers & filtering controls
│   │   └── shared/          # Navigation panels (Sidebar, Navbar, Header)
│   ├── config/              # App configuration, prompts, and static rules
│   │   ├── categories.ts    # Predefined screenshot matching rules & keywords
│   │   └── prompts.ts       # Structured system prompts for Gemini LLM
│   ├── services/            # Core business logic layer
│   │   ├── gemini/          # Google Gemini GenAI service clients and prompts
│   │   ├── immich/          # Immich REST API client integrations
│   │   └── organizer/       # Screenshot grouping & album saving pipelines
│   └── types/               # Shared TypeScript type definitions

---

🛠️ Tech Stack

• Framework: Next.js 16 (App Router & React Server Actions)
• Core UI Library: React 19, @base-ui/react, and Lucide React
• Styling: TailwindCSS v4 & shadcn/ui
• AI SDK: @google/genai (using gemini-2.5-flash)
• State Management & Caching: @tanstack/react-query
• Data Validation: Zod

---

⚙️ Configuration & Environment Setup

1. Environment Variables

Create a .env.local file in the root of the project:

# Immich Server Connection Settings
IMMICH_API_URL="http://localhost:2283"
IMMICH_API_KEY="your-immich-api-key"

# Google Gemini API Key
GEMINI_API_KEY="your-gemini-api-key"

Note

To generate an Immich API Key, log into your Immich Web UI, navigate to Account Settings -> API Keys, and generate a new key. To generate a Gemini API Key, visit the Google AI Studio.

2. Self-Hosted Immich (Docker Compose)

If you do not have an active Immich instance running, you can spin one up locally using the provided configurations:

1. Navigate to the docker setup directory:

   cd docker/immich

2. Review or configure the variables in docker/immich/.env (default port is 2283).

3. Launch the containers:

   docker compose up -d

---

🚀 Getting Started

Once the environment variables and Immich servers are ready, start the companion dashboard:

1. Install dependencies:

   pnpm install
   # or npm install

2. Run the development server:

   pnpm dev
   # or npm run dev

3. Open http://localhost:3000 in your browser to explore the dashboard.

---

💡 How It Works under the Hood

1. Smart Search Pipeline

graph TD
    UserQuery[User types query] --> GeminiParser[Gemini parses query & intent]
    GeminiParser --> Intent{Is it semantic or metadata?}
    Intent -- Semantic/Smart --> ImmichSmart[Call Immich /search/smart CLIP vector endpoint]
    Intent -- Metadata/Filter --> ImmichMetadata[Call Immich /search/metadata with structured Zod filters]
    ImmichSmart --> MergeResults[Display matching photos & videos]
    ImmichMetadata --> MergeResults

Loading

2. Screenshot Organization Pipeline

1. Scan: The application calls scanScreenshotCandidates to locate images with PNG format (lacking camera EXIF tags) or with filenames containing "screenshot".

2. Extract: Immich's native OCR text extraction endpoint (/assets/:id/ocr) retrieves all readable text in the image.

3. Classify: Gemini receives the metadata (filename, timestamp) and the first 1000 characters of OCR text to classify the item into one of the designated categories (banking, shopping, certificates, etc.) using a structured JSON output schema.

4. Organize: The application groups asset IDs, queries existing Immich albums, creates any missing categories, and puts the photos into their matching albums.

---

Created with ❤️ by Pratham Darji