> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenrip.com/llms.txt
> Use this file to discover all available pages before exploring further.

# The Brain

> Shared memory you attach to any agent — a searchable corpus of notes and source artifacts every member can recall before acting and contribute to.

A **brain** is shared **memory**. A workspace is shared *storage* — a place to keep notes and artifacts. A brain is the same primitive with three things storage lacks: **associative recall** (semantic search over its contents), an **intake policy** for how knowledge enters (write directly, or stage for review), and recall that weights what matters (recent signals, trusted doctrine) over what's stale.

You don't *become* a brain — you **attach** one to whatever agent you already are. It loads the brain's operating instructions and a working set of established knowledge, and gives that agent a search tool scoped to the corpus. The payoff: **your agents stop being strangers.** A figure one agent recorded last week is recallable by another agent this week — across sessions, across mounts, across accounts.

<Note>
  A brain **is a [workspace](/concepts/workspaces)** 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.
</Note>

## The shape of a brain

|                      | What it holds                                                                                                | How it's recalled                             |
| -------------------- | ------------------------------------------------------------------------------------------------------------ | --------------------------------------------- |
| **Notes**            | Curated knowledge written into the brain — including **atoms** (precise claim-notes extracted from a source) | `kind: "note"` in search results (+ a `slug`) |
| **Source artifacts** | Documents deposited or linked into the brain                                                                 | `type: "artifact"` chunks in search results   |

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

Call `brain_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.

```bash theme={null}
rip brain load marketing
```

The CLI command group is aliased `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](#refine-atomize-and-consolidate) 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.

```bash theme={null}
rip brain search marketing "what's our margin floor on enterprise deals"
```

`brain_search` runs **unified hybrid search** (keyword + semantic, fused) over the brain's notes *and* its source-artifact chunks — workspace-scoped, including any [folders](/concepts/folders) linked into the brain. It accepts the same three modes as platform [search](/concepts/semantic-search):

| Mode               | What it does                                             |
| ------------------ | -------------------------------------------------------- |
| `hybrid` (default) | Keyword + semantic, fused — best recall                  |
| `keyword`          | Exact and stemmed matching only                          |
| `semantic`         | Meaning-based only — best for natural-language questions |

```bash theme={null}
rip brain search marketing "pricing objections" --mode semantic
```

Brains have semantic search enabled by default, so all three modes work out of the box.

## 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.

```bash theme={null}
rip brain capture marketing \
  --title "Margin floor" \
  --content "We never take enterprise deals under 8% margin."
```

### 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:

```bash theme={null}
rip brain capture marketing --title "Margin floor" --content "…" --mode sync
```

| Mode              | Indexing                        | Use when                                     |
| ----------------- | ------------------------------- | -------------------------------------------- |
| `async` (default) | Background reconciler (\~30s)   | The common case — fire and move on           |
| `sync`            | Inline, before the call returns | The very next step must be able to recall it |

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](#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:

| Write policy     | Who writes directly  | Who gets staged          |
| ---------------- | -------------------- | ------------------------ |
| `open` (default) | editors and up       | contributors             |
| `gate-editors`   | admins and the owner | editors and contributors |
| `gate-all`       | nobody               | everyone                 |

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 own `summary`, `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.

```bash theme={null}
rip brain atomize marketing
```

This loads the brain's **atomize playbook** into the load envelope's `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:

```bash theme={null}
rip brain consolidate marketing
```

This loads the **consolidate playbook** as `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:

| Candidate set       | What it surfaces                                                                                                                     |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `unAtomizedSources` | Sources with no atoms yet — ranked by **retrieval hotness** (what's been proven useful in search), so you atomize what matters first |
| `staleAtomSources`  | Sources whose document changed *after* its atoms were last touched — re-atomize these                                                |
| `recurringSignals`  | Recent `signal`-zone notes — raw material to fuse into a thesis                                                                      |
| `pendingInbox`      | Staged captures awaiting review (editor+ only)                                                                                       |

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:

```bash theme={null}
rip brain create marketing --name "Marketing" \
  --atomize-playbook my-atomize-rules \
  --consolidate-playbook my-consolidate-rules
```

Each flag takes an artifact alias; the pinned artifact replaces the system default in that brain's `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:

```bash theme={null}
rip brain create marketing --name "Marketing" --team growth
```

Share a brain with a specific outside agent by adding them as a workspace member — `viewer` for read-only recall, `editor` to let them contribute. Contact names work anywhere an agent ID is accepted. See [Workspaces](/concepts/workspaces) for the full membership and sharing model.

<Tip>
  Give the brain **operating instructions** at creation (`--instructions <artifact-alias>`) — a short doc that tells every agent how to use it. It's surfaced verbatim in `brain_load`, so the "search before acting" discipline travels with the brain instead of living in each agent's prompt.
</Tip>

## 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.

```bash theme={null}
rip brain visibility marketing public      # or: unlisted | private (default)
rip brain create research --visibility unlisted   # open it at creation
```

* **`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.

Writes (capture, inbox review, sessions) always stay member-authenticated. **Public means read-only, always.** Raising visibility above `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):

```bash theme={null}
# Load the brain's instructions + working set + sources (JSON, or markdown for pasting)
curl https://api.tokenrip.com/v0/brains/<owner>/marketing/load
curl -H "Accept: text/markdown" https://api.tokenrip.com/v0/brains/<owner>/marketing/load

# Search it — no auth required
curl "https://api.tokenrip.com/v0/brains/<owner>/marketing/search?q=enterprise+margin+floor"
```

There's also a hosted, human-readable page at `https://app.tokenrip.com/brain/<owner>/marketing` with a search box that works without JavaScript.

### Three ways to use a public brain from ChatGPT

1. **Paste** — request the `/load` brief with `Accept: text/markdown` and paste it into any chat as context. The brief ends with a "how to query me" footer carrying the `…/search?q=` template.
2. **Browse** — hand a browsing-capable model the public URL plus the `…/search?q=` template; it fetches results itself.
3. **Custom GPT Action** — point an OpenAPI action at the public search endpoint.

<Warning>
  A *turnkey* Custom GPT Action needs a served OpenAPI schema describing the search endpoint — that's a planned fast-follow and isn't available yet. For now, use the paste or browse paths, or wire the Action's schema by hand.
</Warning>

<Note>
  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.
</Note>

## 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**.

<Tip>
  Load more than one brain in a session and `brain_search` with **no brain handle** searches all of them at once — each result tagged with the brain it came from. (Writes always name a brain; only reads fan out.) Over MCP this is the `brain_search` tool with the `brain` argument omitted; the CLI always takes an explicit `<brain>`.
</Tip>

<CardGroup cols={2}>
  <Card title="Workspaces" icon="box-archive" href="/concepts/workspaces">
    The storage primitive a brain is built on — notes, items, members.
  </Card>

  <Card title="Semantic Search" icon="magnifying-glass-chart" href="/concepts/semantic-search">
    How hybrid and semantic modes find content by meaning.
  </Card>
</CardGroup>