How do Shellf's AI recommendations work?

Shellf doesn’t just ask “what genre do you like?” and surface popular books in that genre. The engine builds a structural read of your taste — the kinds of narrative structures, prose styles, themes, and moods you gravitate toward — then searches the catalogue for unread books that fit that shape, deliberately mixing in wildcards and cross-cluster picks so it doesn’t turn into an echo chamber.

For every recommendation, an AI explanation describes why this specific book is being suggested for you, grounded in the books in your library that anchor the match.

Every book in Shellf’s catalogue is processed into a mathematical representation of what it’s actually like as a reading experience — themes, narrative style, mood, structure, prose, tone, setting, audience, pace. Notably, things like awards and bestseller status are deliberately excluded from that representation. If popularity were included, the engine would just keep recommending whatever’s already trending, which is exactly the problem with most existing recommendation engines.

Your rated library is processed into a profile of what you actually respond to. Books you’ve loved pull the profile toward their patterns; books you’ve disliked or dismissed push the profile away. Mid-range ratings carry less weight than strong opinions either way, so the profile lands where your real reactions are, not your indifferences.

The result: instead of a flat “you like fantasy” verdict, the engine builds something more like “literary fiction with unreliable narrators, slow-burn fantasy with morally grey characters, essayistic non-fiction”. Genre is emergent from your actual reading, not prescribed by you.

With a taste profile in hand, the engine doesn’t pick candidates from one source. It uses several retrieval strategies in parallel and enforces diversity across them in the final selection — specifically to avoid the echo-chamber failure mode where you only ever get more of the thing you’re already deepest in.

For every recommendation, an LLM writes a short reason in plain language explaining why this book is being suggested for you — grounded in real books from your library that anchor the match. The reason isn’t a generic description of the book; it’s tailored to your taste profile so you can decide whether the angle resonates.

Important: the AI’s job is to articulate the match already produced by the retrieval engine, not to invent it. The matching is done in a structured way against real similarity data; the LLM is a translation layer that turns that match into a sentence you can read.

Shellf can still recommend on day one — a different pipeline runs when there’s not yet enough rated reading history to build a strong taste profile. It’s less precise than the full engine, but it works from book one and sharpens as your library grows.

This is also where the Goodreads import pays off: bringing a few hundred rated books across gets you to high-quality recommendations on day one rather than after months of slowly building a library inside Shellf.

It isn’t collaborative filtering. That’s the “people who liked X also liked Y” approach Goodreads uses, and the issue with it is that it surfaces popularity rather than fit. If you’ve already read everything popular in your genres, collaborative filtering has nothing left for you.

And it isn’t a chatbot reading your library and freestyling book titles. The AI only writes the explanations; the actual matching is structural, which keeps recommendations grounded in real similarity rather than whatever the model decides sounds plausible in the moment.