My Notes Taking Stack

For years, I’ve been on a quest to find the perfect set of tools for my note-taking needs. This journey began with my first smartphone in 2010, a significant shift from my previous method of using a physical notebook and a fountain pen.

Initially, I experimented with various note-taking apps that offered both mobile and web clients. While these apps were satisfactory at first, they eventually fell short in one aspect or another, failing to meet my evolving needs.

These experiences, however frustrating, helped me define the essential requirements for a note-taking solution that would satisfy me.

The Requirements

Here are my requirements, in no particular order:

Offline First

I want to access my notes regardless of the connectivity of the device I’m using. This is not only for when I’m in remote locations but also for times when I’m in a corner of the house with poor Wi-Fi reception.

Sync between Different Devices

Simultaneously, I want my notes to be synchronized across all my devices. For syncing, there’s no need for a constant connection while I’m working on my notes. A brief connection before and after is all it takes. So, if I leave the house knowing that my handheld device is synced, I can work on the go and sync everything once I get back home.

Full-text Search

I tend to forget things. That’s why I write them down. But I don’t want to struggle with a tagging or category system that forces me to think in advance about how my content will be indexed. I want to be able to search by what comes to mind.

Plain Text Files

I want to access the content easily and programmatically, outside the features of the program itself.

Articles Scraping and Bookmarks

The solution I’m looking for should not only handle simple notes but also allow me to import articles from the web, storing their content locally, stripped of any unnecessary elements. These articles should appear in full-text searches and be linkable from my notes.

Context Related Notes - Ebooks

This requirement is key and is the hardest to meet with ready-made apps or services. I want a solution that allows me to take notes on the books I’m reading, while reading, with quotes and references to the part of the book that inspired the note.

Notes linking

I prefer my notes to be atomic and referenciable. I often find myself conceptually connecting different ideas. This connection should be reflected in my notes. In graph terms, the edges are as important as the nodes, and they often carry significant conceptual value.

Cross-platform

The solution should be available on a variety of systems I use (all UNIX-like). Essentially, it should work on OpenBSD on a PowerPC.

Failed attempts

After many disappointments with various apps and services, I remembered that I’m a programmer and that I could create my own tools.

Graph DB on AWS

I went big with this attempt. I had to sacrifice my offline-first requirement, but I only came to appreciate that after this attempt.

The stack was simple:

Designing the graphs of the models was very educational. I could import books from epub files and link my notes to them up to the paragraph level.

I also started making a nice client, to allow me to start using the system and tweak it. This is when I realized that it was a pain to use. I also had to make sure I had access to the internet to connect to my EC2 instance. And be wary of the security.

I never got to implement a way to import articles from the web. The attempt was killed. It was too complicated to manage.

Text files and git repo

Recycling a lot of the code from the previous attempt, I changed the pain point (the database) with git. I understood there was no real need for a 24/7 server running and that in most of the cases I would only need to sync the changes. So git made sense.

It worked well with books (like the previous try) and while using it, I also went forward with the development and started to make the procedures to import articles.

This was another pain point. I could leverage Firefox read mode to scrape the content of the pages, but managing them was hard.

I created an index in JSON, indexing each word from the contents and pointing to the files path. Each entry in the index looked like this:

{
  "consciousness": ["/contents/Dune/4/1.txt", "/contents/otherBook/4/7.txt"]
}

It was easy to generate, but it was hard to maintain. I could manage to refresh the index when moving/deleting/adding content, but it was hard to keep it in sync with edits. And edits happen a lot when taking notes, jotting down, reviewing, journaling …

On top of this, there will be the inter-notes links. So a graph-like index connecting the things… I could have done it. But it seemed a too big of an effort for a personal too. It’s a side project, not a second job!

This was the moment when I got my requirements straight and starting to look for already made tools I could leverage.

The Solution

This leads us to my current stack for my notes.

Foliate and Gclone

If you read ebooks on Linux/BSD you probably know Foliate. I love it. It has a nice comfortable UI and some nice features for managing ebooks. It has also a built in web search module which comes often handy. Plus: it has the possibility to write notes on highlighted portions of the text. This is already great, but it gets better since the notes are stored as JSON in a Foliate folder! This allows me to link them to my other notes and content.

So the collection of JSON files generated by Foliate it’s a great metadata of my ebooks and it is sync-able. And for my case, a simple configuration of Gclone with Dropbox did the trick (I didn’t use git because Foliate’s JSON files are not formatted, so from a git point of view they are always a single line changing).

This is the script I use to keep ebooks and annotations in sync between devices:

#! /usr/bin/env sh

sync_local() {
    rclone sync -i dropbox:/__rclone/Library ~/Library
    rclone sync -i dropbox:/__rclone/Foliate ~/.local/share/com.github.johnfactotum.Foliate
}

sync_remote() {
    rclone sync -i ~/Library dropbox:/__rclone/Library
    rclone sync -i ~/.local/share/com.github.johnfactotum.Foliate dropbox:/__rclone/Foliate
}

case $1 in
    "local")
        sync_local
        ;;
    "remote")
        sync_remote
        ;;
    *)
        printf "Usage:\nlib-sync local\n\tto sync the local Library\nlib-sync remote\n\tto sync the remote\n" && exit 1
        ;;
esac

NB

When cleaning up my Firefox bookmarks I found out nb. I felt like an idiot at first, but then I was happy. This tool basically does everything I always wanted:

Plus all the wiring and managing one wishes to do with their content.

It takes a while to get acquainted with all its features, but it takes way less than trying to create your own solution from scratch!

It leverages a lot of external programs (like Pandoc and Ripgrep), but it its most basic version works well even on OpenBSD/macppc.

The only feature missing is the contextual notes in books, but we got that covered with Foliate.

NB and Foliate

We mentioned that nb has the possibility to add plugins, and this would be the perfect solution to integrate the notes taken on Foliate.

I haven’t written a proper plugin yet, but for the time being I’m using the following JQ script to convert the JSON notes taken in Foliate in markdown notes to save in nb.

# This script converts Foliate annotations json files into MD

def print_out_the_book_details: (
  "# \(.title)",
  "",
  "Author: \(.creator)  ",
  "Publisher: \(.publisher)",
  "",
  "## Annotations",
  ""
);

def parse_each_of_them_into_md: (
  "### Annotation \(.key + 1) {#\(.value.value | @uri)}",
  "",
  "Color: #\(.value.color)",
  "",
  "> \(.value.text)",
  if (.value.note | length) > 0 then (
    "",
    "**Note**: \(.value.note)"
  ) else empty end,
  ""
);

# MAIN

if has("annotations") then
  (.metadata | print_out_the_book_details),
  (.annotations | to_entries | .[] | parse_each_of_them_into_md)
else
  empty
end

I wrapped in a simple bash for-loop that reads all the files in the Foliate folder and uses nb import to import them in my notes collection. I can from there access them for revision and/or link them to other notes.

My CMS

This stack of tools for notes works so well that I’m using it as CMS for my website/blog.

I have the notes organized in different notebooks/folders and in one folder there are the articles ready to be published. The articles are just very long notes with a front-matter header with some metadata (like the stub or SEO values). They get picked by my website generator and turned into web pages ready to be published.

Some time soon I will give the right space to how this website works.

The Killer Device

You’ve probably have noticed that this article started talking about smartphones and apps, but these two things got lost and not event mentioned as a requirement.

This is because I’ve got a PinePhone, with a keyboard case. I rarely think of it as a phone, but rather as a small, always-on Linux computer.

I run Foliate on that for some reading; or I just keep it by my side while reading on a proper e-paper e-reader and pick it up just to note something down.

It runs nb with all the optional programs I need (like Pandoc), so I can import articles that I read on it. Or I can use it to review my notes or input new ones. The keyboard case is pretty good even for a medium work on the text.

Embracing Technology: A Journey Through Scripting, AI, and the Future of Note-Taking

As we continue to advance into 2024, my journey with note-taking and technology has taken yet another turn, this time towards the integration of artificial intelligence. The landscape of digital note-taking is no longer just about the tools we use but how we can enhance them with AI to make our processes more efficient and intuitive.

Reflecting on my experiences, I’ve come to realize that the meticulous organization of notes, once a cornerstone of my system, has become less critical. AI’s ability to parse and understand my content has allowed me to focus more on the act of creation rather than the management of what’s been created. The AI’s prowess in analyzing data means that I can trust it to make sense of my notes, regardless of their structure.

Throughout the year, I’ve documented not only my thoughts but also the evolution of my tools and scripts. These digital artifacts represent the culmination of research and problem-solving. In hindsight, I wish I had captured the rationale behind these solutions more thoroughly, as it would greatly benefit any future revisits or repurposing.

The idea of reorganizing my journaling by topics or ‘threads’ rather than chronologically was an interesting concept I considered. However, I eventually recognized that AI could later disentangle these threads, thus negating the need for me to manually manage them.

I’ve also started to envision AI as a gatekeeper for both my digital output and the content I consume. This includes not just texts and messages but also articles, videos, and other media. The idea of an AI that helps supervise and curate my digital interactions is both fascinating and promising.

In envisioning the ideal ‘second brain’ device, I’ve outlined features that seem more attainable than ever before. It should be always on, have a comfortable input method, integrate seamlessly with AI tools, play well with other devices, and be portable enough to fit into my daily life.

In conclusion, the fusion of AI with our digital note-taking and scripting tools is transforming the way we manage and interact with information. My journal entries from 2023 highlight the potential of AI to serve as a second brain, aiding us in both the creation and consumption of content. As technology continues to evolve, our tools will become even more sophisticated, allowing us to concentrate on the essence of creativity and the exploration of new ideas.

TO ALL ARTICLES