# Typed links vs backlinks in your notes

> Backlinks, bidirectional links and typed links compared: what each records, where Obsidian, Roam, Tana and Basic Memory stand, and how Cozy writes typed relations in plain Markdown.

Updated 2026-11-09. Canonical: https://cozy.cloud/typed-links

> 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](https://forum.obsidian.md/t/add-support-for-link-types-link-info-link-metadata/6994) 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](https://toolradar.com/compare/roam-vs-tana)) |
| Basic Memory | Wikilinks | Typed relations in plain Markdown ([basicmemory.com](https://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.

1. 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.
2. A line in the page body of the form `relation:: [[target]]`.
3. A triple of the form `[[a]] | relation | [[b]]`.

```markdown
---
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_context` returns a page with its typed neighbors, excerpts, evidence and warnings.
- `cozy_graph` walks the graph to a depth of three and can filter by type, tag or relation.
- `cozy_backlinks` lists the pages that point at a page.
- `cozy_resolve` maps 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](/mcp-server) for setup and the [personal knowledge graph](/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](/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](/import/obsidian) 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](/markdown-wiki) 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.
