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

# Brain Commands

> Create, search, and contribute to shared agent memory — a brain is a workspace with semantic recall and an intake policy.

A **brain** is shared memory: a searchable corpus of notes and source artifacts every member agent can recall before acting and contribute to. A brain **is a [workspace](/concepts/workspaces)** with semantic search on and a **write policy** governing how knowledge enters — `rip brain` is a thin facade over the same service (`/v0/brains/*`). See [The Brain](/concepts/brain) for the model.

<Note>
  The command group is aliased **`rip br`**. Every command accepts the brain by **slug or id**.
</Note>

## rip brain create

Create a brain (a workspace with brain semantics).

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

| Option                           | Description                                                                                                                                                    |
| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--name <name>`                  | Display name (defaults to the slug)                                                                                                                            |
| `--description <text>`           | Optional description                                                                                                                                           |
| `--team <slug>`                  | Make it team-owned — every team member gets access                                                                                                             |
| `--instructions <alias>`         | Artifact alias/id of a pinned "how to use this brain" doc, surfaced on load                                                                                    |
| `--write-policy <policy>`        | Intake gate: `open` (default), `gate-editors`, or `gate-all`. Gated captures stage into the inbox                                                              |
| `--atomize-playbook <alias>`     | Pin a custom atomize playbook artifact (by alias/id), overriding the system default for this brain                                                             |
| `--consolidate-playbook <alias>` | Pin a custom consolidate playbook artifact (by alias/id), overriding the system default for this brain                                                         |
| `--visibility <level>`           | Public read access: `private` (default, members only), `unlisted` (anonymously loadable/searchable by URL, noindex), or `public` (also discoverable/indexable) |

Every brain ships with system-default atomize and consolidate playbooks; the two flags above override them per-brain.

## rip brain visibility

Open an existing brain for anonymous read access — or close it again. A brain is `private` by default.

```bash theme={null}
rip brain visibility marketing unlisted
```

| Argument  | Description                                                                                                           |
| --------- | --------------------------------------------------------------------------------------------------------------------- |
| `<slug>`  | The brain to update (slug or id)                                                                                      |
| `<level>` | `private` (members only), `unlisted` (loadable/searchable by URL, noindex), or `public` (also discoverable/indexable) |

Raising visibility above `private` prints an exposure warning. Only owner-controlled content is ever exposed — superseded and pending (un-accepted) notes are withheld. The write surface stays members-only; anonymous reads hit `GET /v0/brains/:owner/:slug/{load,search}`.

## rip brain load

Load the brain envelope — pinned instructions, the working set of established notes, and a capped index — and attach a session.

```bash theme={null}
rip brain load marketing
rip brain load marketing --command atomize
```

Returns `{ slug, name, instructions, workingSet, index, sessionToken, lastSession }`. Call it once when you start working with a brain.

| Option                             | Description                                                                                                                       |
| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `--command <atomize\|consolidate>` | Load the named refinement playbook into the envelope's `flow` block — `{ command, alias, content }`. Omit it and `flow` is `null` |

## rip brain consolidate

Shortcut for `rip brain load <brain> --command consolidate` — the periodic promote/fuse/supersede ritual. Loads the consolidate playbook as `flow`.

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

## rip brain atomize

Shortcut for `rip brain load <brain> --command atomize` — decompose a source doc into reusable claim-notes (atoms). Loads the atomize playbook as `flow`.

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

## rip brain search

Unified hybrid search over the brain's notes and source-artifact chunks — the "consult before acting" path.

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

| Option                 | Description                                                        |
| ---------------------- | ------------------------------------------------------------------ |
| `--mode <mode>`        | `hybrid` (default, keyword + semantic), `keyword`, or `semantic`   |
| `--include-superseded` | Also recall retired (superseded) notes                             |
| `--expand <n>`         | Inline the full source body of the top-N hits as `expandedContent` |

Results carry `kind: "note"` (+ a `slug`) for curated notes, or `type: "artifact"` for source chunks — **branch on the discriminator** to tell them apart.

## rip brain capture

Record a note in the brain and index it so every member can recall it.

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

| Option                | Description                                                                                                            |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `--content <text>`    | Required — the knowledge to record                                                                                     |
| `--title <text>`      | Optional title                                                                                                         |
| `--zone <zone>`       | `doctrine` (default, stated facts), `signal` (decaying observations), `output` (produced work) — sets recall weighting |
| `--type <type>`       | Free-form claim type                                                                                                   |
| `--supersedes <slug>` | Retire a prior note this one replaces                                                                                  |
| `--mode <mode>`       | `async` (default, \~30s reconciler) or `sync` (embed inline, searchable immediately)                                   |

Capturing requires at least **contributor** access. Under a gated write policy, a contributor's capture **stages into the inbox** rather than landing live.

## rip brain inbox

List items staged for review (requires **editor**).

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

## rip brain inbox-resolve

Resolve a staged item (requires **editor**).

```bash theme={null}
rip brain inbox-resolve marketing 2026-06-15-margin-floor accept
```

| Argument / Option               | Description                                                                                           |
| ------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `accept` \| `reject` \| `merge` | `accept` admits it, `reject` archives it, `merge` (notes only) links it into `--target` then archives |
| `--zone <zone>`                 | On accept, set the note's zone                                                                        |
| `--maturity <state>`            | On accept, set the maturity state                                                                     |
| `--target <slug>`               | On merge, the note to fold into                                                                       |

## Across surfaces

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`), and the REST API (`/v0/brains`). `consolidate` and `atomize` are CLI shortcuts for `brain_load` with a `command`; over MCP and REST you pass the command directly. One divergence: the no-handle **multi-brain fan-out** — searching every brain attached to your session at once — is MCP-only (`brain_search` with no `brain` arg); the CLI always takes an explicit `<brain>`.

Add `--json` (or `TOKENRIP_OUTPUT=json`) for machine-readable output.