STACK
MENU
DOCS / THE ACCOUNT / BRAIN

Brain

How you make documents on the drive searchable by meaning, and how an agent asks them a question. What the brain is and what it costs is on Services.

Before you start

The brain reads files that are already on the drive: see Drive and share links. There is one brain for the account, shared by all of your agents. The account needs credit to cover reading the pages.

Add documents

prompt
Add every file on the drive whose name starts with "Contract" to the brain.

The client calls stack_brain_add. From code or the terminal:

typescript
const added = await stack.brain.add({ file_ids: ['drv_0123456789abcdef'] }, { passportToken });

// or by name:
await stack.brain.add({ name_prefix: 'Contract' }, { passportToken });
bash
npx @getstackrun/cli brain add --prefix Contract
  • Name the files in one way: one file_id, a list of file_ids, or a name_prefix.
  • Each file comes back as reading, unreadable with the reason, or refused.
  • PDFs, images and PowerPoint files are read by the page. Text, Markdown, CSV, HTML, Word and Excel cost no pages.
  • A file is at most 50 MB, and an image at most 3.75 MB. Audio, video, archives and encrypted PDFs cannot be read.
  • A file that changes on the drive is read again. A file deleted from the drive leaves the brain.
prompt
What is the notice period in the Acme contract?
typescript
const found = await stack.brain.search({ query: 'What is the notice period?' }, { passportToken });
// found.passages, found.pending
  • The tool is stack_brain_search. It returns up to 10 passages, each with the file it came from.
  • pending says how many files are still being read. Search again when it is zero.
  • An agent sees passages from files it can see on the drive: its own private files and the account's shared ones.

A passage is content from outside. It is scanned, and a passage that carries instructions aimed at an agent is flagged. With controls on, it is withheld.

See and remove

stack_brain_list lists the files with their status: reading, searchable or unreadable. stack_brain_remove takes files out of the brain. They stay on the drive.

What counts as an action

One add is one action, however many files it names. Searching, listing and removing are free. Pages read are charged from credit after the pages the plan includes each month.

When it is refused

  • A file that cannot be read is not an error. Its row says unreadable and why.
  • 400 on add or remove - name exactly one of file_id, file_ids or name_prefix.
  • 503 BRAIN_UNAVAILABLE or BRAIN_PROVIDER_REFUSED - the knowledge base cannot be reached. The action is not counted.
  • 403 CONTROL_DENIED - with controls on, your policy or your own server refused it. Controls are asked as brain.add, with the number of files and pages and the most it can cost.

Reference

Every field is on Brain in the API reference. Every tool is in the tool reference. For what agents themselves have learned, see Memory.

Brain | Docs