Migrate Roam Research to local Markdown on Mac

Roam Research sparked a revolution in personal knowledge management. When it launched in 2019, Roam introduced knowledge workers, researchers, software engineers, and founders to the transformative power of bi-directional linking, daily notes, and networked thought.

Instead of organizing thoughts into rigid filing cabinet folders or arbitrary tag taxonomies, Roam enabled users to connect concepts organically with [[WikiLinks]], turning a personal notebook into a living “second brain.”

However, as the excitement of the early networked-thought movement matured, long-term Roam users increasingly hit serious architectural, financial, and privacy barriers:

First, the steep subscription tax ($180/year). Roam Research charges $15 per month (or $180 annually) simply to access your own personal thoughts. For users who have maintained graphs for five or six years, that represents over $1,000 in subscription fees for software that has seen minimal core UX development in recent years.

Second, the cloud security and privacy risk. Every idea, private journal entry, confidential company strategy, and client meeting note stored in Roam resides on Google Firebase and Roam’s cloud servers. For founders dealing with sensitive intellectual property, lawyers handling privileged casework, or engineers writing proprietary documentation, storing unencrypted notes in a third-party cloud poses unacceptable risk.

Third, the Firebase image trap. When you paste an image or PDF into Roam, it does not save the file locally; it uploads the asset to a Google Firebase storage bucket (firebasestorage.googleapis.com). If you ever let your Roam subscription lapse or Roam experiences server issues, your images risk becoming permanently inaccessible dead links.

Fourth, the rigidity of the atomic outliner. Roam treats every thought as an atomic bullet point. While great for brainstorming, writing a comprehensive 2,000-word design document, customer proposal, or technical specification inside a tree of nested bullets is exhausting and unnatural.

Migrating your Roam Research graph to sovereign local CommonMark Markdown (.md) in Oyma preserves your hard-earned web of bidirectional links while delivering the speed of native macOS, zero subscription fees, and complete privacy on Apple Silicon.

The architectural chasm: cloud outliner vs local document graph

Understanding how Roam stores data compared to Oyma demonstrates why local Markdown is the superior long-term foundation for your knowledge:

1. The Roam Research cloud architecture

• Proprietary Clojure/DataScript graph: Roam stores notes as an in-memory graph database hosted in the browser and synchronized via web sockets to cloud databases.
• Remote cloud assets: Media files are stored on external Firebase servers, not on your personal computer.
• Strict outliner model: Every line is an atomic bullet with an assigned 9-character alphanumeric UID (((a1b2c3d4e))).
• Heavy web application: Memory-intensive browser execution that drains MacBook battery and lacks native macOS system integration.

2. Oyma‘s local-first architecture

• Standard CommonMark files: Every note is an open, portable .md text file stored directly in native macOS folders.
• True offline independence: 100% functionality without internet. No cloud synchronization servers, no remote dependencies, and zero monthly fees.
• Sovereign local assets: All images, PDFs, and audio recordings live in your local vault’s assets/ directory on your NVMe drive.
• Native macOS craftsmanship: Instant startup, sub-50ms search with SQLite FTS5, and native Apple Silicon acceleration.

Comprehensive transfer matrix: what moves from Roam Research

Exporting from Roam Research into CommonMark preserves the heart of your graph:

Roam Feature	Conversion Status	Result in Oyma & Local Storage
Page-level [[WikiLinks]]	Clean	Preserved 1:1; bidirectional navigation and backlinks work natively in Oyma.
Nested bullet outlines	Clean	Exported as standard CommonMark indented bullet lists (- ).
Daily Notes pages	Clean	Converted from ordinal strings (“October 9th, 2026”) to clean ISO filenames (2026-10-09.md).
Pasted images & PDFs	Partial	Downloaded from Firebase into a local assets/ folder and linked via relative paths.
Roam attributes (Key:: Value)	Clean	Preserved as clean plain text, bold labels, or YAML frontmatter keys.
Block references (((uid)))	Partial	Replaced with referenced text or mapped to standard Markdown section heading anchors.
Roam queries ({{[[query]]: …}})	Unsupported	Replaced by instant SQLite FTS5 search, tag filters, and interactive Graph View.
Block embeds ({{[[embed]]: …}})	Partial	Content is flattened into standard text blocks or inline quotes.

Step-by-step migration playbook: from Roam to Oyma

The following step-by-step procedure guides you through exporting your graph, archiving remote Firebase assets locally, normalizing dates, and mounting your vault in Oyma.

Step 1: Export your Roam graph as Markdown

1. Open Roam Research in your browser or desktop app.
2. Click the three horizontal dots (•••) in the top-right toolbar.
3. Select Export All.
4. In the format selector, choose Markdown with frontmatter (or Markdown).
5. Click Export All. Roam will generate and download a .zip archive containing all your pages as individual .md files.
6. Extract the zip file into a working directory on your Mac (for example, ~/Downloads/Roam-Export).

Step 2: Download Firebase media attachments locally

By default, Roam exports Markdown files containing remote image links like: ![](https://firebasestorage.googleapis.com/v0/b/firescript-577a2.appspot.com/...)

To make your vault truly self-contained and offline, run this Python script to download every remote image to a local assets/ folder and rewrite the markdown links:

#!/usr/bin/env python3
import os
import re
import urllib.request
import hashlib
from urllib.parse import urlparse

EXPORT_DIR = os.path.expanduser("~/Downloads/Roam-Export")
ASSETS_DIR = os.path.join(EXPORT_DIR, "assets")
os.makedirs(ASSETS_DIR, exist_ok=True)

IMAGE_REGEX = re.compile(r"!\[(.*?)\]\((https?://firebasestorage\.googleapis\.com[^\)]+)\)")

def process_file(filepath):
    with open(filepath, "r", encoding="utf-8") as f:
        content = f.read()

    def replace_image(match):
        alt = match.group(1)
        url = match.group(2)
        try:
            # Generate deterministic filename from URL hash
            url_hash = hashlib.md5(url.encode("utf-8")).hexdigest()[:12]
            ext = ".png"
            if ".jpg" in url.lower() or ".jpeg" in url.lower():
                ext = ".jpg"
            elif ".pdf" in url.lower():
                ext = ".pdf"
            
            filename = f"image-{url_hash}{ext}"
            local_path = os.path.join(ASSETS_DIR, filename)
            
            if not os.path.exists(local_path):
                print(f"Downloading: {filename}")
                urllib.request.urlretrieve(url, local_path)
                
            return f"![{alt}](assets/{filename})"
        except Exception as e:
            print(f"Error downloading {url}: {e}")
            return match.group(0)

    new_content = IMAGE_REGEX.sub(replace_image, content)
    
    if new_content != content:
        with open(filepath, "w", encoding="utf-8") as f:
            f.write(new_content)

for root, _, files in os.walk(EXPORT_DIR):
    for file in files:
        if file.endswith(".md"):
            process_file(os.path.join(root, file))

print("All Firebase media assets downloaded and localized!")

Step 3: Normalize Daily Notes filenames to ISO format

Roam names daily notes in conversational English (e.g., October 9th, 2026.md). Standardizing these to ISO 8601 (2026-10-09.md) ensures they sort chronologically in Finder and Oyma:

#!/usr/bin/env python3
import os
import re
from datetime import datetime

EXPORT_DIR = os.path.expanduser("~/Downloads/Roam-Export")

# Match dates like "October 9th, 2026.md"
DATE_PATTERN = re.compile(r"^([A-Za-z]+)\s+(\d{1,2})(?:st|nd|rd|th),\s+(\d{4})\.md$")

for filename in os.listdir(EXPORT_DIR):
    match = DATE_PATTERN.match(filename)
    if match:
        month_str, day_str, year_str = match.groups()
        try:
            date_obj = datetime.strptime(f"{month_str} {day_str} {year_str}", "%B %d %Y")
            new_filename = date_obj.strftime("%Y-%m-%d.md")
            
            old_path = os.path.join(EXPORT_DIR, filename)
            new_path = os.path.join(EXPORT_DIR, new_filename)
            
            os.rename(old_path, new_path)
            print(f"Renamed: {filename} -> {new_filename}")
        except ValueError:
            pass

print("Daily notes filenames successfully normalized!")

Step 4: Open your vault in Oyma

1. Move your cleaned folder to your preferred notes location:

mv ~/Downloads/Roam-Export ~/Documents/Notes/Roam-Vault

2. Launch Oyma on your Mac.
3. Select Open vault (or press ⌘O).
4. Select ~/Documents/Notes/Roam-Vault.

Oyma instantly parses your entire graph:

• Your [[WikiLinks]] automatically resolve across all pages.
• The interactive Graph View renders your interconnected web of ideas.
• Fast offline search scans your entire library in milliseconds.
• All downloaded images render crisp and local.

What Oyma adds to your Roam workflow

Migrating to Oyma does not mean abandoning the power of networked thought—it amplifies it with modern tools built specifically for macOS:

1. Hybrid writing: outliner lists alongside fluid prose

In Oyma, you are never trapped in a rigid outliner. You can structure complex project task lists with indented checkboxes and collapsible bullets, while writing long-form design proposals, technical articles, and customer documentation in expansive, beautiful typography.

2. High-performance spreadsheet tables

Roam’s table support was rudimentary and difficult to format. Oyma includes spreadsheet-like tables with keyboard navigation (Tab/Enter), formula support, instant column sorting, and seamless copy-pasting to and from Apple Numbers or Microsoft Excel—all saved as clean GFM Markdown on disk.

3. Native botless meeting capture and transcription

Many Roam users use their daily notes for meeting logs. Instead of typing frantically during calls, Oyma uses macOS ScreenCaptureKit to record microphone and system audio without sending a bot to your Google Meet or Zoom call. On-device Whisper models transcribe the audio with 100% privacy, and local LLMs generate summaries and action items directly into your notes.

4. Zero recurring subscriptions and 100% local privacy

Free yourself from Roam’s $180 annual subscription tax. Your notes reside on your own Mac, fully private, fully yours, and completely accessible for decades to come.

Reclaim your second brain

The ideas you capture represent your life’s work. Entrusting them to a proprietary cloud service with expensive recurring subscriptions leaves your knowledge base vulnerable.

By migrating your Roam Research graph to Oyma, you preserve the networked power of your notes while securing permanent ownership on open, timeless Markdown standards.

What transfers from Roam Research to local Markdown

Migrating from Roam Research to sovereign Markdown (.md) preserves your core intellectual property while changing how formatting blocks are stored. Here is our empirically tested fidelity matrix:

Step-by-step migration procedure

Follow this sequence to export your Roam Research library safely and open it in Oyma without data loss:

1. Export your complete Roam Research graph

   In Roam Research, click the three-dots menu in the top-right corner and select 'Export All'. Choose 'Markdown with frontmatter' or 'JSON'. Roam generates and downloads a zipped archive containing all graph pages as discrete markdown files.

2. Download remote Firebase image attachments locally

   Roam embeds images as remote URLs pointing to Google Firebase (firebasestorage.googleapis.com). Run an automated media-fetch script to download all remote images into a local `assets/` directory and rewrite image links to local relative paths (``). This prevents losing attachments when closing your Roam account.

3. Normalize Roam Daily Notes dates to standard ISO format

   Roam names daily journal entries in ordinal prose format (such as 'October 9th, 2026.md'). Run an open-source date-renaming script to convert these filenames into standard ISO format ('2026-10-09.md') for clean chronological sorting in macOS Finder.

4. Open the folder directly in Oyma

   Launch Oyma, select 'Open vault', and choose your converted graph directory. Oyma instantly resolves your bidirectional [[WikiLinks]], maps your knowledge graph, builds an offline full-text search index, and presents your notes in our fluid live-preview editor.

Known conversion gaps and practical workarounds

Every proprietary note system utilizes features that have no 1:1 equivalent in plain Markdown. Here is how to navigate Roam Research's structural limitations:

• Atomic block references: Roam allows referencing any individual bullet point via a 9-character UID (`((uid))`); standard Markdown links connect pages or headings.
• Cloud Firebase image hosting: Roam stores media attachments on Google Firebase servers; an automated local download step is required to achieve true offline independence.
• Proprietary Datalog queries: Dynamic `{{[[query]]: ...}}` blocks run inside Roam's cloud Clojure runtime and must be converted to standard searches or static lists.

Frequently asked questions

Why are Roam Research users migrating to local Markdown?

Roam Research costs $15 per month ($180/year) for cloud-hosted software that stores your private intellectual thoughts on external servers. Migrating to Oyma gives you local data sovereignty on macOS, sub-50ms offline search, zero subscription fees, and open CommonMark files that never expire.

What happens to my Roam images when I cancel my Roam subscription?

If you only do a standard text export, image links will continue pointing to Roam's Firebase cloud URLs. If Roam closes your account or cleans up storage, those images will break. Running a media-downloader script pulls every image to your local Mac disk into an `assets/` folder, ensuring permanent local preservation.

How do Roam's [[WikiLinks]] and Graph View compare to Oyma?

Both systems treat bidirectional links as first-class citizens. When you open your exported Roam notes in Oyma, every `[[WikiLink]]` connects automatically, backlinks populate in the side inspector, and our interactive 60fps Graph View renders your network of ideas natively on Apple Silicon.

Does Oyma force me into an outliner format like Roam?

No. Oyma supports standard Markdown bullet lists and outlines, but also lets you write expansive, long-form prose, essays, documentation, and tables without being forced into an endless hierarchy of bullet points.