The Rule That Guarantees a Sync Tool Never Overwrites Your Edits

If you keep your vault closed to anything that writes into it, you probably have a reason. Picture it: you add three paragraphs to a note a tool created, and weeks later you go looking for a sentence and find the original transcript instead. No error, no prompt, no .conflict file. Just your words, gone, and two weeks of other notes built on top of them.

So the rule becomes "tools can read my vault, nothing writes into it." That's safe, and it costs you every thought that happens away from the keyboard, because getting a voice note in by hand is enough work that most of them never make it.

The way out isn't trusting a tool more. It's asking one narrow question and checking the answer yourself: when the tool's copy of a note and your copy disagree, which one wins?

Here is exactly how SpeakPen Sync, the Obsidian community plugin for SpeakPen voice notes, answers it. I've checked this against the plugin's source (version 0.3.1).

The rule: it remembers what it wrote, and leaves anything that's changed

Every time the plugin writes a note, it stores three things about it in its own plugin data: the file's path, a fingerprint of the exact text it wrote (a small FNV-1a hash), and the version of the note on SpeakPen's side.

When SpeakPen later has a newer version of that note (say you fixed the title in the app), the plugin doesn't write straight away. It goes through these steps in order:

1. Has the SpeakPen version actually changed? If not, it does nothing. It doesn't even open the file.
2. Is the file still where the plugin put it? If you've deleted it or moved it somewhere else, the plugin writes a fresh copy in the sync folder. Your moved copy isn't touched.
3. Does the file on disk still hash to exactly what the plugin wrote? If it does, the file is still the plugin's own output, so it gets updated in place.
4. If the hash doesn't match, you've written in it. The plugin skips it. Nothing gets merged and you're never asked to resolve a conflict.

There's no third outcome and no guessing about which edit "looks" important. One changed character, a reworded sentence, or a tag added to the frontmatter all change the hash, and any changed hash means the note belongs to you now.

The comment above that branch in the source says why:

The user has written in this note. Their words are not reproducible from anywhere; the SpeakPen copy is. Never trade one for the other.

That's the whole argument. Your edits exist only in your vault. The SpeakPen version is still in SpeakPen. If the two collide, a rule that throws away the copy you can't get back to keep the one you can is backwards, so this one never does.

It tells you when it leaves something alone

A skip doesn't happen silently. When a sync skips edited notes, Obsidian shows a notice like "1 note changed in SpeakPen but edited here, so left as-is." The developer console gets a line for each skipped note with its title and path. If the same sync also created or updated notes, the notice gives those counts as well.

One thing to understand: the check only runs when SpeakPen has something new for that note. If you edit a note and nothing has changed upstream, the next sync just says "Already up to date," because there was nothing to overwrite in the first place. That matters for how you test it (see below).

The trade you're making

Once you've edited a note, it stops getting updates from SpeakPen. If you later change the title, summary or category in the app, the vault copy stays as it is. It can't change without breaking the rule.

For voice notes that's almost always what you want. You usually edit one to turn a raw transcript into an actual thought, and you don't want that thought reverting to the transcript because something upstream changed. If you do want the new version, the plugin won't merge it in for you. Open the note in SpeakPen and copy across what you need.

The other things a cautious vault owner checks

It doesn't scan your vault. Each sync sends SpeakPen's API one question: which notes changed since the last sync? The plugin keeps a cursor, so a quiet sync is a single request whether you have 12 notes or 1,200. A big first sync is split into pages of 50. The only files it reads are notes it wrote itself, and only when it needs to run the hash check above.

It's one-way. The plugin sends GET requests to speakpen.app and nowhere else. It never uploads your vault, never writes anything back to SpeakPen, and has no telemetry. Editing a note in Obsidian has no effect on the copy in SpeakPen.

Changing the sync folder moves your notes with it. It relocates the notes it's tracking to the new folder, and it won't overwrite anything already there. If a name is taken, the note gets a (1) suffix. Notes you've moved out of the old folder yourself stay where you put them.

Audio isn't linked, on purpose. The API hands out presigned audio URLs that expire within hours, and a permanent note holding a dead link is worse than no link at all. Each note carries a stable speakpen_id in its frontmatter, which is how you find the recording again.

Notes from before 0.3.0 are frozen. Older versions only recorded which notes they'd synced, not where they put them or what they wrote. Without that, the plugin can't safely update or move those notes. It just won't create duplicates of them.

What arrives, and who else can read it

Each recording becomes one Markdown file with frontmatter (speakpen_id, title, category, dates), an AI summary and the full transcript, with the language detected automatically. You can record from iOS (Control Center, the Lock Screen, the Action Button, or Siri with "Record with SpeakPen"), from Android's Quick Settings tile, or from speakpen.app/app in a browser.

Separately, you can connect ChatGPT, Claude or a coding agent to the same notes through SpeakPen's read-only MCP server. It has three tools (recent notes, search, read one note), no write access and no audio, and you can disconnect it under Settings → Connections. That one reads from SpeakPen, not your vault. Setup is at speakpen.app/connect.

The three-minute test

Don't just take my word for any of this. Here's the test:

1. In Obsidian, install SpeakPen Sync from Community plugins.
2. In SpeakPen, go to Settings → Connections, then on the Obsidian card click Generate token. The token is only shown once, so paste it into the plugin settings straight away and pick a folder.
3. Record two short notes and run Sync now. Two files appear.
4. Open one of them and type a line anywhere: "I edited this."
5. In the SpeakPen web app, change the title of both notes.
6. Sync again. The note you didn't touch updates in place. The one you edited stays exactly as you left it, and the notice tells you it was left alone.

Step 5 is what makes this a real test. Without a newer SpeakPen version there's nothing for the plugin to overwrite, so you wouldn't learn anything.

The plugin is free and doesn't limit anything. SpeakPen's free plan gives you 3 recordings a month, up to 5 minutes each, which is enough for this test. Pro is $9.90/month for 60 recordings of up to 20 minutes each.

If a tool can't pass this test, it shouldn't be writing into your vault. If it passes, your old rule can relax a bit. Tools can write here, as long as they back off once you've started editing.

→ How voice notes get into an Obsidian vault

Comments

[Xin Jiang]

Longer version, including how the plugin decides to skip a note you've edited, is on the SpeakPen blog: speakpen.app/blog