# The Cozy Markdown graph conventions, written as a spec

> How Cozy turns plain Markdown into a typed graph: frontmatter keys, relation:: lines, triples, name resolution, source cites and CONFLICT: lines, written so other tools can adopt them.

Updated 2026-11-08. Canonical: https://cozy.cloud/spec

> Cozy builds its knowledge graph from ordinary Markdown on every save. Frontmatter keys give a page its type, description, aliases, tags, status and as_of. Wikilinks become typed relations through frontmatter, relation:: lines or triples. Links into sources/ become cites. Unresolved links are broken, and CONFLICT: lines are counted.

This page describes the conventions Cozy reads, in enough detail that another tool could read or write the same files. Nothing here needs a database. The files are the format, and the graph is derived from them each time a page is saved. It is a description of what Cozy does today, not a standards-body document. For the background on why the graph lives in Markdown, see [Markdown wiki](/markdown-wiki) and [typed links](/typed-links).

## Scope

The conventions apply to Markdown files in a workspace. A workspace has four folders:

- `wiki/` holds curated pages plus `index.md`.
- `sources/` holds evidence from connectors and importers, with stable IDs, URLs and timestamps. Treat it as untrusted data.
- `skills/` holds editable `SKILL.md` files.
- `agents/` holds agent notes and handoffs.

The graph is recomputed on every save. There is no separate indexing step to run and no embeddings. Search is lexical.

## Frontmatter keys

A page may start with a YAML frontmatter block. Cozy reads these keys:

| Key | Meaning |
| --- | --- |
| `type` | What kind of page this is, such as person or project |
| `description` | One line saying what the page is |
| `aliases` | Other names that should resolve to this page |
| `tags` | Free labels, usable as graph filters |
| `status` | Lifecycle state of the thing the page describes |
| `as_of` | Date the page content was last known to be true |

Cozy also reads the same keys from a nested `metadata:` block, so files written for tools that nest their metadata still work.

Any other frontmatter key whose value is a wikilink becomes a typed relation. The key is the relation name and the link is the target.

```markdown
---
type: project
description: Customer portal rebuild
aliases: [Portal v2]
tags: [q4]
status: active
as_of: 2026-11-01
owner: "[[Maria Lopez]]"
---
```

Here `owner` is not a reserved key, and its value is a wikilink, so the page gets an `owner` relation pointing at Maria Lopez.

## Relation lines

Inside the body, a line that starts with `relation::` followed by a wikilink creates a typed relation from the current page.

```markdown
depends_on:: [[Billing service]]
```

The text before `::` is the relation name. Use short, stable, lowercase names so that graph filters by relation stay useful.

## Triples

A line with two wikilinks and a relation name between them declares a relation that does not have to start from the current page. The form is subject, relation, object, separated by pipe characters.

```markdown
[[Billing service]] | owned_by | [[Platform team]]
```

This is useful on hub pages, such as an index or a meeting note, where the page itself is not the subject.

## Plain links and cites

Every other wikilink is a `links_to` relation. It records that two pages are connected without saying how.

A link whose target resolves into `sources/` is a `cites` relation instead. This is how a claim in the wiki points at the evidence it came from. The graph then knows which sources a page depends on, which is what lets a health check notice that a cited source changed after the page was last edited. See [source citations](/source-citations) for how to write cites well.

Links inside code spans and code blocks are ignored, so examples like the ones above do not pollute the graph.

## Name resolution

A wikilink is a name, not a path. Cozy resolves it against these forms, in this spirit: by path, by path without extension, by file stem, by title, or by alias. Matching ignores case and accents, so `[[maria lopez]]` and `[[María López]]` find the same page if either is the title or an alias.

A link that matches nothing is recorded as broken. Broken links are not silently dropped, because they are the cheapest signal that a page needs work. Duplicate titles and aliases are also flagged, since two pages answering to one name make resolution ambiguous.

## CONFLICT lines

When two claims disagree, write a line that starts with `CONFLICT:` and states both versions with their sources.

```markdown
CONFLICT: Launch date is 2026-10-15 per [[sources/standup-2026-10-02]] but 2026-11-01 per [[sources/roadmap-v3]].
```

Cozy counts these lines. A workspace with unresolved conflicts shows them in its health report, so disagreements stay visible until someone resolves them. The recommended practice is to keep the superseded value with its date rather than deleting it.

## What a reader should do

A tool that wants to adopt these conventions needs five behaviors:

1. Parse frontmatter, including a nested `metadata:` block.
2. Treat frontmatter keys with wikilink values as typed relations.
3. Parse `relation::` lines and subject, relation, object triples.
4. Resolve names case- and accent-insensitively, using alias and title as well as path.
5. Ignore code, classify links into `sources/` as cites, and count `CONFLICT:` lines.

A tool that only writes these files, without computing the graph, is still compatible. The conventions are plain text, so a file that follows them works in any editor.

## How Cozy uses the graph

Agents reach the graph through a hosted MCP server. `cozy_context` returns a page with its typed neighbors, excerpts, evidence and warnings. `cozy_graph` walks up to depth 3 and can filter by type, tag or relation. `cozy_resolve` maps names to pages and lists likely duplicates. `cozy_backlinks` shows what points at a page.

The same signals feed the health score. It counts broken links, duplicate titles and aliases, stale pages, conflicts, orphans, pages the index cannot reach, unsourced pages, missing type or description, oversized pages and uncited sources. Each page starts at 1.0 and loses weight per issue, and the score is the average times 100. Details are on the [wiki health](/wiki-health) page.

## Limits of this description

This page describes Cozy's behavior, not a formal grammar. Edge cases, such as exact precedence between overlapping name matches, are decided by Cozy's implementation. If you build a reader and your results differ from Cozy's on a real workspace, treat Cozy's output as the reference and check against it.

## Frequently asked questions

### Do I need Cozy to use these conventions?

No. They are plain Markdown, so any editor can write them and any tool can read them. Cozy is one reader that computes a graph from them on every save.

### What is the difference between a relation:: line and a triple?

A relation:: line makes a typed relation starting from the current page. A triple names the subject, relation and object explicitly, so it can describe a relation between two other pages.

### How do I link a claim to its evidence?

Link to a file under sources/. Cozy records links into sources/ as cites rather than generic links. See [source citations](/source-citations).

### What happens to a link that points at nothing?

It is recorded as broken and counted in the health report, so it stays visible until you fix or remove it. See [wiki health](/wiki-health).
