> ## Documentation Index
> Fetch the complete documentation index at: https://learn.cleftnotes.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Local Sync
> Save every Cleft note as a Markdown file on Mac, iPhone, or iPad. Works with Obsidian, NotePlan, Logseq, Drafts, or any folder
Local Sync is **free for every Mac, iPhone, and iPad user** as of v1.14.0. [Cleft Plus](/user-guides/upgrade-to-plus) lets you point exports at a custom folder: your Obsidian vault, a NotePlan project, a Logseq graph, or anywhere on disk. Free users get Cleft's Documents/Cleft Notes folder.
## What is Local Sync?
Local Sync writes every Cleft note to your device as a `.md` file (and, if you want, the original audio recording next to it as an `.m4a`). When you record a new note, edit a title, change a tag, or a note arrives via cross-device sync, the file on disk updates to match. Works on Mac, iPhone, and iPad.
Local Sync is an export. It adds copies to your folder without changing how Cleft otherwise stores, syncs, or processes your notes and recordings.
This is **one-way sync**: Cleft is the source of truth. Edits you make to the `.md` files in your vault are silently overwritten the next time Cleft syncs that note. Same contract as Notion auto-send.
## Free or Plus
| | Free | Plus |
| ---------------------- | ------------------------------------ | -------------------------------------------------------------------------- |
| Local Sync | Default-on | Default-on |
| Where files land | Cleft's Documents/Cleft Notes folder | Any folder you pick (Obsidian vault, NotePlan project, Logseq graph, etc.) |
| Audio companion (.m4a) | Free toggle | Free toggle |
| Turn it off | Free toggle | Free toggle |
Plus differentiates on **destination choice**, not feature existence. Free users who want exports inside an Obsidian vault, NotePlan folder, or anywhere other than Cleft's Documents/Cleft Notes folder upgrade to Plus to unlock the picker.
## First launch
The first time you open Cleft on Mac, iPhone, or iPad running v1.14.0 or later, a one-time sheet introduces Local Sync:
* **Use default folder.** Accepts Cleft's Documents/Cleft Notes folder. Nothing else to configure.
* **Choose folder.** Pick your own folder ([Plus](/user-guides/upgrade-to-plus)). Routes to the picker if you're already on Plus, or to the upgrade screen if you're not.
* **Don't save files.** Turns Local Sync off entirely. You can change your mind any time in **Settings → Local Sync**.
If you choose either folder option, Cleft then asks whether to **Save existing notes as files** or leave that for later. New and edited notes keep saving automatically either way.
You'll only see the first-launch sheet once. After that, the master "Save notes as files" toggle in Settings is the off-switch.
**Already had Local Sync set up before v1.14.0?** You'll see a different sheet (a one-time migration heads-up) that explains what's about to change on disk and lets you reveal your vault for a backup first. See [Migrating from earlier versions](#migrating-from-earlier-versions) below.
## How files are named
Filenames are readable in your vault sidebar:
```
2026-05-06-meeting-with-jonny-12431.md
```
* The date is `createdAt` in UTC, so a 23:30-recorded note doesn't drift across day boundaries on a different-timezone device.
* The slug is a kebab-case ASCII-folded rendering of your title, capped at 60 characters.
* The trailing number is the immutable Cleft note ID. Multiple "untitled" notes never collide, and it's how files get matched up when titles change.
**Smart title renames.** When your title changes (and the slug regenerates), Cleft renames the existing file *before* overwriting content. On recent Obsidian (1.4 and later) this usually lets Obsidian recognise the rename and keep your wikilinks pointing at the note. It stays best-effort, though: on a slow disk, a busy system, or an iOS-only Obsidian setup, the rename can register as a delete-and-create and break links. If that happens, recover the note by its `cleft_id:` (see Troubleshooting).
## What's inside each file
```markdown theme={null}
---
cleft_id: 12431
title: "My note title"
tags: ["work", "ideas"]
created: 2026-05-06T10:30:00Z
updated: 2026-05-06T11:15:00Z
source: cleft
transcript: "full transcript on one line"
---
AI-generated summary goes here.
#work #ideas
```
All keys are lowercase English (never localised), so Obsidian Properties, NotePlan, and Dataview queries work the same regardless of your device language.
| Field | What it is |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cleft_id` | Stable Cleft note ID. Namespaced under `cleft_` so it can't collide with `id:` fields written by other tools (Readwise, Notion exports, Templater) sharing your vault. Grep `^cleft_id: 12431` to find a note by ID even after manual filename changes. |
| `title` | Your note's title (YAML-quoted, so titles with `:` or `"` round-trip safely) |
| `tags` | Array of tags as a YAML flow-sequence, clickable in Obsidian's Properties panel |
| `created` | When the note was created (UTC, ISO 8601). For Dataview sorting, NotePlan calendar grouping, Drafts smart folders |
| `updated` | When the note was last changed (UTC, ISO 8601) |
| `source` | Always `cleft`. Filter for Cleft-originated notes via Dataview |
| `transcript` | Full transcript on one line (newlines collapsed to spaces) |
Inline `#hashtags` after the body light up tag clickability in Obsidian preview, NotePlan search, and Drafts' tag panel. None of those see the YAML `tags:` field as clickable.
**Version-controlling your vault?** Re-exporting an unchanged note produces a byte-identical file, so a `git diff` only flips lines for real changes. One caveat: when a note's title changes, Cleft renames the file, which git records as a delete plus an add, so per-file history doesn't carry across the rename. The note is still recoverable by its `cleft_id:`.
## Audio companion
A free toggle in **Settings → Local Sync** controls whether Cleft writes the original audio recording next to each markdown file. Default is **on for new installs**, **off for existing Local Sync users** (so a vault inside iCloud Drive, Dropbox, or Obsidian Sync doesn't suddenly start syncing hundreds of MB of audio).
* The exported `.m4a` is the recording **as it was made**. No perceptual filters touch the file, and only AAC codec artefacts apply. Cleft does not re-encode to MP3, WAV, or FLAC.
* Filename mirrors the markdown's basename: `2026-05-06-meeting-12431.m4a` next to `2026-05-06-meeting-12431.md`. In Obsidian, an embed like `![[2026-05-06-meeting-12431.m4a]]` works without manual wiring.
* **Notes recorded on iPhone or Apple Watch:** the markdown exports immediately, but the original audio is per-device-local. On a device (like your Mac) that does not yet have the recording, the audio sidecar is skipped until you download or play that note there. The note text, tags, and summary still sync as usual.
* **On-disk footprint** is shown in Settings (file count and total size) so the cost is visible at a glance.
## Setup
### macOS (Plus: pick a custom folder)
If you're on Plus and want exports to land in your Obsidian vault, NotePlan project, Logseq graph, or anywhere other than the default folder:
1. Open Cleft Settings (press `⌘ + ,` or click the gear icon)
2. Go to **Local Sync**
3. Find **Local Sync** and click **Choose Custom Folder…**
Pick the parent folder: your Obsidian vault root, NotePlan folder, Logseq graph root, or any folder you want Cleft to write into.
On Mac, Cleft creates a dedicated subfolder inside it so your Cleft exports stay separate and never collide with your existing file structure.
Click **Use Folder** on the alert. Cleft now has permission to write to the folder, and your notes start exporting instantly.
Use the reveal button on the Sync Folder row to open your active sync folder in Finder, or **Show path** to check the exact location. To change folder later, click **Choose Custom Folder…** again. The old folder stays untouched on disk.
### iPhone and iPad
Setup is the same on iPhone and iPad. Open Settings, go to **Local Sync**, and pick a folder:
* **Free users** get Cleft's Documents/Cleft Notes folder (out of the box, no configuration needed). On iPhone and iPad you'll find it in the Files app under **On My iPhone → Cleft** (or **On My iPad → Cleft**).
* **Plus users** tap **Choose Custom Folder…** to pick any folder on the device: an Obsidian vault "Store on this iPhone," a Bear local notebook, or your own custom folder via Files app. On iPhone and iPad, Cleft writes to the exact folder you select.
iCloud Drive folders work but are best-effort; Files-app local folders are the recommended path. Once you've picked a folder, your notes start exporting immediately. Use **Show path** in Settings to check the active location.
## Save existing notes as files
Local Sync saves new and updated notes automatically once it is on. If you want Markdown files for notes that were already in Cleft, including archived notes, use **Save existing notes as files** in Settings.
While the backfill runs, Cleft shows progress and keeps the regular Local Sync controls available. You can cancel the backfill without turning off automatic saving for new or updated notes.
## App-specific guides
The setup is the same for every app. Point Local Sync at the right folder. Each app page covers how the synced files render and any app-specific tips:
* **[Obsidian](/user-guides/integrations/obsidian/overview).** Frontmatter renders as Properties; wikilinks preserved on title renames; Dataview-friendly.
* **[NotePlan](/user-guides/integrations/noteplan/overview).** Inline tags clickable; project-folder workflow; calendar views are filename-driven.
* **[Logseq](/user-guides/integrations/logseq/overview).** Point the picker at `/pages/`. Cleft notes appear as Logseq pages alongside the rest of the graph; inline `#tags` work natively.
* **[Drafts](/user-guides/integrations/drafts/overview).** Drafts is database-backed, not folder-watched, so the [Apple Shortcut](/user-guides/integrations/drafts/shortcuts/cleft-voice-note-to-drafts-inbox) is the recommended path. Local Sync works as a file-based fallback you can drag-drop or import.
* **[Bear](/user-guides/integrations/bear/overview).** Like Drafts, Bear stores notes in its own database, so it isn't folder-watched. Local Sync + manual import works today; a native Bear URL-scheme integration is on the roadmap.
## Migrating from earlier versions
If you had Local Sync set up before v1.14.0, you'll see a one-time sheet on Mac, iPhone, or iPad launch explaining what's about to change on disk:
1. **Filenames** migrate from `cleft_12431.md` to `2026-05-06-meeting-with-jonny-12431.md`. Migration is **lazy and per-note**. Each file gets renamed forward the next time that note is edited or re-exported. Notes you never touch again keep the old name indefinitely (frontmatter is correct either way).
2. **Frontmatter** gains `cleft_id:` as the first field and switches to lowercase English keys (`title:` not `Title:`). Any Dataview or Templater queries on the old `Title` key will need updating.
3. **Audio companion** export is available but stays **off** for you on this update. Turn it on from Settings if you want it. Defaulting it on for an existing vault inside iCloud Drive or Dropbox would create a sudden bandwidth spike on the next recording.
The sheet has a "Reveal Vault in Finder" button (Mac) so you can take a backup before the migration begins. On iPhone and iPad, navigate to your folder via Files for the same effect. The "Got it" button dismisses the sheet permanently.
## Troubleshooting
**Notes aren't showing up**
1. Check **Settings → Local Sync**. Is the master "Save notes as files" toggle on? It wins over every other setting.
2. Look for the folder. Free users land in Cleft's Documents/Cleft Notes folder, which is in the Files app under On My iPhone (or iPad) → Cleft. On Mac, Plus users with a custom folder land in a dedicated subfolder inside the parent you picked. On iPhone or iPad, Cleft writes to the folder you picked via the Files app.
3. On Mac, use the reveal control on the Sync Folder row to open the active folder in Finder, or **Show path** to check the exact location. On iPhone and iPad, use **Show path**, then open that location in Files.
4. Did the note actually save in Cleft? If it's not in Cleft's own list, this is a recording issue, not a sync issue.
5. On iPhone or iPad, is your folder inside iCloud Drive? iCloud Drive support is best-effort in this release. Try a local Files-app folder (Obsidian "Store on this iPhone", Bear local notebook, or any local folder) for the most reliable path.
6. On Mac, folder on a network drive (SMB, Dropbox)? Those can be flaky with security-scoped bookmarks. Try a local folder first.
**My German/French/Spanish title shows `Titel:` instead of `title:` in Obsidian Properties**
This was a bug in builds before v1.14.0. Update Cleft, and re-exporting will fix the frontmatter. The file syncs on any change: title regen, tag edit, append, or sync arrival.
**Old filenames like `cleft_12431.md` are still in my vault**
That's the pre-v1.14.0 format. Migration is lazy: files get renamed to `{YYYY-MM-DD}-{slug}-{noteId}.md` the next time that note is edited or re-exported. Notes you never touch again keep the old name indefinitely. To force migration of every file at once, bulk-regenerate summaries; there's no one-shot sweep.
**Wikilinks broke after I retitled a note**
Obsidian's external-rename heuristic is best-effort. On a slow disk, busy system, or iOS-only setup, renames can coalesce into delete+create instead of a pure rename. Recover the note ID via the `cleft_id:` field in frontmatter (`grep "^cleft_id: 12431" *.md`) and manually update the wikilink to the new filename.
**Markdown is appearing but the audio file is missing for some notes**
Expected for notes whose original recording has not downloaded to this device yet. Cross-device sync moves the *note* (text, metadata, summary), but the audio file is per-device-local. Play or download the note on this device and the next export catches it.
**Audio files aren't appearing at all, only markdown**
Check **Settings → Local Sync**. Is the audio toggle on? Default is on for new installs but off for users who had Local Sync set up before v1.14.0. Flip it on and your next note will export the audio.
## iOS and iPadOS
Local Sync is available on iPhone and iPad as of v1.14.0. The setup is the same: **Settings → Local Sync**. Free users get Cleft's Documents/Cleft Notes folder, Plus users can pick any folder on the device.
**File apps:** The folder picker works with any folder in the Files app: Obsidian "Store on this iPhone" vaults, Bear local notebooks, or your own custom folder. **iCloud Drive folders are best-effort** in this release; Files-app local folders are the recommended path.
**Reveal location:** iPhone and iPad can show the active path in Settings, but they cannot reveal an arbitrary security-scoped folder in Files the way Mac can reveal it in Finder. Navigate directly via Files instead.
## Limitations
* **One-way sync.** Cleft → folder, never the reverse. Edits in your vault are overwritten on the next Cleft sync of that note.
* **No wikilinks in the template.** Cleft 1.x has no data model for inter-note references; coming with the Studio engine in 2.0.
* **Persistent failures surface in Settings.** Local Sync keeps retrying automatically. If the folder stays inaccessible, Cleft shows a Settings banner; custom-folder users can choose the folder again from there.
* **iCloud Drive on iOS/iPadOS is best-effort.** Reads of not-yet-downloaded files and recovery after iOS clears cached content aren't fully handled yet. Local Files-app folders are the recommended path for now.
* **Network and cloud-synced folders are best-effort on Mac too.** Custom folders on SMB shares, Dropbox, or other network drives can lose access intermittently. Cleft retries on the next sync, but a local folder is the most reliable destination.
## What's different from Notion auto-send?
| Aspect | Local Sync | Notion |
| ----------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------- |
| Retry on failure | Automatic on every poll; Local Sync keeps retrying even after a banner appears | Paused after 3 failures (account-state errors) |
| User notification | Settings banner after persistent folder access failures | Toast on failure + Settings banner on persistent issues |
| Subscription gate | Folder picker is Plus-only; existing custom folders keep working if you lapse | Runtime check; lapses disable auto-send |
Filesystem errors (security-scope wobble, briefly-locked files, full disk) are usually transient, so silent retry is the right answer. Notion failures are typically account-state (auth expired, database deleted), so a pause-and-notify is needed.
