---
name: braindump-import
description: Bulk-import a folder of markdown notes (an Obsidian vault, a notes export, a docs folder) into the user's BrainDump through the MCP dump_thought tool. Use when the user asks to import, migrate, upload or back-fill notes into BrainDump. Always does a dry run and gets the user's OK first.
---

# BrainDump import

Moves a folder of `.md` files into BrainDump, one thought per note, through `dump_thought`. You need a **read and
write** connection (the user allowed read and write when they signed in). Read the `braindump` skill too.

## 1. Ask

- Which folder.
- Where the notes go: private (the connection must include private notes) or one shared space. For a space you need its
  `space_id`: take it from a `search_knowledge` result in that space, or ask the user. Never guess one.

## 2. Dry run (always first, writes nothing)

Walk the folder and build the plan:

- **Skip** `.obsidian/`, `.trash/`, `.git/` and any other dot folder; every file that is not `.md` (images, PDFs,
  canvases: attachments are not imported); attachment folders (`attachments/`, `assets/`, `_resources/`); and empty
  notes (nothing left after removing frontmatter and whitespace).
- **Secret-scan** every note. Flag and skip a file that contains any of these, and list it (path and kind only, never
  the matched text):
  - private key blocks: `-----BEGIN ... PRIVATE KEY-----`
  - API keys and tokens: `AKIA[0-9A-Z]{16}`, `sk-[A-Za-z0-9_-]{20,}`, `ghp_`/`github_pat_`, `xox[abpr]-`,
    `bd_mcp_[0-9a-f]{32}`, `AIza[0-9A-Za-z_-]{35}`, JWTs (`eyJ...\.eyJ...\.`)
  - `password`, `passwd`, `secret`, `api_key` or `token` followed by `:` or `=` and a value
  - 13-19 digit card-like numbers, IBANs, recovery or seed phrases
  When unsure, skip and list it. The user can fix the file and run the import again.
- **Title**: the file name without `.md`.
- **Tags**: each folder between the vault root and the file becomes a `#tag` (lowercase, spaces to `-`):
  `Clients/Acme Corp/kickoff.md` gets `#clients #acme-corp`. Keep frontmatter `tags:` as `#tags` too. Put the tags
  on the last line of the body.
- **Body**: drop YAML frontmatter. Keep `[[Page]]` and `[[Page|alias]]` as written: BrainDump links each one to the
  note titled `Page` (import the linked notes too). Drop `![[embeds]]`.
- **Split** a note whose title plus body is over 20 KB (BrainDump caps a note at 20,480 characters): cut at headings,
  then at blank lines, into parts of at most 19,000 characters. Title them `Name (part 1 of 3)`, and so on.
- **Order** oldest first (file modified time), so the feed reads in order.

Show the user: notes to import, parts after splitting, skipped files by reason, flagged files, the destination, and
the time it will take (parts ÷ 50 minutes). Wait for their OK.

## 3. Import

- One `dump_thought` per note or part: `{ "title": ..., "body": ..., "space_id": ... }` (`space_id` only for a space).
- **Pace at 50 calls a minute or fewer** (one every 1.2 s or more). BrainDump allows 60 tool calls per person per
  minute across all their connections, so leave room for the user's other apps.
- On **429**, wait for the `Retry-After` seconds (60 if unknown), then retry the same note. On 401, or an error result about
  read_write or a space not allowed, stop and tell the user (connection removed, read-only, or the destination is
  not allowed). On any other error, record it and go on.
- **State file** so the import can stop and resume: `.braindump-import.json` next to the folder (not inside it),
  written after every successful call:
  ```json
  { "destination": "private", "done": { "Clients/Acme Corp/kickoff.md": { "sha256": "...", "ids": ["note-id"] } }, "failed": {} }
  ```
  On a re-run, skip a file whose path and sha256 are already in `done`. A changed file is imported again as a new
  note (nothing is updated in place); tell the user. Never write the key into this file.
- Report progress every 50 notes, and at the end: imported, skipped, flagged, failed.

For a large vault, a small script is steadier than hundreds of tool calls. A script cannot sign in, so it needs a
read and write key the user makes in Settings → Remote MCP and sets as `BRAINDUMP_KEY` in their own terminal. Read
it from that environment variable and never print it:

```sh
curl -sS https://getbraindump.app/mcp \
  -H "Authorization: Bearer $BRAINDUMP_KEY" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"dump_thought","arguments":{"title":"kickoff","body":"... #clients #acme-corp"}}}'
```

A success is `{"result":{"content":[{"type":"text","text":"{\"id\":\"...\",\"space_id\":null}"}]}}`. A tool error is
`{"result":{"isError":true,"content":[{"type":"text","text":"..."}]}}` with HTTP 200. HTTP 401 means the key is
wrong or revoked, and 429 comes with `Retry-After`.

## What happens to imported notes

Each note is saved at once, indexed for keyword and meaning search, and linked to the people, companies and notes it
names. For a big archive, use the `import_notes` tool (up to 50 notes per call) instead of one `dump_thought` per note.
Before a big import, ask the user to open the one-time 72-hour import window (an owner or admin, in BrainDump's
onboarding or Settings → Import; you cannot open it). While it is open, imports run at up to 300 notes a minute instead
of 60. Imported notes are filed for free (title, `#tags`, `- [ ]` checklists, clear future dates, `[[links]]`) plus a
small model for the people, companies and projects in them (the window's allowance, 2,000 per seat, pays for those
calls); they are never sent to the daily AI-filing cap in bulk. The user gets full AI filing on a note by opening it
or pressing "File with AI". A note saved with `dump_thought` is filed like a live capture: the free parser, then
BrainDump's AI, within the daily AI-filing cap (past it, the note keeps the parser's filing and waits). Send each
batch with an `idempotency_key`; a retried batch never creates notes twice, and a different batch reusing a key is
refused.
