Meme-ID: Automated Meme Identification Pipeline

An automated pipeline to identify whether an input image is a meme, based on the methodology from "What Makes a Meme a Meme? Identifying Memes for Memetics-Aware Dataset Creation".

Overview

This tool uses memetics-aware detection to determine if an image is a genuine meme. It supports two search modes:

• Local mode (default): Uses CLIP embeddings + FAISS index to search your local meme datasets
• Online mode: Uses Google Cloud Vision API for reverse image search across the web (matching the paper's original methodology)

Both modes use Qwen-VL vision model to analyze image format and extract elements, then apply the paper's 8-step protocol to classify meme types.

Meme Types Detected

Type	Description
Template Meme	Reused visual backgrounds with different text
Character Macro	Character-centered templates with text overlay
Memetic Image	Image with appended whitespace caption
Transferred Symbols	Superimposed visual elements (e.g., crying emoji)
Memetic Trend	Similar text across visually dissimilar images

Installation

pip install -e .

Usage

CLI

# Identify using local FAISS index (default)
meme-id identify path/to/image.jpg

# Identify using Google APIs (online search)
meme-id identify path/to/image.jpg --search-mode online

# Build local index from meme datasets (first-time setup for local mode)
meme-id build-index --dataset-dir /path/to/datasets

# Batch process images (supports both modes)
meme-id batch path/to/images/ --output results.json --search-mode online

# Save outputs (input image + similar memes) to meme_outputs/
meme-id identify path/to/image.jpg --save-outputs

# Show configuration and status
meme-id info

Python API

from meme_id import MemeIdentifier

# Local mode (default)
identifier = MemeIdentifier()
result = identifier.identify("path/to/image.jpg")

# Online mode (Google APIs)
identifier = MemeIdentifier(search_mode="online")
result = identifier.identify("path/to/image.jpg")

print(f"Is Meme: {result.is_meme}")
print(f"Meme Type: {result.meme_type}")
print(f"Confidence: {result.confidence}")

Configuration

Create a .env file or set environment variables:

# Core settings
MEME_DATASETS_DIR=...
CLIP_MODEL=openai/clip-vit-large-patch14
VISION_MODEL=Qwen/Qwen2.5-VL-3B-Instruct
INDEX_PATH=./meme_index.faiss

# Search mode: "local" or "online"
SEARCH_MODE=local

# Google API settings (required for online mode)
GOOGLE_API_KEY=your-api-key-here        # Required: enables Vision API (IS) and Custom Search (TS)
GOOGLE_CSE_ID=your-cse-id-here          # Optional: enables text-based image search (Step 7)

Setting up Google APIs (Online Mode)

1. Google Cloud Vision API (for reverse image search):

   • Go to Google Cloud Console
   • Enable the Cloud Vision API
   • Create an API key and set GOOGLE_API_KEY

2. Google Custom Search API (optional, for text search):

   • Go to Programmable Search Engine
   • Create a search engine with "Search the entire web" enabled
   • Set GOOGLE_CSE_ID to the search engine ID
   • Enable the Custom Search JSON API in Google Cloud Console

Citation

If you use this software, please cite both this tool and the original paper:

Software

@software{gakoushik2026,
  title={Meme-ID: Automated Meme Identification Pipeline},
  author={Girish A. Koushik},
  year={2026},
  url={https://github.com/gak97/meme-id}
}

Paper

@article{Hazman_McKeever_Griffith_2025, 
    title={What Makes a Meme a Meme? Identifying Memes for Memetics-Aware Dataset Creation}, 
    volume={19}, 
    url={https://ojs.aaai.org/index.php/ICWSM/article/view/35843}, 
    DOI={10.1609/icwsm.v19i1.35843},
    number={1}, 
    journal={Proceedings of the International AAAI Conference on Web and Social Media}, 
    author={Hazman, Muzhaffar and McKeever, Susan and Griffith, Josephine}, 
    year={2025}, 
    month={Jun.}, 
    pages={745-759} 
}