---
name: braindump
description: Use the user's BrainDump company brain through its MCP tools (search_knowledge, search, fetch, get_entity_context, dump_thought, add_action, list_actions, update_action, delete_action, list_open_actions, resolve_todo). Use it before answering questions about the user's work, people, companies, projects or past decisions, to save decisions and meeting takeaways they want remembered, and to add, list, complete or schedule their to-dos and reminders.
---

# BrainDump

BrainDump is the user's (and their team's) second brain. Its MCP server is `https://getbraindump.app/mcp`.
The connection decides what you can reach: some spaces, maybe the user's private notes, read or read and write. The
user chose that when they signed in (or when they made a key, for clients without sign-in).

## Tools

| Tool | Arguments | Returns |
|---|---|---|
| `search_knowledge` | `query` (required), `space_id`, `limit` (1-20, default 8) | notes: `id`, `title`, the first 280 characters of `body`, `space_id`, `url` (opens the note in BrainDump) |
| `search` | `query` (required) | up to 10 `results`: `id`, `title`, `url`. The same search in the shape ChatGPT deep research expects |
| `fetch` | `id` (required) | one note in full: `id`, `title`, `text`, `url`, `metadata` |
| `get_entity_context` | `name` (required) | the entity, up to 12 notes that mention it (with `url`), linked records and cached connector records (CRM, calendar...) |
| `list_open_actions` | `space_id` | up to 40 open to-dos: `note_id`, `title`, `item_index`, `text` |
| `dump_thought` | `body` (required), `title`, `space_id` | the new note's `id`, `space_id` and `url`. Needs a read_write key. |
| `resolve_todo` | `note_id`, `item_index` (required), `done` | the note's to-do list and whether the note is now archived. Needs a read_write key. |
| `add_action` | `text` (required), `lane`, `at`, `repeat`, `note_id`, `space_id` | the new action. Needs a read_write key. |
| `list_actions` | `lane`, `due`, `mine`, `done`, `space_id`, `limit`, `cursor` | open to-dos and upcoming reminders, soonest first, and `next_cursor` for the following page |
| `update_action` | `id` (required), `done`, `text`, `lane`, `at`, `repeat`, `snooze_minutes` | the changed action. Needs a read_write key. |
| `delete_action` | `id` (required) | `deleted: true`. Needs a read_write key. |

An action is a to-do (a checklist line in a note) with an optional reminder time, or a reminder BrainDump found in a
note (its id starts with `r_`). Each one has `id`, `text`, `done`, `lane`, `due_at` (ISO, UTC), `repeat`, `note_id`,
`note_title`, `space_id`, `owner_id` and `item_index` (its place in the note, what `resolve_todo` takes).

## Search before you answer

When the user asks about their work ("what did we promise Acme?", "where are we on hiring?", "who is Dana?"), search
BrainDump first. Do not answer from memory or guess.

- Try two or three phrasings: names, then topics. Search matches keywords (word prefixes) and meaning.
- For a person, company or project, call `get_entity_context` with its name. It returns the notes that mention it and
  any records from connected tools.
- Results are excerpts. Say which notes you used (title, linked with its `url` when you can show links), and say so
  when nothing came back.
- Do not dump the user's search results back into BrainDump.

## Save thoughts worth keeping

Dump a thought when the user makes a decision, agrees a to-do, finishes a meeting, or says "remember this".
Ask first when it is not clear they want it saved.

- One idea per thought. Three decisions are three calls.
- Write it so it makes sense in six months: who, what, when (absolute dates, not "tomorrow"), why.
- Give it a short `title`. BrainDump links notes to people, companies and other notes on its own, so name them plainly.
  No manual [[links]]. A `#tag` or two is fine, never required.
- Omit `space_id` for a private note (the key must allow private notes). To post into a shared space, reuse a
  `space_id` from search results or ask the user. Never guess an id.
- Text only, up to 20,000 characters.

Good thoughts:

```
title: Decision: Postgres stays, no Mongo migration
body:  2026-10-24, Priya + Jamie. We keep Postgres for v2. Mongo saved nothing on the sync workload and doubles ops.
       Revisit if writes pass 5k/s. #infra
```

```
title: TODO: send Dana the retention table
body:  Jamie owes Dana Reyes (Pretend Ventures) the cohort retention table by Fri 2026-10-30, promised on the 10-23 call.
```

```
title: Acme kickoff takeaways
body:  2026-10-22, Sam + Acme (Lee, Ortiz). They need SSO before rollout; budget approved for Q1; pilot is 40 seats
       starting 2026-11-15. Lee is the decision maker.
```

Bad: "meeting went well", "todo stuff", a pasted transcript, a list of five unrelated items.

Thoughts saved through MCP are searchable right away and filed like any capture: a free parser first (the title,
`#tags`, `- [ ]` checklists, clear dates such as "tomorrow 3pm" or "Oct 30 at 9", and `[[Note Title]]` links to the
user's notes with that title), then BrainDump's AI for the rest, within the plan's daily AI-filing cap. Write
`[[Note Title]]` when you mean a specific note. The title still matters: it is the note's first line. A checklist
line you dump shows in `list_open_actions` once the note is filed.

## To-dos and reminders: actions

Use `add_action`, not `dump_thought`, when the user wants something done or wants to be reminded: "remind me to...",
"add ... to my list", "I need to...". It becomes a to-do right away (no AI step), shows in `list_actions` and the app's
Now and Reminders views, and its reminder goes out by SMS, Slack or in the app. Use `dump_thought` for things to
remember (decisions, takeaways). AI filing may also read a date out of a thought, but when the user wants a
reminder, give `add_action` an `at`: that one is certain, and it can be listed, snoozed and completed.

- `text`: one short line, starting with the verb. Up to 500 characters.
- `at`: when to remind. Prefer the user's local wall-clock time without an offset, `2026-11-02T17:30`: BrainDump reads
  it in the user's own timezone (America/New_York unless their account says otherwise). With an offset
  (`2026-11-02T17:30:00-08:00`) it is that exact instant. Resolve "tomorrow at 5" yourself into an absolute date. It
  must be in the future and within 5 years. No time? Leave `at` out: a plain to-do.
- `repeat`: `daily`, `weekly`, `monthly` or `yearly`, at the same local time. Completing a repeating action moves its
  reminder to the next time and leaves it open, the way phone reminders work. To stop it for good, set `repeat` to
  null and complete it, or delete it.
- `lane`: where or how it gets done, so the user can batch errands: `Home`, `Out & about`, `Work`, `Calls`,
  `Someday`, or their own word (30 characters at most). Leave it out when nothing fits.
- Where it goes: with `note_id`, onto that note's checklist (the to-do belongs to that topic; it must be the user's
  own note, 403 otherwise). Without, onto the user's Inbox note (private; with `space_id`, their Inbox in that space).

Examples:

```
"Remind me to stop at building supply for drip edge when I'm out tomorrow afternoon"
add_action { text: "Stop at building supply for drip edge", lane: "Out & about", at: "2026-10-26T14:00" }

"Every Monday at 9 remind me to send the crew schedule"
add_action { text: "Send the crew schedule", lane: "Work", at: "2026-10-26T09:00", repeat: "weekly" }

"Add calling Dana about the Henderson roof to the Henderson note"
add_action { text: "Call Dana about the Henderson roof", lane: "Calls", note_id: "<id from search_knowledge>" }
```

Working the list:

- "What's on my plate?" / "what's due today?": `list_actions` (with `due: "today"`, which includes overdue, or
  `"week"`). `lane: "Out & about"` for errands. Say what is overdue first.
- "Done with X": `update_action { id, done: true }`. The to-do is done for everyone and every reminder on it is
  cancelled (if the user's own reminder repeats, it moves on and the to-do stays open; send `repeat: null` too to end it).
- "Remind me again in an hour": `update_action { id, snooze_minutes: 60 }`. The to-do stays open.
- "Move it to Friday 10am": `update_action { id, at: "2026-10-30T10:00" }`. `at: null` drops the reminder and keeps
  the to-do. Reopening (`done: false`) never brings an old reminder back; send `at` again.
- "Never mind": `delete_action { id }`.
- Reminder times are personal. `due_at` and `repeat` are the user's own; teammates' reminders never show. Setting a
  time on a teammate's to-do in a shared space gives the user their own reminder and leaves the teammate's alone.
  Changing a to-do's text, adding to a note or deleting a to-do is for the note's owner (403 otherwise); anyone who can
  write the space can tick it, set its lane and keep their own reminder.
- Ids are what to pass back. An id may start with `d_` (an older to-do); use it as is, and take the id the call
  returns from then on.
- `list_open_actions` and `resolve_todo` still work (the older note-and-index pair). Prefer the action tools.
- Mark only what the user confirmed. Do not close or delete a colleague's to-do on a guess.

## Access, limits and errors

A tool that fails returns an error result (`isError`) whose text says what went wrong. Read it and act on it:

- "read_write key required": this connection can only read, so it cannot dump, resolve or change actions; it can
  list them. Tell the user what you would have saved, and that connecting again with read and write allowed fixes it.
  Do not retry.
- "private notes are not allowed for this key" or "space is not allowed for this key": the connection does not cover
  where you wrote. Ask which space to use.
- "no note with that id": search again for the id; never guess one.
- Unauthorized (401), or your client says Brain Dump needs authentication: the user removed the connection, or the
  workspace is not on a paid plan. Ask them to sign in to Brain Dump again from their client. Never ask them to paste
  a key into the chat.
- 429 "too many MCP requests": there are 60 tool calls per person per minute, across all their connections. Wait for the
  number of seconds in the `Retry-After` header (60 if you cannot see it), then continue. Do not retry in a loop.

## Never save

- Secrets: passwords, API keys and tokens (including `bd_mcp_...` keys), private keys, recovery codes, card or bank
  numbers, government ids. If the user asks you to save one, refuse and suggest a password manager.
- Other people's sensitive personal data the user did not ask you to keep.
- Anything you only inferred. Save what the user said or decided, not your guesses.
