This manual, authored by Thanos Apollo, offers installation instructions, customization options, and recommendations for effectively using org-gnosis.

The documentation furnished herein corresponds to stable version 0.0.5, released on 2025-02-13.

Org Gnosis (GNU-sis) is an org-mode parsing tool that organizes notes as atomic nodes in an SQLite database. Each heading with an ID is treated as an atomic note (node), storing its metadata, such as title and links, in a relational database to facilitate efficient linking and navigation.

This tool also offers special functionality for journal entries, stored in a separate directory with support for customizable templates. This can serve as an additional space for temporary notes.

COPYING

Copyright (C) 2025 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, with the Front-Cover Texts being “A GNU Manual,” and with the Back-Cover Texts as in (a) below. A copy of the license is included in the section entitled “GNU Free Documentation License.”

(a) The FSF’s Back-Cover Text is: “You have the freedom to copy and modify this GNU manual.”

Installation & Configuration

  • The org-gnosis package is available from the GNU ELPA archive, which is enabled by default.

    • Prior to querying an archive, make sure to update the index, with M-x package-refresh-contents.

  • Then all you need to do is type M-x package-install and specify the org-gnosis package.

Example installation & configuration using use-package

    (use-package org-gnosis
      :ensure t
      :init
      ;; Example for separated journaling & notes keymap
      (define-prefix-command 'my/notes-map)
      (define-prefix-command 'my/journal-map)
      :config
      ;; Common settings you might want to tweak to your liking
      (setf org-gnosis-dir "~/Notes"
            ;; Whe non-nil, create notes as gpg encrypted files
            org-gnosis-create-as-gpg nil
            ;; TODO files, commonly used for templates.
            org-gnosis-todo-files org-agenda-files
            ;; Used in #'org-gnosis-todos for template generation
            org-gnosis-bullet-point-char "+"
            ;; Default completing-read function
            org-gnosis-completing-read-func #'org-completing-read
            ;; Recommended if you use a vertical completion system (e.g vertico)
            org-gnosis-show-tags t)
    
      (defun example/org-gnosis-book-template ()
        (let ((date (format-time-string "%Y-%m-%d"))
              (book-title (completing-read
                         "Example book: "
                         '("Free Software, Free Society" "How to Take Smart Notes"))))
          (format "#+DATE: %s \n#+BOOK_TITLE: %s\n\n* Main Idea\n* Key Points\n* Own Thoughts"
                  date book-title)))
    
      (add-to-list 'org-gnosis-node-templates
                   '("Book Example" example/org-gnosis-book-template))
      :bind (("C-c n" . thanos/notes-map)
             ("C-c n j" . thanos/journal-map)
             :map thanos/notes-map
             ("f" . org-gnosis-find)
             ("i" . org-gnosis-insert)
             ("t" . org-gnosis-find-by-tag)
             :map thanos/journal-map
             ("j" . org-gnosis-journal)
             ("f" . org-gnosis-journal-find)
             ("i" . org-gnosis-journal-insert)
             :map org-mode-map
             ("C-c C-." . org-gnosis-insert-tag)
             ("C-c i" . org-id-get-create)))

Taking Notes With Org Gnosis

For Org Gnosis there are 2 types of notes,

  • Your “permanent” notes, which you can visit & and create using M-x org-gnosis-find

  • Your journal notes, which you can visit & create using M-x org-gnosis-journal-find, which optionally can serve as “fleeting” notes.

As mentioned before, opening & searching your notes should be done using M-x org-gnosis-find as this will enable org-gnosis-mode.

If org-gnosis-mode is not enabled, files will not be parsed and saved in the database when you run save-buffer.

Org Gnosis does not automatically sync the database. To delete a file, use org-gnosis-delete-file or run org-gnosis-db-sync after manual deletion.

Organizing your notes

org-gnosis provides a zettelkasten-inspired approach to note-taking, treating knowledge (gnosis) as valuable and not merely something to be boxed into a single category, to be disposed after a certain period of time or task accomplishment.

Using directories to organize your notes is not recommended, a preferred method is to create MOC files (Maps Of Contents) for specific categories/projects that you are working on.

An MOC file can be the syllabus of a class or a project road map. For example, you might create an MOC like this for a class on Biopolymers:

  • First create a node using M-x org-gnosis-find followed by Biopolymers, which will be created if it does not already exist.
  • Use M-x org-gnosis-insert-tags to insert moc tag.
  • Start inserting your syllabus points with M-x org-gnosis-insert as nodes, which will be automatically created & saved in separated files.

Example:

    :PROPERTIES:
    :ID:       15edada1-9815-4fb3-9b8f-7da08107bdb2
    :END:
    #+title: Biopolymers Syllabus
    #+filetags: :moc:
    
    * Proteins
    - Protein Structure Levels
    - Protein Domains
    - Protein MOTIF
    - Difference between a motif and a domain in a protein
    - Protein Families
    
    * Nucleic acids
    - DNA
    - RNA
    - Recognition and self-assembly of macromolecules
    - Cytoskeleton

Note: Items with - would be links. The headings in the above example could be links to an MOC as well.

This way your notes are atomic & can be reused used in future classes/projects.

  • For example you’d reuse your notes on nucleic acids in a genetics class MOC for your next semester.

Importing Notes

If you are a previous user of packages that use org-mode and org ids, your current note collection should be able to work with org-gnosis without you having to change anything.

To sync your note collection use M-x org-gnosis-db-sync

Contributing

Sources

Code contributions are most welcome. For any major edit (more than 15 lines, or so, in aggregate per person), you need to make a copyright assignment to the Free Software Foundation. This is necessary as the FSF must at all times be in a position to enforce the GNU General Public License.

Here’s the process:

  1. Review and adapt the request form below.
  2. Email the specified address with your request.
  3. Await a legal agreement from the FSF.
  4. Sign and return the document, which can be done via email.

The entire process usually takes about a week and needs to be completed only once, allowing you to contribute to GNU Emacs.

Please email the following information to assign (at) gnu (dot) org, and we
will send you the assignment form for your past and future changes.

Please use your full legal name (in ASCII characters) as the subject
line of the message.

REQUEST: SEND FORM FOR PAST AND FUTURE CHANGES

[What is the name of the program or package you're contributing to?]

Emacs

[Did you copy any files or text written by someone else in these changes?
Even if that material is free software, we need to know about it.]


[Do you have an employer who might have a basis to claim to own
your changes?  Do you attend a school which might make such a claim?]


[For the copyright registration, what country are you a citizen of?]


[What year were you born?]


[Please write your email address here.]


[Please write your postal address here.]


[Which files have you changed so far, and which new files have you written
so far?]