Add Link-tags feature

Link-tags! What are they?

I don’t love the term, but it’s functional and apropos for comparison to the much-more-common note-/file-tags (or just… ‘tag’). If you have a better term, please chime in! The basic idea is while a ‘note-tag’ acts as a broad, categorical label for an entire note, a ‘link-tag’ acts as a broad, categorical label for a single link within notes – they live at the level of individual links, while note-tags exist at the level of entire notes.

A note-tag allows a note to belong to multiple collections of notes, and ideally (but anecdotally, rarely) helps resurface the note when you want to find it later within a specific, categorical context.

A link-tag, on the other hand, categorizes the link (duh) between two individual notes. The link-tag’s purpose is double: To resurface targeted, specific links when you want to find them later (rather than an entire note), and also to provide a formalized context for why that particular link exists.

Link-tags, or something like them, have come up a few times in different discussions on Slack, github, or here (see #572, #627 and this post). I’m a huge fan! So I made something I plan on using. In #627 bdarcus challenged new feature requests to present 1) Concrete use-cases, and 2) Some kind of grounding in zettelkasten, or at least the spirit of org-roam, to show why it may be a good idea.

I accept the challenge! If you are already mind-linked with me, skip to the bottom to see a demo (feedback, please!). Otherwise this is a bit of a long post, since tags generally have a bad connotation in places like, and community discussions on ‘link-tags’ have not generally been focused or formalized.


Spirit of Note-taking

Personally I identify three inter-related key components of using org-roam (or any other note-taking method) for personal knowledge management:

  1. Notes are stored with a mindset of, “in what context do I want to see this again?”
  2. Notes are written with an emphasis on synthesis and content creation
  3. Notes avoid the ‘collector’s fallacy’.

The digital zettelkasten method addresses component 1 by linking notes together and providing a retrieval system. I think including link-tags doubles-down on this component and as a bonus includes component 2 (avoiding collection habits is just up to the user).
With a link-tag you form an intentional, meaningful relationship between two notes at the time of link creation (or mark up an existing, tag-less link). While the default modus operandi is vanilla references (an implicit, universal link-tag), when it is warranted you can make the extra connection to conceptually link two topics together. A vanilla reference alone only collects the relationship, but does nothing to add synthesis of ideas.

You could do your synthesizing in the text surrounding links – this must be done when you have no other options – but this has disadvantages compared to a simple link-tag. The context is not formalized, and otherwise similar types of context will likely be inconsistent with each other over time and across notes/links. This makes search and review difficult. The note is not easily resurfacing when you want it to.

To be clear I am not suggesting you don’t write around links. However, many paragraphs of text boil down to describing certain types of relationships between the current topic and a reference you link to. When scanning for notes/links, a wall of descriptive text obscures the context in which links appear, adding friction to writing and comprehension. A link-tag cuts through the noise!


A key benefit of the note-graph is that it is, generally, flat, and any note can connect to any other note. Folder and note hierarchies are toxic! Hiss, boo!
Inevitably a note-graph accumulates a lot of notes over sets of topics, and it can be advantageous to create ‘structure’ or ‘index’ notes. These curate links over a subject area, permitting top-down navigation of a topic.
Structure notes certainly have a place in the zettel-style system, but they also have potential issues (YMMV). Their purpose is to curate links to notes, and can therefore encourage a collector’s mentality as well as drive creation of pseudo-hierarchies (a structure note for structure notes. Boo!). Once you’ve collected all of the links, you then have … a lot of links. The index doesn’t spur coherence or synthesis (some posts on lament curating a structure note with a broad view of their research subject, but having no actionable connections between the notes when it came time to write).

Additionally, the manual curation process is an interruption to reading/writing. You must stop, switch context, add a link to an index note, then return. This emphasizes an anti-pattern of collection, not creation. Finally, although an index/structure note in theory is just like any other note and may be linked to/from, in practice it is treated as special – it may even get a fancy file-naming scheme. Boo, hiss! Notes should be flat!

Alternatively, using link-tags as the entry point for introducing structure within your note graph can help alleviate some of these problems. It is trivial to tag a link as ‘index’ or ‘concept’. There is no interruption to workflow, and structure can be curated as easily as writing any note. A note you link to as ‘index’ is not preemptively bestowed with special status; its content and links grow organically as you write.
This also allows any note to have many different relationships, and not simply ‘index’ or ‘structure’. This brings me to the next section:


A fun word! It describes things that are so recursive and inter-relating that nothing can be said to be the bottom or the top (a heavily connected network of relationships), although a hierarchy of relationships can (and often do) emerge naturally.

The important distinction contrasting it to a hierarchy is that in the heterarchy the organically derived relationship is the key property; not the node itself. Something like a structure note implies hierarchy (even if it doesn’t necessarily prescribe it), because the node is considered special.

The motivation of the note system is to achieve a heterarchy, though – a flat network of links between thoughts. The structure note is necessary only to wrangle the tangled mess of links into something navigable. Using link-tags to define relationships between nodes is not only an alternative way to craft structure, but it may be better (TBD something something personal preference…).

A strict hierarchy potentially loses information, certainly restricts the flow of information, and inevitably promotes further division and categorization. A heterarchy on the other hand allows hierarchies to grow within itself organically with relationships: The nodes are flat, and one node is not greater than the others.

Structure use-case


Personally this is something I plan on using myself. Using a link-tag, ‘index’, to indicate that I want a different note to serve as the ‘index note’ for my current note. I can link to as many ‘index’ notes as I feel are appropriate. Even better, the decision and curation is done within the note itself.
This gives me more freedom, and less friction! Additionally, while reviewing the note I can quickly see what note(s) serve as an index. You could also do this with file-naming schemes like #index and ##index but boo, hiss! I don’t like naming schemes, and this works against my heterarchy.


I haven’t yet made use of daily notes or org-journal, but I have seen people lamenting that they are potentially polluting their note space (especially in graph view) with lots of links to/from daily notes.
With link-tags, any/all links in a daily note could be labeled as ‘daily’ in order to add links where you want them, but filter the same connections out of the graph/buffer when you don’t want to see them. You could already hypothetically filter out dailies with a naming scheme or note-tags, but a link-tag gives you more precision (in case you want some, but not all links to show up. You could also apply the ‘daily’ tag outside of the daily note if you wanted to without fear).

Inbox aggregation

A link-tag could help with inbox-style aggregation of things you want to only temporarily connect, or plan to later follow up on (marking things as ‘read’ or ‘todo’ or belonging to ‘projectA’).

Other aggregation methods work just fine (note-tags, linking to a specific aggregation note), but a link-tags gives you more context, specificity, and flexibility. And, since the link-tag communicates across two notes (the one the link-tag points to, and the one where it is written), it is easy to stumble across a note you flagged for some kind of follow-up but subsequently forgot about. In comparison, a central aggregation note requires you to visit it and parse the entries, and a note-tag approach is generally non-contextual, non-specific, and only touches a single note.

Of course, both styles can happily thrive together with no interference!


Link-tags may help to distinguish between your own thoughts and other simple, factual notes/references. If you only have a single link relationship to work with (the link itself in org-roam and basically every other zettel system), you must structure the way you use the link to encourage forming new thoughts, and not simply the collection of links. Link-tags help encourage synthesis of your personal thoughts as you take notes. When you re-visit notes, you already have context for a connection (rather than only seeing that a connection, any connection, exists period).

Relationship use-case

Thought breadcrumbs

A bit like structure, a bit like context, a link-tag lets you add formalized breadcrumbs for your thinking process. When writing a new concept-level note built from several research papers, you could use link-tags like ‘hypothesis_of’, ‘conclusion_of’, ‘refuted_by’, ‘derived_from’, etc. This type of usage is ‘derived_from’ learning about neo4j (and other graph database) schemas.

This is again a personal use case for me. I have a lot of notes I take over papers and methods that involve references to other papers. When I’m trying to synthesize new ideas from all of these notes, it is very helpful to classify exactly what relationship a paper has to an idea.
Rather than wading through paragraphs of explanations just to get a snapshot, I can see a list of papers/notes-about-those-papers that expound key ideas, critiques of those ideas, where I might find free-form open-ended discussions, which papers reach which conclusions, and which papers prescribe novel methods.

As a bonus, when reviewing a paper I’ve used in my notes I can immediately see where I’ve referenced its hypotheses, its methods, its conclusions. This makes it easy to link/discover different review/concept notes that both reference the paper, but don’t have a link to each other. With some additional tag-types, I can immediately get snapshots of both where the paper is applied and where it is discussed (eg. ‘refutes’ and ‘refuted_by’).

Of course you can manage around all of this without link-tags. I think link-tags make this process much more sublime, though.

Social network

You could use link-tags for literally any graphic relationship you wanted – PersonA is ‘friend_of’ PersonB and ‘enemy_of’ PersonC. If I need to interact with PersonA next week, I can go quickly look up a list of their enemies! Muahah! While there are obviously alternative solutions for this type of scenario, it is something you can’t formally and consistently achieve with file-naming schemes or general note-tags alone.


A comment on this post brings up an interesting use case:
You have a note on a prolific author. You have other notes that discuss the author’s work, some more notes that discuss things written about the author, and still more notes that detail interactions the author has with his contemporaries. Now when you link to the author note, you don’t know what the link is for without re-reading notes over and over.
The commenter solved the issue with multiple highly specific note-tags. A link-tag is much easier. Just link to the author like you normally would, and add a tag defining what the context of the link is: [link:author-name::about].

Good vs. Bad tags

The consensus in posts like this is that prospective note-tags (guessing the topics your note will belong to when you want to find it in the future) tend to end up being noise, and are generally unhelpful. What can be useful, however, is tagging a note when you actually use it for something.

In my opinion, a link-tag is even better, because by definition it is assigned on use! There is nothing prospective about it. The link-tag is also more specific and constrained than the similarly used note-tag.

Another post discusses the difference between ‘object’ tags (good) and ‘topic’ tags (bad). Topic tags tend to be tooooo broad, and aren’t helpful on search/filter – hundreds of notes under a vague topic with no relation or connection to each other.
‘Object’ tags are, “… specific to the objects I use and mention … The connection in itself should be a piece of knowledge that adds to the value of my archive. A precise, lucid, and insightful connection should be placed.”
Topic vs. object also suffer from the fact that they are both note-tags and the styles shouldn’t be mixed or you can muffle the effect of your good, useful tags. A link-tag however has no conflicts, and happily lives alongside any style of note-tags. They are their own entity. Best of both worlds!


Inspired by a Conor White-Sullivan twitter rant:
“…writing is a tool for thinking, it is a way of expressing our thoughts to ourselves.” Any time I add a link, I should be able to aswer ‘Why am I linking to this note?’. A link-tag helps express my thoughts in the moment for my future self. They empower me to think, and not simply to blindly link :wink:

Each article/book/etc. will fit into multiple places in your notes. This is why hierarchies are boo-hiss-bad! and zettel is hooray-good-confetti! But even zettel falls a little bit into the hierarchy trap with its structure notes and topic tags. A link-tag lets an article/note about a subject be what it needs to be in the moment without changing the core content of the note/article itself.

In the future you might read something that invalidates a past line of thinking. There is no way to simply fit this into a structure note, and the two (or more) conflicting notes are otherwise living isolated lives. You might have a paragraph around a link indicating the conflict, but this is not enough – there is no ‘pop-out’ of the conflict or the context. Even if you review the paragraph later to understand the context in which the link was made, the criticality of the notes’ intersection is not made clear enough.
A strategic link tag like ‘refutes’ makes the connection and context immediately clear.

Thinking use-case

Questions / follow-up

What do you do if you want to link to something, but the context is in the form of a question? Something you’d like to follow-up on, or think about later?
You can stop writing and add something to a todo list, but this is an interruption (and maybe you don’t really want it on a todo; you just want to leave a reminder). You can leave the question in writing as context, but gross! Now you have to read it, and you have no filters or reminders.

It’s much easier to just add a link-tag! The whole note is not a question, after all, but now you can immediately see a specific question you came up with while writing. The interruption is minimal to none. You can leave it for a day or a year.

Long bib notes

There are a few different styles and preferences I’ve seen about long-form notes over eg. textbooks. I won’t prescribe general solutions since this is mostly personal preference, but link-tags open up possibilities in style for longer notes.

You’ve got a book about birbs :bird:. It’s long and you take a plethora of notes on it in a single document. You know some sections relate to other birb :bird: concept notes you have, and want to link them.
Rather than having to write out what/why you’re linking, such as, “This section is a criticism of theory X”, you can simply note, “Birbs :bird: are only okay, overall [link:birb-theory::criticism]”. Org-noter would keep that note synced with the section of your birb :bird: book. Months fly by, and now when you are writing a hipster blog post about birbs :bird:, you can pull up your birb-theory conceptual note and immediately locate links that hold criticism of the theory (and with org-noter a direct link to the original source/inspiration of the criticism).

The note reappears in the context you want it, when you want it!

Evergreen notes

Worth reading!
Notes should be ‘evergreen’ – written to organically grow, evolve, and accumulate over time across projects. They help to develop insight and encourage thinking. They should be concept-oriented, densely linked, and use associative ontologies (explicit, labeled connections) rather than hierarchical taxonomies. I argue all of these requirements point to using link-tags!

Note-tags are generally ineffective associations because they jumble disparate ideas all together without contextual reference. A link-tag also jumbles if you just search generally for a link-tags over all notes, but the attachment to a specific link helps keep their context highly-specific and associative. It helps to answer, “in which context will I want to stumble upon it again?”.

Two quotes:

  • “The process of thinking about the relationships between items is part of how you can ‘Do your own thinking’.”
  • “You want your associations to be high-signal so that you don’t have to try to evaluate some unordered list of links. Being able to quickly evaluate such a list without navigating among the items requires that you remember what all those items contain. Tightly-curated associations will be higher-signal.”

Implementation of link-tags

Key ideas

  • Extremely low threshold for writing (easy to just keep writing on a link)
  • Completely optional (zero effort to NOT use them, just like normal tags)
  • Able to use multiple tags on a single link
  • Co-exist with note-tags (they serve different purposes)
  • Completionsssssss!
  • User-intention agnostic – do whatever you want!

Usage / Demo

I’m showing link-tag use with the custom roam-link I made (see #592 and my post if you haven’t). They can definitely be used with standard org file: links, but that requires adding a little complexity. If link-tags end up in org-roam then the exact implementation should be discussed, so I didn’t spend much time with the file: link component.

The key implementation detail is to have a tag separator to identify which part of the link is the ‘note’ compoenent, and which (if any) is a link tag(s). I chose double colons :: since they’re simple and it seems unlikely that any notes will use them in a title (they can be escaped in the title if it does happen), but it’s trivial to change that detail.

A few added functions parse the TITLE from link-tags, so all the normal link functions work. The ‘links’ table in the database gets a new column ‘tags’ (null permitted) where tags get saved along with the corresponding link itself.

The tags get a separate face for visual pop, but the specs can be set to look like the link face generally if a user prefers uniform font-locking on links.

Inserting links and link-tags

Basic usage while writing notes

Organically create structure/index/concept hubs

Identify source materials, use multiple tags on a single link, add a reminder to read something

Browse link-tags in backlinks buffer

I added a section to the top of the backlinks buffer to display all of the link-tags (and corresponding links) associated with a note. These start folded, so that it is easier to get an overview of the tags (and still see the regular backlinks/citelinks, unless you just add a hundred link-tags everywhere… which you shouldn’t. Focus!). The links under the link-tags are redundant with the regular backlinks (that have link-tags), so you can find them in either heading – the link-tag heading just provides easy aggregation for the different types of tags in the case that you wanted to find eg. your ‘index’ links.

Query / aggregation

Just a demo, but you have imagination-power :rainbow: Basic aggregation across all notes. Here the query grabs anything that has been tagged with the ‘read’ link-tag. The query/aggregation is of course extendable to any combination of include/exclude specific link-tags or whatever other modifier someone wanted to add.


What world is complete without completions now? Not my world. There is optional link-tag completion/insertion with a prefix C-u when calling normal link insertion. Another function provides a completion prompt for adding a link-tag on to an existing link.

Also company completion! You can even get crazy and use a (single) leading special character with company if you want to compartmentalize types of tags (#index, #super-index, as opposed to @method, @refutes, as opposed to !read, !todo. You do you.).

It should also be possible to insert multiple link-tags at once with completion support, but I have not gone that far. Best practice is likely to limit the number of tags used on any given link, anyway.

Your feedback is appreciated! :smiley:


I personally support the ability to assign per link relations. This is somehow similar to org-brain, except that the relations here are arbitrary (i.e. not just limited to a fixed set, like “friend”, “child” and “sibling”) and more flexible (in term of assignment). They can absolutely coexist and complement the current tags; as mentioned, we had the discussion about this in #572 (particularly starting from here).

Just call them “relations”? In the documentation it would sound like “… when linking to other notes you can also specify what kind of relations the individual link can cast to a linked note…”, which is imo, less confusing than something like “… when linking to other notes you can also add another kind of tags to each note to express its relation…” Another idea is to name these kind of links as “typed links” (as they’re in hypertext theory).

Regarding visualization, on graph the relations can be shown as labeled edges, while normal tags can be shown as virtual (i.e. without pointing to any file) nodes. Relations don’t necessary need to be always explicit, e.g. in case of tags, the virtual nodes can implicitly show tagged relation. The implicit relation could be also added through a custom set of programmable rules. However, I’m just brain dumping here and not necessary suggest this as a good idea.

As for the org-roam-buffer, as I understand there’s plans for a major rewrite that would allow to have a search interface along with breadcrumbs #245 and other kind of separators, which could be utilized by refs, tags, relations and maybe other metadata.


Wow; pretty impressive amount of work and thought you’ve put into this @alan!

I’ll need some time to digest. But in the meantime, I’m hoping @cobblepot will also review.

1 Like

Really well done an impressive argument and potential implementation.
Forgive me if what I ask next was already explained or answered in someway,…
the idea of link tags, arguably demands direction (including abscence of direction),
these directions are unidirectional, [which might relate, taking a heirarchical system as analogous, to parent-child, or ‘vertical’, the alternative is horizontal, which may be bidirectional or without dircection (or two unrelated but opposite facing unidirectional links).
Essentially from what I can see, the system you’re proposing, which I like very much, where all links either prescribe some kind of meaning or relation to the system but also allows and encompasses the current non-relational links, the infinite posibilities of this system, boils down to 3 categories : no-/uni-/bi-directional; or if visualised, a line (as link), line with one arrow at the end and a line with an arrow at both ends.
Many examples are above eg hypothesis_of, refuted_by, etc,
these are grammatically cleanly directional and I think you gave some examples where there are arguably no direction or bidirectional.
My question is, since this (the 3 directions (or more accurately 2 directions and 1 abscence of direction)) is arguably the most fundamental distinction in this new system, upon which you build semantic meaning into with the actual wording of tag, should and can the 3 categories be built into the system notation, for the purposes of further clarity to the relations beyond that than the tag itself (the ‘directional’ semantics of some tags might be more wooly than those clearly inferred from the examples above) lends the system as you so clearly describe, [and secondly to more easily allow this to be visualised with arrows (or not) by graph viz.]
a quick idea for example, (that’s probably full of holes), instead of, ::, could use >>, <<, <>, ::, [where the dots are no direction];
this also allows flexibility in where you are writing the tag, for example you want to write “a x refuted_by y”, ie x -> y link, with refuted_by tag; if you are in the x note use the >> notation (with remaining surrounding syntax of course), and if in y note use <<.

sorry i’ve written this freeform, I hope it’s comprehendable;

in summary, there’s three fundamental relational options (uni, bi, non), and defining this along with the tag is in my opinion to the benefit, from a ‘clarifying thought’ and clarifying meaning, where one is ascribed, particularly if the semantics are ambiguous (given they can be anything you like; an example would be “questioned_by”, relatively easy to understand, but without knowledge of the texts, the dirction and therefore the meaning may be lost. [Also benefits to visualisation.] :grinning:

I think I’m going to start by breaking off a few specific bits to ask questions or comment about @alan. Here’s the first:

Why does your prototype buffer have a separate section for link-tags? Since we’re tagging links here, why is not the proposed UI impact only on the backlinks section?

Also, just for clarity, aren’t examples like “concept” really properties of a note; not any links?

Related, for purposes of discussion and demonstration, I’ve often found it helps clarify modeling to use verbs for relation labels; so “indexes” or “indexedBy” rather than “index” (the noun).



I love the idea, but the results may be better off as a separate package that uses org-roam as its foundation.

The ‘I like reading long posts’ version:

You are very nearly describing something like Cypher, neo4j’s graph query language. It uses ASCII art to both create the query for the database but also render the query human-readable. For example:

or, conversely:

An un-directed query just removes the arrow:

Links in org-roam actually already have directionality even without the addition of link-tags. Every link you make has an implicit ‘link-tag’ – the link in your note goes one direction, and the population of links in the backlinks buffer go the other direction (with a different implicit link-tag):

It is considered bad practice however to apply both link-types when the relationship in one direction can be automatically inferred by the relationship in the original direction. So while NoteA links_to NoteB in the content of what you write in NoteA, the backlinks buffer of NoteB is populated by just querying for all the NotesX that links_to NoteB (rather than establishing and then querying for is_linked_by).

The system I’m proposing allows a user to arbitrarily create new back-directional (from NoteB to NoteA) relationships between notes in addition to the directional relationship already implicitly used by org-roam. It is best practice (as @bruce points out with my use of index instead of indexes) to use verbs for the relationship rather than nouns, but if a user can keep their own personal use-cases in mind then the link-tag can be anything you want. For example my demo of tagging a link ::read doesn’t really fit a directional interpretation, even though it has one. A more appropriate tag would be something like reminded_to_read_by, but read is easier to write and unlikely to be misinterpreted.


I have been thinking about this a lot while using org-roam generally and while putting this prototype together. A more complete notation would literally let you define links and relationships between any two notes anywhere in your database.
If I am writing in NoteA and have a salient point relevant to NoteX and NoteY, it would be possible to write in NoteA:

This creates a three-way relation where NoteX refutes NoteY in the context of NoteA. More plainly, if I simply am thinking about NoteX/Y while writing in NoteA it would be possible to make a vanilla link, (NoteX)->(NoteY), in the context of NoteA. While this may seem unnecessarily convoluted (in the current system / zettel-style generally, you would open up NoteX/Y, add a link to NoteA and write the thoughts there), it is actually just a more formally defined synthesis of ideas.

Good, bad? That’s a different discussion. The notation simply makes it a possibility within the existing org-roam system. I would guess 100% that if there is any interest in creating such a notation it would be best to spin off a new, separate package that uses org-roam as its foundation, since it does not fit either Roam or Zettelkasten implementations / ideaologies.

Bringing it back around

This may seem like a complete tangent, but here I’ll bring it back around to your suggestion: Just like directionality, there is already an implied in_the_context_of property of the link (again looking at a true graph database like neo4j, both nodes and edges can have properties defined on them).

Every time you make a new link in a note with org-roam, you are creating a new graphical entry that looks like:
(NoteA)-[:links_to {in_the_context_of: NoteA}]->(NoteB)

Your suggestion of using <<, >> changes this implied context property of the link between the notes – NOT the directionality, somewhat counter-intuitively, if you are considering the relationship between the notes to be the same (as in your example above). The directionality changes by using the same notation (eg. <<) but in one or the other note. This is already true of the :: notation by itself.

Creating a link in NoteA to NoteB with a link-tag indexes with my current implementation looks something like [[roam:NoteB::indexes]] and becomes two entries in the theoretical-note-graph:
(NoteA)-[:links_to {in_the_context_of: NoteA}]->(NoteB)
(NoteB)-[:indexes {in_the_context_of: NoteA}]->(NoteA)

Using << and >> you can express the same relationship by flipping the context property:
[[roam:NoteB>>indexes]] is identical to the original :: version above:
(NoteA)-[:links_to {in_the_context_of: NoteA}]->(NoteB)
(NoteB)-[:indexes {in_the_context_of: NoteA}]->(NoteA)

And to express the same index relationship from NoteB using << instead of >>, [[roam:NoteA<<indexes]] becomes:
(NoteB)-[:links_to {in_the_context_of: NoteB}]->(NoteA)
Here’s the flip:
(NoteB)-[:indexes {in_the_context_of: **NoteB**}]->(NoteA)


I make no claims about what is a better system – being able to flip context, or just let the user utilize different tags like indexes and indexed_by. Like I said I have been thinking about it a lot. Personally I like the idea of not just context-flipping but being able to fully define three-way relations, because it fits my personal way of thinking and writing. This is a huge bias :wink: Others will definitely disagree.

If enough people like the idea of at least being able to flip context between two notes (not the full three way relation), then the >>, << notation is certainly possible, and :: could be kept as a neutral way of defining tags if the context-flips were too confusing for a user (but to be clear, even :: are directional to the linking Note).

@Wetlize I kind of like ‘typed-links’. Not so sure about relations, even though semantically it makes sense.


The short answer is this is proof-of-concept, and a final implementation could be integrated better if the consensus was to do so. More specifically they offer different views and accessibility: The ‘backlinks’ section is an unfolded dump of all the backlinks grouped by files. The ‘link-tags’ section is folded, and grouped by link-tag, where each tag will have contents spanning across multiple files. The folding is particularly important because it is unlikely you will remember all the tags you have (and even more unlikely you will remember the tags associated with that file), so you get a quick snapshot overview.

Unless/until there is a query interface for the backlinks buffer, there is no way to combine these views without giving something up.

No, and this is the key point (perhaps my example usage is not the best). A note may overall be best described as a ‘concept-note’, but this is an emergent property endowed by its relationship to other notes. This is the heterarchical interpretation – the note itself has no special properties. It is just a note like any other.
EDIT to add: In this use-case, concept should really be conceptualizes, just like I used index instead of indexes.

The utility of this is:

  1. Notes grow organically, and their content and meaning grow/evolve over time. My example of ‘meme-theory’ may be so obviously a ‘concept’ that you wonder why not just call it that prospectively, but other notes may not be so obvious at first. Also my initial note may be just a quick thought about something I read. It would be odd (to me) to so quickly anoint an entry a ‘concept’ when it has almost no contents and no links.
    Appointing a concept note early also creates a context-switch where you go from writing to collecting (again I will emphasize to me at least, since not everyone is the same. I am uncomfortable with a two sentence ‘concept note’ with no links, and immediately want to begin filling it so it can fulfill its destiny). There are also many times that I will not be aware I am initially creating a concept note, so when it does become obvious I will feel the need to rearrange and replicate its bits into a ‘formal’ concept note, potentially moving or removing original content so it better fits the ‘concept’ mold. I don’t like that.

  2. I define the relationships at the time that I use them (not prospectively). I may want meme-theory to be a conceptual hub for birb-theory and doggo-theory, but not birbs and doggos (which fit better under their respective ‘theory’ notes). Unless I’m converting a pile of existing notes, planning this design is difficult, inconsistent, and pushes towards a collector’s mentality. By using link-tags to define relationships at the time of link creation, I never have to consider the design of a note – if I never link birbs and doggos as ::concept children, then they aren’t. If I do, who cares that I may not have originally intended them to be a part of the conceptual hub – clearly I found a case where I thought one or both should be.
    Other times I may want to link to meme-theory without invoking its status as a ‘concept note’ – if the note itself is ordained ‘concept’ then this is impossible, and at best I have to infer context from a sentence/paragraph of text that goes along with the link. By using ::concept (or something different, or nothing at all) I get to control what its relationships to other notes are.

  3. From what I’ve seen of others’ uses, concepts and other overlord-type notes at best have a small summary blurb, and then a ton of links to their lesser-than child notes. By labeling the link as ‘concept’ I move all of the ‘child’ notes to the backlinks buffer, organized and perusable, leaving the note body free for any content I might want to have there, without cluttering the space with a list of links (that I would also have to curate and maintain, whereas using a link-tag is free and easy).

Obviously this is personal preference. If this workflow/concept goes against the grain of your thinking then you are free to completely ignore it and make ‘concept notes’ and other note-types where the note itself is imbued with properties. I am just offering options! :slight_smile:

You are correct and I should have made that uniform for the demo. index was a special case because I couldn’t decide (still can’t) if its usage is likely to be 99% one-way. I prefer index to indexes, but in principle you are correct. FWIW I also didn’t want to emphasize that the link-tags had to be verbs if someone wants to use them some other way (though as I point out in my response to @Bijang above, even the non-verb tags really are verbs if you bend your mind around the use case).

Thanks for taking the time to reply, I’m glad you made sense of my ramblings.
I’m having a difficult time grasping

Here’s the flip:
(NoteB)-[:indexes {in_the_context_of: **NoteB**}]->(NoteA)

I think it the word flip I don’t get…

I think I’m following you up to here, that is that

  1. there’s directionality at all times (?) in links,
  2. there is always(?) context (I’m note sure if I’ve got that correct)
  3. the context is given by which node the link is tagged in
  4. The proposed <<>> could flip context but not direction [this is where i’m not fully following the example

And to express the same index relationship from NoteB using << instead of >> , [[roam:NoteA<<indexes]] becomes:
(NoteB)-[:links_to {in_the_context_of: NoteB}]->(NoteA)
Here’s the flip:
(NoteB)-[:indexes {in_the_context_of: **NoteB**}]->(NoteA)

apologies for being slow on the uptake here.

my imperfect understanding makes me think directionality is derived from context,
but that doesn’t fit the above example and also wouldn’t fit with youre idea that’s really interesting, of creating a (directional) link betweem 2 nodes, from a third party node,
this ‘involvement’ could be made explicit by optinally creating a (non-directional?) link, by invoking the context, ie the third party node, in which the link was created.

[to stretch it further, does this optionality of context mean that any number of nodes (or ‘contexts’) be invoked to create not just a 3 way link but an x-way linked].

sorry if im coming up with ridiculous stuff, i think it’s cause i don’t understand how context relates to direction (or vice versa) if at all,
and is it always there or is it optional?

from your ideas about the 3 way link it sounds like ‘context’ essentially is an optional, floating node (or nodes?), waiting to be invoked and linked to
(going back to my earlier simplistic thoughts… is this a non-directional link?)

@Bijang I love talking about this stuff so I will do it all day long :slight_smile:
I made this super long again though, and perhaps I didn’t need to.


Possibly the simplest way I can explain (and probably where I should have started instead of all of this esoteric stuff), is imagine << and >> aren’t notation, but part of the link-tag:
Then indexes is equivalent to >>indexes and indexed_by is equivalent to <<indexes. So I still have two different link-tags to remember. Using << and >> as notation means I can use indexes as a single link-tag to mean different things in different contexts, which is interesting, but not the way org-roam works currently.

Long post version

Yes, every link is directional, always. The plain, current org-roam links are directional. Any link-tag you could possibly use is also directional.
In actual graph theory you can have undirected edges, but it doesn’t really apply for something like org-roam because there is always an ‘origin’ note (where you are starting) that links_to a ‘destination’ note (where you travel to).

In org-roam you can travel backwards from ‘destination’ to ‘origin’, but this is because the software implicitly creates a directional is_linked_by edge between the notes (implicit because the relationship is implied by the existence of the original links_to edge). So even though you can travel back and forth between two notes, the relationship is directional.

Yes, there is always context. This is confusing because nothing about ‘context’ is explicitly defined by org-roam, and it really is something you would never need to think about to use or even write the program. It is another implicit property.

Yes, this is correct with how org-roam works (and I think every other link-heavy note-taking software also. I would love to learn of one that lets you define links anywhere). By ‘context’ I just mean “the note where the link is written”. The way org-roam works, a new, plain link (ignore link-tags for a moment) is always defined inside the ‘origin’ note. This intuitively makes sense: I am writing in NoteA, I want to reference NoteB, so I make a link in NoteA. Therefore, NoteA is the context for the link from NoteA to NoteB. If I were writing in NoteB and wanted to reference NoteA, I would make a new link and then NoteB would be the context for the link to NoteA.

I will mention here that context, then, is a property of the link. Not the notes. Where was the link created? In another system, it would be possible to say, “the link from NoteA to NoteB was written in NoteX.” The way that org-roam is currently conceived, the context must always be the link’s ‘origin’ note (again, just for plain vanilla links). If I make a link from NoteA to NoteB, then NoteA is the ‘origin’ note, and the link must be written there. I cannot link from NoteA to NoteB with the link written in NoteB, and certainly not NoteX.

A link-tag is extremely similar, but the context is the ‘destination note’, instead of the ‘origin’. If I write [[roam:NoteB::indexes]] it is conceived as:
and if I write [[roam:NoteB::indexed_by]] it is conceived as:
So the link is written (the context) in the ‘destination’, NoteA, in both cases.

This is a fuzzy thing to interpret. It flips context if your intent is to express the same relationship. If your intent is to change the relationship, then it flips the direction, except… not really. I will take the example of indexes I used just above and use << and >> to define the same relationship – this is key – but in different notes.

Written in NoteA: [[roam:NoteB>>indexes]]
Creates: (NoteB)-[:indexes]->(NoteA)
Written in NoteB: [[roam:NoteA<<indexes]]
Creates: (NoteB)-[:indexes]->(NoteA)

The relationship and directionality are identical. Only where the link was written changed. If I add the in_the_context_of property, you will see the difference expressed formally. This is the ‘flip’ I was talking about:
Written in NoteA: [[roam:NoteB>>indexes]]
Creates: (NoteB)-[:indexes {in_the_context_of: *NoteA*}]->(NoteA)


Written in NoteB: [[roam:NoteA<<indexes]]
Creates: (NoteB)-[:indexes {in_the_context_of: *NoteB*}]->(NoteA)

So having both << and >> lets you define the same relationship and the same directionality in either NoteA/B location, which is not how org-roam otherwise currently functions. I actually like this idea, but it is a switch in the way the software works.

Now… you can change directionality if your intent is to change the relationship. BUT !!! The relationship expressed in one direction implicitly gives the relationship in the other direction also – indexes implies indexed_by, and vice versa. Switching between << and >> let’s me change which ‘link-tag’ I explicitly use (indexes everywhere instead of a mix of indexes and indexed_by), but the relationship (and therefore the directionality) doesn’t actually change if I’m just substituting switching indexes for indexed_by with switching << for >>. What changes is the context – in which note I explicitly define the relationship.

If I write, in NoteA: [[roam:NoteB>>indexes]] then I get:
but also implicitly

If I switch notation from >> to <<, then I get a ‘direction switch’ [[roam:NoteB<<indexes]]:
and implicitly

But this is because I’m expressing a different relationship than the original >> usage. I think this is your intent in creating and using this notation to begin with. However! The same relationship could be expressed in NoteB with [[roam:NoteA<<indexed_by]]. So by flipping << and >> all I do is change what context the link (and the relationship) is explicitly written.
The benefit of the notation use is that I ONLY have one version of a link-tag floating around: just indexes instead of both indexes and indexed_by. But !!! When it comes time to look at those links and link-tags in the backlinks buffer of a note (like in my demo example) org-roam still has to parse out the implicit side of the relationship – in this case <<indexes will need to be parsed in a way that already implies indexed_by.

So the net result is that the notation allows links to be defined in different contexts, which is not something org-roam currently does.

Directionality is derived from context, but only if you keep notation the same :wink: By changing between << and >>, you can keep directionality the same while in different contexts, or change directionality while in the same context.

I made a diagram that may help:

The link actually doesn’t really change. You still have a single, directional link from NoteA to NoteB, but that link is given the property {in_the_context_of: NoteX} instead of NoteA. The node, NoteX, gains links depending on the software implementation. For example it contains a reference to NoteA and NoteB, so you could give it plain vanilla links_to both. Or it’s use of NoteA/B in creating a three-way relation could be considered special and so it could be given a new link-type to NoteA/B to indicate that it isn’t a plain, vanilla reference. It doesn’t really matter, the main point is that the link between NoteA and NoteB was defined outside of their contents.

Yes and no. Hypothetically you can create whatever you can imagine. Realistically, in note-taking software you’re limited by writing in a specific place (a note). The link must be written somewhere, and that is just going to be a single note. So a three-way relation is really the limit of what you can do here.

For org-roam, both directionality and context are always there, no matter what (even with a three-way relation). You would need an abstract layer of additional software to add non-directional, non-contextual links, and that doesn’t really make sense for note-taking. Even then, the non-directional links would live at the level of the abstraction, not within org-roam.

1 Like

The link tagging itself in your prototype seems elegant; am just trying to internalize how I, or other users, know, without thinking too much, when and how to use link tags (vs note tags, vs simply links).

A lot of your examples make total sense to me, but am just stuck on this one.

What’s the distinction between your “overall” concept note (of the object), and your “emergent property” (of the relation)?

And I will encourage as concise a response as possible; the kind of content that could go in documentation almost :wink:

Since @bruce requested, here’s my unorganized take on this interesting set of ideas.

  • I think this allows a level of complexity that could be useful but also has the potential to regularly interrupt the free flow of ideas, with the minuses that interrupted work usually entails. If I was tagging links, every time I typed a link, I would stop and think ‘how should I tag this?’ and it would distract me from the idea I was previously thinking about. That’s just me, of course.
  • TheBrain software has something like this for characterizing links, and I think they have very active users, so if you want to theorize about it I recommend checking their forums.
  • My personal history with tagging suggests that it would not be useful for me, since I have spent lots of time tagging things but despite my predictions have not actually gotten very much value out of the activity. This is probably very individual. Many people like the Getting Things Done workflow model, but (at least so far) for me the overhead was more than I could maintain, so it wasn’t as useful in the end for me as a simpler to-do list.
  • I can definitely imagine possible scenarios (such as the ones described above) in which link tags provide insight that would not otherwise be accessible, but I don’t think I will try them until someone with at least 100s of notes demonstrates how they have added value to their workflow in practice.

I look forward to seeing how others implement this concept!

1 Like

Thanks that’s cleared up a lot! It’s interesting, I don’t have enough experience using org roam at present to say anything too meaningful, the suggestions I feel probably need to be put into a prototype as you suggested and see what results real world use generate

1 Like

Looking forward to this feature!!! If the PR is not merged into org-roam in the end, how could I use this feature? @alan

What can I say, I like to write :laughing: I am not sure where you are stuck though, so I will provide a few approaches, each of which will be concise by itself :wink: :

In zettelkasten, a ‘concept note’ is a denotation for the note itself – it is different from other notes, regardless of any links it has. Any link to it is a link to a ‘concept note’. Bear in mind, though, what you are really doing then is ‘tagging’ all links as ‘conceptualizes’ automatically. The denotation of the note projects onto the links.

In a heterarchy of link-tags all notes are denoted the same (just a note), and considering something a ‘concept-note’ is a connotation – by virtue of it’s connections, the note represents a concept. Connotation allows a note to have many types of relationships. Any link to it is just a link to another note.

If 8/15 links are typed ‘conceptualizes’, 1/15 is typed ‘refutes’, 1/15 is typed 'supports`, and 5/15 are vanilla un-typed links, then I might abstractly consider a note to be a ‘concept note’. That abstraction is an emergent property from its link-types. The note itself has no special properties. The next link I make to it is free to be of any type. Calling it a ‘concept note’ is simply a means of communicating the predominant relationship it has to other notes.

If all of this still doesn’t make sense, just consider a note graph that abolishes note-specific properties as a rule. There is no such thing as a structure, index, concept, or any other ‘note-type’ or note properties. They are banned. Outlawed. Forboden. You have unlimited typed-links you can use though. When you want to then find a ‘concept note’ – that is, a hub of related ideas or an apparent locus for an overarching theme – you search for notes that predominantly have ‘conceptualizes’ links. It is just a normal note, but its connections make it of interest in the moment.


The short answer is you should use a link-tag any time you find yourself describing why the link appears in your note. In this case, you are clearly trying to communicate to your future-self something that the link by itself is not conveying. Can you describe this context in one word? There is your tag. Is this context something you want to re-discover in the future? Make the tag something you would search for to discover this link right now. Don’t get clever and try and guess your future motivations and needs – you will usually be wrong. Per my original post, this is the benefit of a link-tag: You don’t guess or prescribe meaning. Instead you assign meaning at the time that you create it.

The use case should be obvious. If you are pausing on fresh links over and over, trying to think through all of your tags and if any apply, you are doing it wrong. If there is not an obvious tag you want to throw on to it, then it doesn’t need one.

An even better method might be to write out several complete thoughts (or even the entirety of the note you are working on) without adding any link-tags along the way. This way you never interrupt your thoughts. Once done, do a pass over your paragraph(s) and it should be obvious if you are saying something you want to formalize in a link-tag(s). Again, if it isn’t obvious, you probably don’t need one.

Simply links

If you just want to reference another note/topic/idea, but don’t have something specific and targeted to say about it, you would just use a plain link. This communicates, “I was thinking about this while writing”, or, “This topic was invoked as part of another topic’s explanation.” This is wiki-style links, with the benefit of backlinks to see where a topic has been mentioned in the rest of your notes.

As an example, from the heterarchy wiki:

The concept of heterarchy was first employed in a modern context by Warren McCulloch in 1945.

I would just make “Warren McCulloch” a plain link (as the wiki does) because I referenced him, but have nothing targeted to say. There is no context to explain. The implicit is_linked_by tag is enough.


Note-tags should be used anywhere you want to make a note-wide statement. If you find the idea of using link-tags to establish concept notes is repulsive, you could use a note-tag to identify a note as ‘concept note’. Note-tags are your amorphous bins for gross categorization. They exist entirely separate from links and link-tags, so you should never find yourself wondering, “should I use a link-tag instead?”. If you do, you’re probably overthinking your note organization.

1 Like

See my response to @bruce above. If you notice you have a habit of doing this, it would be best practice to not use any link-tags until you are done completely writing out your thoughts. Afterwards you can do a once over and add any link-tags where they now seem appropriate. If it is not obvious, then you probably don’t need any at all. This way you have no interruptions while writing.

I thought they just used the paradigm copied by org-brain which is mostly parent-child type of relationships. I would argue against using link-tags for something like this. It creates a type of “Folgezettel” which, according to users at doesn’t really make sense with the volume and abilities of a digital archive.

Looking through some of their support videos they may allow a wider range of ‘tags’ and ‘types’ than I thought. I’ll check them out.

I am working on it :laughing: I also don’t know if they truly offer what I think I want, or if they will end up being some extra noise. The ability to focus on individual links and thoughts at least make me think that they will work very well for me individually.

1 Like

Quite detailed explanations! I quite love this comment. As you said here, we could use “link-tags” to simulate all the properties of a note(like topic-notes or structure notes)


If I have a note, which is a “topic note”, and then I try to remove the internal property of this note. What I can is to transfer this property to the links that emerge from it, tagging(or said naming) the links of this note as “topic_of”. Then, right now, all the notes are just note, the properties of it are externalized on the links!!!

Quite inspiring ideas!

@leekeifon Thanks! :slight_smile: It’s definitely a different mode of thinking.

@jethro is discussing the possibility of making org-roam more modular and therefore easier to implement any number of custom implementations without modifying org-roam internals. If that happens, then I will make this (with some modifications) available as an option for others to use. Otherwise the branch will at least appear on my github, but I make no promises it won’t break! Ultimately if it doesn’t become a merged PR, it will live as a somewhat permanent alpha-level feature for my own personal use :wink: Unless I get really motivated to create a new package that uses org-roam as a foundation like I was discussing with @bijang.

The feature you offer here is definitely great, as it makes the need of thinking about “why you link this two notes” explicitly. And this feature force you to think a little bit slower, especially when you’re writing permanent notes. For those who try to write as quick as possible, the contents should be inside a fleeting notes.

This is the kind of language that could go in the documentation, coupled with @jethro’s on when to link in general.

1 Like

So, I somehow think of this feature as a way to link between note taking system and category theory.

With link tags, we define all the the properties of notes by links, and considering every note is atomic(this should be especially useful when searching), which is the same fundamental idea as category theory.

And therefore, we may finally get more abstract power from the category theory mathematical model, which may indeed help structure our complex system, though I’ve not think through it yet.

A video talking about Philosophy of Category Theory