Brain Dump in an Obsidian vault: what it reads, what it writes

Brain Dump is file-native, and inside an Obsidian vault it is Obsidian-native. It does not export to Obsidian, and it does not keep a parallel copy. It writes into the vault you already have, reads the configuration Obsidian keeps in .obsidian, and defers to it.

That is the difference worth knowing before you link a folder. Most voice-capture apps that claim Obsidian support write a .md file into a directory and ignore the vault entirely. This one reads four of Obsidian's own configuration files and writes three of them back.

How Brain Dump recognizes a vault

Detection is one check: an .obsidian directory at the root of the folder you linked. No toggle, no setup step, no "Obsidian mode." If the directory is there, the folder is a vault.

Once detected, the folder shows up in Folders & Storage labelled Obsidian Vault, with its own icon and accent color, described as an external Markdown vault you point at. The detection result is cached against the folder's size, modification time, inode, and permissions, so it is not re-derived on every read. A config file that exists but cannot be read is deliberately not cached, so an iCloud stall does not pin an empty configuration in place.

The four config files

daily-notes.json is read and never written. Your Daily Notes configuration stays exactly as Obsidian left it.

The writes are splices, not rewrites

This is the part that matters if you have plugins. When Brain Dump changes one of those three files, it reads the current bytes, finds the key that is already present in the file, replaces only that one value, and writes through a coordinated merge. Everything else in the file survives unchanged: keys Brain Dump has never heard of, ordering, formatting, values written by plugins.

types.json gets extra care because it is co-owned by Obsidian and its plugins. Mutations to it are serialized across the whole app, key spelling is preserved with no case folding, unknown type identifiers survive, and the original key order is kept.

Attachment placement follows the vault when you ask it to. Brain Dump has its own per-folder media setting with modes for following Obsidian, using its own default, the vault root, the note's own folder, or a custom path. Only the "follow Obsidian" mode reads attachmentFolderPath, and it resolves Obsidian's own syntax: / means the vault root, . and ./… mean note-relative, and anything else is a vault-relative path.

What actually appears on disk

A note you dictate into a vault folder lands as:

<vault>/<folder>/<Note Title>.md

• The filename is the note's title, sanitized, not a UUID and not a timestamp. Characters Obsidian and the filesystem dislike are substituted: / \ : * ? | become -, " becomes ', < and > become parentheses, runs of whitespace collapse, and leading dots are stripped. A name collision appends 2, 3, and so on before the .md.
• An untitled note gets a placeholder name you can change. Renaming the note in Brain Dump renames the file. Editing the body or the properties does not.
• There is no frontmatter block by default. Writing created_at and updated_at is controlled by a setting that ships off. With it off, those keys are not written, and if they somehow appear they are stripped.
• Attachment embeds are Obsidian wikilinks, written as ![[folder/image.png]], not ![](folder/image.png).
• One hidden directory, .braindump/, is added to the vault. It holds the app's per-note sidecars, editor documents, rendered artifacts, recorded audio, and staging files. It is skipped by Brain Dump's own indexer, and so are .obsidian, .trash, and trash.

The durability machinery stays out of your vault entirely. The write-ahead log and the operation ledger live in Application Support, not in the vault.

If your notes already have frontmatter

Brain Dump preserves it. Unknown keys and the original key order are round-tripped unchanged. title is replaced only if the file already has a title key; the writer never inserts a new one. created_at and updated_at are treated as Brain Dump's to touch only when the frontmatter also carries a braindump_id; otherwise they are assumed to be yours or a plugin's and left alone.

Property extraction, when you use it, has no fixed vocabulary. It writes whatever key the extractor names, in place, preserving the rest of the block byte for byte, and registers the type in .obsidian/types.json.

Editing from both sides

Edit a note in Obsidian and Brain Dump picks it up; edit it in Brain Dump and Obsidian sees the file change. If both sides changed, Brain Dump shows you the two versions and asks, and no path throws one away to keep the other. A prompt occasionally appears when nothing meaningful changed, and choosing Keep mine is safe in that case. The conflict guide covers what each choice does.

Setup

Step 1: Open Folders & Storage

In Brain Dump, go to Settings → Folders & Storage. This screen lists every folder Brain Dump reads and writes: the app-managed iCloud folder, any on-device folders, and any external folders or Obsidian vaults you have linked.

Step 2: Add your vault

Tap Add a folder. Three options:

• New folder: creates a fresh Markdown folder, by default under iCloud Drive → BrainDump. Use this if you do not have a vault yet and want to start one.
• Open an existing folder…: points Brain Dump at a Markdown folder or Obsidian vault you already have. This is the one to use.
• Open temporarily…: browses a folder once without keeping it.

Choose Open an existing folder… and select your vault in the system picker.

Going the other direction works too. Create a new folder in Brain Dump, then in Obsidian use Open folder as vault on that same location. Obsidian writes .obsidian on first open, and Brain Dump picks the vault up from there.

Granting access through the system picker creates a security-scoped bookmark, which is how iOS lets an app keep permission to a folder across launches.

Step 3: Confirm the detection

The folder should now read Obsidian Vault in Folders & Storage. If it does not, the folder you picked has no .obsidian directory at its root, which usually means you selected a parent directory or a subfolder rather than the vault itself.

Step 4: Record a note

Record or type a note in that folder, then open Obsidian and sort by Modified. You should see a file named after the note's title, containing your text and nothing else.

Obsidian syntax Brain Dump handles

Wikilink authoring is the load-bearing one. Typing [[ opens a vault-wide fuzzy autocomplete that ranks candidates by title, filename stem, alias, and path, and accepts #heading sub-queries. Heading and block references resolve for real: [[Note#Heading]] slugifies the heading and finds it, [[Note^block]] finds the block anchor. Aliases declared in frontmatter are indexed and matched.

Two caveats worth stating plainly. Callout types are accepted permissively rather than checked against Obsidian's fixed vocabulary, so > [!anything] parses. And inline #tags written in a note's body are not indexed for search; frontmatter tags: are. Brain Dump also has one extension beyond Obsidian syntax, an @date reminder autocomplete in tasks, which is Brain Dump flavoured rather than standard.

Obsidian Bases

Brain Dump has a Bases client, not a Bases viewer. It parses .base files, evaluates the expression language and formulas, applies filters, and renders table, list, and cards views. It also creates and edits Bases: you can build a filter tree visually, add formulas, change views, and edit note-property cells from a Base row. Find it under Settings → Structured Notes → Bases.

The behaviour is deliberately fail-closed. A filter it cannot represent yields zero rows and a warning rather than a wrong answer. A view type it does not support degrades visibly instead of being silently re-rendered as a table. Unknown syntax in the file is preserved. Invalid YAML, duplicate keys, or a stale fingerprint block the write rather than corrupting the file.

Supported views are narrower than Obsidian's full set: no board, gallery, calendar, or map.

Troubleshooting

My Brain Dump notes do not appear in Obsidian. Confirm the linked folder is the same one Obsidian has open as its vault. If it is in iCloud, check iCloud Drive sync on both devices. If the folder is on-device only, it never syncs through iCloud; only Obsidian Sync, a manual copy, or a shared local folder will move it.

The folder is not labelled "Obsidian Vault." There is no .obsidian directory at the root of the folder you linked. Open the folder as a vault in Obsidian once, and Obsidian will create it.

I deleted a note in Obsidian and it is gone from Brain Dump. Both apps read the same files, so a delete is a delete. Use Obsidian's trash, or keep independent history with the Git backup guide.

Can I use Obsidian templates with Brain Dump? Yes, and more directly than you might expect. Brain Dump reads your templates folder from .obsidian/templates.json and treats every Markdown file in it as a template. It can also write that key back if you point it somewhere else. See the daily journal template guide.

Advanced

Query voice notes with Dataview Dataview reads plain Markdown, and these are plain Markdown files.

LIST
FROM ""
WHERE file.ctime > date(today) - dur(7 days)
SORT file.ctime DESC

Maps of Content Build index notes in Obsidian that link to voice captures. The links are editable from both sides, because [[ autocomplete works in Brain Dump too.

Tag from the properties panel Frontmatter tags: are typed and editable in Brain Dump's properties panel, and they are what the index actually reads. Tagging inline in the body will not make a note findable by tag.

Related guides

• Organize notes with iCloud topic folders: folder structure inside and outside a vault
• Daily journal template: how templates and templates.json fit together
• Backup with Git: version control a vault of voice notes
• Why plain text outlasts a proprietary notes database

Frequently asked questions

Do I need Obsidian Sync? Not if the folder is in iCloud Drive. Obsidian Sync, or a manual copy, is only needed if the folder is on-device only, or you want it on Android or a non-Apple device.

Can I use Brain Dump with Obsidian on Windows? Yes, with iCloud for Windows installed and Obsidian pointed at the synced folder.

Will this work with Obsidian Publish? Yes. Notes in a linked vault publish like any other vault content.

What about Obsidian plugins? The files are plain Markdown, so plugins that read Markdown read them. Dataview, Calendar, Templater, and Advanced Tables all work on plain Markdown. Brain Dump does not implement any plugin's own syntax inside its editor, so a Dataview block stored in a note stays as a code fence there.

What if I stop using Brain Dump? Delete the app and delete the .braindump folder. Your notes, your Obsidian configuration, and your templates are untouched, because they were never Brain Dump's to begin with.