--- title: Match Wise emoji: ๐Ÿƒ colorFrom: purple colorTo: pink sdk: gradio sdk_version: 6.17.3 python_version: '3.12' app_file: app.py pinned: true short_description: AI-Powered Educational Memory Game with Llama.cpp hf_oauth: true tags: - track:wood - sponsor:openbmb - achievement:offgrid - achievement:offbrand - achievement:llama - achievement:sharing - achievement:fieldnotes - matchWise - gradio - minicpm5-1b thumbnail: >- https://cdn-uploads.huggingface.co/production/uploads/683d69c43015d6c975e276c1/f9OyOJSr8M08WCArixzvb.png --- # ๐Ÿƒ MatchWise **AI-Powered Educational Memory Game with Adaptive Challenge Levels using MiniCPM5 llm via Llama.cpp** [![The Build Small Hackathon](https://img.shields.io/badge/The%20Build%20Small%20Hackathon-Hugging%20Face-yellow?style=for-the-badge)](https://huggingface.co/build-small-hackathon) ![An Adventure in Thousand Token Wood](https://img.shields.io/badge/An%20Adventure%20in%20Thousand%20Token%20Wood-TRACK-blue?style=for-the-badge) --- ### ๐Ÿš€ Purpose MatchWise attempts to make memory training more playful and educational by combining emoji card matching, AI-generated learning themes, session-wise performance tracking, and challenge levels that unlock when the player performs well. The game starts simple, then gradually moves the player from **Easy** toward **Challenge Me** using a performance meter based on level completion, matching accuracy, and gameplay progress. Instead of using fixed handcrafted stages, MatchWise keeps generating fresh memory boards and learning themes with LLM, so players can continue progressing through an endless learning loop. --- ### โœจ Key Features of MatchWise * ๐ŸŽด Emoji-based memory card matching game * ๐Ÿค– Infinite AI-generated levels with fresh themes and card sets * ๐Ÿง  Performance Meter that moves from **Easy** to **Challenge Me** * โšก Challenge levels unlocked through strong gameplay performance * โค๏ธ 5-life system to begin with * ๐Ÿ’ก Peek system to help players during difficult boards * ๐Ÿ† Persistent leaderboard support using SQLite storage * ๐ŸŽฎ Interactive Gradio UI with polished game-style visuals --- ### ๐Ÿ‘จโ€โš–๏ธ Hackathon Tracks & Judging Notes ๐Ÿ‘‰ [Social Media Post](https://x.com/tejasashinde/status/2066230745228886325) ๐Ÿ‘‰ [Watch MatchWise in action](https://youtu.be/Wlb0md_pMDg) ๐Ÿ“ด Off the Grid / Local-first: No cloud AI APIs are used. The game runs locally through MiniCPM5-1B-GGUF inside the Space. ๐ŸŽจ Off-Brand / Custom UI: MatchWise uses a custom game-style frontend with handcrafted HTML, CSS, and JavaScript instead of the default Gradio look. ๐Ÿฆ™ Llama Champion: The model runs through the llama.cpp runtime using llama-server. ๐Ÿ“ก Sharing is Caring / Open Trace: I've shared the Codex agent trace artifacts on the Hub so the community can explore my development process and build on top of it: [MatchWise Open Trace](https://huggingface.co/datasets/build-small-hackathon/MatchWise-agent-trace) ๐Ÿ““ Field Notes: I also wrote a full build report about the design, challenges, small-model constraints, and lessons learned: [Building MatchWise](https://huggingface.co/blog/build-small-hackathon/building-match-wise) ๐Ÿ—ƒ๏ธ Collection: https://huggingface.co/collections/build-small-hackathon/matchwise --- ### ๐Ÿง  Models Dataset and APIs Used * **LLM:** openbmb/MiniCPM5-1B-GGUF model running locally through llama.cpp * **Model File:** MiniCPM5-1B-Q4_K_M.gguf * **Inference Runtime:** llama.cpp `llama-server` * **Game Content:** AI-generated level titles, educational messages, challenge content, learning simple facts * **Leaderboard Storage:** SQLite database stored in HuggingFace Bucket capturing HF username and high scores * **UI Framework:** Gradio with custom HTML, CSS, and JavaScript game logic --- ### ๐Ÿ› ๏ธ Core Functionality Overview 1. Start the MatchWise game from the landing screen 2. Memorize the emoji cards during the preview timer 3. Flip cards and match identical emoji pairs 4. Earn score, peeks, and performance progress through clean gameplay 5. Move the Performance Meter from **Easy** toward **Challenge Me** 6. Unlock AI-generated challenge levels when performance is high enough 7. Continue playing while protecting your lives and improving your high score 8. Save and compare scores using the leaderboard --- ### ๐Ÿงช Install dependencies after clonning with: ```bash pip install -r requirements.txt ```` Run locally with: ```bash python app.py ``` Made with โค๏ธ using Gradio, MiniCPM5-1B via llama.cpp, and Hugging Face CPU (Free Tier) Spaces ๐Ÿค— Created by [tejasashinde](https://huggingface.co/tejasashinde) for [The Build Small Hackathon](https://huggingface.co/build-small-hackathon) 2026.