Org Gnosis User Manual

Next:  

Org Gnosis User Manual

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

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


1 Installation & Configuration

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

2 Taking Notes With Org Gnosis

For Org Gnosis there are 2 types of 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.


2.1 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 in future classes/projects.

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

2.2 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


3 Contributing