Living in Org-roam

First posted on May 14, 2020

I’ve been eagerly following developments in tools for thought, most notably Roam Research. After extensively using an Emacs-based implementation called Org-roam, I thought I’d summarize my thoughts here. See the links at the bottom for more examples / info.

If you’re already familiar with Emacs + Org-mode, Org-roam is a must-try package. For everyone else, Gwern said it best:

“Friends don’t let friends use heroin or org-mode — are you ever really going to make back the time it takes to learn & customize org-mode?”

Well, Gwern, I’m working on it. If you go down this rabbit hole, I’ve documented my configuration here.

Org-roam enables building and leveraging an emergent graph structure on top of Org-mode. Each node is an Org file, which is usually an entity or concept that I care about, like a person, place, company, book, paper, codebase, technology, etc… A bi-directional graph edge is generated whenever the contents of one node reference another node, enabling structure to form incrementally. Edges can also be pinned to specific sub-sections of a node, for more specificity. Critically, Org-roam enables generating nodes and links with minimal overhead, friction, or cognitive load. It’s joyfully streamlined.

Here are some things I currently find useful to augment with this graph structure:

  1. Notes on my engineering work / personal research
  2. Notebooks with executable code blocks (see Org babel and emacs-jupyter)
  3. PDFs, references, and annotations (see my org-noter config and org-roam-bibtex config)
  4. Tasks (see my org-agenda config here)
  5. Daily journal entries

Here’s a realistic example how I leverage the graph structure. I create a journal entry describing my learnings about a computational method, which I recently used for a work task. The journal entry links to the task description, and the task description links to the implementation (emacs-jupyter notebook). The inline documentation of the notebook links to an equation in a paper (PDF) describing the computational method. A year later, I go back to the same paper for a different project and immediately see the backlinks attached to the equation. The related code, task, and journal entry are now at my fingertips to review, and would likely otherwise be forgotten.

Here’s a bird’s-eye view of part of my graph (courtesy of org-roam-server):

Some interesting projects / resources in this space:

And don’t miss the classic “As We May Think”.