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

> Export your Roam graph as Markdown, split it into pages, push it into Cozy through the ingest API or browser upload, then run Health to find broken links.

Updated 2026-11-08. Canonical: https://cozy.cloud/import/roam-research

> 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](https://dev.to/onsen/roam-research-review-2026-is-it-still-worth-it-2kin)). 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.

- **Block references and embeds.** Every Roam bullet has a UID, and Roam links at block level. Cozy links at page level. Heptabase documents the same gap in its own Roam import, which brings in journals and pages only, not block-level references ([Heptabase](https://support.heptabase.com/en/articles/10447948-import-notes-from-other-apps)). The converter Jimmy turns block links into page links ([Jimmy](https://marph91.github.io/jimmy/formats/roam_research)). Expect the same here.
- **Queries and attributes.** Roam queries and Datalog do not run in Cozy. They arrive as text.
- **Daily notes.** They export as ordinary pages named by date. Cozy keeps them as files, and your agent can later fold them into topic pages.

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](/compare/roam-research) 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:

```bash
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](/connect/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](/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](/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

- No native Roam importer exists yet. The script and conversion steps are yours to run.
- Block-level references and Roam queries are not preserved as structure.
- Roam has a longer history and a plugin ecosystem. Cozy is newer and agent-first.
- Roam pricing is reported inconsistently by third-party trackers, so this page quotes no number. Check roamresearch.com directly.

For other sources, see the general [Markdown import guide](/import/markdown).

## 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](/import/markdown) 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.
