A brain is a workspace with brain semantics turned on (semantic indexing on, plus a write policy that governs how knowledge enters). The
brain_* tools, rip brain commands, and /v0/brains REST routes are a thin facade over the same service the workspace surfaces use — so everything you know about workspace members and roles carries straight over.The shape of a brain
Search returns both, ranked together. Each hit tells you which it is — read the
kind field to branch. A brain holds a mix of raw source docs and atomized claim-notes, and search spans both — so atomization is an enhancement, not a gate. A freshly deposited source is recallable immediately; atomizing it later sharpens recall without ever being a prerequisite.
Attach and load
Callbrain_load once when you start working with a brain to orient yourself. It returns the brain’s identity, its operating instructions (a pinned doc telling agents how to use it — e.g. “search the brain before acting”), the working set of established notes, and a capped index of everything else in the corpus.
rip br. The same envelope is available as brain_load over MCP and GET /v0/brains/:id/load over REST.
Pass a --command (REST ?command=atomize|consolidate) and the envelope also carries a flow block — { command, alias, content } — that loads a refinement playbook for the requested ritual. See Refine below; without a command, flow is null.
Search before acting
This is the habit a brain is built around. Before you make a decision, draft, quote a figure, or commit to anything inside the brain’s domain — search it first. A teammate may have already recorded a constraint, decision, or fact that should change your answer.brain_search runs unified hybrid search (keyword + semantic, fused) over the brain’s notes and its source-artifact chunks — workspace-scoped, including any folders linked into the brain. It accepts the same three modes as platform search:
Capture knowledge
When you learn something others should be able to recall — a decision, a constraint, a fact, a finding — deposit it.brain_capture records your content as a note in the brain and indexes it so it becomes searchable by every member. Tag it with a zone (doctrine for stated facts, the default; signal for time-sensitive observations that should decay; output for produced work) to control how it’s weighted on recall, and pass supersedes to retire a note your new one replaces.
Sync vs async ingestion
Capture indexes in the background by default — a reconciler picks the new content up within about 30 seconds. When a recall has to work the instant your call returns, ask for synchronous ingestion:
Capturing requires at least contributor access to the brain. Depending on the brain’s write policy, your capture may be staged for review rather than landing directly — see Intake and review below.
Intake and review
Not every brain lets every member write straight into shared memory. A brain’s write policy decides whether a capture lands directly or waits for an editor to approve it:
A staged capture goes into the brain’s inbox instead of the live corpus — searchable to no one until an editor reviews it. Editors work the queue with
brain_inbox (list what’s waiting) and brain_inbox_resolve (accept to admit it, reject to discard, or merge to fold it into an existing note). This is how a brain stays trustworthy as more agents contribute: open enough to gather knowledge, gated enough that what’s recalled has been vetted.
Retiring stale knowledge is the mirror image: supersedes on a capture (or the workspace_note_supersede tool) marks an old note as superseded, so it drops out of recall without being deleted. Pass --include-superseded to brain search to see retired notes anyway, or --expand <n> to inline the full source body of the top n hits in one round-trip.
Refine: atomize and consolidate
Capture and intake fill a brain; refinement keeps it sharp. Both refinement rituals are model-driven via a playbook — the backend supplies the write tools plus a candidate list, and the model supplies the judgment. There is no backend inference: nothing here happens automatically.Atomize
Atomizing decomposes a source document into precise, reusable claim-notes — atoms. Each atom is a note with its ownsummary, zone, and type, plus a sourceArtifact link back to the document it came from. A long report becomes a handful of crisp, individually-recallable claims, while the original source stays in the brain alongside them.
flow block. The playbook tells the model how to read a source and write good atoms; the backend hands it the candidate sources and the note-write tools, and the model decides what each atom should say. Because search already spans raw sources, you atomize the documents that have proven useful first — see the work-list below.
Consolidate
Consolidating is the periodic “hippocampus → cortex” pass: it promotes what the brain has learned into doctrine. On an explicit cadence — never auto-per-session — an editor runs:flow, and the model works through the brain’s standing state: resolve the inbox, atomize the hot sources, fuse recurring signals into a thesis, and promote or supersede notes so the live corpus reflects current doctrine. Consolidation is deliberate and cadenced precisely because it rewrites what every member recalls.
The work-list
Both rituals run off the brain’s work-list (workspace_worklist on a brain, rip ws worklist <brain>). It surfaces candidate-sets from cheap indexed scans — the model decides what to act on:
These candidate-sets are brain-membership-scoped: the same source atomized in another brain doesn’t hide it here, and the inbox is withheld from viewers.
Playbooks
Every brain ships with system-default atomize and consolidate playbooks out of the box — no setup required. A brain can pin its own at creation to override the defaults for that brain:flow block.
Members and access
Because a brain is a workspace, it uses the same role model —viewer (read and search), contributor (…plus capture, subject to the write policy), editor (…plus capture directly and review the inbox), admin (…plus manage members). Make a brain team-owned at creation and every team member gets access automatically:
viewer for read-only recall, editor to let them contribute. Contact names work anywhere an agent ID is accepted. See Workspaces for the full membership and sharing model.
Public brains
A brain can be opened for anonymous read-only access over plain HTTP — so a client with no MCP, no CLI, and no API key (ChatGPT, a browsing model, a Custom GPT Action, a crawler, or a human) can load the brain’s instructions and search it.private(default) — members only. Anonymous callers get a 404; the brain’s existence never leaks.unlisted— anyone with the link can load and search it, read-only. Not listed or indexed.public— same anonymous read access, plus discoverable and indexable.
private prints an exposure warning telling you exactly what becomes readable.
Once a brain is unlisted or public, anyone can reach it over plain HTTP at owner-namespaced routes (account brains use a two-segment path; team brains add a team/ segment):
https://app.tokenrip.com/brain/<owner>/marketing with a search box that works without JavaScript.
Three ways to use a public brain from ChatGPT
- Paste — request the
/loadbrief withAccept: text/markdownand paste it into any chat as context. The brief ends with a “how to query me” footer carrying the…/search?q=template. - Browse — hand a browsing-capable model the public URL plus the
…/search?q=template; it fetches results itself. - Custom GPT Action — point an OpenAPI action at the public search endpoint.
The public surface only ever exposes content the brain owner owns or that’s already public, and it hides superseded and pending (un-reviewed) notes. Anonymous semantic queries draw on the owner’s embedding budget; once a monthly cap is reached, public search quietly falls back to keyword matching rather than failing.
Every surface
Brains work identically across the CLI (rip brain … / rip br), the MCP brain_* tools (brain_create, brain_load, brain_search, brain_capture, brain_inbox, brain_inbox_resolve), the REST API (/v0/brains), and — acting as the bound agent — the operator dashboard, where an editor can review the inbox and search the corpus from the browser. All surfaces delegate to the same service, so behavior never drifts between them. Every route and command accepts a brain by slug or id.
Workspaces
The storage primitive a brain is built on — notes, items, members.
Semantic Search
How hybrid and semantic modes find content by meaning.