How to export Roam Research to Markdown and bring it into Cozy

Updated · By the Cozy team

To move Roam Research into Cozy, export your graph as Markdown from Roam, split the export into one file per page, then upload the files in the browser or push them with Cozy's ingest API. Cozy has no native Roam importer today, so the path is export, convert, push. Block references need manual attention.

What you get from a Roam export

Roam stores your graph in its own database on its servers. Reviews report that JSON and Markdown export are available, and rate portability below Obsidian and Logseq (review). Take the Markdown export for this guide, and keep the JSON export as a backup in case you need the block structure later.

Cozy stores plain Markdown, text, JSON and CSV. Page links written as [[Page name]] carry over as wikilinks, and Cozy builds backlinks from them on every save. Roam's nested bullets become nested Markdown lists, which Cozy stores as written.

What does not carry over cleanly

Be clear about the losses before you start.

If block-level linking is central to how you think, keep Roam for that and use Cozy for the pages your agents need. The Roam and Cozy comparison covers where Roam is stronger.

Step 1: Export and split

  1. Export your graph from Roam as Markdown and unzip it.
  2. Check that each page is its own .md file. If the export is a single large file, split it on page headings so each page becomes a file named after its title.
  3. Keep every file under the size limits. Curated wiki files can be up to 90,000 bytes. Imported sources can be up to 1,500,000 bytes.

Step 2: Choose a landing folder

Cozy has four folders: wiki/ for curated pages, sources/ for imported evidence, skills/ and agents/. Imports through the ingest API land in the built-in Inbox as sources. That is the safer place for a raw Roam dump. Sources are treated as untrusted data with stable IDs, and your agent can then promote the useful pages into wiki/ with citations back to the source.

Step 3: Push the files

You have two routes.

Browser upload. Upload up to 25 files per selection, 1 MB per file. This works for a small graph or a trial batch.

Ingest API. For a full graph, send documents in batches of 25, with up to 1.5 MB each:

curl -X POST "https://cozy.cloud/api/wiki/workspaces/$COZY_WORKSPACE/ingest" \
  -H "Authorization: Bearer $COZY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"documents":[{"id":"roam/Project Alpha","content":"# Project Alpha\n- Kickoff notes with [[People]]"}]}'

Use a stable id for each page, such as roam/ plus the page title. A stable id means a re-push updates the same source instead of creating a duplicate. Sources you delete are never re-imported, so you can prune without fighting the next run. For a single file you can also post raw Markdown with ?id= on the URL.

A short script that loops over the exported files and posts them 25 at a time is enough. Create the bearer credential under Agents, give it the source-write scope, and revoke it when the import is done.

Step 4: Let your agent organize the result

Cozy runs no model itself, so you bring your own agent. Connect it through the hosted MCP endpoint, for example with Claude Code, and ask it to read the imported sources, write curated pages with frontmatter, and link them. Typed relations such as relation:: [[target]] give you more than Roam's plain backlinks, and typed links explains the syntax. Search is lexical, so descriptive titles and aliases on migrated pages help your agent find them.

Step 5: Check the result with Health

After the import, run Health. It reports broken links, orphans, duplicate titles and aliases, pages that index.md cannot reach, and uncited sources. Roam graphs often contain many references to pages that were never created, so expect broken links at first. The "next" list orders fixes by priority, and wiki health describes how scoring works.

Every edit after the import is versioned. Cozy keeps the last 50 revisions of each file, and deletions are tombstones you can restore.

Honest limits

For other sources, see the general Markdown import guide.

Frequently asked questions

Does Cozy have a native Roam Research importer?

No. You export Roam as Markdown, split it into one file per page, and upload it in the browser or push it through the ingest API. A native importer is not available today.

What happens to Roam block references?

Cozy links at page level, so block references and embeds do not survive as structure. Other tools show the same gap, and converters typically turn block links into page links. Review those spots by hand or ask your agent to rewrite them.

Where do imported Roam pages go in Cozy?

Ingest API documents go to the built-in Inbox as sources by default. Your agent can then write curated pages in wiki/ that cite those sources. See Markdown import for the general flow.

Can I re-run the import without creating duplicates?

Yes, if you give each document a stable id. Pushing the same id again updates that source. Sources you deleted in Cozy are never re-imported.

How large can an imported Roam page be?

Browser upload allows 1 MB per file and 25 files per selection. The ingest API accepts 25 documents per request with 1.5 MB each. Curated wiki files are capped at 90,000 bytes.

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