Messages
How the Messages export works, from connecting to fixing problems.
Connect
Press “connect” on the Messages card. The panel opens in ~/Library/Messages: press “Select this folder”. Exporter reads only that folder, with no Full Disk Access. Then press “select export folder”.
The first pass reads your whole history into the app’s index, which takes minutes on a long history; the indexed row shows its progress, and “sync now” stays greyed out until it finishes.
Where the files go
One Markdown file per conversation, all at the top of the export folder: Anna Kowalski.md for a person. A group’s file name carries its conversation id, like Cabin crew-57.md, so a new member never renames it. Photos, video and audio go into attachments/, a folder per conversation. A folder right in your home folder, like ~/Documents, gets a messages-export folder inside it; a deeper one, like ~/Documents/messages, is used as it is.
What is exported
The conversations ticked on the card. The tabs only filter the list: All, People, Groups, Recent (the last 30 days), Popular (the most messages) and Unread.
A sync writes only conversations with something new. After you unlock Messages, the next sync writes every conversation. After you tick an older conversation, press “full resync” to write it now; otherwise it arrives when it next gets a message.
In the file, a heading per day, then one block per message: who sent it, when, and a link that opens the conversation in Messages. A reply links to the message it answers, an edit keeps each earlier version as a footnote, reactions sit on a line under the message, and every message ends with a block id you can link to. With Contacts exported too, each participant links to their contact file, and the contact lists the conversations back.
Media
Photos, video and audio are copied into attachments/, and iPhone HEIC photos are converted to JPEG so editors can show them. Media that was never downloaded to this Mac is named in the file instead of embedded.
Format
Always Markdown.
The file
| key | holds |
|---|---|
title |
the person or the group |
id |
the conversation’s id |
created, modified |
the first and the latest message |
source_url |
an sms:// link to the first participant, which opens the conversation |
participants |
each person, as a link to their contact file when Contacts is exported, and Me |
is_group |
true for a group |
message_count |
how many messages |
service |
the conversation’s service, like iMessage |
---
title: "Anna Kowalski"
id: "412"
created: 2026-03-09T18:02:11
modified: 2026-03-09T18:04:10
source_url: "sms://+14155550123"
participants: ["[[contacts/Anna Kowalski]]", "Me"]
is_group: false
message_count: 2
service: "iMessage"
---
# Anna Kowalski
## Monday, March 9, 2026
**[[contacts/Anna Kowalski|Anna Kowalski]]** [open](sms://+14155550123) (2026-03-09 18:02:11)
Are we still on for the cabin weekend?
^msg-7C1E2A9B4F30
**[Me]** (2026-03-09 18:04:10)
> replying to [[#^msg-7C1E2A9B4F30]]
Yes! Ferry at 9:40 on Friday (edited) [^e1]
> 👍 Anna Kowalski
^msg-A83D5E6F0B12
[^e1]: was "Yes! Ferry at 9:10 on Friday" (2026-03-09 18:04:10)Free and unlocked
Your 10 most recent conversations among the ones you ticked export and keep syncing free; the rest need the one-time unlock (pricing).
Sync and full resync
While Exporter runs, new messages reach the index and the conversations they belong to are written again. A conversation deleted in Messages leaves the export on the next sync.
“full resync” asks first, then removes only the files Exporter wrote, copied media included, and writes every conversation again from the index. Anything else in the export folder stays.
Problems and fixes
- “no chat.db in that folder (pick the Messages folder itself)”: press “connect” again and select the folder the panel opens in
- “sync now” is greyed out: the first pass is still running; the
indexedrow shows how far it is - older conversations are missing after unlocking: press “sync now”, which writes every conversation
- a photo is missing: open the conversation in Messages so the photo downloads, then sync again
- names are plain text: export Contacts too. Conversations written after that link their people, and “full resync” writes them all again now
Contacts