memi-engine

In a world where a language model will answer almost anything in an instant, the part of your mind that recalls — that retrieves what you know on its own — gets little exercise. memi is a small counterweight: a game built on active recall. You look at an image, try to name it before revealing the answer, and follow the know more link to learn more. Each round strengthens the link between what you see and what you know. The answer is always one tap away — the point is to reach for it yourself first.

memi-engine lets you build your own memi game — a tap-to-reveal flashcard trainer — from a list of names and where to find their images.

You define categories (countries, animals, monuments, movies…); the engine gives you the responsive web UI, the menu, image fetching from Wikipedia and friends, filters, clue mode, a "know more" link to each item's Wikipedia (or source) page on reveal, theming, and a reporting system.

pip install memi-engine

from memi_engine import CategoryProvider, MemiConfig, create_app, register


class Animals(CategoryProvider):
    key = "nature:animals"
    items = ["Lion", "Tiger", "Elephant", "Aardvark"]


register(Animals())
app = create_app(MemiConfig(title="My Memi"))

if __name__ == "__main__":
    app.run(debug=True)

Open http://localhost:5000, pick nature → animals, and play. Images are resolved from Wikipedia automatically from each item's name.

Concepts

A memi game is just a set of category providers registered with the engine. Each provider declares:

• items — the list of names to guess.
• key — where the category sits in the menu (see below).
• how to get an image for an item (default: Wikipedia), and optionally a tag (a subtitle shown on reveal) and a clue.

The engine handles routing, the random game loop (/api/random), filtering, prefetching, and rendering.

Keys are the menu

A category key is a colon-separated path. The engine splits it to build a nested menu, and renders each segment verbatim as the on-screen label — so the key is also your menu copy. This is why localized games keep their keys in the game's language:

Up to four levels are supported. A child labelled all always sorts first.

CategoryProvider

Subclass it and set at least key and items. Override the methods you need.

class Monuments(CategoryProvider):
    key = "culture:monuments"
    items = ["Belém Tower", "Eiffel Tower"]
    override_name = True            # show the item name, not the article title

    def get_tag(self, item):       # subtitle on the revealed card
        return PARISHES.get(item)

Register each provider with register(Monuments()), or use @register as a class decorator on the definition.

Attributes

Methods

The details panel. With MemiConfig(layout="enriched") a panel opens beside the card on reveal. By default it holds the opening paragraph of the card's Wikipedia article (the one know more links to), in the game's html_lang when that edition has the article. Set map_zoom on categories of places to pin a map on the article's coordinates; override get_wikipedia_title for cards whose link isn't a Wikipedia article, or get_details to write your own.

The optional url in the get_image result is the item's source page; the engine turns it into the "know more" link shown on reveal (label set via MemiConfig.label_more). The built-in image helpers populate it automatically — e.g. get_wikipedia_image returns the Wikipedia article URL — so Wikipedia-backed categories get the link for free.

Scientific names

ScientificNameProvider tags each item with its Latin name. It ships a bundled English database (SCIENTIFIC_NAMES, ~1500 species) used by default; pass your own mapping for other languages. The tag is shown only when the Latin name differs from the display name, in italic scientific style.

from memi_engine import ScientificNameProvider, register

class Animals(ScientificNameProvider):
    key = "nature:animals"
    items = ["Lion", "Tiger"]      # → "Panthera leo", "Panthera tigris"

class Plantas(ScientificNameProvider):
    key = "natureza:plantas"
    items = ["Sobreiro"]
    scientific_names = {"Sobreiro": "Quercus suber"}

Filters

A filter maps option values to subsets of items. The engine renders the filter buttons and applies the choice via a URL parameter.

class Countries(CategoryProvider):
    key = "geography:countries"
    items = ["France", "Spain", "Japan"]
    filters = {
        "continent": {"europe": ["France", "Spain"], "asia": ["Japan"]},
    }

Images

memi_engine.images resolves item names to image URLs and caches results in-memory. Providers call these from get_image:

get_wikipedia_image, get_wikipedia_file_image, get_commons_file_image, get_tmdb_image, get_tmdb_tv_image, get_fandom_image, get_country_shape, get_album_cover, get_logo_image, and more.

Some sources need configuration via environment variables:

MemiConfig

Passed to create_app. Common fields:

For a non-English game, set wikipedia_lang so the default image lookup and the "know more" link resolve against that language's Wikipedia (e.g. "pt"). It can also be set with the MEMI_WIKIPEDIA_LANG environment variable.

All UI strings are label_* fields, so a fully localized game keeps its labels and about_html in its own language while the code stays English.

Instance static files

To serve your own logo or images, point create_app at a static folder; its files take precedence over the engine's:

app = create_app(config, instance_static="/path/to/static")
# served at /static/... , falling back to the engine's static files

Search discoverability

One game is served from many URLs: /, a /<slug> landing page per category, and /about. The category you are playing is a JavaScript variable, so nothing in the markup distinguishes those pages — left alone they are one page repeated, and a crawler indexes one and discards the rest.

The engine gives each of them its own metadata, derived from what the instance already declares:

The title and description patterns are home_title, category_title and category_description on MemiConfig; a category pattern can also use {count}, the number of items in it. Defaults are punctuation only, so a localized game stays in its own language without touching them.

A category page also renders content a crawler can read, since the game above it is pure JavaScript state: a heading with the category's label, the optional category_intro line, and the category's item names in a <details> that is closed by default — the names are the answers the game asks players to recall, so they belong in the markup without being shown to a player who didn't ask for them. label_contents is that block's summary (localize it like any other label); contents_max caps a long list at 200 names.

Every page also carries a <nav> of real links to each category page. The menu itself is buttons wired to JavaScript, so without it nothing on the site links to a landing page at all.

Two more things fall out of this:

• /robots.txt opens the site, excludes /api/ (JSON a crawler can do nothing with) and names the sitemap.
• /sitemap.xml lists /, /about and every category — built from the registry, so a new provider appears without an edit. A category whose last segment is unique answers at both /food and /culture-food; only the short one is listed, and the long one canonicalises to it.

Canonical and og: URLs need the site's real origin. Behind a reverse proxy that sends X-Forwarded-Proto and X-Forwarded-Host (Caddy does by default) the engine works it out per request. Set site_url — or MEMI_SITE_URL — to pin it instead.

Set html_lang per instance. It defaults to "en", and a Portuguese game that tells Google it is English is a game shown to the wrong people.

Deployment

The app is a standard WSGI Flask app. For production, install the server extra and run under gunicorn:

pip install "memi-engine[server]"
gunicorn "yourgame:app"

Two optional data files are read from the working directory at runtime: excluded_items.txt (items to hide) and reported_items.log (written when players report a bad card).

Live examples

Real games built on this engine, all linked from memi.games: memi · memi portugal · memi lisboa · memi slovensko · memi US.

Development

uv sync --extra dev
pytest          # run the test suite
ruff check .    # lint

License

MIT — see LICENSE.