Roam Research

Graph ops

Call get_graph_guidelines once per graph per session before the first read or write. Use the connected roam or roam_research MCP tools. Honor that graph's roamSyntax for ordinary blocks.

When a write includes a mermaid diagram, load the matching reference below and write a {{mermaid}} block. A code fence shows the mermaid source and does not render the picture.

When a write includes any other code snippet, load the code fence reference.

Why MCP mermaid breaks

create_page and create_block parse a nested - bullet tree. A newline outside a code fence is a new block. update_block writes one block's string literally and does not create children. The two characters \ and n are not a line break. get_block prints that pair where a newline is, and passing the pair to update_block stores it. Mermaid does not treat the pair as a new statement.

{{mermaid}} turns its children into mermaid source. Those children are still Roam blocks, so this markup is consumed before mermaid runs: [alias], [[page]], {{component}}, ((uid)).

A bar or xy chart needs []. Roam consumes those brackets before mermaid runs. Write a pie instead.

Roam's UI docs nest --> bullets under {{mermaid}}. That path is not either reference dialect. Do not copy UI flowchart examples into create_block markdown.