Cleaning Up & Migrating Notes
Structure-agnostic field guide for reorganizing Apple Notes libraries and migrating between Apple Notes, Apple Mail, and Markdown knowledge bases.
Large Apple Notes libraries tend to grow organically into dozens or hundreds of deeply nested folders, single-note folders, duplicate subfolder names, and orphaned scratchpads. Reorganizing them manually is tedious, and doing it with naive scripts risks losing attachments or deleting non-empty folders.
This field guide summarizes practical patterns learned from real-world migrations with MacFly. It is completely independent of which organizational system you prefer — whether you use PARA, Johnny.Decimal, topic-based folders, or a flat archive.
The 4-Phase Safe Migration Method
Phase 1: Audit metadata before touching anything
Start with a read-only inventory so you see the actual shape of your library without sending note bodies to any model:
macfly notes overview
macfly notes audit
notes audit highlights the highest-leverage cleanup targets automatically:
- Empty folders (zero notes and zero active subfolders)
- Single-note folders (often signs of over-fragmentation)
- Duplicate folder names across different branches (e.g. multiple
TasksorTemplatesfolders) - Duplicate note titles (often caused by repeated captures or Smart Folders)
- Oldest unmodified notes (candidates for archiving)
Phase 2: Protect sensitive areas first
Before letting an AI agent inspect note contents or suggest a reorganization,
add sensitive folders (credentials, taxes, health, personal) to deny_folders
in ~/.config/macfly/config.json:
"deny_folders": ["Passwords", "Taxes", "Health", "Recently Deleted"]
Tip: Moving a whole folder with
notes_move_folder_contentsonly touches folder metadata and native note objects — no model ever needs to read the contents of sensitive notes just to relocate them into a cleaner folder.
Phase 3: Build the new structure in parallel, then move in batches
Avoid renaming and reshuffling old folders in place. Instead:
- Create the target folders first in one
macfly planusingnotes_create_folder(idempotent — safe to re-run).- Keep nesting shallow (max. 2 levels works well across macOS and iOS).
- If you want deterministic top-level ordering across Mac, iPhone, and iPad,
use numeric prefixes (e.g.
00 ·,10 ·,20 ·,90 ·) since Apple Notes sorts top-level folders alphabetically.
- Move contents folder by folder using
notes_move_folder_contentsin small batches (10–15 folders per plan).- Because MacFly uses Apple Notes’ native
moveoperation, attachments, tables, checklists, images, andapplenotes://internal links stay 100 % intact. - After each batch, run
macfly notes overviewand verify that the total note count is unchanged (N → N, zero notes lost).
- Because MacFly uses Apple Notes’ native
Phase 4: Clean up empty legacy folders bottom-up
Only after all notes are verified in their new homes, remove the now-empty old
folders using notes_delete_empty_folder — starting from the deepest leaf
folders and working upward in rounds.
MacFly enforces two live guards before deleting any folder:
notes.length == 0- zero active child folders referencing it as their container
If anything is still inside, MacFly aborts safely rather than deleting data.
Real-World Apple Notes Edge Cases to Know
- Smart Folders (tag-based folders) are virtual views:
Smart Folders appear in Apple Notes’ folder list, but their notes are only
virtual matches (for example on
#task). Moving notes out of a Smart Folder does not empty it — and because it still reports notes, MacFly will never accidentally delete it. - Locked and shared notes stay put:
Password-protected or externally shared notes cannot be relocated via
automation. Expect their source folder to keep
remaining: 1after a batch move; handle those manually in Apple Notes. - System folders cannot be removed:
Notes(default capture) andQuick Notesare built-in Apple system folders. TreatNotesas your raw capture inbox rather than trying to fight it. - Rich-note edits vs. lossless moves:
Moving a note object is lossless. Replacing a note’s HTML body via scripting
is not — it destroys attachments and checklists. MacFly’s fidelity guard
therefore separates safe
move/appendoperations from destructive body replacement. - macOS folder-count caching during cleanup:
Immediately after deleting child folders, Apple Notes’ cached
folder.folders.lengthcan lag behind reality. MacFly resolves active subfolders from live container references so bottom-up cleanup converges cleanly across rounds.
Keeping It Clean Over Time
Once your library is reorganized, run a quick monthly check:
macfly notes audit
Catching new single-note folders, empty folders, and duplicate titles early takes two minutes — and keeps your Notes library fast, searchable, and easy for both humans and AI agents to navigate.
Cross-System Migrations (Apple Notes & Mail ⇄ Markdown / Git)
Beyond reorganizing folders inside Apple Notes, MacFly supports deterministic migrations between Apple’s native apps and local Markdown repositories (such as Git-backed knowledge bases, Obsidian, or static documentation):
1. Exporting Apple Notes to Markdown + YAML frontmatter
# Export an entire folder tree (mirrors subfolder structure 1:1)
macfly notes export --output ./kb-export --folder "10 · Work" --limit 500
Each note is written as <title>.md with structured YAML frontmatter (title,
id, account, folder, modified_at, revision). By default, DLP
redaction remains active; pass --no-redact when creating a private local
backup.
2. Archiving project emails to Markdown
# Export project or invoice emails as cleaned Markdown files
macfly mail export --output ./project-mails --query "Project Alpha" --limit 50
Each email becomes <date>-<local_id>-<subject>.md with frontmatter (subject,
from, to, cc, date_received, account, mailbox, trust_level) and
quote-trimmed body text.
3. Importing Markdown files into Apple Notes via Plan
When migrating notes into Apple Notes (for example from a Markdown folder or another note tool’s export) so they sync across Mac, iPhone, and iPad:
macfly notes import --input ./markdown-notes --folder "00 · Inbox"
Instead of writing blindly, notes import parses frontmatter titles (or top
# Heading lines) and creates a tamper-evident macfly plan that you
inspect, approve, and apply like any other change.