Guides
Typed links vs backlinks in your notes
A backlink is a plain link seen from the page it points to. A bidirectional link is the same link visible on both ends. A typed link adds a label such as supports, contradicts or supersedes, so a reader or an AI agent knows how two notes relate, not just that they are connected.
Three ideas that get mixed up
Backlinks answer one question: which pages mention this page? You write [[Project Atlas]] on a meeting note, and the Project Atlas page shows that meeting note in its backlinks list. The link was written once, in one direction, and the tool computes the reverse view.
Bidirectional links are how most note apps describe this feature. Roam Research popularized the term. In practice it means the same thing as backlinks: you author one side, the tool displays both. Nothing records why the pages are related.
Typed links (also called semantic links or link types) keep that missing information. The link carries a relation name. "Atlas supports the Q3 goal" and "Atlas was superseded by Atlas v2" are different facts, and a typed link stores the difference.
Why the type matters more with AI agents
A person skimming a backlinks list brings context. They remember which mention was a decision and which was a passing reference. An agent that reads the same list sees only a set of pages and has to read each one to guess the relationship.
With typed links, an agent can ask narrower questions: what does this page contradict, which notes supersede this one, what is this decision based on. That lowers how much text it must load before it can answer.
There is an honest limit here. In a small vault, a few hundred notes, plain links and good titles are often enough, and a relation vocabulary is extra work. Types start to pay off when the graph is large, when several agents write to it, or when you need to find contradictions and stale claims.
How common tools handle it
| Tool | Backlinks | Link types |
|---|---|---|
| Obsidian | Yes, built in | No native types. Users rely on plugins and frontmatter. A forum request for link types dates from 2020 |
| Roam Research | Yes, the core feature | Untyped links; structure comes from outline blocks and attributes |
| Tana | References and fields | Structure comes from supertags and fields, built for human editing (comparison) |
| Basic Memory | Wikilinks | Typed relations in plain Markdown (basicmemory.com) |
| Cozy | Yes, derived on save | Typed relations from Markdown conventions |
Obsidian is the strongest choice if you want a local editor with a deep plugin ecosystem. Tana is stronger as a structured workspace for a human who wants supertags. Basic Memory is the closest to Cozy in file format, and it runs locally for free. The question that separates these tools is who writes the links: a person in an editor, or an agent over MCP.
How Cozy stores typed links
Cozy builds its graph from Markdown conventions every time a page is saved. There is no separate graph database to maintain. You can write a typed relation in three ways.
- A frontmatter key whose value is a wikilink. Any key other than the reserved ones (type, description, aliases, tags, status, as_of) becomes a relation name.
- A line in the page body of the form
relation:: [[target]]. - A triple of the form
[[a]] | relation | [[b]].
---
type: decision
description: Move the API to Streamable HTTP
supersedes: "[[Decision: SSE transport]]"
---
based_on:: [[Spike: MCP transports]]
contradicts:: [[Old integration plan]]
[[Atlas API]] | blocked_by | [[Auth rewrite]]
Every other link in the page body becomes a plain links_to relation. A link into the sources/ folder becomes a cites relation, which ties a claim to its evidence. Links inside code blocks are ignored, so examples like the one above do not pollute the graph.
Names resolve by path, path without extension, file stem, title or alias, ignoring case and accents. A name that matches nothing is recorded as a broken link, and the Health check reports it.
Because the inline form uses the relation:: [[target]] pattern, the files stay ordinary Markdown. You can open them in any editor, and tools that read that field syntax can parse the same lines.
Reading the graph through MCP
Cozy runs no model of its own. Your agent connects over the hosted MCP endpoint at https://cozy.cloud/mcp, and a few tools read the graph:
cozy_contextreturns a page with its typed neighbors, excerpts, evidence and warnings.cozy_graphwalks the graph to a depth of three and can filter by type, tag or relation.cozy_backlinkslists the pages that point at a page.cozy_resolvemaps names to pages and flags likely duplicates, which helps keep one canonical target per relation.
Writes go through cozy_write, cozy_edit and cozy_append, and each edit carries an expected revision, so two agents cannot silently overwrite each other. See the MCP server page for setup and the personal knowledge graph page for how the graph fits the rest of the workspace.
Keeping typed links honest
A relation label is a claim, and claims go stale. Cozy's wiki health check looks for broken links, orphans, pages the index cannot reach, and pages whose cited source changed after the last edit. Lines that start with CONFLICT: are counted, so a contradiction you record stays visible until someone resolves it.
The optional Dreaming pass is run by your own agent. It checks changed pages against their sources, keeps superseded values with dates, merges duplicates and writes missing typed relations. Nothing happens unless you run it.
Choosing a convention
Keep the relation vocabulary short. A list of five to ten names, such as supports, contradicts, supersedes, based_on, part_of and blocked_by, is easier for an agent to apply consistently than fifty names. Write the vocabulary in one page so every agent reads the same rules.
If you already have a vault, the Obsidian import path brings Markdown files across, and existing wikilinks become links_to relations on the first save.
Frequently asked questions
What is the difference between a backlink and a typed link?
A backlink only shows that one page links to another. A typed link also names the relationship, such as supports, contradicts or supersedes, so a person or agent can filter by meaning.
Does Obsidian support typed links?
Not natively. Obsidian shows backlinks, and typed relations usually come from plugins or frontmatter conventions. A request for link types has been open on its forum since 2020.
How do I write a typed relation in Cozy?
Use a frontmatter key whose value is a wikilink, a line like relation:: [[target]], or a triple of the form [[a]] | relation | [[b]]. Cozy reads them on every save. See the Markdown wiki page for the full conventions.
Do I need typed links for a small vault?
Often not. With a few hundred notes, plain links and clear titles can be enough. Types help more as the graph grows or when several agents write to it.
Can an agent query the relations?
Yes. Through the hosted MCP endpoint, cozy_context and cozy_graph return typed neighbors and can filter by relation. You bring your own agent, since Cozy runs no model.
Give your agents a memory worth keeping
Cozy gives every account a private wiki that Claude, Codex, ChatGPT and other MCP clients can read and maintain.
Start your wiki