Unleashing the Mind: Heptabase
Exploring the Tools for Thought Universe
From Amplenote to Zettlr - a no-nonsense, in-depth analysis. This post is part of a series of articles digging deep into the current landscape of Tools for Thought.
In the last article of this series, we explored Amplenote. I explained why Amplenote is a good choice for people needing a multi-platform, offline-capable PKM with good search and exporting capabilities. This time, we explore Heptabase, which uses an entirely different approach.
I joined Heptabase's waitlist in early 2021 when it was still called “Project Meta.” It was later renamed when Facebook became Meta. They have chosen Heptabase, which is related to an alien species called Heptapods in the book “Story of Your Life," (I love that book, too), which can speak a unique visual language connecting past, present, and future.
In September 2021, Alan introduced Project Meta to me, and I remember being deeply impressed by its unique visual approach and profound concept, even though the prototype had some rough edges.
Disclaimer: The Links to Heptabase and additional content in this article are referral links. This in no way affects my independence and sincere opinion.
Introduction
Heptabase is an Electron-based knowledge management tool centered on using visual learning approaches to support researching and learning complex topics. While Amplenote is more of a classical notetaking app, Heptabase's primary purpose is to support acquiring new knowledge by offering features to support atomization, connection, re-arrangement, and synthesis of concepts visually.
It is available for the Web, Windows, macOS, iOS, iPadOS, Linux, and Android and supports light and dark modes.
Heptabase supports different layouts for different tasks, but it has a somewhat classical 3-column layout at its core.
Heptabase comprises six so-called Meta-Apps arranged at the left sidebar: Journal, Map, Card Library, Tag, Task, and Highlight.
All these apps are centered around one global card database. There are seven card types: PDFs, images, audio, video, notes, journals, and highlights. These cards can be modified, re-used, linked, embedded, and arranged as needed across the apps.
The mobile clients
Heptabase offers mobile clients for iOS, iPadOS, and Android. I have tested them thoroughly on iOS and iPadOS. The clients are mature, offline-capable, performant, and very usable but not feature-equal with the web and desktop versions:
There is no task meta-app yet, which means we don't have the task overview showing due and overdue tasks nor the ability to schedule tasks. You also don't get reminders on your device.
You can work with existing maps but can't change them yet (create new cards, move cards on the whiteboard, make arrows). It is still beneficial because you can pan, zoom, and edit existing content. Getting the interface right for small devices with only touch input is challenging, but Obsidian got further with its canvas approach. I'm unsure why the corresponding meta-app is called “Whiteboard" and not “Map" on mobile.
The mobile client does not support table views for cards with properties as columns. The cards will be presented as a flat list. You can see card properties in their info box but can't change them.
You can open PDF cards, browse existing highlights, and add annotations, but you can't create new highlights for PDFs. This would be an excellent addition (especially when using the Apple Pencil on an iPad).
There is almost no support for gestures except pinch & zoom for maps. No long-press on cards in the library to open an action menu, no swipe to quickly delete them.
Versioning isn't fully supported yet. While there is a menu entry for showing them, the corresponding list is always empty (“No snapshots available at the moment.").
You can't share or export content from within the mobile app, nor can you share content from other apps with Heptabase using the iOS share menu.
But let me say it loud and clearly - despite these missing features, you get excellent mobile apps supporting your work while on the go.
The PKM Process with Heptabase
We will dive deep into the PKM process, from collecting information, organizing, and analyzing to reflecting, sharing, and updating.
Collecting
Heptabase offers various ways to get content into the app:
A block-based card editor supporting linking and embedding other cards as well as videos, images, audio, tables, and a lot more
A journal for date-related content
Tasks with and without due dates
Maps for visually arranging cards and combining them with other elements like arrows, mindmaps, grouping, and stacking them
Uploading PDFs and highlighting as well as annotating them
Tight Readwise integration for all your highlights
Journal
Heptabase has an integrated meta-app for journaling, showing the selected week on the top. It has an integrated calendar to quickly change to another date, visually indicating if there are already any entries.
You can link blocks to specific dates using the in-built @-command and typing the desired date. Heptabase uses NLP to create a link to the corresponding journal page. Dates will show a calendar icon in front of it.
Editor
The editor is based on blocks and supports block conversion from one type to another (e.g., bulleted list to numbered list, text into a heading, a code block, or a quote).
It supports up to three headings levels, bullet and numbered lists, toggle blocks, quotes, tables (no sorting, no formulas), images (including animated gifs), audio, video, math equations, syntax formatted code blocks, colored text, and standard formats like bold, underlined, italics, and strike-through.
Templates
You can create templates by selecting blocks that contain the structure you want and selecting "Create template."
You can access them from the template menu or by directly typing "/" followed by the template name or by using the template menu.
Maps
Maps are a visual representation of connections between different cards. They are instrumental while exploring a topic because arranging, grouping, and connecting them helps understanding and remembering. You can drop any library card onto as many infinite maps as you want. The cards on the whiteboards are references to the original card, so changing it will update its content everywhere.
You can also add text, images, videos, and mindmaps, enabling content-rich boards when exploring topics.
You can add non-, one- and bi-directional connections between objects on the map, color, and label them. These connections are only visual and don't add value to searches yet.
In addition to using existing cards, you can open a website in the sidebar and copy content. This is very useful when researching a topic.
You can create extensive maps to visualize complex topics, and it is helping me give structure and explore these. I'm sure it also helps to remember, as I still know what a specific part of the map looks like weeks after I created it.
Finally, you can nest whiteboards into whiteboards and reference them, allowing you to break down complex topics as needed.
Heptabase has not yet implemented good mass actions when pasting content (e.g., creating a mindmap or a bunch of cards by pasting a list).
Tasks
You can add new tasks to every card you are working on. Heptabase automatically offers a schedule icon with an integrated calendar.
The task meta-app collects all these tasks in one central view, which I'll introduce later.
Highlights & Annotations
Heptabase has one of the best in-built PDF highlighting and annotation implementations I've seen. You can mark text passages and image areas in seven different colors. Every highlight automatically becomes a card containing as many additional note blocks supporting various types like tasks, images, and tables as needed. You can show all highlights of a PDF in the right sidebar sorted by page order or chronologically.
You can work with these highlights by putting them into maps or embedding them into other cards.
Readwise
Instead of uploading PDFs and highlighting and annotating them in Heptabase, you can link your Readwise account and import from there. If you are on a map, you can open all your highlights (PDFs and Readwise) in the right sidebar. It shows all sources with the number of highlights and a search bar to find them quickly.
When you click on a source, you see all the highlights you made within Readwise and work with them like with every other card. Additionally, you can add annotations or jump to the source. It is also possible to edit the highlighted text (e.g., to fix line breaks within the PDF highlight or to add some context).
Synchronization between Readwise and Heptabase is almost instantly. So you can highlight a source in Readwise and directly work with the results in Heptabase.
Organizing
Heptabase supports tags, properties, tables, Kanbans, collapsable lists, headings, and sections to organize your content.
Tags and Properties
Cards can have as many tags as you want; they can be displayed in different colors, and the list of your current tags will be used for quick lookup when you try to add another tag. Unfortunately, tags can't be nested. I mainly use tags as a class identifier (album, book, human, project, …) and not as keywords (where I use simple multi-select entries).
You can define properties for tags to classify cards further, similar to a schema. Currently, nine different property types are supported: text, number, select, multi-select, date, checkbox, URL, phone, and Email.
You can use the information within the properties to filter your tag lists. Unfortunately, this information is not yet included in the full-text search; I'll get deeper into this in the corresponding section below.
You can view all elements with a specific tag in a table view showing properties as columns. You can filter the table by logically combining (all or any match) property queries (is, is not, contains, does not contain, starts with, ends with, is empty, is not empty) and sort them by one or more properties ascending or descending. You can create different views for a tag by storing a filter/sort combination under a custom name.
While you can use links to cards within the properties, it's not yet possible to make properties dependent on tags (e.g., have an author property that allows multi-selecting cards with the #human tag). Also, when you use links within a property, the corresponding card will not appear in the backlinks section of the linked card.
Kanban
You can also view cards in a Kanban view grouped by any single-selection field, forming a visual project management solution or issue tracker.
You can then visually drag and drop cards from one column to another, automatically updating the corresponding property. You can combine this with the filter and sort options described above and store this together in a custom view.
Tags, properties, tables, and Kanbans are potent instruments for working with large amounts of data. Allowing relations between properties would be the next step in reaching the next level here.
Update March 11th: Heptabase now supports relations between tags
Collapsable lists
Outliners' strengths are the ability to show and hide details as required. Heptabase supports this feature for all lists.
Collapsable Headings and sections
Heptabase supports two different kinds of headings: standard and collapsable. Additionally, you can define a collapsable section (toggle lists) where you can put in any number of blocks and fold them as needed.
Extract cards
When working on new concepts, I often need to take a particular part and create a card based on this. Thankfully, Heptabase supports that operation by highlighting the blocks you want to create a new card from and selecting the corresponding context menu entry.
Analyzing
Backlinks and searches are here to help you find content within Heptabase.
Search
Heptabase supports searching in different places. First, the "Quick Find” (CMD+O) allows a block-based full-text search within all your cards and whiteboards.
Unfortunately, the search is limited to finding content within a single block and not spread on more than one. It also does not support finding text within properties (you have to use the table view for this).
You can also search cards on whiteboards; Heptabase then visually shows you where the card is on the map. Unfortunately, you can't use this function to search within highlights or annotations you put on the board.
The table and Kanban view also supports full-text search. Here, you can also search your properties.
Graph
Currently, there is no support for an automatically created graph based on links between cards.
Backlinks
Heptabase supports bi-directional linking between cards and shows the connection in the info area of each card. You can directly jump to the source of the backlink, but you can't edit the text here. There is also no way to quickly filter the backlinks, which could be necessary if you have many of them and are looking for something particular.
Reflect
Tasks
All unfinished tasks from your cards (whether regular, journal, or highlights) are collected in one central place, the tasks meta-app.
You can find them all listed and grouped by their due dates here. You can finish tasks by clicking their checkbox, re-schedule them on the calendar icon, and jump to their source by clicking the corresponding link. This way, you will never lose an open task hidden on a card you wrote some time ago. When you have a lot of open tasks, the list can get very long, so I would love to see a quick search bar and the opportunity to filter or group the tasks by the links within. One expansion stage could also be the allocation of priorities.
Sharing
Publishing
You can publish whiteboards to the web by pressing the Share Link. You'll then get a secret link. The whiteboard supports searching, zooming, panning, and clicking on cards, almost as in the native app, but no collapsing, re-arrangement, or editing. The content is limited to the shared whiteboard (so you can't follow links to cards not included in the board).
You can try a shared whiteboard here. When you update a whiteboard, you have to re-publish the changes. There is no way to publish single cards or your whole library.
Exporting
You can export single or multiple cards. All referenced assets are also included within the provided ZIP File in a folder with the card's name.
The exported markdown files include all properties in front-matter YAML, which can be imported to many other apps. Links are absolute links to the Heptabase card, so you need to rework the links when importing them into another PKM system.
You can also make a complete export, which contains all data in a structured format, including whiteboards, mindmaps, highlights, and all assets (PDFs, images, audio, videos, …). Unfortunately, you still don't get Wiki links, so reworking is necessary when importing.
Heptabase also creates automatic daily backups on your desktop so you are always safe if something goes wrong.
Share to Edit
It's currently not possible to work with other people on cards.
Updating
Versioning
Heptabase includes version management for all your cards and whiteboards, storing snapshots for different moments.
When you click on older versions, the preview window instantly updates to reflect the status at that time.
You can restore any older version overwriting the current document.
Security
Infrastructure
When utilized on a single device, Heptabase ensures the secure storage of your data directly on your computer's local database. Yet, enabling the feature for syncing across multiple devices results in your data being additionally stored on Amazon Web Services (AWS).
Throughout the process, your data is safeguarded through encryption during transmission and storage. Amazon facilitates server-side encryption, employing the widely recognized AES-256 encryption standard to secure the data. AWS is responsible for managing the encryption keys. Moreover, the data exchange between the application and the database is protected using SSL/TLS encryption.
To enhance the efficiency and precision of web app searches, Heptabase utilizes Elastic Cloud, also hosted on AWS, ensuring swift and reliable search results.
Heptabase supports login by email/password or through Google's 3rd-party authentication. Right now, you can't use 2FA for email/password.
Encryption of Cards
Right now, it is not possible to encrypt single cards or blocks, but it is on Heptabase's roadmap.
Ecosystem
There are no custom themes or 3rd-party plugins available for Heptabase yet.
A public wiki with in-depth articles, a roadmap, and a backlog is available. Search is not yet available.
You can use the built-in chat client or the discord channel to submit bugs and feature requests with quick reaction times. Unfortunately, there is no public issue tracker where you can re-visit the submitted bugs and requests.
Suggestions for the developers
Heptabase is a very mature product, but there are some important things I miss:
Feature equality between desktop, web, and mobile apps
Support for Apple Pencil to add sketches to cards and whiteboards as well as to highlight PDFs
Gesture support on mobile apps (context menu, delete, rename, …)
Full-text search that supports properties and cross-block content
Exporting a part of your library to the web in the form of a wiki
Option to create wiki links when exporting instead of absolute links
Implementation of mass actions when pasting content (e.g., creating a mindmap based on a copied list)
Advanced search that takes the connections and sections on whiteboards into account, as well as links between cards
Optimized editing functions like selecting a word and pressing [ to create a link
Priority support for tasks, as well as grouping tasks by links in the overview
Settings for changing the font size
Support for custom themes (you know I love tinkering with themes) and a plugin store
The PDF viewer should store the last position I've been in so I continue working where I left off (especially important for large documents)
Support for an alias property that supports linking as if the alias has its own card
Better duplicate card management (finding duplicates and merging them)
Better undo (undo behaves sometimes crazy, leaving you with unexpected results)
Support for more than one database
Multi-User Editing
Simple formulas for tables and the possibility of sorting them
Final verdict
To make it short, I love Heptabase. It is conceptually well thought out and has a unique, strongly visual approach with many remarkable ideas that appeal to me. It is very mature with a streamlined and efficient UI; I had no stability or synching issues during my intense work with it during the last months on four parallel devices (Web, iOS, iPadOS, and macOS). Since they implemented the task support, it supports all the necessary features to be a daily driver for me.
I hope that Heptabase's team continues its focused development of its outstanding vision of a modern knowledge management system.
Next up
Unleashing the Mind: Reflect
From Amplenote to Zettlr - a no-nonsense, in-depth analysis. This post is part of a series of articles digging deep into the current landscape of Tools for Thought. In the last article of this series, we explored Heptabase. I explained why Heptabase is an excellent choice for people needing a PKM with a visual approach and excellent PDF annotations. This time, we explore
If you want to compare popular note-taking programs like Heptabase on a detailed feature basis, I highly recommend NoteApps.info.
Great review, Alexander! Thanks. I am using Heptabase for recipes ;) but planning to use it more widely for specific projects.
As Baibhav from Roam is working on new /Diagram features, I will hopefully use Roam more visually too.