Mnemogogo design overview

The Mnemosyne Project is a program for memorising facts from flash cards using a spaced repetition algorithm. It is written in Python using the Qt windowing toolkit. It runs on PCs under most common operating systems (Windows, Linux, Mac, *BSD).

Mnemosyne is most effective when used daily, but it can be difficult to find free time in front of a computer. Making Mnemosyne available on mobile platforms, like mobile phones, handheld games, and Portable Media Players, would make it possible to review cards anywhere and anytime. This would be a great advantage for many users.

This document outlines a simple and open design for making Mnemosyne mobile. The design applies to the existing Mnemosyne 1.0, which can no longer be changed, but it should also be adaptable to Mnemosyne 2.0, which could be adapted if required.

Document details

Principles

1. There is no single mobile platform. Users will want to use Mnemosyne on, for example,
   • Symbian S40/S60 phones,
   • iPhones,
   • Android phones,
   • the Nintendo DS (for example, see ndsrs),
   • Flash Lite players (for instance, the Cowon D2), and,
   • Maemo tablets.
2. Many programming languages are used across devices. For instance, Java, C++, Python, Flash. Devices will have differing display capabilities, for instance the S60 phones have a browser control for displaying HTML but S40 phones do not. Most devices will not support all Unicode characters.
3. While reviewing cards on a mobile device is reasonable, entering or editing cards is less convenient and more easily done at a PC. Omitting this feature also simplifies the programming task.
4. Card databases by themselves are not large, approximately 2MB for 7000 cards, but adding images or sounds may increase the size by a factor of ten. The simplest architecture involves loading the entire card database into memory. Mnemosyne 1.0 works in this way.
5. Hosting cards on a website is not always the ideal solution.

Proposal

The Mnemosyne program remains critical for:

1. Creating and editing cards.
2. Maintaining and backing up the card database.
3. Uploading logs to the project server.
4. Reviewing cards when most convenient.

Three separate components are introduced for mobile reviewing:

1. A locking exporter plugin for Mnemosyne that provides a simple user interface and architecture. The would be reusable.
2. Various interface scripts that are called by the locking export plugin to produce data suitable for mobile devices.
3. Various players that run on mobile devices to review and grade cards.

There are two main possiblities for the locking export plugin¹:

1. N-days ahead: the exporter only produces enough cards for the next N days.
2. Fully synchronizing: a full copy of the database is maintained on the mobile device. Changes are periodically synchronized from the Mnemosyne master copy. Sharing the whole Mnemosyne database between devices is effectively fully synchronizing, it may be a practical approach under Mnemosyne 2.0 but it is likely to make implementing players more complicated.

This document proposes the N-days ahead approach, which has two main advantages:

1. It is simpler to implement. Both in terms of the locking exporter and various players.
2. It requires less resources on mobile devices. Further the available resources can be traded against the number of days worth of exported cards.

The main disadvantage is that synchronisations must be performed more regularly.

The design does not address synchronization between exported files and mobile devices. It is envisaged that this step will be performed manually in early versions until more experience is gained.

The Locking Exporter

The locking exporter will be a Mnemosyne plugin. It will add a menu option and single form GUI. The exporter will have two modes: local review and mobile review. In local review, Mnemosyne is used for all tasks. In mobile review, Mnemosyne can be used to add, edit, and delete cards but not to review them; the show answer and grading buttons will be disabled.

The GUI will show which mode is active, and offer two buttons:

1. Export, which switches from local reviewing to mobile reviewing.
2. Import, which switches from mobile reviewing to local reviewing.

It will be possible to force a switch back to local reviewing.

The GUI will also show three configuration options:

1. Number of days: the value N of days to export.
2. Path: the path to export to, or import from.
3. Type: the type of device. This option selects an interface script.

The parameter values will be stored in Mnemosyne's configuration store between runs.

Exporting does the following:

1. Selects all cards scheduled for the next N days, plus N * 1.05 times the Number of grade 0 cards to hold in your hand new cards to export.
2. Calls the interface script to commence the export, passing the export/import path. (Ideally this would instantiate an exporting object.)
3. Calls the interface script for each card that is to be exported, passing its id, question text, answer text, and statistics. (Optionally calling normal Mnemosyne plugins to process this data before exporting. Such plugins should also be used to handle LaTeX markup.)
4. Calls the interface script to finalise the export.
5. Switches to mobile reviewing mode.

Importing does the following:

1. Calls the interface script to commence the export, passing the export/import path. (Ideally this would instantiate an importing object.)
2. Iterates over an import routine that returns the id and statistics for a single card. The statistics are merged back into the database.
3. Calls the interface script to finalise the import.
4. Switches to local reviewing mode.

Interface Scripts

When exporting interface scripts transform the Mnemosyne data into the format most easiest to process on a particular mobile device. This may mean converting the Mnemosyne HTML format into gif or png files, as Antonini's script does now, or other tools like khtml2png do, converting certain Unicode characters into images, etcetera. Interface scripts also store the card statistics in a form that can be readily loaded into memory and manipulated on the mobile device; this may be a binary format. Interface scripts will manage the structure of files and directories at the import/export path, including copying and transforming image files from other locations as required.

When importing, interface scripts simply read the cards statistics file and pass the data back to the exporter.

Interface scripts will be handled similarly to normal Mnemosyne plugins.

Players

Each player will have a small number of essential features:

1. Read/write a card statistics file.
2. Display a question and wait for a show answer button press.
3. Display an answer and wait for a grading button press.
4. Update the card statistics.

The implementation of items 1–3 is shared with the interface script, which can accomodate for limitations of the APIs to which the player has access.

Item 4 requires reimplementing the Mnemosyne scheduling (SM2) algorithm in the player implementation language. Namely, the functions process_answer and rebuild_revision_queue from the Mnemosyne core library. These algorithms could be isolated as functions that might be shared across many players. They must give identical results to the official Mnemosyne version. A script could be developed to run schedulers, in any language, and compare their results to the official version. It would, however, have to account for some randomization.

Players could provide additional features. They should probably implement the answer overlay patch. They may or may not support sound.