Meme Search: self-hosted semantic retrieval for image folders
The open source Meme Search Engine and Finder. Free and built to self-host locally with Python, Ruby, and Docker.
At a glance
- What is it?
- Meme Search indexes a local image collection by describing each file with a vision model, embedding the description, and serving keyword and semantic search from a Docker Compose stack. It is built for one operator on one machine, and its documentation says so explicitly.
- Who is it for?
- Adopt Meme Search if you have a personal image folder, a machine that can run a vision model locally, and no requirement to expose the UI beyond 127.0.0.1. Do not adopt it as a multi-user service or as anything reachable from the public internet: the README states the web UI has no user authentication, that API bearer tokens cover only the versioned integration endpoints, and that direct public exposure is unsupported.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 5 days ago.
- What is it written in?
- Mainly Ruby, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem: filenames do not describe image content
A folder of saved memes is searchable only by whatever the file is called. `cat_typing.gif` is findable; the screenshot you saved as `IMG_4821.png` is not, and neither is the reaction image whose punchline is rendered inside the pixels. Meme Search attacks that gap by treating each image as a document. It runs a vision language model over the file to produce a text description, then indexes that description so the image can be retrieved by words that never appear in its filename. The README frames the audience directly: people who want their memes "easily retrievable for your meme warfare pleasures," with processing performed locally by default. That default matters. The description text is generated on your hardware, embeddings are computed on your hardware, and search runs on your hardware, so the image collection never leaves the machine unless you deliberately opt into a remote vision API.
Description first, embedding second: the indexing pipeline
The architecture implied by the README is a two-stage pipeline. Stage one is image-to-text: a vision language model reads the image and emits a description covering content and any text visible in the image. Stage two turns that description into a vector and stores it in a vector database, which is what the semantic-search topic tag refers to. Keyword search runs alongside semantic search, so a query can match both literal terms in a generated description and approximate meaning. The repository is a multi-service Compose stack rather than a single binary. Ruby is the primary language, with Python in the mix for the model side and Docker as the packaging layer. The practical consequence of the two-stage design is that description quality caps retrieval quality. If the model misreads an image, no amount of vector search recovers it, which is why the project ships manual description editing as a first-class feature rather than a fallback.
Six vision models, and the memory bill that comes with them
Model choice is the main resource dial. The README lists Florence-2-base as the default, described as roughly 250 million parameters, alongside Florence-2-large at about 700 million, SmolVLM-256 and SmolVLM-500 at 256 and 500 million, Moondream2 at 2 billion, and Moondream2-INT8, a quantized build intended for memory-constrained hardware. The README gives one concrete number: quantization reduces Moondream2 memory from about 5GB to about 1.5 to 2GB, described as minimal quality loss, and calls the INT8 variant ideal for CPU-only machines. That is the clearest signal in the material about who each model is for. A 2-billion-parameter model on a machine without a capable GPU is the wrong default; the INT8 path or one of the SmolVLM variants is the documented alternative. Note also that the first local description generation downloads the selected model, so the initial run is slower than subsequent ones. That download is a one-time cost per model, not per image, but it is a cost you pay before you see whether the descriptions are good enough for your collection.
Running it: three commands and a loopback binding
The quick start is short. Clone the repository, change into it, and bring up the stack:
git clone https://github.com/meme-search/meme-search.git cd meme-search docker compose up
Then open http://localhost:3000 and drag, drop, or paste images on the upload page. The web UI binds to 127.0.0.1 by default. The README states the reason plainly: the UI does not include user authentication. Custom bind address and app port are configurable, and there is a documented path for building the app locally with Docker rather than pulling images. For automation, the project ships a token-authenticated Search API v1 documented in docs/search-api.md, a dependency-free local CLI in integrations/cli/README.md, and an experimental unpacked Chromium popup under integrations/browser-extension/README.md. The API is read-only and officially supported on loopback only. Bearer tokens protect the versioned integration endpoints; they do not protect the web UI or the settings pages.
The security boundary is the honest part of this project
Most self-hosted projects bury the exposure caveat. This README leads with it. The web UI has no authentication, the API tokens do not cover the UI or settings, official support is loopback-only for API v1 and the bundled clients, and direct public exposure is unsupported. Proxy or VPN operation is described as advanced and unsupported, with authentication, TLS, and network controls left entirely to the operator. Read that as a design decision rather than an oversight: the project is scoped to a single trusted machine, and the maintainers decline to pretend otherwise. The failure mode follows directly. The moment you put this behind a reverse proxy on a public hostname, you have an unauthenticated interface that can read your image library and change its settings, and you are outside the support envelope. There is no documented multi-user mode, no role model, and no per-collection access control. If you need shared access, this is the wrong tool, and the README effectively says so.
Where the documentation thins out
The README is strong on setup and boundaries and thin on operations. It does not state which vector database backs the index, how large the index grows relative to the image count, or what happens to existing embeddings when you switch vision models. That last gap is the one worth probing before you commit to a large collection. If descriptions are regenerated under a new model, are the old vectors replaced or duplicated? The material does not say. Rescan is a visible feature, with screenshots for rescan, rescan status, and rescan options, so re-indexing exists as a workflow, but the README does not document its semantics for model changes. The same applies to backup and migration: nothing in the supplied material describes how to move an index between machines, which matters because the index is the expensive artifact. These are questions to answer from the repository's docs and issue tracker, not from the marketing page.
Against a hosted vision API and against plain folder search
Two alternatives frame the choice. The first is using a hosted vision API to caption images and a hosted embedding service to index them. That approach removes the model download, the memory ceiling, and the hardware question entirely, and for a few thousand images the per-call cost may be trivial. The difference in approach is where the data lives: with a hosted pipeline, every image or every description transits a third party. Meme Search inverts that. Its README notes you can optionally use an OpenAI-compatible vision API for description generation while keeping embeddings and search local, which is a middle path: outsource the captioning, keep the index on your disk. The second alternative is doing nothing beyond filenames and your operating system's file browser. That is genuinely adequate if your collection is small, well named, or rarely searched. Meme Search earns its keep when the collection is large enough that you cannot remember filenames and the content is text-heavy, which is exactly the case where a vision model reading the rendered text inside an image beats any filename convention.
Maintenance cost, licensing, and what to check first
The project is active, not archived, with a last push in September 2026 and three releases in the v2.3.x line during July and August 2026. That cadence suggests you should expect to pull updates, and each update carries the usual Compose risk of schema or service changes. The licence is Apache-2.0, which permits commercial and private use and modification and includes an explicit patent grant; it also requires that you preserve copyright and licence notices and state significant changes if you redistribute. That is a summary of the licence text, not legal advice, and if you plan to redistribute a modified version you should read the full Apache-2.0 terms yourself. The recurring costs are disk for models and the index, memory during generation, and the time to re-describe images when you change models. The one-time cost is the first model download. Before adopting, run the three-command quick start against a small test folder with the default Florence-2-base model, confirm the descriptions are accurate enough on your own images, and only then point it at the full collection.
Editorial conclusion
Adopt Meme Search if you have a personal image folder, a machine that can run a vision model locally, and no requirement to expose the UI beyond 127.0.0.1. Do not adopt it as a multi-user service or as anything reachable from the public internet: the README states the web UI has no user authentication, that API bearer tokens cover only the versioned integration endpoints, and that direct public exposure is unsupported. Before committing, verify that your hardware fits the model you intend to run (the README cites roughly 5GB for Moondream2 and 1.5 to 2GB for Moondream2-INT8 on CPU-only machines), confirm that the first-run model download completes on your connection, and read docs/search-api.md and integrations/cli/README.md to check that the loopback-only API surface matches how you plan to query the index.
Community notes