Intro – Matthias Steffens, creator of Keypoints

Hi there,

I stumbled across this forum in my daily quest to learn from other people about their reading & note-taking workflows. Coming from the natural sciences and having worked on reference management systems I realized that the focus was often on the management of literature (and its bibliographic metadata), but not on the actual information/knowledge that could be extracted from it. However, these extracted info/knowledge bits (together with your own thoughts) are essential for your own writings, or when trying to gain insight into a topic. And these bits form the basis for all other steps that belong to personal knowledge management (like connecting them via links, commenting on them, categorising/filtering/weighing them, ordering the relevant/related ones in an outline, or adding new insights, etc).

To achieve some kind of PKM workflow, many people have implemented their own solutions – combining (manually or via scripting) apps from different categories, e.g. PDF highlighting, note taking and reference management. About 5 years ago, I decided to build an app that tries to combine elements from these categories and that would improve on such workflows. The app (Keypoints, see also here) is a plain-text focussed note-taking & PDF annotation app for the Mac.

My app stores each extracted PDF highlight annotation as a separate plaintext (MultiMarkdown) note. These notes are self-contained, i.e., they each contain all relevant info (e.g., the PDF file & annotation info as well as the citation info which can be auto-fetched from your reference manager). The notes get auto-linked to the exact location of the extracted/highlighted text in the PDF. I.e., selecting a note will also jump to its quoted text in the PDF and highlight it. And clicking a highlight annotation in the PDF will select its corresponding note.

Having individual (atomic) and self-contained plaintext notes is crucial IMO – not only for reasons of maximum portability & long-term stability. This also enables you to sort/filter and organize them (e.g. via tags, color labels & ratings), mix & arrange them with other notes from other PDFs (e.g. via queries or structure/overview notes), and link them together (via drag & drop or autocompletion). This allows you to create a network of semantically rich and linked notes, and to build your very own knowledge database.

My app also exposes its parsed elements via a scripting API (see e.g. here). This is meant to facilitate custom workflows and tight integration with other PKM apps or apps used for outlining/writing/graphing/mindmapping etc.

Currently I’m working on link types (aka semantic links) which allow you to specify why you’re actually linking to another note. I.e., for each cross-link, you can add one (or more) type(s) (like “supports”, “refutes”, “uses data from” etc) which let you describe the nature of the link. But you could also just add labels (aka link tags) that describe what the linked note is about, or add key/value attribues (like “quantity=50g”) to a link. You can assign colors to these link types and they will appear as colored edge labels in the graph visualization.

Unfortunately, the app still isn’t available as a public (alpha/beta) release, and there’s no release date yet. During the last year, progress has been rather slow (my day job demands more focus than I’d like, and there were also other reasons). But I’m dedicated to push app development forward.

Here are two screencasts that show the app in action:

The first screencast is also available as a high-res version.

As for my background, I’m a former marine biologist (having worked for ~10 years on sea ice & polar research) converted into a Mac (and web) developer. Since the last 15+ years, I’ve worked on reference management systems, first the collaborative web-based literature manager refbase, then worked for Citavi and Papers and contributed to Bookends. I’m now working on (and will continue to work on) Keypoints.

Thanks for reading all of this. I’m looking forward to fruitful discussions!


Wow, this all sounds really cool! Converging with a lot of ideas and other apps also being developed in the space, including Codex (relationships between nodes/notes/entities), Kosmik, Liquidtext, and many others. The fact that you already have an API is also a good sign, I wish more devs had put in the time and effort to have that in their app from day 1.

Sadly I am not a Mac user, but I have to say, with so many amazing productivity tools are made or being made for Mac, along with the new M1 direction that is so far looking really impressive, I am seriously considering a major platform switch in the next year or two. Your app is another one to look forward to. :smiley:

By the way, I noticed something interesting in one of the threads you linked to. You said:

While the app has many v1.0 features already implemented and working nicely, some important things are still missing (like e.g. import & export) Keypoints App - A note-talking and PDF app for academic researchers - Tools - Tools For Thought

What is “important” or even “necessary” for launch (even at an alpha level!) seems to be highly variable between developers/teams. I experiment with a lot of tools on a daily basis, and I would say many of them lack one or both of these, especially in alpha states. It sounds like Keypoints already uses plain text/markdown, so that in itself somewhat obviates the need for export, at the least (and perhaps even import, to some degree).

Certainly you should only launch when you feel ready, I would just encourage you to consider that your list of “must haves” may not actually be “musts” for an early launch, and that getting your ideas and implementation in front of actual people to test it is one of the best ways of understanding what needs to be improved/implemented/etc. I’m sure you’re aware of all that, but I just had to say it. :smile:

Keep us apprised! And if there’s anything we can do to help, let us know.


Many thanks for the encouraging feedback, @Oshyan!

You’re right that import/export features may not be a hard requirement for an initial alpha version, and other apps indeed seem to leave these out initially. However, from a user POV, import is nice to have so you can get started quickly. And export helps you to see whether this new app fits into your workflow, and gives you a good data exit strategy. Thus I thought of including at least some basic import & export functionality from day one.

OTOH, you’re right that Keypoints notes are plaintext already. But its Markdown format is MultiMarkdown with some custom extensions (esp. for the note metadata) so the notes may not be directly compatible with another tool. A compromise could be to leverage the capabilities of other tools. E.g., I’d like to integrate Keypoints with Marked 2. This would offer a dynamically updated preview for the note(s) currently selected/edited in Keypoints. Then users could also use the export features of Marked 2 to export these notes to common formats (like HTML, PDF, RTF, DOCX or ODT). In a similar fashion, for import of PDF annotations, I could at least support import of selected annotations from Skim (via a script).

W.r.t. development status, during the last months, I’ve made some good progress and finished my implementation of the above mentioned link types feature:

Clicking a link type in a note or graph will select it in the “Link Type” filter view (the left-most view in the screenshot above). As a result, the main notes list will only show notes that were linked using that link type, and the graph will bolden the arrows/edges matching the currently selected link type(s).

IMO link types are very useful since they allow us to add semantic meaning to our links. And this, in turn, will help us again to better filter & analyse our notes, and to further make sense of them.

1 Like

This approach seems quite promising. My only concern is whether it is more work than basic import/export. I think going with one or the other to start, for alpha, makes sense. But certainly not both. And I still question whether even is strictly necessary for alpha. Remember it doesn’t have to be feature complete at that stage. :smiley:

Totally agree! We have all these graph-enabled apps now, but this is really the next step, making those connections much more meaningful.

1 Like