Language: English | Deutsch
MEMOKI generates complete, playable Memory card games using generative AI. Users chat with an AI agent to describe their game, and the system produces a full deck of illustrated cards -- with reliably correct image content, exact object counts, and consistent visual style across all cards.
Bilingual (German/English) with language-specific knowledge bases and a full i18n system.
The core challenge: getting generative AI to produce exactly 7 apples (not 6, not 8) across 20+ cards in a single session. Anyone who has tried counting tasks with DALL-E or Gemini knows how unreliable this is out of the box. MEMOKI solves this through production-grade prompt engineering.
The prompt system is the heart of MEMOKI. The math mode alone (prompts/math_memory.py, 320+ lines) contains specialized prompt strategies for:
- Exact quantity enforcement -- layout hints force specific grid arrangements ("3 top row, 2 bottom row" for 5 objects) so the model can't silently add or drop items
- Count verification instructions -- every prompt includes explicit verification ("IMPORTANT: count all dots -- total must be exactly N, not more, not less")
- 5 distinct rendering strategies for abstract counting: geometric shapes, dice pip patterns, tally marks, domino tiles, and hand/finger poses -- each with custom prompt logic
- Anti-morphing constraints -- Gemini tends to turn inanimate objects into cute characters; the pairs mode prompt explicitly forbids anthropomorphization ("do NOT reshape into an animal, do NOT add faces or eyes")
- Number card protection -- themed number cards use constraints to prevent the model from reshaping digits into themed objects
This isn't "generate an image of a cat". It's systematic prompt engineering that makes unreliable AI output reliable and consistent.
The MEMOKI agent (agents/memoki.py) orchestrates a guided conversation using Gemini 2.5 Flash:
- Adapts its questions based on the selected game mode (5 different parameter sets)
- Collects theme, art style, and audience through natural conversation
- Outputs a structured JSON action block that triggers the generation pipeline
- No manual form-filling -- the user just chats
User --> Streamlit UI --> MemokiAgent (Gemini Chat)
|
JSON Action
|
Content Layer (LLM generation or curated knowledge bases)
|
Mode-specific Prompt Builders
|
Parallel Image Generation (ThreadPoolExecutor, 5 workers)
Primary: Gemini 3 Pro | Fallback: Gemini 2.5 Flash
|
Deck Assembly --> Play or Download
- Clean separation: agents / prompts / tools / game logic / generators / knowledge bases / i18n
- Abstract generator interface -- swap image backends without touching game logic
- Automatic fallback -- if the primary model (Gemini 3 Pro) fails, falls back to Gemini 2.5 Flash
- Parallel generation -- 20-40 images generated concurrently via ThreadPoolExecutor
- Full i18n -- bilingual UI with language-specific homonym knowledge bases
- Frontend: Streamlit 1.39+
- Chat Model: Google Gemini 2.5 Flash (agent orchestration)
- Image Model: Google Gemini 3 Pro (primary) / Gemini 2.5 Flash (fallback)
- Language: Python 3.11+
- i18n: German & English (extensible)
- Key Libraries: google-genai, Pillow, python-dotenv
| Mode | Card A | Card B | Content Source |
|---|---|---|---|
| Classic Memory | Image of object | Identical image | LLM-generated object list |
| Pairs Memory | Object A (e.g. pot) | Related object B (e.g. lid) | Curated knowledge base (10 themes, 150+ pairs) |
| Teekesselchen / Teapot Memory | Meaning A of word | Meaning B of same word | Curated knowledge base (DE: 130 homonyms, EN: 119 homonyms) |
| Math Memory I | Number (e.g. "5") | 5 abstract shapes | Curated shape definitions (20+ variations) |
| Math Memory II | Number (e.g. "5") | 5 real objects | LLM-generated countable objects |
git clone https://github.com/leelesemann-sys/memoki-prompt-engine.git
cd memoki-prompt-engine
pip install -r requirements.txt
# Add your Google AI Studio API key
cp .env.example .env
# Edit .env: GOOGLE_API_KEY=your_key_here
streamlit run app.pymemoki-prompt-engine/
app.py Streamlit frontend (950 lines) -- UI, game loop, state
app_test.py Test/QA mode -- all cards face-up for visual inspection
agents/
memoki.py Conversational agent (Gemini 2.5 Flash, JSON action output)
prompts/ <-- The core prompt engineering
math_memory.py 320+ lines: number cards, shapes, dice, tally, domino
pairs_memory.py Anti-morphing constraints for object pairs
teekesselchen.py Homophone meaning prompts
classic_memory.py Standard image prompts
tools/
content.py LLM object generation + knowledge base loaders
image.py Style/audience mapping, prompt assembly, image generation
game/
card.py Card data model (pair_id, label, image)
deck.py 5 deck builders (one per mode), shuffle logic
session.py Game state tracking
generators/
base.py Abstract ImageGenerator interface
nano_banana.py Gemini 3 Pro implementation
knowledge/
teekesselchen_de.json 130 curated German homonyms
teekesselchen_en.json 119 curated English homonyms
pairs_v2.json 10 themes x 15+ object pairs
math_shapes.json 20+ shape variations across 5 categories
i18n/
__init__.py Language registry, t() helper function
de.py German strings + How-It-Works content
en.py English strings + How-It-Works content
config/
settings.py API keys, model config, defaults
pages/
1_How_It_Works.py Interactive documentation (7 mode pages + architecture)
- Pick a language (Deutsch / English) in the sidebar
- Select a mode from the sidebar
- Chat with MEMOKI -- the agent asks for theme, style, and audience
- Generation pipeline builds mode-specific prompts and generates images in parallel
- Preview all cards sorted by pair, or play a full Memory game in the browser
- Download the complete deck as a ZIP file
For full technical documentation, see docs/architecture.md.
| Variable | Description |
|---|---|
GOOGLE_API_KEY |
Google AI Studio API key (required) |
Reads from .env (local) or Streamlit Secrets (cloud deployment).
Built by Lee Lesemann as a portfolio project demonstrating production-grade prompt engineering, LLM agent orchestration, and multi-modal AI integration.