Quickroam

Is your org-roam slow?

If you’re like me, you think org-roam has the right idea, but the current implementation is not reliable or fast enough for day-to-day work.

1. The end-user commands take me 5 seconds to get the minibuffer ready.
   • A workaround by memoizing works well most of the time, but if I create a new node and immediately want to insert it elsewhere, I have to wait for an idle timer to update the memoization.
2. Very large Org files take me 10 seconds to save with org-roam-db-autosync-mode.
   • I can turn the mode off, but then I need to manually run M-x org-roam-db-sync every now and then! Not great when I’m in the zone and writing.

As best I can tell by reading the source code, problems #1 and #2 are totally separate. Problem #1 should be fixable, but #2 arises from the fact that org-roam is very generalized – for example, it lets you plug in user-defined functions to exclude or include a node. That’s nice and hackable, but it means that org-roam is forced to use Org functions to “properly” parse every file it scans, incurring all the penalties of doing so.

Fix

This package provides alternatives to common commands:

• org-roam-node-find – use quickroam-find
• org-roam-node-insert – use quickroam-insert

They don’t look up the org-roam DB at all, just rely on ripgrep. They’re fast, fixing problem #1, and they always find up-to-date hits, which means you can set org-roam-db-update-on-save to nil to fix problem #2.

If you do the #2 fix, be aware that backlinks won’t update until you run M-x org-roam-db-sync RET.

Limitations

This is very fast but very simplistic, you get no ROAM_ALIASES, no ROAM_EXCLUDE, no org-roam-node-display-template, etc! My attempt at supporting all that resulted in a different package, org-node.

Setup

Install ripgrep on your computer. Then add to Emacs initfiles something like this, assuming you install packages with straight.el:

(use-package quickroam
  :straight (quickroam :type git :host github :repo "meedstrom/quickroam")
  :after org
  :config (quickroam-mode))

(global-set-key (kbd "<f2> f") #'quickroam-find) ;; or whatever key you use
(global-set-key (kbd "<f2> i") #'quickroam-insert)

Future work

(2024-04-23: quickroam has hit version 1.0 and is NOT EXPECTED TO CHANGE. Now I dogfood a spin-off with more features: org-node!)

This package is a proof-of-concept that ripgrep can collect part of the data needed by the org-roam DB. However, simple regexps cannot collect all that’s needed. Some challenges:

• TODO/DONE keywords
  • Need awareness of buffer-local #+seq_todo settings – good luck doing that with grep
• The outline path
  • What it’s used for: https://fosstodon.org/@nickanderson/112249581810196258
  • Can be calculated, but it requires a lot more code
• Backlinks: requires knowing the name of the subtree-node in which a link is found
  • If we mandated the rule of “one file, one node” like zk/orgrr/denote do, we’d only need to grab the file title. But that’s not why we’re here. We like subtrees.
    • One option is to satisfice with a poor-man’s backlinks buffer by letting it just show, say, 2 lines above and below each link, reminiscent of a diff output.
    • Another option is to cache the backlinks as a property or drawer(!) like org-super-links does. And then just let a grep job collect those backlinks.

Thanks

Inspired by a Mastodon conversation with the orgrr author :)