open-context open-context
October 29, 2026 · 6 min read

Why open-context Exports Conversations as Markdown

open-context converts every ChatGPT conversation into a plain Markdown (.md) file instead of keeping the original JSON, because Markdown is readable by both people and language models without any extra parsing step. Each file carries the conversation title, timestamps, and a clearly labeled sequence of user and assistant turns — structure a model can use, in a format a person can open in any text editor. That single choice is what lets the same output double as Claude Project knowledge, a searchable local archive, and a plain-text file you can diff in version control.

Key takeaways

  • open-context's MarkdownFormatter turns each conversation into one self-contained .md file: an H1 title, bold metadata lines, then an H2 heading per turn (User, Assistant, or System).
  • Markdown's lighter token footprint than JSON or HTML means more of a model's context window goes to the actual conversation instead of markup — Microsoft's MarkItDown project notes that "Markdown conventions are also highly token-efficient."
  • Claude's documented Project upload list doesn't name the .md extension specifically — it lists PDF, DOCX, CSV, TXT, HTML, ODT, RTF, EPUB, and JSON — but Markdown content works regardless, since Claude reads the text itself, not the file extension.
  • Every filename is sanitized and zero-padded (001-first-conversation.md) by generateFilename(), and an index.md file lists every conversation in order so nothing requires a database to browse.
  • Titles are escaped before they reach a heading — #, *, and _ are backslash-escaped — so a conversation titled "#1 Notes" can't break the Markdown it's rendered into.

The export problem Markdown solves

ChatGPT's own export isn't built for reading. conversations.json stores your entire history as a flat mapping object keyed by message ID, with each node pointing at a parent and a list of children — you have to walk that tree just to get one conversation back in order. That representation makes sense for a client that already has a tree-walking renderer. It's unreadable if you open it directly, and pasting the raw JSON into a chat with Claude burns tokens on brackets, quotes, and key names instead of your actual words.

open-context's conversion pipeline — covered in more depth in From ChatGPT Export to Claude Format — exists to close that gap: parse the export, normalize every message into a common schema, then hand the result to a formatter. Markdown is the formatter it ships with, not because producing JSON would have been harder, but because the output needed to be something a person reads directly and a model reads cheaply.

What the Markdown output actually looks like

src/formatters/markdown.ts builds each conversation file the same way every time. A typical output looks like this:

# How to debug a flaky test

**Created:** 2026-08-01
**Last Updated:** 2026-08-01
**Messages:** 2

---

## User

Why does this test only fail in CI?

## Assistant

A few common causes: shared state between test runs, timezone...

*Model: gpt-4*

---

*Exported from ChatGPT via opencontext*

Three details in that file are doing real work. The role headers (## User, ## Assistant) give the model an unambiguous turn boundary without inventing a custom delimiter. The metadata block at the top is bolded Markdown, not a separate JSON sidecar, so a reader gets context without switching files. And generateFilename() sanitizes the title and zero-pads an index — 007-debug-flaky-test.md — so a folder of hundreds of conversations still sorts and scans in a normal file browser.

A second function, formatIndex(), writes one additional file, index.md, that lists every converted conversation with its filename, creation date, and message count — a table of contents you can open without any tool beyond a text editor.

Why Markdown over JSON or HTML for this specific job

JSON and HTML both carry structure, but neither carries it cheaply for prose. Microsoft's MarkItDown project — built specifically to prepare documents for LLM consumption — states plainly that "Markdown conventions are also highly token-efficient," and notes that mainstream LLMs tend to produce Markdown unprompted in their own responses, which it takes as a sign of how much Markdown the models were trained on. Neither JSON's escaped quotes and bracket nesting nor HTML's opening and closing tags add meaning for a conversation transcript — they're overhead a model has to read past before it reaches the words that matter.

That tradeoff is specific to this use case. JSON is still the right call for open-context's own REST API and its MCP tool responses, where a client needs exact, typed fields. For a document meant to be read — by a person skimming it or a model summarizing it — flat headings and bold labels do the same structural job as JSON's keys and HTML's tags, at a fraction of the character count.

Markdown and Claude Projects: the extension nuance

One thing worth being precise about: Claude's own documentation for file uploads to a Project lists PDF, DOCX, CSV, TXT, HTML, ODT, RTF, EPUB, and JSON as supported document types — it does not name the .md extension by itself. In practice this rarely matters. Claude ingests the text content of a file, not its extension, so a Markdown file saved with a .txt extension, or Markdown text pasted directly into a Project's knowledge or into chat, behaves identically to a native upload — the headings and bold text still parse as structure, because that's just how the characters read. If you want to be extra safe about an upload being recognized, rename the file from .md to .txt before adding it; the content inside doesn't need to change at all.

What this means for your own export

Run npm run dev convert path/to/chatgpt-export.zip or use the web UI, and the conversations/ folder you get back is plain Markdown end to end — no proprietary format, no lock-in, and nothing that requires open-context itself to read later. Upload the whole folder to a Claude Project as knowledge, paste a single conversation into a chat when you need it as context, or just keep it as a local, searchable archive of a service that was never going to let you export it this cleanly on its own.

Convert your own ChatGPT export to Markdown in minutes.

Get started with open-context →

FAQ

Does open-context export ChatGPT conversations as Markdown files?

Yes. open-context's MarkdownFormatter converts each conversation into a standalone .md file with a title, metadata, and one heading per message, plus an index.md file that lists every conversation in order.

Can I upload open-context's Markdown files directly to a Claude Project?

In practice, yes, though Claude's documented Project file list names PDF, DOCX, CSV, TXT, HTML, ODT, RTF, EPUB, and JSON rather than the .md extension by name. Claude reads the text content, not the file extension, so pasting the Markdown directly or saving it with a .txt extension behaves the same way.

Does converting to Markdown lose any information from the original ChatGPT export?

No message content is lost — role, text, timestamps, images, attachments, and the model name all carry through the normalizer before formatting. What it doesn't special-case is ChatGPT's branching: the parser walks the message tree breadth-first from the root, so regenerated or alternate replies can appear in the output alongside the branch ChatGPT's UI shows as current.

Why does open-context use Markdown instead of exporting JSON directly?

JSON is what ChatGPT exports, but it's built for a renderer, not a reader — nested keys and escaped strings cost tokens without adding meaning for a conversation. Markdown keeps the same content behind plain headings a person can skim and a model can parse without stripping markup first.

What happens to images and attachments in the Markdown output?

Each image or attachment is written as a bracketed reference line, like [Image: file-abc123], directly under the message it belongs to, and open-context separately copies the actual image files from the export into an images/ folder next to the conversation markdown.