Mnemosyne: Optimized Flashcards and Research Project

Mnemosyne is:

• a free, open-source, spaced-repetition flashcard program that helps you learn as efficiently as possible.
• a research project into the nature of long-term memory. If you like, you can help out and upload anomynous data about your learning process (this feature is off by default).

Important features include:

• Bi-directional syncing between several devices
• Clients for Windows/Mac/Linux and Android
• Flashcards with rich content (images, video, audio)
• Support for Google text-to-speech and Google translate
• Powerful card types
• Flexible card browser and card selection
• Visualization to illustrate your learning process
• Extensive plugin architecture and external scripting
• Different learning schedulers
• Webserver for review through browser (does not implement any security features so far)
• Cramming scheduler to review cards without affecting the regular scheduer
• Core library that allows you to easily create your own front-end.

You can find a more detailed explanation of the features on the webpage, as well as the general documentation.

If you just want to download the latest Mnemosyne release as a regular user, please see the Download section. If you are interested in running and changing the latest code, please read on.

Installation of the development version and hacking

We use the git version control system and Github to coordinate the development. Please use a search engine to find out how to install git on your operating system. If you are new to git and github, there are many tutorials available on the web. For example, this interactive tutorial. See also section working locally with the code and sharing your changes for some info about git and Github.

About the code base

To get an overview of how all the different bits of the library fit together, see the documentation in the code at mnemosyne/libmnemosyne/docs/build/html/index.html. In order to keep the code looking uniform, please following the standard Python style guides PEP8 and PEP257.

Running the development code

You can find instructions for Windows here. The following instructions are valid for Linux and Mac (if you use homebrew or some other package manager).

Runtime requirements

To start working on Mnemosyne, you need at least the following software.

• Python 3.10 or later
• PyQt 6.0 or later, including QtWebEngine.
• Matplotlib
• Easyinstall
• cheroot 5 or later
• Webob 1.4 or later
• Pillow
• gTTS for Google text-to-speech
• googletrans-new for Google translate support (Note: version 1.1.9 does not work, you need the latest version from Github.)
• argon2-cffi
• [legacy-cgi] (https://pypi.org/project/legacy-cgi/) when using Python 3.13 or later.
• For Latex support: the latex and dvipng commands must be available (e.g., TeXLive on Linux, MacTeX on Mac, and MikTeX on Windows). On Arch based distributions, you'll need texlive-core package too.
• For building the docs: sphinx (If you get sphinx-related errors, try installing sphinx as root)
• For running the tests: pytest

These can be installed/upgraded using pip:

pip install --upgrade PyQt6 PyQt6-WebEngine matplotlib cheroot webob pillow googletrans gTTS argon2-cffi

You can either run a development version of Mnemosyne by using your system-wide Python installation, or by using a virtual environment with virtualenv. If your distribution provides and packages all necessary libraries in a recent enough version, using the system-wide Python install is probably easier and the recommended way.

Using the system-wide python installation

First, install all dependencies with your distribution's package manager. Then, run make, followed by make run from the top-level mnemosyne directory. This will generate all the needed auxiliary files and start Mnemosyne with a separate datadir under dot_mnemosyne2. If you want to use mnemosyne interactively from within a python shell, run python from the top-level mnemosyne directory. You can check if the correct local version was imported by running import mnemosyne; print(mnemosyne.__file__).

Using a local python installation

If your distribution does not provide all required libraries, or if the libraries are too old, create a virtual environment in the top-level directory (virtualenv venv), activate it (source venv/bin/activate) and install all the required dependencies with pip install. Then, follow the steps of the previous paragraph.

Using pyenv and poetry

As of Mnemosyne-2.11, you may use Pyenv and Poetry to develop for this project. Pyenv allows you to easily install and switch between multiple python interpreters, while Poetry is a modern tool for dependency management.

To get started, open a terminal at the project root, and run pyenv local. This will tell pyenv to use the python version specified in the .python-version file.

Before activating poetry, make sure to run the following settings:

poetry config virtualenvs.prefer-active-python true

This will make sure that poetry will recognize the python interpreter activated by pyenv.

Afterwards, run poetry shell to activate the project virtual environment. Then run poetry install to install all dependencies on your virtual environment. You can now get started on coding for Mnemosyne.

If there is a need to change dependencies, you may either poetry add <package_name> to add a dependency and poetry remove <package_name> to remove one. Run the following command to update the requirements.txt for those prefer to download project dependencies via pip install -r requirements.txt.:

poetry export -f requirements.txt --output requirements.txt --without-hashes

Running the test suite

As of Mnemosyne-2.11, nose has been replaced by the modern pytest framework.

You can run the test suite through:

make test

or:

make test-prep
python3 -m pytest tests -ra --junitxml=test-results.xml

Both commands will display a summary of test results and a junitxml file named test-results.xml, which is useful if you wish to go through the results outside of the terminal, such as an xml reader.

If you want to get a more actionable version of test-results.xml, you may run ./tools/convert_junitxml.py after, which converts the test result xml into a simpler todo.txt format. Because of the way the xml is parsed, the summary count of convert_junitxml.py and the terminal results of pytest may not always match, but the tool is sufficient for acting on the test results in a plain text editor.

Single tests can be run like this:

python3 -m pytest tests/<file_name>.py::<class_name>::<method_name> 

System-wide installation from source

For testing the development version it is not necessary to do a system-wide installation. If you want to do so anyway, here are the instructions.

Linux

Follow the installation instructions from above (install the dependencies, get the source code - either by cloning it from github, or by downloading and extracting the .tar.gz archive). Then, run the following command from within the top-level directory of the repository (which is also the location of this README.md file):

sudo python setup.py install

Depending on your setup, you might need to replace python with python3. To test the installation, change to any other directory and run mnemosyne. For example:

cd ~
mnemosyne

If you run into the issue of non-latin characters not displaying on statistic plots, install ttf-mscorefonts-installer and regenerate the font cache of matplotlib.

Mac

• Download and install Homebrew (see http://brew.sh)
• Create a CODESIGN_IDENTITY certificate as described at https://github.com/pyinstaller/pyinstaller/wiki/Recipe-OSX-Code-Signing
  • Open Applications > Utilities > Keychain Access
  • From the Keychain Access menu, choose Certificate Assistant > Create a Certificate
  • Name: something unique, I used "Devin Howard - Mnemosyne".
  • Identity Type: Self Signed Root
  • Certificate Type: Code signing
  • when you run "make macos" below, ensure you have set the CODESIGN_IDENTITY environment variable to the Name you chose above. For example, I run it like export CODESIGN_IDENTITY="Devin Howard - Mnemosyne" make clean make macos
  • But you might instead run export CODESIGN_IDENTITY="My Cool Certificate" make clean make macos
• Open the Terminal.
• Make sure you are using the latest version of Homebrew:

brew update

• Install dependencies for Mnemosyne.

brew install python@3.9 qt@5 mplayer openjpeg libffi
brew install --cask xquartz # needed for mplayer dylibs

• For Mnemosyne 2.8, we used Python 3.9.13 and Qt 5.15.3. To confirm you're using the correct versions:

python3 --version
brew list --versions qt@5

• If the v