The Cozy Markdown graph conventions, written as a spec

Updated · By the Cozy team

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 and typed links.

Scope

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

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:

KeyMeaning
typeWhat kind of page this is, such as person or project
descriptionOne line saying what the page is
aliasesOther names that should resolve to this page
tagsFree labels, usable as graph filters
statusLifecycle state of the thing the page describes
as_ofDate 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.

---
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.

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.

[[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.

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 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.

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 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.

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.

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