#+TITLE: Gnosis User Manual
#+AUTHOR: Thanos Apollo
#+email: public@thanosapollo.org
#+language: en
#+options: ':t toc:nil author:t email:t num:t
#+startup: content
#+macro: stable-version 0.5.8
#+macro: release-date 2025-11-08
#+macro: file @@texinfo:@file{@@$1@@texinfo:}@@
#+macro: space @@texinfo:@: @@
#+macro: kbd @@texinfo:@kbd{@@$1@@texinfo:}@@
#+macro: file @@texinfo:@file{@@$1@@texinfo:}@@
#+macro: space @@texinfo:@: @@
#+macro: kbd @@texinfo:@kbd{@@$1@@texinfo:}@@
#+texinfo_filename: gnosis.info
#+texinfo_dir_category: Emacs misc features
#+texinfo_dir_title: Gnosis: (gnosis)
#+texinfo_dir_desc: Spaced Repetition System
#+texinfo_header: @set MAINTAINERSITE @uref{https://thanosapollo.org,maintainer webpage}
#+texinfo_header: @set MAINTAINER Thanos Apollo
#+texinfo_header: @set MAINTAINEREMAIL @email{public@thanosapollo.org}
#+texinfo_header: @set MAINTAINERCONTACT @uref{mailto:public@thanosapollo.org,contact the maintainer}


Gnosis is a learning tool designed to enhance memory retention by
integrating a note-taking system with spaced repetition and
self-testing.

#+texinfo: @noindent
This manual is written for Gnosis version {{{stable-version}}}, released on {{{release-date}}}.

+ Manual:
  + <https://elpa.nongnu.org/nongnu/doc/gnosis.html>
  + <https://thanosapollo.org/projects/gnosis/> (Mirror)
+ Git repositories:
  + <https://git.thanosapollo.org/gnosis>
  + <https://codeberg.org/thanosapollo/emacs-gnosis> (Mirror)
  + <https://git.savannah.gnu.org/cgit/emacs/nongnu.git/?h=elpa/gnosis> (Mirror)

#+texinfo: @insertcopying

* Introduction

Gnosis consists of a note taking module (=org-gnosis=) and a self
testing module.

Users can use each module independently, but Gnosis is designed for a
workflow that starts with writing a note on a topic. After completing
a note, the user creates themas (questions/flashcards) for that topic,
which are used for reviews based on the [[Gnosis Algorithm]].

* Getting started Tutorial

To follow this tutorial, clone the demo deck available at codeberg

 Demo Deck: https://codeberg.org/thanosapollo/gnosis-demo

Import it to your gnosis collection via {{{kbd(M-x gnosis-import-deck)}}}

** Gnosis Dashboard

The first thing new users should familiarize themselves with is
=gnosis-dashboard=, which you can access via {{{kbd(M-x gnosis-dashboard)}}}.

You can start a review session from the dashboard by pressing {{{kbd(r)}}} or with {{{kbd(M-x
gnosis-review)}}}.

  NOTE: Gnosis supports reviewing specifics topics for notes of
  =org-gnosis= with {{{kbd(M-x gnosis-review-topic)}}}

You can add new themata from the dashboard {{{kbd(a)}}} or with {{{kbd(M-x gnosis-add-thema)}}}

** Linking Themata to Note Topics
We can create a demo note topic for Vancomycin, an antibiotic, with
{{{kbd(M-x org-gnosis-find RET Vancomycin)}}}.  For this demo, just save
the buffer contents by pressing {{{kbd(C-x C-s)}}}.

Back to the dashboard {{{kbd(M-x gnosis-dashboard)}}}, we can view all
our themata by pressing {{{kbd(n)}}} or we can press {{{kbd(s)}}} to
search our themata.  For this demo, we are looking for a thema from
the demo deck we imported, that contains a questions about
=Vancomycin=.

To link that thema to the note topic we created before, press
{{{kbd(e)}}} to edit the thema.  In the =Keimenon= section delete
"Vancomycin" and press {{{kbd(M-x org-gnosis-insert RET
Vancomycin)}}}.

After saving the thema with {{{kbd(M-x C-c C-c)}}}, you can review all
themata linked to that topic by {{{kbd(M-x gnosis-review-topic)}}}.

View more on [[Linking gnosis themata to org-gnosis content]].

* Thema Types
Each note is a *thema* consisting of the following components:

- *Keimenon*; The main text or question.
- *Hypothesis*; Assumptions/hints for the text to guide to the right answer
   - For example this is used as hints for cloze type or as choices in MCQs
- *Answer*; The correct response or solution to the keimenon.
- *Parathema*; expansion of keimenon, that can include links to e.g
  org-gnosis topics or even files, serving as a way to link org-gnosis
  topics to current thema.

Optionally, you can use also add tags for each note.

Themas can have multiple hypotheses and answers (*depending on
their type*), separated by =gnosis-export-separator=, which defaults to
="\n-"= /(a new line followed by a dash)/.

** Cloze
:PROPERTIES:
:CUSTOM_ID: Cloze
:END:
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-thema= and
selecting ~Cloze~.

Example format:

*** Default cloze format
#+begin_src org
  ,* Thema                      :pharmacology:antimicrobials:penicillin:
  :PROPERTIES:
  :GNOSIS_ID: NEW
  :GNOSIS_TYPE: cloze
  :END:
  ,** Keimenon
  What is the treatment for Actinomyces infection?

  Penicillin

  ,** Hypothesis
  - drug type

  ,** Answer
  - Penicillin

  ,** Parathema
  Sulfonamides → Nocardia
  Actinomyces → [[id:680ca944-8ee9-4513-92d6-25696ee01f48][Penicillin]]
  (treatment is a SNAP)
#+end_src

*** Using anki-like syntax
#+begin_src org
  ,* Thema                      :pharmacology:antimicrobials:penicillin:
  :PROPERTIES:
  :GNOSIS_ID: NEW
  :GNOSIS_TYPE: cloze
  :END:
  ,** Keimenon
  {c1:Cyproheptadine::drug name} is a(n) {c2:5-HT2} receptor antagonist used to treat {c2:serotonin syndrome}

  ,** Hypothesis
  -

  ,** Answer
  -

  ,** Parathema

#+end_src


You can format clozes like Anki if you so prefer with hints; e.g ~{{c1::Cyproheptadine::drug name}}~
   + You can use the keyword =::= to indicate a hint.

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

  + If a cloze is repeated, such as in phrases with "acetyl" &
    acetylcholine, include whitespace in the cloze to denote a single
    word.

** MCQ
:PROPERTIES:
:CUSTOM_ID: MCQ
:END:
Example format:
#+begin_src org

  ,* Thema                                                            :clinical:
  :PROPERTIES:
  :GNOSIS_ID: NEW
  :GNOSIS_TYPE: mcq
  :END:
  ,** Keimenon
  A 60-year-old man comes to the physician with chills, nausea, and
  diffuse muscle aches for 3 days. His niece had similar symptoms 2
  weeks ago and H3N2 influenza strain was isolated from her respiratory
  secretions. He received his influenza vaccination 2 months ago. His
  temperature is 38.5°C. A rapid influenza test is
  positive. Which of the following mechanisms best explains this
  patient's infection despite vaccination?

  ,** Hypothesis
  - Random point mutations within viral genome
  - Complementing with functional viral proteins
  - Exchange of viral genes between chromosomes
  - Reassortment of viral RNA segments
  - Acquisition of viral surface proteins

  ,** Answer
  - Random point mutations within viral genome

  ,** Parathema
  Random point mutations within the viral genome are responsible for
  antigenic drift, which creates a new virus strain.

#+end_src

* Linking gnosis themata to org-gnosis content

+ You can create notes using =M-x org-gnosis-find=, to link them to a
  gnosis thema use =M-x org-gnosis-insert= to insert a link of said
  topic, either on the keimenon or parathema.

+ You can review gnosis questions that are linked to a topic by using
  =M-x gnosis-review-topic=.

* Customization
:PROPERTIES:
:CUSTOM_ID: Customization
:END:
** 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:
#+begin_src emacs-lisp
(setf gnosis-string-difference 1)
#+end_src

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

* Gnosis Algorithm

Each gnosis note has a gnosis score, which is a list of 3 values,
(gnosis-plus gnosis-minus gnosis-synolon/total).  Gnosis-synolon is
what is used to determine the next interval upon a successful recall,
gnosis-plus is added to gnosis-synolon upon a successful recall as
well, gnosis-minus is subtracted from gnosis-synolon upon failing to
recall a note's answer.

Gnosis has 2 special events, one is ~anagnosis~ /ανάγνωση/ and ~lethe~ /λήθη/.

** Anagnosis Event
~Anagnosis~, which means comprehension & recognition of knowledge, is
triggered when the consecutive successful or failed recalls are equal
or greater to anagnosis value.

When ~anagnosis~ is triggered by consecutive *successful* recalls,
~epignosis~ value is added to gnosis-plus.  /Epignosis means accuracy of knowledge/.

When ~anagnosis~ is triggered by consecutive *failed* recalls,
~agnoia~ value is added to gnosis-minus. /Agnoia means lack of knowledge/

You can set specific values for each deck and tag of the variables
mentioned above by adjusting =gnosis-custom-values=.

** Lethe event

The ~Lethe~ event triggers after a certain number of consecutive
failures to recall an answer correctly.

When this threshold is reached, the next interval is reset to 0.

For example, with lethe value of 2, upon having 2 consecutive failed
recalls the next review will be set for the current day.

** Proto

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

=gnosis-algorithm-interval= is a list of numbers, representing the
first initial intervals for successful reviews.  There is no limit on
the length of the list.

Example:

#+begin_src emacs-lisp
  (setq gnosis-algorithm-interval '(0 1 2 30))
#+end_src

Upon each successful note review, the algorithm will increment to the
next interval value: 0 days (0), 1 day later (1), 2 days later
(2), and 30 days later.

Upon failing to review a note without completing it's proto successful reviews,
it's next review date will be on the same date.

* 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~

* Sync between devices

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

You will need to configure your remote manually.

Example:

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


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:
#+begin_src emacs-lisp
(setf gnosis-vc-auto-push t)
(gnosis-vc-pull) ;; Run vc-pull for gnosis on startup
#+end_src

* Interactions with other software
** emacs-no-littering

If you are a user of [[https://github.com/emacscollective/no-littering][emacs-no-littering]], you can theme Gnosis to fit
its standards by adding the following snippet to your configuration:

#+begin_src emacs-lisp
(setq gnosis-dir (no-littering-expand-var-file-name "gnosis/"))
#+end_src

This sets =gnosis-dir= to =~/.emacs.d/var/gnosis=, in line with the folders of other packages.

* Contributing

Thank you for considering contributing back to gnosis.  You can
contribute by submitting a pull request on the codeberg mirror
repository, or directly sending me patch via email.

** How to create a patch

/Example:/

#+begin_src bash
$ git clone https://git.thanosapollo.com/gnosis.git && cd gnosis
$ emacs something
$ git add something
$ git commit -m "Fix something"
$ git format-patch HEAD^1
0001-Fix-something.patch
#+end_src

You can sent the patch to "Thanos Apollo", the email of which you can
find on the git log.
