Gnosis (γνῶσις), pronounced “noh-sis”, meaning knowledge in Greek, is a spaced repetition system implementation for note taking and self testing.

This manual is written for Gnosis version 0.2.0, released on 2023-03-08.

1 Introduction

Gnosis, is a spaced repetition system for note taking & self testing, where notes are taken in a Question/Answer/Explanation format & reviewed in spaced intervals, determined by the success or failure to recall a given answer.

Gnosis implements a highly customizable algorithm, inspired by SM-2. Gnosis algorithm does not use user’s subjective rating of a note to determine the next review interval, but instead uses the user’s success or failure in recalling the answer of a note. Read more on 5

2 Adding notes

Creating notes for gnosis can be done interactively with:

M-x gnosis-add-note

When it comes to adding images, you can select images that are inside gnosis-images-dir. For adjusting image size, refer to 4

3 Note Types

3.1 Cloze

A cloze note type is a format where you create sentences or paragraphs with “missing” words. A fill-in-the-blanks question.

You can create a cloze note type using M-x gnosis-add-note and selecting Cloze, the question should be formatted like this:

{c1:Cyproheptadine} is a(n) {c2:5-HT2} receptor antagonist used to treat {c2:serotonin syndrome}

You can also format clozes like Anki if you prefer; e.g {{c1::Cyproheptadine}}

  • For each `cX`-tag there will be created a cloze type note, the above example creates 2 cloze type notes.

  • Each `cX` tag can have multiple clozes, but each cloze must be a UNIQUE word (or a unique combination of words) in given note.

You can remove the guidance string by adjusting gnosis-cloze-guidance.

3.2 MCQ (Multiple Choice Question)

A MCQ note type, as the name suggests, is a multiple choice question.

The stem field (question) is separated by the options (choices) via gnosis-mcq-separator, each option is separated by gnosis-mcq-option-separator.

You can remove the guidance string by adjusting gnosis-mcq-guidance.

3.3 Basic Type

Basic note type is a simple question/answer note, where the user first sees a “main” part, which is usually a question, and he is prompted to input the answer.

3.4 Double

Double note type, is essentially a note that generates 2 basic notes. The second one reverses question/answer.

Ideal for vocabulary acquisition notes.

3.5 y-or-n

y-or-n (yes or no) note type, user is presented with a question and prompted to enter character “y” or “n”.

When using the hidden function gnosis-add-note--y-or-n, note that the ANSWER must be either 121 (y) or 110 (n), as those correspond to the character values used to represent them.

4 Customization

4.1 Image size

Adjust image size using gnosis-image-height & gnosis-image-width

Example:

(setf gnosis-image-height 300
      gnosis-image-width 300)

4.2 Typos | String Comparison

You can adjust gnosis-string-difference, this is a threshold value for string comparison that determines the maximum acceptable Levenshtein distance between two strings, which identifies their similarity

Let’s illustrate with an example:

(setf gnosis-string-difference 1)

In this scenario, we set gnosis-string-difference to 1. This implies that two strings will be recognized as similar if they exhibit a difference of at most one character edit.

To demonstrate, ’example’ and ’examples’ will be recognized as similar, considering that the latter involves just one additional character.“

5 Gnosis Algorithm

Each gnosis note has an ef (easiness factor), which is a list of 3 values. The last value is the total ef for a note, which will be used to determine the next interval upon a successful answer recall, the second value is the ef-decrease value, this value will be subtracted from the the total ef upon failure to recall the answer of a note, the first value is the ef increase, will be added to the total ef upon a successful recall.

Each gnosis deck has gnosis-algorithm-ef-threshold, it’s an integer value that refers to the consecutive success or failures to recall an answer. Upon reaching the threshold, gnosis-algorithm-ef-decrease or gnosis-algorithm-ef-increase will be applied to the ef-increase or ef-decrease of note.

You can customize deck specific algorithm values using gnosis-dashboard.

5.1 Initial Interval

The default initial interval is defined at gnosis-algorithm-interval, you can define a custom initial interval for each deck as well.

gnosis-algorithm-interval is a list of 2 numbers, representing the first two initial intervals for successful reviews.

Example:

(setq gnosis-algorithm-interval '(0 1))

Using the above example, after first successfully reviewing a note, you will see it again in the next review session, if you successfully review said note again, the next review will be tomorrow.

5.2 Easiness Factor

The gnosis-algorithm-ef is a list that consists of three items:

  1. Easiness factor increase value: Added to the easiness factor upon a successful review.

  2. Easiness factor decrease value: Subtracted from the total easiness factor upon a failed review.

  3. Total Easiness factor: Used to calculate the next interval.

How this is used:

Multiplies the last interval by the easiness factor after a successful review.

For example, upon a successful review, if the last review was 6 days ago with an easiness factor of 2.0, the next interval would be calculated as 6 * 2.0, and the next total easiness factor would be updated by adding the increase value 2.0 + <increase-value>.

Configuration example:

(setq gnosis-algorithm-ef '(0.30 0.25 1.3))

5.3 Forgetting Factor

gnosis-algorithm-ff is a floating number below 1.

Used to determine the next interval after an unsuccessful review.

Multiplied with the last interval to calculate the next interval. For example, if gnosis-algorithm-ff is set to 0.5 and the last interval was 6 days, the next interval will be 6 * 0.5 = 3 days.

Example configuration:

(setq gnosis-algorithm-ff 0.5)

You can set a custom gnosis-algorithm-ff for each deck as well.

6 Editing notes

  • Currently there are 2 ways for editing notes:
    • You can edit a note after review by pressing e
    • Open gnosis-dashboard with M-x gnosis-dashboard, find the note you want to edit and press e

7 Sync between devices

Gnosis uses git to maintain data integrity and facilitate synchronization across devices.

You will need to configure your remote manually.

Example:

cd ~/.emacs.d/gnosis # default location for gnosis
git init # After completing your first review session, a git repo should have been initialized automatically.
git remote add <remote_name> <remote_url>
git push --set-upstream origin master

You can interactively use gnosis-vc-push & gnosis-vc-pull. As the name suggests, they rely on vc to work properly.

Depending on your setup, vc might require an external package for the ssh passphrase dialog, such as x11-ssh-askpass.

To automatically push changes after a review session, add this to your configuration:

(setf gnosis-vc-auto-push t)
(gnosis-vc-pull) ;; Run vc-pull for gnosis on startup

8 Extending Gnosis

To make development and customization easier, gnosis comes with gnosis-test module, that should be used to create a custom database for testing.

To exit the testing environment, rerun M-x gnosis-test-start and then enter n (no) at the prompt “Start development env?”

8.1 Creating Custom Note Types

Creating custom note types for gnosis is a fairly simple thing to do

  • First add your NEW-TYPE to gnosis-note-types

    (add-to-list 'gnosis-note-types "new-note-type")

  • Create 2 functions; gnosis-add-note-TYPE & gnosis-add-note--TYPE

Each note type has a gnosis-add-note-TYPE that is used interactively & a “hidden function” gnosis-add-note--TYPE that handles all the logic.

Refer to gnosis-add-note-basic & gnosis-add-note--basic for a simple example of how this is done.

  • Create gnosis-review-TYPE

This function should handle the review process, displaying it’s contents and updating the database depending on the result of the review (fail/pass). Refer to gnosis-review-basic for an example of how this should be done.

  • Optionally, you might want to create your own custom gnosis-display functions