Tools

List the brains you are a member of, with your role in each. Takes no input. Then call start_here on the brain you'll work in.

Access required: Any signed-in user (only lists brains you already belong to).

Example (run against a synthetic brain)

list_brains({})

{ "brains": [{ "slug": "docs-verification", "name": "Docs Verification", "brain_type": "project", "role": "owner" }] }

Returns just this brain's conventions (BRAIN.md). Prefer start_here at session start — it includes this guide plus recent activity and open tasks.

Access required: Viewer or higher.

Parameters

Example (run against a synthetic brain)

get_brain_guide({ brain: "docs-verification" })

{ "content": "# Brain guide: Docs Verification\n\n**This is a starter placeholder…" }

Call this FIRST, before searching, reading, or writing anything — it is the mandatory first tool call of any session on a brain, before any other tool. It is distinct from and richer than get_brain_guide: get_brain_guide returns only the raw conventions, while start_here returns those conventions plus recent teammate activity plus open tasks, in one call. If this tool isn't visible yet, some hosts lazy-load a connector's toolset — load or enable this connector's tools rather than guessing or searching for an alternative.

Access required: Viewer or higher.

Parameters

Example (run against a synthetic brain)

start_here({ brain: "docs-verification" })

{ "content": "## Conventions\n# Brain guide: Docs Verification…\n\n## Recent activity\n- 2026-09-06T16:43:06Z, Maxwell Henderson: create_brain BRAIN.md\n" }

Create a new brain and become its owner. Any authenticated user may call this — no existing brain membership required. After creating, call start_here on the new brain before doing anything else in it.

Access required: Any signed-in user. No existing brain membership required.

Parameters

Example (run against a synthetic brain)

create_brain({ name: "Docs Verification", slug: "docs-verification" })

{ "slug": "docs-verification", "brain_id": "7f85dc04-…", "role": "owner" }

List notes in a brain, sorted by path. Returns up to `limit` (default 200, max 999) at a time — fewer if the page would be oversized — plus `total` (the real count of all matching notes) and `next_cursor` when there are more. Large brains should pass `prefix` to browse a folder (e.g. prefix: 'decisions/') and/or page with `cursor` — a bare call on a big brain will not return everything in one page.

Access required: Viewer or higher.

Parameters

Example (run against a synthetic brain)

list_notes({ brain: "docs-verification" })

{ "notes": [{ "path": "BRAIN.md", "title": "Brain guide", … }, { "path": "overview.md", … }], "total": 2, "has_more": false, "next_cursor": null }

Read a note's content and current version. Pass the returned version as expected_version on write_note to detect concurrent edits. Notes over 39000 characters are truncated automatically: the response carries total_chars, returned_range and next_offset — pass next_offset back as offset to keep reading from where you left off. Pass outline: true to see the note's heading structure (with offsets and section sizes) without its content — the cheap way to navigate a huge note before deciding what to read. To locate exact text inside a note you can't read whole (so you can pass it to edit_note as old_string), use find_in_note instead of guessing.

Access required: Viewer or higher.

Parameters

Example (run against a synthetic brain)

read_note({ brain: "docs-verification", path: "overview.md" })

{ "path": "overview.md", "version": 1, "content": "# Docs Verification\n\n…", "truncated": false, "returned_range": [0, 221], "next_offset": null }

Full-text search this brain before writing — extend an existing note instead of creating a duplicate.

Access required: Viewer or higher.

Parameters

Example (run against a synthetic brain)

search({ brain: "docs-verification", query: "appended section" })

{ "hits": [{ "path": "overview.md", "title": "", "snippet": "…<b>Appended</b> <b>section</b>…", "rank": 0.186813 }] }

Find exact text inside one note or across a whole brain. Unlike search (full-text, stems words, misses identifiers), this does literal substring matching and returns character offsets — so an excerpt from a match can be passed straight to edit_note as old_string, without ever reading the whole note. Omit path to search every note in the brain (optionally scoped with prefix); pass path to search just one.

Access required: Viewer or higher.

Parameters

Example (run against a synthetic brain)

find_in_note({ brain: "docs-verification", path: "overview.md", query: "Appended section" })

{ "matches": [{ "path": "overview.md", "offset": 97, "line": 6, "excerpt": "…" }], "total_matches": 1, "truncated": false }

See what teammates changed recently. Check at the start of a work session to sync up.

Access required: Viewer or higher.

Parameters

Example (run against a synthetic brain)

recent_activity({ brain: "docs-verification" })

{ "activity": [{ "actor_name": "Maxwell Henderson", "action": "append", "note_path": "overview.md", "at": "2026-09-06T16:44:38Z" }, …] }

If you haven't called start_here for this brain in this session, call it first. Create a note or fully replace its content. For adding to an existing note, prefer append_note. Pass expected_version (from read_note) so teammates' concurrent edits are flagged.

Access required: Editor or higher.

Parameters

Example (run against a synthetic brain)

write_note({ brain: "docs-verification", path: "overview.md", content: "…", expected_version: 1 })

{ "path": "overview.md", "version": 4, "conflict_warning": "This note was changed by Maxwell Henderson at 2026-09-06T16:43:43Z (you had v1, current is v3). Your change was saved on top." }

If you haven't called start_here for this brain in this session, call it first. Add content to a note without overwriting it. Prefer this over write_note when adding to logs, decisions, running documents, or task lists. For retry safety, pass a caller-stable idempotency_key and reuse it only for the same path and content; a replay returns the original result, while conflicting reuse fails. Omitting the key preserves legacy non-idempotent behavior.

Access required: Editor or higher.

Parameters

Example (run against a synthetic brain)

append_note({ brain: "docs-verification", path: "overview.md", content: "## Appended section\n\n…" })

{ "path": "overview.md", "version": 6 }

If you haven't called start_here for this brain in this session, call it first. Add content to the TOP of a note without overwriting it. Use this for logs and journals whose newest entry belongs first — a brain's guide may specify newest-on-top ordering. For retry safety, pass a caller-stable idempotency_key and reuse it only for the same path and content; a replay returns the original result, while conflicting reuse fails. Omitting the key preserves legacy non-idempotent behavior.

Access required: Editor or higher.

Parameters

Example (run against a synthetic brain)

prepend_note({ brain: "docs-verification", path: "overview.md", content: "## Newest entry (prepended)" })

{ "path": "overview.md", "version": 7 }

If you haven't called start_here for this brain in this session, call it first. Replace an exact string inside a note without rewriting it. Prefer this over write_note for small changes — closing a task, correcting a line, updating a status — especially on large notes. old_string must match exactly and must be unique unless you pass expected_occurrences.

Access required: Editor or higher.

Parameters

Example (run against a synthetic brain)

edit_note({ brain: "docs-verification", path: "overview.md", old_string: "Newest entry (prepended)", new_string: "Newest entry (edited via edit_note)" })

{ "path": "overview.md", "version": 8, "occurrences_replaced": 1 }

If you haven't called start_here for this brain in this session, call it first. Rename or relocate a note to a new path. Fails if a note already exists at to_path — move or delete it first.

Access required: Editor or higher.

Parameters

Example (run against a synthetic brain)

move_note({ brain: "docs-verification", from_path: "overview.md", to_path: "notes/overview.md" })

{ "path": "notes/overview.md" }

If you haven't called start_here for this brain in this session, call it first. Delete a note. Its content is preserved in version history, so this is recoverable, not permanent data loss.

Access required: Editor or higher.

Parameters

Example (run against a synthetic brain)

delete_note({ brain: "docs-verification", path: "overview.md" })

{ "deleted": true }

Recover a note that was deleted. Restores its most recent saved content.

Access required: Editor or higher.

Parameters

Example (run against a synthetic brain)

undelete_note({ brain: "docs-verification", path: "overview.md" })

{ "path": "overview.md", "version": 5 }

List the edit history of a note — who changed it and when. Use before restoring or to see recent activity on a specific note.

Access required: Viewer or higher.

Parameters

Example (run against a synthetic brain)

get_history({ brain: "docs-verification", path: "overview.md" })

{ "versions": [{ "version": 8, "edited_by_name": "Maxwell Henderson", "created_at": "…" }, …] }

Read a note's content as of a specific past version. Get version numbers from get_history.

Access required: Viewer or higher.

Parameters

Example (run against a synthetic brain)

read_version({ brain: "docs-verification", path: "overview.md", version: 2 })

{ "path": "overview.md", "version": 2, "content": "# Docs Verification\n\nUpdated: second write…", "edited_by_name": "Maxwell Henderson", "created_at": "…" }

Roll a note back to an earlier version. The current content is saved to history first, so a restore can itself be undone.

Access required: Editor or higher.

Parameters

Example (run against a synthetic brain)

restore_version({ brain: "docs-verification", path: "overview.md", version: 2 })

{ "path": "overview.md", "version": 5, "restored_from": 2 }

If you haven't called start_here for this brain in this session, call it first. Add another user to this brain by email with an explicit role (owner-only). Roles: owner (full control, including managing members), editor (read/write notes, default if omitted), or viewer (read-only). Re-adding an existing member updates their role instead of erroring.

Access required: Owner only.

Parameters

Example call

add_member({ brain: "docs-verification", email: "teammate@example.com", role: "editor" })