Setting up Org-roam

Org-roam’s capabilities stem from its aggressive caching: it crawls all files within org-roam-directory, and maintains a cache of all links and nodes.

To start using Org-roam, pick a location to store the Org-roam files. The directory that will contain your notes is specified by the variable org-roam-directory. Org-roam searches recursively within org-roam-directory for notes. This variable needs to be set before any calls to Org-roam functions.

For this tutorial, create an empty directory, and set org-roam-directory:

(make-directory "~/org-roam")
(setq org-roam-directory (file-truename "~/org-roam"))

The file-truename function is only necessary when you use symbolic links inside org-roam-directory: Org-roam does not resolve symbolic links. One can however instruct Emacs to always resolve symlinks, at a performance cost:

(setq find-file-visit-truename t)

Next, we setup Org-roam to run functions on file changes to maintain cache consistency. This is achieved by running M-x org-roam-db-autosync-mode. To ensure that Org-roam is available on startup, place this in your Emacs configuration:

(org-roam-db-autosync-mode)

To build the cache manually, run M-x org-roam-db-sync. Cache builds may take a while the first time, but subsequent builds are often instantaneous because they only reprocess modified files.