Building an AI That Reads Tarot Cards (and Actually Remembers Your Last Reading)

Most tarot apps work like this: shuffle, deal, look up card meaning from a table, display. It's a random number generator wearing a mystical costume.

I wanted to build something that actually understood readings — that could connect The Tower showing up today with the upheaval themes from last week's Celtic Cross, and that treated reversed cards as more than just "the opposite meaning."

The Problem With Generic Interpretations

Card meanings aren't static. The Three of Swords in a "past" position tells a very different story than in "what you need to let go of." And if the querent has been pulling Swords cards for three weeks straight, that pattern matters.

Traditional apps ignore all of this context. Luna's Circle doesn't.

The Stack

• FastAPI — async API serving readings, grimoire, horoscopes
• Claude API — multi-layer persona architecture for Luna (the AI companion)
• Swiss Ephemeris — accurate birth chart calculations (same library astro.com uses)
• Qdrant — vector search over 300+ crystal and herb correspondences
• SQLite — reading history, user profiles, grimoire entries
• ElevenLabs — voice-narrated readings

The Interesting Technical Challenge

Getting an LLM to be consistent in tarot interpretation is harder than it sounds. Most training data is generic copy-paste card meanings. My solution:

1. Card-position-context matrices — each card gets different interpretation weights based on spread position, surrounding cards, and reading question
2. Quality scoring — a separate evaluation pass rejects below-threshold interpretations and regenerates
3. Reading memory — Luna maintains a rolling context window of your past readings, connecting themes across sessions
4. Persona layers — base knowledge, mystical warmth voice, user-specific context, and a final coherence check

What 22,000+ Readings Taught Me

• The Tower generates the most follow-up readings when it appears in future positions
• Reversed cards double engagement time (people read more carefully)
• The Moon is the hardest card for AI to interpret consistently (illusion vs. intuition depends heavily on context)
• Users who get 3+ readings are 5x more likely to convert to paid

Try It

Free daily readings at Luna's Circle — no signup needed for basic features.

The full platform includes 10 spread types, a digital grimoire (Book of Shadows), birth chart analysis, moon phase tracking with ritual suggestions, community covens, and daily horoscopes.

Happy to answer questions about the architecture or the spiritual AI space in general.