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.1.9, released on 2023-02-22.

1 Introduction

Gnosis is a spaced repetition note taking and self testing system, where notes are taken in a Question/Answer/Explanation-like format & reviewed in spaced intervals.

Gnosis can help you better understand and retain the material by encouraging active engagement. It also provides a clear structure for your notes & review sessions, making it easier to study.

2 Installation

Gnosis is available via MELPA

2.1 Using straight.el

If you have not installed straight.el, follow the instructions here:

https://github.com/radian-software/straight.el

Once you have installed straight.el, you can install gnosis using the following emacs lisp snippet:

(straight-use-package
 '(gnosis :type git
          :host nil
          :repo "https://git.thanosapollo.org/gnosis"))

2.2 Installing manually from source

Gnosis depends on the compat & emacsql libraries which are available from MELPA. Install them using M-x package-install RET <package> RET or you may also install them manually from their repository.

  • Clone gnosis repository

    $ git clone https://git.thanosapollo.org/gnosis ~/.emacs.d/site-lisp/gnosis
    
  • Add this to your emacs configuration

    (add-to-list 'load-path "~/.emacs.d/site-lisp/gnosis")
    (load-file "~/.emacs.d/site-lisp/gnosis/gnosis.el")
    

3 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 Image Size

4 Note Types

4.1 Cloze

A cloze note type is a format where you create sentences or paragraphs with “missing” words. Almost all note types can be written as a cloze type in a way. Ideal type for memorizing definitions.

To get the most out of gnosis, you have to become familiar with cloze type notes.

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.

4.2 MCQ (Multiple Choice Question)

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

First you will be prompted to input the question stem field.

Afterwards you will be prompted to enter the choices, each - indicates a choice, the choice inside {} will be marked as the correct one.

Example of options:

  • Option 1

  • Option 2

  • {Correct choice}

4.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.

4.4 Double

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

Ideal for vocabulary acquisition, creating vocabulary/translation notes for a foreign language.

4.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.

5 Customization

5.1 Image size

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

Example:

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

5.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.“

6 Gnosis Algorithm

6.1 Initial Interval

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

Example:

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

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

6.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))

6.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)

7 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

8 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

9 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?”

9.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-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