Brain data model and tools

Start with the outcome

Begin with the purpose of the work. Are you planning a project, capturing a conversation, keeping reference material, or bringing an existing system into Brain? Understand what should be easier to find, decide or do afterward. Let that purpose guide the structure you create.

Read what is already in the destination workspace and reuse the records that fit. A new workspace starts with Inbox; you can create areas, projects, contacts and notes as you need them. When working with an agent, explain the outcome and any constraints, then have it read the relevant Brain context before making changes.

This guide explains the record choices first, then the tools for saving and finding them. Connection setup explains how to give an agent access to your workspace.

Choose a record for what you mean

Brain has five kinds of record. Each answers a different question about your work. Images and connections add context to those records.

For a website launch, you might keep a Business area, a Launch website project, tasks for the work to do, a contact for the designer, and a note recording design decisions. Screenshots can sit beside the relevant decisions in the note. Connections make that information easy to reach from the project or the designer’s contact record.

Use a checklist for small steps within one task. Make separate tasks when actions need their own dates, completion states or supporting context. Save explanations, observations and decisions in notes so the task title can stay focused on the action.

Give work a home and connect its context

Areas and projects organize work. A project can sit in an area, and each task has one home: an area or a project. Inbox is the built-in area for tasks you have not organized yet. A task created without a home goes there.

Connections explain how records relate. Connect a project to its decision notes, a task to supporting research, or a note to the people involved. The same note can be useful in several places; save it once and connect those records to it.

A task in a project gets its area context through that project. Set one task home. To move the task, update its home field; to change a connection, use its edge ID.

The graph shows project and task homes as contains relationships alongside labeled connections and dependencies. Dependencies are directed relationships between tasks and cannot form a cycle.

Use list_areas to find Inbox by is_inbox: true. Inbox is permanent and cannot be renamed or deleted.

Write notes that preserve useful context

Use a note for information someone will need later: what happened, what was decided, why a choice was made, or where supporting material came from. Give it a recognizable title and enough context to make sense outside the conversation that produced it.

A note’s body supports Markdown, including headings, lists, links and uploaded images. Connect the note to the relevant work and people so it can be found from those records.

1. Create the document with add_note, supplying body and an optional title. Keep the returned note ID.
2. Connect it to relevant records with create_edge, using the note ID and a label that explains the relationship.
3. Before editing, use get_note to read the complete document. List and graph results may contain a shortened body marked body_is_preview.
4. Call update_note with id, expected_updated_at from that read, and the fields to change. A supplied body replaces the document body, so include the text and image references you want to keep.
5. If another edit has changed the note, read it again and reconcile your change with the current document.

Each note can hold up to 1 MiB of UTF-8 Markdown. Split larger collections into documents that are useful to read and connect them by topic or purpose. Include source links or identifiers when they help explain or verify the information.

Add images to a note

Keep photos, screenshots and diagrams beside the text they explain. In the Brain note editor, choose Add image, paste an image, or drop an image file into the editor. Save the note and use Preview to check the result.

Through tools, first upload the image bytes, then include the returned image reference in the note’s Markdown. Brain accepts private PNG, JPEG, GIF and WebP images up to 5 MiB and 10 million pixels each. A note can reference up to 100 distinct images.

1. Call begin_attachment_upload with filename, content_type and size_bytes matching the file. Keep the returned id, upload_url and headers.
2. Send the file bytes with HTTP PUT to upload_url using the returned headers.
3. Call complete_attachment_upload with the attachment id. This validates the image and returns its permanent markdown_url.
4. Insert a Markdown image in the note body: an exclamation mark, a useful description in square brackets, then the returned markdown_url in parentheses. The reference has the form /attachments/<id>.
5. Save a new note with add_note, or read the full existing note and use update_note with expected_updated_at. Check the saved document and image in Preview.

Save the permanent markdown_url in the note. The upload_url and the download_url returned by get_attachment are temporary access links. get_attachment also provides the image’s metadata.

Image transfer requires access to the file bytes and an HTTP upload capability. If an agent’s client cannot upload bytes, use the Brain note editor for that step. For other file types, such as PDFs, keep a useful source link and relevant text in a note.

An image can appear in several notes in the same workspace. When importing into another workspace, upload a copy there. Keep captions and image order when they carry meaning.

Label connections so their meaning is clear

A useful connection answers “why would I open this other record?” Use a short label that explains the relationship. The note or record holds the detail; the label helps someone find it.

Read a directed connection as “source — label → target.” In create_edge, from_id is the source, to_id is the target, and text is the label. Direction defaults to true. Set directed: false for a mutual association.

Labels are freeform text, up to 255 Unicode characters. Reuse the workspace’s wording when the meaning is the same. related_to is the connection type used for these associations; depends_on is the type for task prerequisites.

For a project decision discussed with a designer, save one note with the decision and rationale. Connect the project to the note with decision, and the note to the designer’s contact with discussed with. Each connection describes a different part of the context.

Each connection has its own edge ID. Use get_edge to read it, update_edge to change its text, and delete_edge to remove it. Supply expected_updated_at when changing a label to protect against overwriting another edit. To change endpoints, type or direction, create the intended connection and remove the old one.

Several connections can join the same pair of records. Keep their IDs and meanings distinct, and check what is saved before retrying a creation. Removing a connection leaves both records and their content available.

Find the information you need

Start with a known record or browse with list_areas, list_projects, list_tasks, list_contacts or list_notes. Use the returned IDs when reading or changing records; names can be shared by several items.

To find a project’s decision notes, call list_related_items with the project’s entity_id, related_type: note, text: decision and direction: outgoing. Read each matching document with get_note. The label is an exact, case-sensitive filter, so use the wording saved in the workspace.

Use list_notes with connected_to_id to collect notes connected to a particular record. This includes connections in either direction and returns each note once, even if several connections link it to that record.

list_related_items returns related_to connections with their related records. Its direction filter accepts incoming, outgoing or either; incoming and outgoing select directed connections, while either also includes mutual connections. Omit text for all labels, or supply an empty string for unlabeled connections.

Use list_task_dependencies for prerequisites and dependents. The interactive graph uses get_todo_graph to read a record’s direct neighborhood, including work homes, dependencies and related context.

When a result includes next_page_token, request the next page with the same filters. Continue until the token is null when you need the complete collection. Keep distinct connection IDs when several relationships point to the same record.

Keep dates and status meaningful

Dates and status help the next reader understand when something happened and what still needs doing. Use the meaning supplied by the work or source material.

• planned_date is the day to work on a task or project; deadline_date is when it must be done. Both are calendar dates.
• For a note about an event, use occurred_on when you know only the date. Use occurred_at with an IANA occurred_timezone when you know the time. Created and updated timestamps describe saving activity.
• Use date-only or timed occurrence fields. When switching to date-only, clear occurred_at and occurred_timezone with null. When switching to timed, clear occurred_on. Omitted update fields keep their saved values.
• Use complete_task and reopen_task to change completion. Checklist progress, notes and connections remain available. Archiving a project leaves its tasks’ completion states as they are; dependencies provide context and do not prevent completing a task.
• Deleted records can be restored. Deleting an area or project also hides work inside it until the parent is restored. A note connected to a deleted record remains available in Notes. Use delete_note when the note itself should be removed.

Bring existing material into Brain

An import should preserve what the source means and make it useful in Brain. Start with a manageable batch, verify the result, and keep enough of a working record to resume without creating duplicates.

1. Establish the desired outcome, destination workspace and source material. Decide which information needs to become actionable work and which should be kept as context.
2. Read the relevant Brain records and connections. Match existing items using source identifiers, content and surrounding context. Keep a mapping from each source item to its Brain ID.
3. Choose records by meaning: responsibilities become areas, outcomes become projects, commitments become tasks, people and organizations become contacts, and knowledge becomes notes. Create missing records and reuse suitable matches.
4. Save work in its intended homes. Upload images before saving note bodies that reference them, then add connections with labels that explain the relationships.
5. Preserve source links, actual event dates, captions and useful distinctions. Leave uncertain actions in Inbox and keep reference material in notes while its wider context is being clarified.
6. Read back each batch: check task homes, full note bodies, images, dates and connection labels and direction. If a write was interrupted, inspect what was saved before retrying it. Record creation and connection creation can produce duplicates on replay.
7. Report what was created, reused or updated, along with unresolved questions. Keep the source intact unless its removal was requested, and save the source-to-ID mapping so the next session can continue.

For duplicate checks across task statuses, omit view; view: all selects open tasks. include_deleted can help locate an item that should be restored instead of recreated.

When working with an agent, have it read the relevant records at the start and save decisions, context and next actions before finishing. A later conversation can then continue from the same Brain records.