Motivation
The current cross-linking design, as defined in §5 is very brittle. Links will be prone to breaking, and the OKF will need to be regularly maintained to repair broken links. This will require either a lot of work from human review, or burning a lot of agent tokens to repair broken links and find missing resources. Either way, the value of the OKF will diminish because we will lose confidence in the knowledge base. We will not know if something is unlinked because two concepts are unrelated, or the linked file hasn't been created yet, or the link actually does exist but the link is now broken.
[My Other Concept](path/to/concept.md)
If the above file is ever moved to say `my/other/concept.md` then now the above link is broken and it is difficult to repair the broken link because there may be many files with the same name.
Admittedly the SPEC does mention: "Consumers MUST tolerate broken links – a link whose target does not exist in the bundle is not malformed; it may simply represent not-yet-written knowledge." I think this stance is correct. 1. I often write a link to a concept that I MIGHT explore in depth later. 2. When an agent is in the process of writing to a file, they will often need to mention a file that they have not yet created.
But this quote only tackles one part of the broken links problem: links to files that do not exist yet. What it does not cover is links to files that STILL exist and yet the link is broken. We need to provide solutions that enable link resiliency1.
As of OKF v0.1, links are only path based (relative or absolute). The problem is that once the file needs to be moved or renamed then every single link needs to be updated. Obsidian, and some other tools handle this by monitoring every file, and once a file is renamed, it will find every link and update them. This solution works well enough when you have one human user, but this solution is especially problematic when you have agents.
Agents will happily move or rename files without knowing that it broke all the links. An automated tool could repair broken links, just like Obsidian does, but then the agent doesn't know that these changes happened under its nose. This problem increases exponentially as users parallelize with multiple agents and subagents. Even if we used a tool like an MCP to dynamically notify an agent when a file path has changed, the agent still has the incorrect path earlier in its context, increasing the likelihood that it will use the old incorrect path.
"Permalinks"
OKF should reserve a top level YAML property permalink which holds a slug for a particular concept file. Relative and absolute links will still behave just as before (§5.1 and 5.2), but now there will be a new option.
File: /Books/The Lion, The Witch, and The Wardrobe
---
title: The Lion, The Witch, and The Wardrobe
type: Books
permalink: the-lion-the-witch-and-the-wardrobe
---
Now we can link to this file like this: [The Lion, The Witch, and The Wardrobe](the-lion-the-witch-and-the-wardrobe). Now this link is resilient. It will still work even if the name is changed2 or if the path is changed3.
Users may use a permalink slug and it will link to a file whose permalink YAML property matches that string value. This way even if the file name changes or any of the ancestor directories change, the link will not break.
For reference, here is how Obsidian implemented permalinks: [Permalinks - Obsidian Help](https://obsidian.md/help/publish/permalinks).
Motivation
The current cross-linking design, as defined in §5 is very brittle. Links will be prone to breaking, and the OKF will need to be regularly maintained to repair broken links. This will require either a lot of work from human review, or burning a lot of agent tokens to repair broken links and find missing resources. Either way, the value of the OKF will diminish because we will lose confidence in the knowledge base. We will not know if something is unlinked because two concepts are unrelated, or the linked file hasn't been created yet, or the link actually does exist but the link is now broken.
Admittedly the SPEC does mention: "Consumers MUST tolerate broken links – a link whose target does not exist in the bundle is not malformed; it may simply represent not-yet-written knowledge." I think this stance is correct. 1. I often write a link to a concept that I MIGHT explore in depth later. 2. When an agent is in the process of writing to a file, they will often need to mention a file that they have not yet created.
But this quote only tackles one part of the broken links problem: links to files that do not exist yet. What it does not cover is links to files that STILL exist and yet the link is broken. We need to provide solutions that enable link resiliency1.
As of OKF v0.1, links are only path based (relative or absolute). The problem is that once the file needs to be moved or renamed then every single link needs to be updated. Obsidian, and some other tools handle this by monitoring every file, and once a file is renamed, it will find every link and update them. This solution works well enough when you have one human user, but this solution is especially problematic when you have agents.
Agents will happily move or rename files without knowing that it broke all the links. An automated tool could repair broken links, just like Obsidian does, but then the agent doesn't know that these changes happened under its nose. This problem increases exponentially as users parallelize with multiple agents and subagents. Even if we used a tool like an MCP to dynamically notify an agent when a file path has changed, the agent still has the incorrect path earlier in its context, increasing the likelihood that it will use the old incorrect path.
"Permalinks"
OKF should reserve a top level YAML property
permalinkwhich holds a slug for a particular concept file. Relative and absolute links will still behave just as before (§5.1 and 5.2), but now there will be a new option.Now we can link to this file like this:
[The Lion, The Witch, and The Wardrobe](the-lion-the-witch-and-the-wardrobe). Now this link is resilient. It will still work even if the name is changed2 or if the path is changed3.Users may use a permalink slug and it will link to a file whose
permalinkYAML property matches that string value. This way even if the file name changes or any of the ancestor directories change, the link will not break.For reference, here is how Obsidian implemented permalinks: [Permalinks - Obsidian Help](https://obsidian.md/help/publish/permalinks).
Footnotes
enable, not guarantee ↩
Like, say for example, when we realize that the oxford comma is not in the original book title and the file should be named
The Lion, the Witch and the Wardrobe.md. ↩Like, say for example, if we decided to move the /Books/ folder into /Media/ so that the path is now
/Media/Books/The Lion, The Witch, and The Wardrobe.md, then the link would not break because we used the permalink. ↩