nbrain

Files (4)

• SKILL.md
• provision-scopes.sh
• roster.example.tsv
• tool.json

SKILL.md (first lines)

# nbrain — the company brain

This sandbox has the `nbrain` CLI connected (thin-client) to the org's central
brain. It is the deep, indexed, cross-source memory: org docs, shared channel
knowledge, and every agent's durable notes. Your scope's own notebook stays the
fast per-turn memory; the brain is where knowledge outlives a scope and becomes
searchable by everyone entitled to it.

## First-run setup (once per sandbox — skip if `nbrain remote doctor` passes)

Your scope's brain credentials arrive via the deployment's secret handoff
(keychain entry or one-time secret drop named `nbrain`). Then:

```bash
nbrain init --mcp-only \
  --issuer-url "https://brain.<org>.com" \
  --mcp-url "https://brain.<org>.com/mcp" \
  --oauth-client-id "<client id from the handoff>" \
  --oauth-client-secret "<client secret from the handoff>"
nbrain whoami   # must succeed before using any other command
```

Pass the secret with `--oauth-client-secret`, not via `NBRAIN_REMOTE_CLIENT_SECRET`:
an env-sourced secret is deliberately NOT written to `~/.nbrain/config.json`, so
every later command would fail with "No client_secret available" once the
variable is out of scope. The flag persists it to the config file on this
sandbox's durable disk, which is what the tool's credential capture expects.

Do not run `nbrain remote doctor` — it needs `admin` scope, which your client
does not have (by design). `nbrain whoami` is the read-scope health check.

## Reading (do this liberally)

```bash
nbrain search "who decided X and why"     # hybrid semantic + keyword search
nbrain get <slug>                          # read one page
nbrain query "question" --json             # search tuned for agent consumption
```

You can read: the shared agent-memory source, org read-only sources (wiki,
handbook), and everything under them. Reads are isolation-enforced server-side;
you only ever see sources your client is entitled to.

## Writing (durable knowledge only, under YOUR prefixes)

Your client is write-fenced to slug prefixes — your own namespace plus the
channels you belong to. Writes outside them are rejected server-side.

```bash
# personal durable memory (your namespace):
nbrain put emp-<your-slug>/people/jane-example --content "..."

# shared channel knowledge (channels you are in):
nbrain put chan-eng/decisions/2026-08-database-choice --content "..."
```

Conventions:
- Write conclusions and durable facts, not chat transcripts. One page per
  entity/decision/topic; update the page rather than appending near-duplicates.
- Markdown with YAML frontmatter; the brain chunks, embeds, and links it.
- Cross-reference liberally: `nbrain link <from> <to>` (from must be in your
  namespace; linking TO any readable page is fine).
- When you learn something channel-relevant in personal work, mirror the
  conclusion into the channel prefix with a `(said in <where>)` provenance
  note.

## When to reach for the brain

- Any question about the org, a person, a project, a decision, or history →
  `nbrain search` FIRST, then answer.
- You produced knowledge with value beyond this conversation → `nbrain put`.
- Something looks wrong (auth errors, empty results you don't expect) →
  `nbrain whoami` to confirm which client and scopes you're using, and report
  its output.

From nastechresearch/nbrain, MIT.

More from nastechresearch/nbrain