This is gnosis.info, produced by makeinfo version 7.2 from gnosis.texi.

INFO-DIR-SECTION Emacs misc features
START-INFO-DIR-ENTRY
* Gnosis: (gnosis).     Unified knowledge management and spaced repetition.
END-INFO-DIR-ENTRY


File: gnosis.info,  Node: Top,  Next: Introduction,  Up: (dir)

Gnosis User Manual
******************

* Menu:

* Introduction::                 What gnosis is and how it is organized
* Installation and Setup::       How to install gnosis and configure it for first use
* Nodes: Nodes (1).              Zettelkasten-style notes stored as org-mode files
* Journal::                      Date-based journal entries with TODO integration
* Themata (Spaced Repetition Cards)::
* Review System::
* The Algorithm::
* Dashboard::
* Export and Import::
* Link Health and Maintenance::

-- The Detailed Node Listing --

Introduction

* Why Gnosis::
* The Two Subsystems::
* Greek Terminology Reference::
* Data Storage::

The Two Subsystems

* Nodes::
* Themata::
* The Link Between Nodes and Themata::

Installation and Setup

* Requirements::
* Installing from GNU ELPA::
* Installing with GNU Guix::
* Basic Configuration::
* Key Directories::
* Upgrading from org-gnosis::
* Version Control::
* Completing Read Integration::
* Full Example Configuration::

Key Directories

* gnosis-dir::
* gnosis-nodes-dir::
* gnosis-journal-dir::

Nodes

* What Makes an Org Heading a Node::
* Creating and Finding Nodes::
* File Naming::
* Displaying Tags in Completion::
* Templates::
* Automatic Sync::
* Links Between Nodes::
* Backlinks::
* Tags::

Creating and Finding Nodes

* gnosis-nodes-find::
* gnosis-nodes-find-by-tag::

File Naming

* gnosis-nodes-timestring::
* GPG Encryption::

Templates

* gnosis-nodes-templates::
* The {*} Heading Marker::
* Inserting a Template Manually::

Automatic Sync

* Manual Sync::
* Force Rebuild::

Tags

* Adding Tags::

Journal

* Creating Entries::
* File vs Single-File Mode::
* GPG Encryption: GPG Encryption (1).
* Templates: Templates (1).
* ``TODO'' Integration::
* Checked Item Tracking::
* Inserting Journal Links::
* Full Journal Configuration Example::

Creating Entries

* gnosis-journal::
* gnosis-journal-find::

File vs Single-File Mode

* Separate Files (Default)::
* Single Journal File::

Templates

* gnosis-journal-templates::

"TODO" Integration

* gnosis-journal-todo-files::
* gnosis-journal-todo-keywords::
* Bullet Point Character::
* How TODO Carry-Forward Works::

Themata (Spaced Repetition Cards)

* Fields of a Thema::
* Thema Types::
* Creating Themata::
* Editing Themata::
* Tags on Themata::
* The Link Between Themata and Nodes::
* Suspending Themata::

Thema Types

* Basic::
* Double::
* MCQ (Multiple Choice Question)::
* Cloze::
* MC-cloze (Multiple Choice Cloze)::

Review System

* Starting a Review Session::
* Tag Filtering::
* The Review Flow::
* Type-Specific Review Behaviour::
* Node-Based Review::
* Activity Logging::
* Monkeytype::
* Sample Configuration::

Type-Specific Review Behaviour

* Basic: Basic (1).
* MCQ::
* Cloze: Cloze (1).
* MC-cloze::

The Algorithm

* Overview::
* The Gnosis Score Triplet::
* Proto Phase::
* Interval Calculation::
* Anagnosis Events::
* Lethe::
* Fuzz::
* Day Boundary::
* Per-Tag Algorithm Customisation::
* All Algorithm Variables::

Dashboard

* Opening the Dashboard::
* The Themata View::
* The Nodes View::
* The Tags View::

Export and Import

* Exporting::
* Importing::
* The Export Format::
* Editing Themata (Org Format)::
* Importing from Anki::

Exporting

* Tag Filter Notation::
* Programmatic Use::

Importing from Anki

* What Gets Imported::
* What Does Not Transfer::
* Requirements: Requirements (1).

Link Health and Maintenance

* Checking Link Health::
* Full Synchronisation::
* Syncing the Node Database::
* Version Control: Version Control (1).


File: gnosis.info,  Node: Introduction,  Next: Installation and Setup,  Prev: Top,  Up: Top

1 Introduction
**************

Gnosis is a personal knowledge management and spaced repetition system
for Emacs.  It integrates two complementary subsystems in a single
package: a Zettelkasten-style note system called *nodes*, and a
flashcard-based self-testing system built around *themata*.  Both
subsystems share a single SQLite database, and their contents are
designed to be linked together so that flashcard questions can refer
directly to the notes they are drawn from.

   The name gnosis (Greek: _γνῶσις_, knowledge) reflects the package's
philosophical orientation: the goal is not mere memorization but the
deliberate construction of knowledge over time.

* Menu:

* Why Gnosis::
* The Two Subsystems::
* Greek Terminology Reference::
* Data Storage::


File: gnosis.info,  Node: Why Gnosis,  Next: The Two Subsystems,  Up: Introduction

1.1 Why Gnosis
==============

Most spaced repetition tools treat flashcards as isolated units.  You
create a card, review it, and the system schedules the next review.  The
cards have no relationship to each other or to anything outside the
review loop.

   Most note-taking tools do the opposite: they help you build a web of
interconnected ideas, but they offer no mechanism for systematically
testing and reinforcing what you have written.

   Gnosis bridges these two approaches.  Your notes and your review
material live in the same system, linked together.  When you write a
node about a topic, you can create themata whose questions reference
that node.  When you review, you can review all the questions linked to
a given note, or follow the link graph to review related topics.  The
goal is a single system where understanding and recall reinforce each
other.


File: gnosis.info,  Node: The Two Subsystems,  Next: Greek Terminology Reference,  Prev: Why Gnosis,  Up: Introduction

1.2 The Two Subsystems
======================

* Menu:

* Nodes::
* Themata::
* The Link Between Nodes and Themata::


File: gnosis.info,  Node: Nodes,  Next: Themata,  Up: The Two Subsystems

1.2.1 Nodes
-----------

Nodes are Zettelkasten-style notes stored as plain org-mode files.  Each
node is a file, or a heading within a file, identified by a unique UUID
stored as an ‘#+id:’ org property.  Nodes are indexed in the database so
that they can be searched, browsed by tag, and linked together.  Links
between nodes use standard org-mode ‘[[id:UUID]]’ syntax, which means
they remain compatible with any tool that understands org-id links.


File: gnosis.info,  Node: Themata,  Next: The Link Between Nodes and Themata,  Prev: Nodes,  Up: The Two Subsystems

1.2.2 Themata
-------------

A _thema_ (Greek: _θέμα_, a subject set before one; plural _themata_) is
a review card.  Each thema consists of a _keimenon_ (Greek: _κείμενον_,
the text that underlies something; the question or prompt), an _answer_
(the expected response), and an optional _parathema_ (Greek: _παράθεμα_,
a side-text; supplementary context shown after the answer).  Themata are
reviewed using a spaced repetition algorithm that adapts the interval
between reviews based on performance.

   Themata support five question types:

   • *Basic*: A direct question with a typed answer.
   • *Double*: Two prompts, each with its own answer, presented in
     sequence.
   • *MCQ* (Multiple Choice Question): The user selects one correct
     option from a list.
   • *Cloze*: A sentence with one or more words obscured; the user types
     the missing text.
   • *MC-Cloze* (Multiple Choice Cloze): A cloze question where the
     missing text is chosen from a list of options.


File: gnosis.info,  Node: The Link Between Nodes and Themata,  Prev: Themata,  Up: The Two Subsystems

1.2.3 The Link Between Nodes and Themata
----------------------------------------

Themata and nodes are not siloed.  When you write a node about a topic,
you can create themata whose keimenon or parathema contains an
‘[[id:NODE-UUID]]’ org-id link to that node.  Gnosis records these
relationships so that you can later run ‘gnosis-review-topic’ to review
all themata associated with a particular node.  This is the intended
workflow: write a note, create questions about it, link the questions to
the note, then review by topic.


File: gnosis.info,  Node: Greek Terminology Reference,  Next: Data Storage,  Prev: The Two Subsystems,  Up: Introduction

1.3 Greek Terminology Reference
===============================

The following terms appear throughout this manual and in user-facing
prompts:

   • *Gnosis* (_γνῶσις_, knowledge): the name of the package, and also
     the name of the internal score used by the spaced repetition
     algorithm to track performance per thema.
   • *Thema* (_θέμα_, topic or subject; plural _themata_): a single
     review card.
   • *Keimenon* (_κείμενον_, underlying text): the question or prompt
     shown during review.
   • *Parathema* (_παράθεμα_, side-text): supplementary text shown after
     answering, used to add context or a longer explanation.
   • *Anagnosis* (_ἀνάγνωσις_, recognition): an event in the algorithm
     that fires after a streak of consecutive successes or failures,
     adjusting the gnosis score.
   • *Epignosis* (_ἐπίγνωσις_, full knowledge): the increment applied to
     the gnosis score on a correct answer during an anagnosis event.
   • *Agnoia* (_ἄγνοια_, ignorance): the decrement applied on an
     incorrect answer during an anagnosis event.
   • *Amnesia* (_ἀμνησία_, forgetting): the multiplier applied to the
     interval on failure.
   • *Lethe* (_λήθη_, forgetting; the river of oblivion): the threshold
     of consecutive failures that triggers an interval reset.
   • *Proto* (_πρῶτο_, first): the sequence of fixed intervals used
     during the initial learning phase before the adaptive algorithm
     takes over.


File: gnosis.info,  Node: Data Storage,  Prev: Greek Terminology Reference,  Up: Introduction

1.4 Data Storage
================

All data lives in a single SQLite database at ‘GNOSIS-DIR/gnosis.db’.
The database is created and migrated automatically; no manual setup or
maintenance is required.  Gnosis requires Emacs 29.1 or later (for
built-in SQLite support) and the ‘compat’ library.  There are no other
external dependencies.


File: gnosis.info,  Node: Installation and Setup,  Next: Nodes (1),  Prev: Introduction,  Up: Top

2 Installation and Setup
************************

* Menu:

* Requirements::
* Installing from GNU ELPA::
* Installing with GNU Guix::
* Basic Configuration::
* Key Directories::
* Upgrading from org-gnosis::
* Version Control::
* Completing Read Integration::
* Full Example Configuration::


File: gnosis.info,  Node: Requirements,  Next: Installing from GNU ELPA,  Up: Installation and Setup

2.1 Requirements
================

Gnosis requires:

   • GNU Emacs 29.1 or later, compiled with SQLite support.  Verify this
     with ‘(fboundp 'sqlite-open)’; it should return ‘t’.
   • The ‘compat’ library, available from GNU ELPA.

   No external programs are required.  Git is optionally used by the
version control integration (‘gnosis-vc-auto-push’), but is not a hard
dependency.


File: gnosis.info,  Node: Installing from GNU ELPA,  Next: Installing with GNU Guix,  Prev: Requirements,  Up: Installation and Setup

2.2 Installing from GNU ELPA
============================

Gnosis is available from GNU ELPA.  To install it:

     M-x package-install RET gnosis RET

   Or with ‘use-package’:

     (use-package gnosis
       :ensure t)


File: gnosis.info,  Node: Installing with GNU Guix,  Next: Basic Configuration,  Prev: Installing from GNU ELPA,  Up: Installation and Setup

2.3 Installing with GNU Guix
============================

Gnosis is available from the official Guix channel:

     guix install emacs-gnosis

   For development, the repository includes a ‘guix.scm’ that mirrors
the upstream recipe but builds from the local checkout:

     # Development shell with all dependencies:
     guix shell -D -f guix.scm

     # One-shot install from the working tree:
     guix package -f guix.scm

   To use gnosis from a Guix Home configuration, load the package
definition and reference it from your services:

     (use-modules (gnu home)
                  (gnu home services)
                  (gnu home services guix)
                  (gnu services)
                  (guix channels)
                  (guix gexp))

     (define emacs-gnosis-git
       (load "/path/to/gnosis/guix.scm"))

     (home-environment
      (packages (list emacs-gnosis-git)))

   Re-run ‘guix home reconfigure’ after pulling new commits and the
package will be rebuilt from the updated checkout.


File: gnosis.info,  Node: Basic Configuration,  Next: Key Directories,  Prev: Installing with GNU Guix,  Up: Installation and Setup

2.4 Basic Configuration
=======================

The minimal configuration requires only specifying where gnosis should
store its files.  All directories are created automatically on first
use.

     (use-package gnosis
       :ensure t
       :custom
       ;; Directory for the gnosis database and related files.
       ;; Defaults to ~/.emacs.d/gnosis/
       (gnosis-dir "~/gnosis/")

       ;; Directory where node (note) files are stored.
       ;; Defaults to ~/Notes/
       (gnosis-nodes-dir "~/Notes/")

       ;; Directory for journal files. Defaults to GNOSIS-NODES-DIR/journal/
       (gnosis-journal-dir "~/Notes/journal/"))


File: gnosis.info,  Node: Key Directories,  Next: Upgrading from org-gnosis,  Prev: Basic Configuration,  Up: Installation and Setup

2.5 Key Directories
===================

* Menu:

* gnosis-dir::
* gnosis-nodes-dir::
* gnosis-journal-dir::


File: gnosis.info,  Node: gnosis-dir,  Next: gnosis-nodes-dir,  Up: Key Directories

2.5.1 ‘gnosis-dir’
------------------

The gnosis data directory.  This is where ‘gnosis.db’ is stored.  It is
also the root used for version control when ‘gnosis-vc-auto-push’ is
enabled.  Defaults to ‘{user-emacs-directory}/gnosis/’.

     (setopt gnosis-dir (expand-file-name "gnosis/" user-emacs-directory))


File: gnosis.info,  Node: gnosis-nodes-dir,  Next: gnosis-journal-dir,  Prev: gnosis-dir,  Up: Key Directories

2.5.2 ‘gnosis-nodes-dir’
------------------------

The directory containing your note files.  All ‘.org’ and ‘.org.gpg’
files in this directory are indexed by gnosis.  Defaults to ‘~/Notes/’.

     (setopt gnosis-nodes-dir "~/Notes/")


File: gnosis.info,  Node: gnosis-journal-dir,  Prev: gnosis-nodes-dir,  Up: Key Directories

2.5.3 ‘gnosis-journal-dir’
--------------------------

The directory for journal entry files.  Defaults to a ‘journal/’
subdirectory inside ‘gnosis-nodes-dir’.  Journal files are indexed
separately from regular nodes but use the same underlying mechanism.

     (setopt gnosis-journal-dir (expand-file-name "journal/" gnosis-nodes-dir))


File: gnosis.info,  Node: Upgrading from org-gnosis,  Next: Version Control,  Prev: Key Directories,  Up: Installation and Setup

2.6 Upgrading from org-gnosis
=============================

If you previously used org-gnosis as a separate package, gnosis
automatically imports your org-gnosis database when it first detects the
old data.  No manual action is required beyond installing the new
version.


File: gnosis.info,  Node: Version Control,  Next: Completing Read Integration,  Prev: Upgrading from org-gnosis,  Up: Installation and Setup

2.7 Version Control
===================

Gnosis can automatically push your database to a remote Git repository
after each review session.  This is controlled by ‘gnosis-vc-auto-push’.

     (setopt gnosis-vc-auto-push t)

   When this is ‘t’, gnosis pushes ‘gnosis-dir’ at the end of every
review session.  To use this, initialize ‘gnosis-dir’ as a Git
repository and configure a remote before enabling this option.


File: gnosis.info,  Node: Completing Read Integration,  Next: Full Example Configuration,  Prev: Version Control,  Up: Installation and Setup

2.8 Completing Read Integration
===============================

Gnosis respects your preferred completion framework.  The
‘gnosis-completing-read-function’ variable defaults to ‘completing-read’
when Vertico, Ivy, Helm, or fido-mode is detected, and to
‘ido-completing-read’ otherwise.

     ;; Explicitly set if auto-detection does not work for your setup:
     (setopt gnosis-completing-read-function #'completing-read)


File: gnosis.info,  Node: Full Example Configuration,  Prev: Completing Read Integration,  Up: Installation and Setup

2.9 Full Example Configuration
==============================

     (use-package gnosis
       :ensure t
       :custom
       (gnosis-dir "~/gnosis/")
       (gnosis-nodes-dir "~/Notes/")
       (gnosis-journal-dir "~/Notes/journal/")
       (gnosis-vc-auto-push nil)
       (gnosis-center-content-during-review t)
       (gnosis-review-new-first t)
       (gnosis-new-themata-limit nil))


File: gnosis.info,  Node: Nodes (1),  Next: Journal,  Prev: Installation and Setup,  Up: Top

3 Nodes
*******

Nodes are gnosis's note-taking system.  A node is an org-mode heading
(or an entire org file) that has been assigned an org ID.  Gnosis
indexes all nodes in its database, enabling fast search, tag-based
browsing, backlink navigation, and linking from themata.

   The node system is deliberately minimal.  Files live on disk as plain
org-mode files, readable and editable without gnosis.  The database is a
derived index that can be rebuilt at any time from the files themselves.

* Menu:

* What Makes an Org Heading a Node::
* Creating and Finding Nodes::
* File Naming::
* Displaying Tags in Completion::
* Templates::
* Automatic Sync::
* Links Between Nodes::
* Backlinks::
* Tags::


File: gnosis.info,  Node: What Makes an Org Heading a Node,  Next: Creating and Finding Nodes,  Up: Nodes (1)

3.1 What Makes an Org Heading a Node
====================================

Any org-mode heading that has an ‘:ID:’ property becomes a node.  The
file-level title (expressed with ‘#+title:’) paired with a file-level ID
also constitutes a node.  Gnosis assigns UUIDs using ‘org-id-get-create’
when it creates a new file.

   A file may contain multiple nodes if multiple headings carry IDs.  In
that case, gnosis tracks the hierarchy: a heading's title is stored as
‘ParentTitle:ChildTitle’ to reflect its position in the outline.


File: gnosis.info,  Node: Creating and Finding Nodes,  Next: File Naming,  Prev: What Makes an Org Heading a Node,  Up: Nodes (1)

3.2 Creating and Finding Nodes
==============================

* Menu:

* gnosis-nodes-find::
* gnosis-nodes-find-by-tag::


File: gnosis.info,  Node: gnosis-nodes-find,  Next: gnosis-nodes-find-by-tag,  Up: Creating and Finding Nodes

3.2.1 ‘gnosis-nodes-find’
-------------------------

The primary command for opening a node is ‘gnosis-nodes-find’.  It
presents a completing-read prompt listing all known node titles.  Select
an existing title to open that node's file, positioned at the correct
heading.

   If you type a title that does not match any existing node, gnosis
creates a new file for it in ‘gnosis-nodes-dir’, prompts you to choose a
template, and opens the file in a new buffer.


File: gnosis.info,  Node: gnosis-nodes-find-by-tag,  Prev: gnosis-nodes-find,  Up: Creating and Finding Nodes

3.2.2 ‘gnosis-nodes-find-by-tag’
--------------------------------

To browse nodes by tag, use ‘gnosis-nodes-find-by-tag’.  It prompts for
a tag name drawn from existing tags, then presents all nodes carrying
that tag for selection.


File: gnosis.info,  Node: File Naming,  Next: Displaying Tags in Completion,  Prev: Creating and Finding Nodes,  Up: Nodes (1)

3.3 File Naming
===============

When gnosis creates a new node file, the filename is derived from the
node title.  By default, filenames are prefixed with a timestamp to
ensure uniqueness and to prevent collisions when two nodes share similar
titles.

* Menu:

* gnosis-nodes-timestring::
* GPG Encryption::


File: gnosis.info,  Node: gnosis-nodes-timestring,  Next: GPG Encryption,  Up: File Naming

3.3.1 ‘gnosis-nodes-timestring’
-------------------------------

This variable controls the timestamp prefix format.  It is a
‘format-time-string’ format string.  The default is ‘"%Y%m%d%H%M%S"’,
producing filenames like ‘20240315143022--My_Topic.org’.

   Set it to ‘nil’ to use the title alone as the filename, with no
timestamp prefix:

     ;; Use timestamp prefix (default):
     (setopt gnosis-nodes-timestring "%Y%m%d%H%M%S")

     ;; Use title only, no timestamp:
     (setopt gnosis-nodes-timestring nil)

   When ‘gnosis-nodes-timestring’ is ‘nil’ and a file with the same
title already exists, gnosis will ask whether you want to visit the
existing file or abort.


File: gnosis.info,  Node: GPG Encryption,  Prev: gnosis-nodes-timestring,  Up: File Naming

3.3.2 GPG Encryption
--------------------

Setting ‘gnosis-nodes-create-as-gpg’ to ‘t’ causes all new node files to
be created with a ‘.gpg’ suffix, triggering Emacs's built-in EasyPG
encryption on save.

     (setopt gnosis-nodes-create-as-gpg nil)  ; default

   This setting affects only newly created files; existing ‘.org’ files
are not retroactively encrypted.


File: gnosis.info,  Node: Displaying Tags in Completion,  Next: Templates,  Prev: File Naming,  Up: Nodes (1)

3.4 Displaying Tags in Completion
=================================

By default, the completing-read prompt for nodes displays only titles.
Set ‘gnosis-nodes-show-tags’ to ‘t’ to display each node's tags
alongside its title, rendered with the ‘gnosis-nodes-face-tags’ face.

     (setopt gnosis-nodes-show-tags t)

   Tags are displayed in the format ‘Title #tag1#tag2’ and are stripped
from the string before the title is used for lookup.


File: gnosis.info,  Node: Templates,  Next: Automatic Sync,  Prev: Displaying Tags in Completion,  Up: Nodes (1)

3.5 Templates
=============

When gnosis creates a new node, it optionally inserts template content
into the file.  Templates are configured via ‘gnosis-nodes-templates’.

* Menu:

* gnosis-nodes-templates::
* The {*} Heading Marker::
* Inserting a Template Manually::


File: gnosis.info,  Node: gnosis-nodes-templates,  Next: The {*} Heading Marker,  Up: Templates

3.5.1 ‘gnosis-nodes-templates’
------------------------------

This variable is an alist of ‘(NAME . FUNCTION)’ cons cells.  Each
function takes no arguments and returns a string that is inserted into
the new file after the initial ‘#+title:’ and ‘#+filetags:’ lines.

   You can use named functions or inline lambdas.  When using inline
lambdas, build the list with ‘list’ and ‘cons’ so the lambdas are
compiled under lexical-binding (a quoted ‘'(...)’ form leaves lambdas as
inert data):

     ;; Using named functions (recommended):
     (defun my/annotated-template ()
       (concat "{*} Summary\n\n"
               "{*} Notes\n\n"
               "{*} References\n"))

     (setopt gnosis-nodes-templates
             '(("Empty" . ignore)
               ("Annotated" . my/annotated-template)))

     ;; Using inline lambdas (note `list' / `cons'):
     (setopt gnosis-nodes-templates
             (list (cons "Empty" (lambda () ""))
                   (cons "Annotated"
                         (lambda ()
                           (concat "{*} Summary\n\n"
                                   "{*} Notes\n\n"
                                   "{*} References\n")))))


File: gnosis.info,  Node: The {*} Heading Marker,  Next: Inserting a Template Manually,  Prev: gnosis-nodes-templates,  Up: Templates

3.5.2 The ‘{*}’ Heading Marker
------------------------------

Template strings use ‘{*}’ as a placeholder for an org heading.  When
gnosis inserts a template, it expands each ‘{*}’ to the appropriate
number of asterisks for the context in which the template is being
inserted.  If you are inserting into a new top-level file, ‘{*}’ becomes
‘*’.  If you are inserting under an existing level-2 heading, ‘{*}’
becomes ‘***’.

   Use ‘{**}’ for a heading one level deeper than the base, ‘{***}’ for
two levels deeper, and so on.

   For example, the template string:

     {*} Key Ideas

     {**} Subpoint

   Inserted at the top level of a new file produces:

     * Key Ideas

     ** Subpoint

   Inserted under an existing ‘**’ heading produces:

     *** Key Ideas

     **** Subpoint


File: gnosis.info,  Node: Inserting a Template Manually,  Prev: The {*} Heading Marker,  Up: Templates

3.5.3 Inserting a Template Manually
-----------------------------------

Use ‘gnosis-nodes-insert-template’ to insert a template at point in an
existing buffer.  It detects whether the buffer is a journal file and
selects the appropriate template list automatically.


File: gnosis.info,  Node: Automatic Sync,  Next: Links Between Nodes,  Prev: Templates,  Up: Nodes (1)

3.6 Automatic Sync
==================

‘gnosis-nodes-mode’ is a minor mode that is automatically activated for
any org file located in ‘gnosis-nodes-dir’ or ‘gnosis-journal-dir’.
When this mode is active, saving the buffer updates that file's entries
in the database.

* Menu:

* Manual Sync::
* Force Rebuild::


File: gnosis.info,  Node: Manual Sync,  Next: Force Rebuild,  Up: Automatic Sync

3.6.1 Manual Sync
-----------------

To sync all files without waiting for saves, use ‘gnosis-nodes-db-sync’.
Called interactively without a prefix argument, it updates only files
that have changed since the last sync.  Called with a prefix argument
(‘C-u M-x gnosis-nodes-db-sync’), it purges all node entries and
rebuilds the database from scratch.

     ;; Sync only changed files:
     M-x gnosis-nodes-db-sync

     ;; Force full rebuild:
     C-u M-x gnosis-nodes-db-sync


File: gnosis.info,  Node: Force Rebuild,  Prev: Manual Sync,  Up: Automatic Sync

3.6.2 Force Rebuild
-------------------

‘gnosis-nodes-db-force-sync’ provides a dedicated command for the full
rebuild case, with a confirmation prompt before proceeding.


File: gnosis.info,  Node: Links Between Nodes,  Next: Backlinks,  Prev: Automatic Sync,  Up: Nodes (1)

3.7 Links Between Nodes
=======================

Gnosis uses standard org-mode ‘[[id:UUID][description]]’ link syntax for
linking between nodes.  When a file is synced, gnosis parses all id
links in the file and stores them as directed edges from source to
destination.

   To insert an id link to another node, use ‘gnosis-nodes-insert’.  It
prompts for a node title, looks up its UUID, and inserts an org-id link
at point.  If the named node does not yet exist, it is created.

     ;; Insert a node link at point:
     M-x gnosis-nodes-insert

     ;; With prefix arg, prompts for a custom link description:
     C-u M-x gnosis-nodes-insert

   If a region is active when ‘gnosis-nodes-insert’ is called, the
selected text is used as the link description.


File: gnosis.info,  Node: Backlinks,  Next: Tags,  Prev: Links Between Nodes,  Up: Nodes (1)

3.8 Backlinks
=============

‘gnosis-nodes-visit-backlinks’ shows all nodes that link to the current
node.  It presents the source node titles in a completing-read prompt
and visits the selected node.

   If no backlinks exist, it reports this with a message.


File: gnosis.info,  Node: Tags,  Prev: Backlinks,  Up: Nodes (1)

3.9 Tags
========

Tags in gnosis nodes come from two sources:

  1. *File-level tags*: The ‘#+filetags:’ keyword at the top of the org
     file.  These apply to the file-level node.
  2. *Heading-level tags*: Tags applied to individual org headings using
     standard org syntax (‘:tag:’ at the end of the heading line).
     These are inherited downward through the outline.

* Menu:

* Adding Tags::


File: gnosis.info,  Node: Adding Tags,  Up: Tags

3.9.1 Adding Tags
-----------------

Use ‘gnosis-nodes-insert-tags’ to add tags to the current node
interactively.  It presents a completing-read prompt supporting multiple
selections (separated by commas).  If the cursor is on a heading, the
tags are added to that heading; otherwise they are inserted as filetags.

   To add a single existing tag to the ‘#+filetags:’ line, use
‘gnosis-nodes-insert-filetag’.  The command completes against tags that
already exist in the database, which helps maintain consistent tag names
across notes.


File: gnosis.info,  Node: Journal,  Next: Themata (Spaced Repetition Cards),  Prev: Nodes (1),  Up: Top

4 Journal
*********

The journal module provides date-based entry creation with optional TODO
carry-forward and checkbox-to-done tracking.  Journal entries are
org-mode files (or headings within a single file) stored in
‘gnosis-journal-dir’.  They are indexed alongside nodes but in a
separate table.

* Menu:

* Creating Entries::
* File vs Single-File Mode::
* GPG Encryption: GPG Encryption (1).
* Templates: Templates (1).
* ``TODO'' Integration::
* Checked Item Tracking::
* Inserting Journal Links::
* Full Journal Configuration Example::


File: gnosis.info,  Node: Creating Entries,  Next: File vs Single-File Mode,  Up: Journal

4.1 Creating Entries
====================

* Menu:

* gnosis-journal::
* gnosis-journal-find::


File: gnosis.info,  Node: gnosis-journal,  Next: gnosis-journal-find,  Up: Creating Entries

4.1.1 ‘gnosis-journal’
----------------------

The quickest way to open today's journal entry is ‘gnosis-journal’.


File: gnosis.info,  Node: gnosis-journal-find,  Prev: gnosis-journal,  Up: Creating Entries

4.1.2 ‘gnosis-journal-find’
---------------------------

‘gnosis-journal-find’ accepts an optional title argument.  Called
interactively without arguments, it prompts for an existing or new
journal entry title via completing-read.  If the entry already exists,
gnosis opens it; if it does not, gnosis creates a new file (or heading,
in single-file mode) for it.


File: gnosis.info,  Node: File vs Single-File Mode,  Next: GPG Encryption (1),  Prev: Creating Entries,  Up: Journal

4.2 File vs Single-File Mode
============================

Gnosis supports two modes for journal storage:

* Menu:

* Separate Files (Default)::
* Single Journal File::


File: gnosis.info,  Node: Separate Files (Default),  Next: Single Journal File,  Up: File vs Single-File Mode

4.2.1 Separate Files (Default)
------------------------------

By default, each journal entry is its own file in ‘gnosis-journal-dir’.
File naming follows the same rules as nodes (timestamp prefix by
default, configurable via ‘gnosis-nodes-timestring’).

     ;; Default: separate files per entry
     (setopt gnosis-journal-file nil)


File: gnosis.info,  Node: Single Journal File,  Prev: Separate Files (Default),  Up: File vs Single-File Mode

4.2.2 Single Journal File
-------------------------

Setting ‘gnosis-journal-file’ to a file path causes all journal entries
to be added as top-level headings in that file.  Each entry is a ‘*
YYYY-MM-DD’ heading with an org ID.

     (setopt gnosis-journal-file "~/Notes/journal/journal.org")

   When this is set, gnosis creates the file if it does not exist,
adding an appropriate ‘#+title:’ and ‘#+filetags:’ header.  New entries
are appended at the end of the file.


File: gnosis.info,  Node: GPG Encryption (1),  Next: Templates (1),  Prev: File vs Single-File Mode,  Up: Journal

4.3 GPG Encryption
==================

Like nodes, journal files can be created with a ‘.gpg’ suffix.  The
option ‘gnosis-journal-as-gpg’ controls this independently from
‘gnosis-nodes-create-as-gpg’.

     (setopt gnosis-journal-as-gpg nil)  ; default


File: gnosis.info,  Node: Templates (1),  Next: ``TODO'' Integration,  Prev: GPG Encryption (1),  Up: Journal

4.4 Templates
=============

Journal templates follow the same mechanism as node templates.  They are
configured via ‘gnosis-journal-templates’.

* Menu:

* gnosis-journal-templates::


File: gnosis.info,  Node: gnosis-journal-templates,  Up: Templates (1)

4.4.1 ‘gnosis-journal-templates’
--------------------------------

     (setopt gnosis-journal-templates
             (list (cons "Default"
                         (lambda ()
                           (concat "{*} Daily Notes\n\n"
                                   "{*} Goals\n"
                                   (gnosis-journal-todos))))
                   (cons "Empty" (lambda () ""))))

   The default template calls ‘gnosis-journal-todos’, which produces a
checkbox list of any TODO items from ‘gnosis-journal-todo-files’ that
are due today (or have no scheduled date).  The ‘{*}’ heading marker
works exactly as in node templates.


File: gnosis.info,  Node: ``TODO'' Integration,  Next: Checked Item Tracking,  Prev: Templates (1),  Up: Journal

4.5 "TODO" Integration
======================

The journal module can pull TODO items from your org agenda files into
each journal entry as checkboxes.  This provides a daily task list drawn
automatically from your existing TODO state.

* Menu:

* gnosis-journal-todo-files::
* gnosis-journal-todo-keywords::
* Bullet Point Character::
* How TODO Carry-Forward Works::


File: gnosis.info,  Node: gnosis-journal-todo-files,  Next: gnosis-journal-todo-keywords,  Up: ``TODO'' Integration

4.5.1 ‘gnosis-journal-todo-files’
---------------------------------

The list of org files from which TODOs are pulled.  Defaults to
‘org-agenda-files’.

     (setopt gnosis-journal-todo-files org-agenda-files)


File: gnosis.info,  Node: gnosis-journal-todo-keywords,  Next: Bullet Point Character,  Prev: gnosis-journal-todo-files,  Up: ``TODO'' Integration

4.5.2 ‘gnosis-journal-todo-keywords’
------------------------------------

The TODO keywords recognized when scanning files.  Defaults to
‘org-todo-keywords’.  Keywords that appear after the vertical bar ‘|’
(which in standard org convention separates active from done states) are
ignored.

     (setopt gnosis-journal-todo-keywords org-todo-keywords)


File: gnosis.info,  Node: Bullet Point Character,  Next: How TODO Carry-Forward Works,  Prev: gnosis-journal-todo-keywords,  Up: ``TODO'' Integration

4.5.3 Bullet Point Character
----------------------------

The character used to introduce each TODO checkbox in the journal
template output is configured via ‘gnosis-journal-bullet-point-char’.
It defaults to ‘+’, which org-mode renders as a plain-list item.

     (setopt gnosis-journal-bullet-point-char "+")


File: gnosis.info,  Node: How TODO Carry-Forward Works,  Prev: Bullet Point Character,  Up: ``TODO'' Integration

4.5.4 How TODO Carry-Forward Works
----------------------------------

When a journal entry's template is applied, ‘gnosis-journal-todos’ scans
‘gnosis-journal-todo-files’ for headings whose TODO keyword matches an
active keyword from ‘gnosis-journal-todo-keywords’.  It includes items
that either have no scheduled date or are scheduled for today.  Each
included item is rendered as a checkbox line:

     + [ ] Write documentation
     + [ ] Review pull requests


File: gnosis.info,  Node: Checked Item Tracking,  Next: Inserting Journal Links,  Prev: ``TODO'' Integration,  Up: Journal

4.6 Checked Item Tracking
=========================

When you mark a checkbox in a journal entry as done (‘[x]’) and save the
buffer, gnosis identifies all checked items, finds the corresponding
TODO headings in ‘gnosis-journal-todo-files’ by title, and marks them as
‘DONE’.  It also records a ‘LAST_DONE_DATE’ property on the heading so
that the same item is not marked done twice in one day.

   In single-file mode (‘gnosis-journal-file’ non-nil), gnosis restricts
checked-item lookup to the section of the file corresponding to today's
date heading.


File: gnosis.info,  Node: Inserting Journal Links,  Next: Full Journal Configuration Example,  Prev: Checked Item Tracking,  Up: Journal

4.7 Inserting Journal Links
===========================

From within any gnosis buffer, you can insert an org-id link to a
journal entry using ‘gnosis-journal-insert’.  It works identically to
‘gnosis-nodes-insert’ but queries journal entries instead of nodes.


File: gnosis.info,  Node: Full Journal Configuration Example,  Prev: Inserting Journal Links,  Up: Journal

4.8 Full Journal Configuration Example
======================================

     (use-package gnosis
       :ensure t
       :custom
       ;; Journal in separate files (default):
       (gnosis-journal-file nil)
       (gnosis-journal-dir "~/Notes/journal/")
       (gnosis-journal-as-gpg nil)
       (gnosis-journal-bullet-point-char "+")
       (gnosis-journal-todo-files org-agenda-files)
       (gnosis-journal-todo-keywords org-todo-keywords)
       (gnosis-journal-templates
        (list (cons "Default"
                    (lambda ()
                      (concat "{*} Daily Notes\n\n"
                              "{*} Goals\n"
                              (gnosis-journal-todos))))
              (cons "Empty" (lambda () "")))))


File: gnosis.info,  Node: Themata (Spaced Repetition Cards),  Next: Review System,  Prev: Journal,  Up: Top

5 Themata (Spaced Repetition Cards)
***********************************

Gnosis organises all review material into units called _themata_
(singular: _thema_).  The word is Greek for "that which is placed" or "a
topic set before you," and a thema in gnosis is precisely that: a
question or prompt placed before you for recall.  Each thema carries its
own review history, scheduling state, and algorithm parameters.

* Menu:

* Fields of a Thema::
* Thema Types::
* Creating Themata::
* Editing Themata::
* Tags on Themata::
* The Link Between Themata and Nodes::
* Suspending Themata::


File: gnosis.info,  Node: Fields of a Thema,  Next: Thema Types,  Up: Themata (Spaced Repetition Cards)

5.1 Fields of a Thema
=====================

Every thema shares a common set of fields:

   • *keimenon* (_κείμενον_, "underlying text"): The question, prompt,
     or sentence context.  This is what the user sees first during
     review.
   • *hypothesis* (_ὑπόθεσης_, "assumption"): Supporting material.  Its
     role differs by type: for MCQ it holds the list of answer choices,
     for basic it holds an optional hint, and for cloze and mc-cloze it
     holds hints corresponding to each gap.
   • *answer*: The correct answer or list of cloze gaps.
   • *parathema* (_παράθεμα_, side-text): supplementary text shown after
     answering, used to add context or a longer explanation.
   • *tags*: A list of strings for organising themata and applying
     per-tag algorithm customisation.
   • *links*: Node IDs extracted from ‘[[id:...]]’ org-links present in
     the keimenon or parathema.  Used for topic-based review.


File: gnosis.info,  Node: Thema Types,  Next: Creating Themata,  Prev: Fields of a Thema,  Up: Themata (Spaced Repetition Cards)

5.2 Thema Types
===============

Gnosis provides five thema types:

* Menu:

* Basic::
* Double::
* MCQ (Multiple Choice Question)::
* Cloze::
* MC-cloze (Multiple Choice Cloze)::


File: gnosis.info,  Node: Basic,  Next: Double,  Up: Thema Types

5.2.1 Basic
-----------

A straightforward question and answer.  The keimenon is the question;
the answer is a single string.  An optional hypothesis serves as a hint
displayed before the user types their response.  The comparison is
case-insensitive and allows for a small Levenshtein distance, controlled
by ‘gnosis-string-difference’.


File: gnosis.info,  Node: Double,  Next: MCQ (Multiple Choice Question),  Prev: Basic,  Up: Thema Types

5.2.2 Double
------------

A convenience type that creates *two* basic themata from a single
definition: one in the forward direction (keimenon -> answer) and one in
reverse (answer -> keimenon).  Both cards are stored independently and
scheduled separately.


File: gnosis.info,  Node: MCQ (Multiple Choice Question),  Next: Cloze,  Prev: Double,  Up: Thema Types

5.2.3 MCQ (Multiple Choice Question)
------------------------------------

The keimenon is the question.  The hypothesis holds a list of answer
options (at least two) shuffled on each review.  The answer is a single
string that must be one of the hypothesis options.  The user selects
from the completion interface rather than typing freely.


File: gnosis.info,  Node: Cloze,  Next: MC-cloze (Multiple Choice Cloze),  Prev: MCQ (Multiple Choice Question),  Up: Thema Types

5.2.4 Cloze
-----------

A fill-in-the-blank type.  The keimenon is a sentence with one or more
gaps to fill.  Gnosis supports standard Anki-style cloze notation:

     The capital of {{c1::Greece}} is one of the oldest cities in the world.
     {{c1::Athens}} was named after {{c2::Athena}}.

   Each ‘c1’, ‘c2’, etc.  group is extracted into a separate thema.  The
user must supply each gap in turn; a wrong answer on any gap fails the
whole thema.  Hints can be embedded after a double colon:
‘{{c1::Athens::city}}’.


File: gnosis.info,  Node: MC-cloze (Multiple Choice Cloze),  Prev: Cloze,  Up: Thema Types

5.2.5 MC-cloze (Multiple Choice Cloze)
--------------------------------------

Like cloze, but the user selects the correct word from a list of
candidates (the hypothesis) rather than typing it.  Only a single gap is
supported per thema.  The answer must appear verbatim in the sentence.


File: gnosis.info,  Node: Creating Themata,  Next: Editing Themata,  Prev: Thema Types,  Up: Themata (Spaced Repetition Cards)

5.3 Creating Themata
====================

Use ‘M-x gnosis-add-thema’ to create a new thema interactively.  The
command first prompts for the type, then opens a dedicated edit buffer
(‘*Gnosis NEW*’) pre-populated with a template for the selected type.

   Inside the edit buffer, use ‘C-c C-c’ to save, ‘C-c C-q’ to add tags,
‘C-c C-o’ to follow an org-id link, or ‘C-c C-k’ to quit without saving.


File: gnosis.info,  Node: Editing Themata,  Next: Tags on Themata,  Prev: Creating Themata,  Up: Themata (Spaced Repetition Cards)

5.4 Editing Themata
===================

To edit an existing thema, use ‘M-x gnosis-edit-thema’ or press ‘e’
during a review session.  The same edit buffer is used, this time
populated with the existing values.  Saving updates the record in place,
re-synchronising both tags and node links.


File: gnosis.info,  Node: Tags on Themata,  Next: The Link Between Themata and Nodes,  Prev: Editing Themata,  Up: Themata (Spaced Repetition Cards)

5.5 Tags on Themata
===================

Tags are free-form strings that serve two purposes:

  1. *Organisation*: Filter themata during review by including or
     excluding tags (see *note Review System::).
  2. *Algorithm customisation*: Override the default spaced repetition
     parameters for all themata carrying a given tag (see *note The
     Algorithm::).

   During thema creation or editing, press ‘C-c C-q’ in the edit buffer
to add tags interactively using completion against existing tags.


File: gnosis.info,  Node: The Link Between Themata and Nodes,  Next: Suspending Themata,  Prev: Tags on Themata,  Up: Themata (Spaced Repetition Cards)

5.6 The Link Between Themata and Nodes
======================================

When a keimenon or parathema contains an org-mode id link of the form
‘[[id:NODE-UUID][description]]’, gnosis extracts the UUID and records
the association.

   This linking means:

   • Reviewing by topic (‘gnosis-review-topic’) fetches all themata
     linked to a given node.
   • Viewing a linked node during review navigates directly to the
     relevant note.
   • The dashboard can show which themata are associated with which
     nodes.

   Links are re-synchronised on every edit: the old links are cleared
and the current links are re-inserted from the saved content.


File: gnosis.info,  Node: Suspending Themata,  Prev: The Link Between Themata and Nodes,  Up: Themata (Spaced Repetition Cards)

5.7 Suspending Themata
======================

A suspended thema is excluded from all regular review sessions.
Suspended themata remain in the database and can be unsuspended at any
time, either through the review interface or the dashboard.


File: gnosis.info,  Node: Review System,  Next: The Algorithm,  Prev: Themata (Spaced Repetition Cards),  Up: Top

6 Review System
***************

The review system is the mechanism through which themata are presented
to the user, evaluated, and then fed back into the spaced repetition
algorithm.  All review activity is recorded and optionally committed to
a Git repository for version control.

* Menu:

* Starting a Review Session::
* Tag Filtering::
* The Review Flow::
* Type-Specific Review Behaviour::
* Node-Based Review::
* Activity Logging::
* Monkeytype::
* Sample Configuration::


File: gnosis.info,  Node: Starting a Review Session,  Next: Tag Filtering,  Up: Review System

6.1 Starting a Review Session
=============================

Call ‘M-x gnosis-review’ to open the review transient menu.  The menu
presents several review modes:

   • *Due themata*: All due and new themata, looping until none remain.
   • *Due themata of tag(s)*: Due themata filtered by +include/-exclude
     tags.
   • *Overdue themata*: Only themata whose scheduled date has passed
     (excludes never-reviewed themata).
   • *Due without overdue*: Today's due themata, excluding overdue ones.
   • *All themata of tag(s)*: All themata for selected tags, ignoring
     due status.
   • *Review node*: All themata linked to a specific node topic.

   New themata (never reviewed) are interleaved with due ones.  By
default they are shown first; set ‘gnosis-review-new-first’ to ‘nil’ to
review them last.  The number of new themata presented per session can
be capped with ‘gnosis-new-themata-limit’.


File: gnosis.info,  Node: Tag Filtering,  Next: The Review Flow,  Prev: Starting a Review Session,  Up: Review System

6.2 Tag Filtering
=================

When reviewing by tag, gnosis prompts for tags using
‘completing-read-multiple’.  Each entry is prefixed with ‘+’ to include
or ‘-’ to exclude:

     Filter tags (+include -exclude): +biology -advanced

   This selects all themata tagged ‘biology’ that are not also tagged
‘advanced’.


File: gnosis.info,  Node: The Review Flow,  Next: Type-Specific Review Behaviour,  Prev: Tag Filtering,  Up: Review System

6.3 The Review Flow
===================

For each thema in the session, gnosis proceeds through the following
stages:

  1. *Display*: The keimenon is rendered in the ‘*gnosis*’ buffer.  If
     the keimenon contains a ‘[[file:...]]’ image link, the image is
     opened in a secondary window.  Content is centred by default
     (controlled by ‘gnosis-center-content-during-review’).

  2. *Input*: The user provides an answer.  The exact mechanism depends
     on the thema type.

  3. *Feedback*: The answer is evaluated and the result is displayed
     alongside the correct answer, the user's input (when wrong), and
     the parathema if one is present.

  4. *Next review date*: The algorithm computes and displays the next
     scheduled review date.

  5. *Action prompt*: The user chooses what to do next via a
     one-character prompt.  Available actions include advancing to the
     next thema, overriding the result (useful when the user typed a
     valid alternative answer), suspending or deleting the thema,
     editing the thema, viewing linked nodes, or quitting the session.

  6. *Algorithm update*: After the user confirms the result, the review
     log and gnosis score are updated.

   During a session, the header line shows the current progress as
‘Reviewed: N/Total’.


File: gnosis.info,  Node: Type-Specific Review Behaviour,  Next: Node-Based Review,  Prev: The Review Flow,  Up: Review System

6.4 Type-Specific Review Behaviour
==================================

* Menu:

* Basic: Basic (1).
* MCQ::
* Cloze: Cloze (1).
* MC-cloze::


File: gnosis.info,  Node: Basic (1),  Next: MCQ,  Up: Type-Specific Review Behaviour

6.4.1 Basic
-----------

The keimenon and optional hint are displayed.  The user types a
free-form answer into the minibuffer.  The comparison is
case-insensitive and accounts for a small edit distance
(‘gnosis-string-difference’).  If the answer uses a non-Latin script,
gnosis activates the appropriate input method from
‘gnosis-script-input-method-alist’.


File: gnosis.info,  Node: MCQ,  Next: Cloze (1),  Prev: Basic (1),  Up: Type-Specific Review Behaviour

6.4.2 MCQ
---------

The keimenon is displayed.  The user selects one of the shuffled
hypothesis options via completion.  Both the correct answer and the
user's choice are shown side by side.


File: gnosis.info,  Node: Cloze (1),  Next: MC-cloze,  Prev: MCQ,  Up: Type-Specific Review Behaviour

6.4.3 Cloze
-----------

The keimenon is displayed with each gap replaced by the placeholder
‘(...)’.  The user types each answer in turn.  On a correct guess, that
gap is revealed and the next is presented.  On a wrong answer, all
remaining gaps are highlighted and the card is marked as failed.


File: gnosis.info,  Node: MC-cloze,  Prev: Cloze (1),  Up: Type-Specific Review Behaviour

6.4.4 MC-cloze
--------------

The keimenon is displayed with the single gap replaced.  The user
selects the correct word from a shuffled list via completion.


File: gnosis.info,  Node: Node-Based Review,  Next: Activity Logging,  Prev: Type-Specific Review Behaviour,  Up: Review System

6.5 Node-Based Review
=====================

‘gnosis-review-topic’ reviews all themata linked to a chosen node.  With
a prefix argument, gnosis additionally prompts for forward and backward
link depths, allowing review of nodes reachable through the link graph:

     C-u M-x gnosis-review-topic RET
     Forward link depth: 1 RET
     Backlink depth: 0 RET

   This lets you review not just the selected node's themata, but also
those of related nodes at the specified distance in the knowledge graph.


File: gnosis.info,  Node: Activity Logging,  Next: Monkeytype,  Prev: Node-Based Review,  Up: Review System

6.6 Activity Logging
====================

Every reviewed thema increments a daily activity counter, recording
total and new themata reviewed per day.  This data drives the
dashboard's streak display.  To clear the log, call ‘M-x
gnosis-history-clear’.


File: gnosis.info,  Node: Monkeytype,  Next: Sample Configuration,  Prev: Activity Logging,  Up: Review System

6.7 Monkeytype
==============

After a failed review, gnosis can present the correct answer as a typing
exercise.  The user types character by character; correct characters are
highlighted in green, and backspace is disabled.  Upon completion, the
words-per-minute figure is displayed.

   Controlled by ‘gnosis-monkeytype-enable’ (default: ‘t’).  Restrict to
specific types via ‘gnosis-monkeytype-themata’:

     (use-package gnosis
       :config
       ;; Disable monkeytype entirely.
       (setq gnosis-monkeytype-enable nil)

       ;; Or restrict to cloze cards only.
       (setq gnosis-monkeytype-themata '("cloze")))


File: gnosis.info,  Node: Sample Configuration,  Prev: Monkeytype,  Up: Review System

6.8 Sample Configuration
========================

     (use-package gnosis
       :config
       (setq gnosis-review-new-first nil)
       (setq gnosis-new-themata-limit 20)
       (setq gnosis-center-content-during-review nil)
       (setq gnosis-vc-auto-push t))


File: gnosis.info,  Node: The Algorithm,  Next: Dashboard,  Prev: Review System,  Up: Top

7 The Algorithm
***************

Gnosis uses a modified spaced repetition algorithm inspired by SM-2 but
with distinct vocabulary and several extensions for fine-grained
control.

* Menu:

* Overview::
* The Gnosis Score Triplet::
* Proto Phase::
* Interval Calculation::
* Anagnosis Events::
* Lethe::
* Fuzz::
* Day Boundary::
* Per-Tag Algorithm Customisation::
* All Algorithm Variables::


File: gnosis.info,  Node: Overview,  Next: The Gnosis Score Triplet,  Up: The Algorithm

7.1 Overview
============

The core idea is that every successful recall increases the interval
before the next review, while every failure decreases it.  The rate of
growth and decay is governed by a per-thema _gnosis score_, which itself
adapts over time based on review history.

   Gnosis uses actual elapsed time (days since the last review) rather
than the scheduled interval when computing the next interval.  This
rewards successful recall after longer delays.


File: gnosis.info,  Node: The Gnosis Score Triplet,  Next: Proto Phase,  Prev: Overview,  Up: The Algorithm

7.2 The Gnosis Score Triplet
============================

Each thema carries a gnosis score stored as a list of three values:

     (gnosis-plus  gnosis-minus  gnosis-synolon)

   • *gnosis-plus*: How much ‘gnosis-synolon’ grows on success.  Itself
     grows via _anagnosis_ events.  Default: ‘0.35’.
   • *gnosis-minus*: How much ‘gnosis-synolon’ shrinks on failure.
     Grows via anagnosis events on failures.  Default: ‘0.30’.
   • *gnosis-synolon* (_synolon_, "total"): The interval multiplier.  On
     success, next interval = ‘synolon * elapsed-time’.  Capped at
     ‘gnosis-algorithm-synolon-max’ (default 3.0), floored at 1.3.

     ;; Default: plus=0.35, minus=0.30, synolon=1.3
     (setq gnosis-algorithm-gnosis-value '(0.35 0.30 1.3))


File: gnosis.info,  Node: Proto Phase,  Next: Interval Calculation,  Prev: The Gnosis Score Triplet,  Up: The Algorithm

7.3 Proto Phase
===============

New themata go through a _proto_ phase with fixed intervals before the
standard algorithm applies:

     ;; Default: 0, 1, 2 days for the first 3 successes.
     (setq gnosis-algorithm-proto '(0 1 2))

   After exhausting the proto list, the algorithm switches to the
standard ‘synolon * elapsed-time’ calculation.  Failing a review during
the proto phase always resets the interval to 0 (due again today),
regardless of elapsed time.


File: gnosis.info,  Node: Interval Calculation,  Next: Anagnosis Events,  Prev: Proto Phase,  Up: The Algorithm

7.4 Interval Calculation
========================

On a *successful* review:

     next-interval = round(fuzz(gnosis-synolon * elapsed-time))

   The computed date is compared to the previously scheduled date, and
the *later* of the two is kept, preventing early reviews from deflating
intervals.

   On a *failed* review:

     failure-factor = 1 - gnosis-algorithm-amnesia-value
     next-interval  = round(fuzz(failure-factor * elapsed-time))

     ;; Default: 0.5 -- interval halved on failure.
     (setq gnosis-algorithm-amnesia-value 0.5)


File: gnosis.info,  Node: Anagnosis Events,  Next: Lethe,  Prev: Interval Calculation,  Up: The Algorithm

7.5 Anagnosis Events
====================

_Anagnosis_ (_ἀνάγνωσις_, "recognition") events fire when consecutive
successes or failures reach a threshold, permanently adjusting the
gnosis-plus or gnosis-minus values.

     ;; Fire every 3 consecutive successes or failures.
     (setq gnosis-algorithm-anagnosis-value 3)

     ;; Increase gnosis-plus by 0.1 on success anagnosis.
     (setq gnosis-algorithm-epignosis-value 0.1)

     ;; Increase gnosis-minus by 0.2 on failure anagnosis.
     (setq gnosis-algorithm-agnoia-value 0.2)

   A thema you keep getting right will grow its intervals faster over
time; one you keep failing will be penalised more harshly.


File: gnosis.info,  Node: Lethe,  Next: Fuzz,  Prev: Anagnosis Events,  Up: The Algorithm

7.6 Lethe
=========

_Lethe_ (the river of forgetfulness) resets the interval to zero when
consecutive failures reach or exceed the threshold, and reduces
gnosis-plus to slow future growth:

     ;; Default: reset on 2 consecutive failures.
     (setq gnosis-algorithm-lethe-value 2)


File: gnosis.info,  Node: Fuzz,  Next: Day Boundary,  Prev: Lethe,  Up: The Algorithm

7.7 Fuzz
========

Random variation applied to intervals to prevent review clustering:

     ;; Default: +/-10%. Set to 0 to disable.
     (setq gnosis-algorithm-interval-fuzz 0.1)

   Fuzz is not applied to intervals of 2 days or fewer.


File: gnosis.info,  Node: Day Boundary,  Next: Per-Tag Algorithm Customisation,  Prev: Fuzz,  Up: The Algorithm

7.8 Day Boundary
================

By default, a new review day begins at midnight.
‘gnosis-algorithm-day-start-hour’ shifts that boundary so that reviews
done in the small hours count as part of the previous calendar day:

     ;; Default: 0 (midnight).  Set to e.g. 6 to treat 00:00--05:59 as the
     ;; previous day.
     (setq gnosis-algorithm-day-start-hour 6)

   The variable accepts any integer from 0 to 23.  When set to 0 the
behaviour is identical to the default.  A non-zero value is useful for
reviewers who work late at night and want reviews completed after
midnight to be counted against the same day as the rest of their evening
session.

   _The setting affects all date-dependent logic_


File: gnosis.info,  Node: Per-Tag Algorithm Customisation,  Next: All Algorithm Variables,  Prev: Day Boundary,  Up: The Algorithm

7.9 Per-Tag Algorithm Customisation
===================================

‘gnosis-custom-values’ lets you override algorithm parameters for all
themata carrying a given tag:

     (use-package gnosis
       :config
       (setq gnosis-custom-values
             '(;; Strict scheduling for Greek vocabulary.
               (:tag "greek"
                     (:proto     (0 1 3 7)
                      :amnesia   0.6
                      :lethe     2
                      :anagnosis 4
                      :epignosis 0.15
                      :agnoia    0.25))

               ;; Lenient scheduling for programming concepts.
               (:tag "programming"
                     (:proto     (0 1)
                      :amnesia   0.4
                      :lethe     3
                      :anagnosis 2
                      :epignosis 0.2
                      :agnoia    0.15)))))

   When a thema carries multiple tags with overlapping parameters,
gnosis aggregates: for ‘:amnesia’, ‘:epignosis’, ‘:agnoia’ the maximum
is used; for ‘:anagnosis’, ‘:lethe’ the minimum is used; for ‘:proto’
the element-wise maximum.


File: gnosis.info,  Node: All Algorithm Variables,  Prev: Per-Tag Algorithm Customisation,  Up: The Algorithm

7.10 All Algorithm Variables
============================

Variable                             Default             Description
--------------------------------------------------------------------------------------------------------
‘gnosis-algorithm-proto’             ‘(0 1 2)’           Fixed intervals for the first N successes
‘gnosis-algorithm-gnosis-value’      ‘(0.35 0.30 1.3)’   Starting (plus minus synolon) score
‘gnosis-algorithm-amnesia-value’     ‘0.5’               Memory loss factor on failure (0 < x < 1)
‘gnosis-algorithm-epignosis-value’   ‘0.1’               gnosis-plus increment per success anagnosis
‘gnosis-algorithm-agnoia-value’      ‘0.2’               gnosis-minus increment per failure anagnosis
‘gnosis-algorithm-anagnosis-value’   ‘3’                 Consecutive review threshold for anagnosis
‘gnosis-algorithm-lethe-value’       ‘2’                 Consecutive failures before lethe reset
‘gnosis-algorithm-synolon-max’       ‘3.0’               Maximum value for the interval multiplier
‘gnosis-algorithm-interval-fuzz’     ‘0.1’               Fuzz fraction applied to intervals (0 = off)
‘gnosis-algorithm-day-start-hour’    ‘3’                 Hour (0-23) at which a new review day begins


File: gnosis.info,  Node: Dashboard,  Next: Export and Import,  Prev: The Algorithm,  Up: Top

8 Dashboard
***********

The dashboard is the central interface for browsing and managing
everything stored in gnosis.  It presents themata, nodes, and tags in
tabulated views with contextual transient menus.

* Menu:

* Opening the Dashboard::
* The Themata View::
* The Nodes View::
* The Tags View::


File: gnosis.info,  Node: Opening the Dashboard,  Next: The Themata View,  Up: Dashboard

8.1 Opening the Dashboard
=========================

     M-x gnosis-dashboard

   This opens the ‘*Gnosis Dashboard*’ buffer with a header showing your
review streak and today's statistics.  A transient menu opens
automatically, providing access to nodes, themata, review sessions,
export/import (‘e’ to export, ‘i’ to import), and database
synchronisation.


File: gnosis.info,  Node: The Themata View,  Next: The Nodes View,  Prev: Opening the Dashboard,  Up: Dashboard

8.2 The Themata View
====================

Lists all review items in a tabulated format, with columns for the
keimenon, hypothesis, answer, tags, type, and suspension status.

   From this view you can edit or delete individual themata, suspend
them, search or filter the list by content, filter by review count, and
use bulk operations on marked entries (bulk link replacement, suspend,
delete).  All actions are available through a transient menu.


File: gnosis.info,  Node: The Nodes View,  Next: The Tags View,  Prev: The Themata View,  Up: Dashboard

8.3 The Nodes View
==================

Lists org-mode knowledge nodes with connectivity metrics: forward link
count, backlink count, and the number of themata that reference each
node.

   From this view you can navigate the knowledge graph by following
forward links or backlinks from any node, see which themata reference a
node, find isolated nodes with no connections, open a node's org file,
or start a review of all themata linked to a node (optionally specifying
link depth to include related nodes).

   Each navigation action pushes the current view onto a history stack,
so you can step back through your browsing path.

     (use-package gnosis
       :config
       (setopt gnosis-dashboard-nodes-default-sort-column "Backlinks")
       (setopt gnosis-dashboard-nodes-default-sort-ascending nil))


File: gnosis.info,  Node: The Tags View,  Prev: The Nodes View,  Up: Dashboard

8.4 The Tags View
=================

Lists every tag with a count of associated themata.  From this view you
can open the themata view filtered to a specific tag, rename tags,
suspend all themata carrying a tag, or delete a tag from all themata.


File: gnosis.info,  Node: Export and Import,  Next: Link Health and Maintenance,  Prev: Dashboard,  Up: Top

9 Export and Import
*******************

Gnosis exports and imports themata using SQLite database files
(‘.gnosis’ extension).  This is faster and more reliable than text-based
formats, especially for large collections.

* Menu:

* Exporting::
* Importing::
* The Export Format::
* Editing Themata (Org Format)::
* Importing from Anki::


File: gnosis.info,  Node: Exporting,  Next: Importing,  Up: Export and Import

9.1 Exporting
=============

     M-x gnosis-export-db

   When called interactively, you are asked for:

  1. Tag filters using +/- notation.
  2. The output file path (defaults to ‘gnosis-export.gnosis’).
  3. Whether to include suspended themata.

   The export uses ‘ATTACH DATABASE’ to write directly from your main
database to the export file, making it efficient even for large
collections.

* Menu:

* Tag Filter Notation::
* Programmatic Use::


File: gnosis.info,  Node: Tag Filter Notation,  Next: Programmatic Use,  Up: Exporting

9.1.1 Tag Filter Notation
-------------------------

Each candidate is prefixed with ‘+’ (include) or ‘-’ (exclude):

     Filter tags (+include -exclude): +greek -draft

   When no ‘+’ entries are chosen, the export starts from all themata
and applies only exclusions.


File: gnosis.info,  Node: Programmatic Use,  Prev: Tag Filter Notation,  Up: Exporting

9.1.2 Programmatic Use
----------------------

     (gnosis-export-db "~/backups/greek.gnosis"
                       '("greek") '("draft"))


File: gnosis.info,  Node: Importing,  Next: The Export Format,  Prev: Exporting,  Up: Export and Import

9.2 Importing
=============

     M-x gnosis-import-db

   Opens a diff review buffer showing NEW and CHANGED entries before
applying any changes.  From this buffer:

   • ‘RET’: View detailed field-by-field comparison for the entry at
     point.
   • ‘a’: Apply all changes (inserts new themata, updates changed ones).
   • ‘q’: Quit without applying.
   • ‘?’ / ‘h’: Open the transient help menu.

   New themata receive initialised review state (due immediately).
Changed themata have their content and tags updated without affecting
review history.  After applying, the database is committed to Git.


File: gnosis.info,  Node: The Export Format,  Next: Editing Themata (Org Format),  Prev: Importing,  Up: Export and Import

9.3 The Export Format
=====================

The ‘.gnosis’ file is a plain SQLite database with four tables:
‘themata’, ‘thema_tag’, ‘extras’, and ‘gnosis_meta’.  Values use emacsql
encoding (Lisp values serialized with ‘prin1-to-string’).


File: gnosis.info,  Node: Editing Themata (Org Format),  Next: Importing from Anki,  Prev: The Export Format,  Up: Export and Import

9.4 Editing Themata (Org Format)
================================

The org-based format is still used for the ‘*Gnosis Edit*’ buffer when
editing individual themata (‘M-x gnosis-edit-thema’ or ‘e’ during
review).  The ‘:GNOSIS_TYPE:’ property is editable; the type is
validated on save against ‘gnosis-thema-types’.


File: gnosis.info,  Node: Importing from Anki,  Prev: Editing Themata (Org Format),  Up: Export and Import

9.5 Importing from Anki
=======================

Gnosis can import Anki collections and decks directly:

     M-x gnosis-import-anki

   The command auto-detects the file format by extension:

   • ‘.apkg’: Anki deck package (extracted via ‘7z’, including modern
     zstd-compressed ‘.anki21b’ format)
   • ‘.anki2’ / ‘.anki21’: Anki collection database (opened directly)

   Supported note types:

   • *Basic* (and reversed): Imported as gnosis basic themata.
   • *Cloze*: Anki ‘{{c1::answer::hint}}’ syntax is converted to gnosis
     cloze themata.  Each cloze group becomes a separate thema.

   Image occlusion notes are skipped.

* Menu:

* What Gets Imported::
* What Does Not Transfer::
* Requirements: Requirements (1).


File: gnosis.info,  Node: What Gets Imported,  Next: What Does Not Transfer,  Up: Importing from Anki

9.5.1 What Gets Imported
------------------------

   • Question and answer fields (HTML converted to org-mode markup)
   • Tags (Anki hierarchical tags like ‘anatomy::upper_limb’ are split
     into individual tags: ‘anatomy’, ‘upper_limb’)
   • Parathema from extra fields (if the note model has more than 2
     fields)


File: gnosis.info,  Node: What Does Not Transfer,  Next: Requirements (1),  Prev: What Gets Imported,  Up: Importing from Anki

9.5.2 What Does Not Transfer
----------------------------

Review history, scheduling data, and deck organisation are not imported.
All imported themata start fresh with default algorithm values and are
due immediately.


File: gnosis.info,  Node: Requirements (1),  Prev: What Does Not Transfer,  Up: Importing from Anki

9.5.3 Requirements
------------------

   • ‘7z’ (p7zip) for ‘.apkg’ extraction
   • ‘zstd’ (optional, for modern ‘.anki21b’ format; ‘7z’ can also
     handle it)

   The import runs asynchronously in chunks of 200, keeping Emacs
responsive during large imports.


File: gnosis.info,  Node: Link Health and Maintenance,  Prev: Export and Import,  Up: Top

10 Link Health and Maintenance
******************************

Over time, links between themata and nodes can fall out of sync:

   • *Orphaned links*: destination node no longer exists.
   • *Stale links*: link recorded but no longer present in the thema
     text.
   • *Missing links*: link present in thema text but not recorded.

* Menu:

* Checking Link Health::
* Full Synchronisation::
* Syncing the Node Database::
* Version Control: Version Control (1).


File: gnosis.info,  Node: Checking Link Health,  Next: Full Synchronisation,  Up: Link Health and Maintenance

10.1 Checking Link Health
=========================

     M-x gnosis-links-check

   Reports a summary without modifying anything.


File: gnosis.info,  Node: Full Synchronisation,  Next: Syncing the Node Database,  Prev: Checking Link Health,  Up: Link Health and Maintenance

10.2 Full Synchronisation
=========================

     M-x gnosis-links-sync

   Removes orphaned and stale links, inserts missing ones.  Prompts for
confirmation with counts before making changes.


File: gnosis.info,  Node: Syncing the Node Database,  Next: Version Control (1),  Prev: Full Synchronisation,  Up: Link Health and Maintenance

10.3 Syncing the Node Database
==============================

     M-x gnosis-nodes-db-sync

   Walks all org files in ‘gnosis-nodes-dir’ and updates the database.
Changed files are re-parsed; unchanged files are skipped.  For a
complete rebuild:

     C-u M-x gnosis-nodes-db-sync


File: gnosis.info,  Node: Version Control (1),  Prev: Syncing the Node Database,  Up: Link Health and Maintenance

10.4 Version Control
====================

Gnosis automatically commits ‘gnosis.db’ to a Git repository inside
‘gnosis-dir’ after review sessions, migrations, and imports.  Enable
‘gnosis-vc-auto-push’ to push to a remote after each session:

     (setq gnosis-vc-auto-push t)


Tag Table:
Node: Top227
Node: Introduction3816
Node: Why Gnosis4682
Node: The Two Subsystems5639
Node: Nodes5879
Node: Themata6416
Node: The Link Between Nodes and Themata7555
Node: Greek Terminology Reference8200
Node: Data Storage9881
Node: Installation and Setup10324
Node: Requirements10718
Node: Installing from GNU ELPA11232
Node: Installing with GNU Guix11596
Node: Basic Configuration12760
Node: Key Directories13535
Node: gnosis-dir13781
Node: gnosis-nodes-dir14197
Node: gnosis-journal-dir14563
Node: Upgrading from org-gnosis15008
Node: Version Control15414
Node: Completing Read Integration15992
Node: Full Example Configuration16573
Node: Nodes (1)17085
Node: What Makes an Org Heading a Node17887
Node: Creating and Finding Nodes18546
Node: gnosis-nodes-find18803
Node: gnosis-nodes-find-by-tag19390
Node: File Naming19745
Node: gnosis-nodes-timestring20185
Node: GPG Encryption20983
Node: Displaying Tags in Completion21461
Node: Templates22031
Node: gnosis-nodes-templates22421
Node: The {*} Heading Marker23723
Node: Inserting a Template Manually24690
Node: Automatic Sync25068
Node: Manual Sync25499
Node: Force Rebuild26070
Node: Links Between Nodes26331
Node: Backlinks27209
Node: Tags27570
Node: Adding Tags28052
Node: Journal28656
Node: Creating Entries29313
Node: gnosis-journal29502
Node: gnosis-journal-find29721
Node: File vs Single-File Mode30187
Node: Separate Files (Default)30477
Node: Single Journal File30934
Node: GPG Encryption (1)31535
Node: Templates (1)31918
Node: gnosis-journal-templates32220
Node: ``TODO'' Integration32952
Node: gnosis-journal-todo-files33438
Node: gnosis-journal-todo-keywords33777
Node: Bullet Point Character34292
Node: How TODO Carry-Forward Works34766
Node: Checked Item Tracking35360
Node: Inserting Journal Links36062
Node: Full Journal Configuration Example36472
Node: Themata (Spaced Repetition Cards)37328
Node: Fields of a Thema38025
Node: Thema Types39107
Node: Basic39420
Node: Double39831
Node: MCQ (Multiple Choice Question)40198
Node: Cloze40648
Node: MC-cloze (Multiple Choice Cloze)41314
Node: Creating Themata41697
Node: Editing Themata42252
Node: Tags on Themata42686
Node: The Link Between Themata and Nodes43349
Node: Suspending Themata44177
Node: Review System44551
Node: Starting a Review Session45148
Node: Tag Filtering46180
Node: The Review Flow46644
Node: Type-Specific Review Behaviour48086
Node: Basic (1)48358
Node: MCQ48814
Node: Cloze (1)49113
Node: MC-cloze49520
Node: Node-Based Review49773
Node: Activity Logging50412
Node: Monkeytype50781
Node: Sample Configuration51535
Node: The Algorithm51891
Node: Overview52378
Node: The Gnosis Score Triplet52939
Node: Proto Phase53833
Node: Interval Calculation54429
Node: Anagnosis Events55091
Node: Lethe55876
Node: Fuzz56254
Node: Day Boundary56582
Node: Per-Tag Algorithm Customisation57409
Node: All Algorithm Variables58695
Node: Dashboard60116
Node: Opening the Dashboard60517
Node: The Themata View60981
Node: The Nodes View61547
Node: The Tags View62464
Node: Export and Import62793
Node: Exporting63246
Node: Tag Filter Notation63789
Node: Programmatic Use64162
Node: Importing64394
Node: The Export Format65135
Node: Editing Themata (Org Format)65526
Node: Importing from Anki65999
Node: What Gets Imported66874
Node: What Does Not Transfer67321
Node: Requirements (1)67672
Node: Link Health and Maintenance68063
Node: Checking Link Health68627
Node: Full Synchronisation68872
Node: Syncing the Node Database69221
Node: Version Control (1)69655

End Tag Table


Local Variables:
coding: utf-8
Info-documentlanguage: en
End:
