How to use TeamBrain

Everything a developer needs to use TeamBrain day to day — connect your AI tool, the slash commands, the Slack bot — with snippets pre-filled for you when you're signed in. For per-repo setup (register, capture-on-merge), see Repositories.

Connect your AI tool

TeamBrain is a remote HTTP MCP server — no local install, no stdio. The endpoint is the same for everyone; the only per-developer value is your bearer JWT. Pick your client:

# ~/.codex/config.toml
[mcp_servers.teambrain]
url = "https://pr.fabric-testbed.net/functions/v1/teambrain-mcp/mcp"
bearer_token_env_var = "TEAMBRAIN_JWT"

export TEAMBRAIN_JWT=''
codex

{
  "mcpServers": {
    "teambrain": {
      "url": "https://pr.fabric-testbed.net/functions/v1/teambrain-mcp/mcp",
      "headers": { "Authorization": "Bearer ${TEAMBRAIN_JWT}" }
    }
  }
}

export TEAMBRAIN_JWT=''
curl -sS -X POST \
  https://pr.fabric-testbed.net/functions/v1/teambrain-rest/thoughts/search \
  -H "Authorization: Bearer $TEAMBRAIN_JWT" \
  -H "Content-Type: application/json" \
  -d '{"query":"how do we handle timestamps?","project_slug":"fabric-testbed/TeamBrain","limit":5}'

Slash commands

Optional one-keystroke shortcuts over the connected MCP server — they add no new transport and carry no credentials. Connect the server (above) first.

Claude Code: committed at .claude/commands/ — auto-discovered, no install. Cursor: templates under examples/slash-commands/cursor/ (community, untested). To add them to another repo, see Install into any repo below — no TeamBrain checkout needed.

Codex skills

The same three actions are packaged as Codex skills under .agents/skills/ (tb-recall, tb-recent, tb-remember) — repo-discovered, no install. They're the Codex equivalent of the Claude Code slash commands: trigger them with /skills or a $-mention, or just ask Codex to remember or recall and it picks the right one. To add them to another repo, see Install into any repo below.

Install into any repo

Cloned a registered repo but it doesn't carry the commands? You don't need a TeamBrain checkout — pull them straight from here. They're credential-free prompt templates, so connect the MCP (above) first or they have nothing to call.

Ask your agent. If TeamBrain is connected, just say "install the TeamBrain slash commands" — the get_client_commands MCP tool returns the files and the agent writes them into this repo. No URLs, no copying, no crawling the TeamBrain source.

Or run the installer from your repo root:

curl -fsSL https://pr.fabric-testbed.net/install.sh | sh

Installs all three clients by default; scope with … | sh -s -- --client claude-code (claude-code, codex, or cursor), or preview with --list. The machine-readable file list is at /install/manifest.json.

Slack live

Capture and recall from Slack with a /tb slash command — no AI tool required. A project admin links the channel to a project first (one channel ↔ one project); after that, everyone in the channel can use it.

Linking a channel (one-time, project admin)

1. In the target channel, run /tb link fabric-testbed/your-repo — it replies (only to you) with a curl pre-filled with that channel's IDs.
2. Grab your JWT from Home, then run the curl (it POSTs to …/teambrain-slack/links). You must be a TeamBrain admin of the project.
3. /tb status confirms the link. Unlink later with DELETE …/teambrain-slack/links/{id} (also admin-gated). Check your role on Repositories.

Creating the Slack app itself (workspace admin, one-time) is covered by examples/slack/README.md. After the /tb command is added, the app must be reinstalled to the workspace — Slack only registers a slash command on (re)install, so until then /tb returns "not a valid command."

Which project_slug to use

Every operation is scoped to a project, identified by its owner/repo slug (e.g. fabric-testbed/TeamBrain). Pass it explicitly — if you omit it the server falls back to a configured default, which is rarely the repo you mean.

Auto-capture on PR merge

A GitHub Action proposes memories every time a PR merges and opens an approval issue listing them; an approver comments /approve (or /deny) whenever they get to it — there's no time limit, and zero GitHub Actions minutes are spent while the issue waits. Wiring it up (issue a token, set repo secrets, open the workflow PR) is a per-repo admin task — do it from Repositories, or read capture-on-merge-adoption.md for the full walkthrough.

Need to pause it — say, to conserve GitHub Actions minutes? A repo admin can toggle capture off from Repositories without removing the workflow file, or set the repo variable TEAMBRAIN_CAPTURE=off for a zero-minute hard stop.

Memory lifecycle: stale, re-verify, deprecate, promote

Memories are living, not write-once. A background scan can flag a thought as stale — a badge that means "a human should re-check this," not a verdict that it's wrong. Two signals set it today:

• A commit touched a pinned path. If a thought lists files in its paths and a merged commit changes one, it flags itself — "the code this advice was about just changed; is the advice still true?"
• An expires_at passed. Captured with a shelf life (a temporary workaround, a "remove after date X" note)? It flags when that time arrives.

When you see a flagged thought, re-read it against current reality and pick one:

When an already-confirmed thought flags again

A confirmed memory turning up flagged is not a contradiction — confidence and the stale flag are orthogonal. Confidence is a trust verdict; the flag is a "re-check this" badge tripped by a heuristic (a commit touched a pinned path, or expires_at passed). A confirmed thought can flag, by design. Usually that's the system working: if a reviewer re-raises something the thought already settled, surfacing it (with its promoted_pr_url) is the answer — clear the flag once you've reconfirmed the decision still holds. If the change actually invalidated it, fix the source of truth (update the docs/ markdown by PR) and deprecate the thought.

One wrinkle for the still-true case: mark_stale only accepts tentative or deprecated — there is no "re-verify and stay confirmed" in a single call. So re-verifying a confirmed thought downgrades it to tentative (rank multiplier 1.15 → 1.0, minor), and promote_to_docs re-stamps confirmed but does not bump last_verified_at, so it won't clear the flag on its own. To land a thought both unflagged and confirmed, order matters:

1. mark_stale(thought_id, confidence: 'tentative') — the thoughts_clear_stale_flag_on_verify trigger clears the flag the moment last_verified_at advances.
2. promote_to_docs(thought_id) — idempotent; re-stamps confirmed.

In practice most people stop at step 1: once a thought is promoted, the markdown in docs/ is the real source of truth, so letting the thought ride as tentative is fine — only re-promote if the "confirmed" badge matters to you.

Under the hood, search orders by a freshness-aware rank_score = similarity × confidence (confirmed 1.15 · tentative 1.0 · deprecated 0.4) × expiry × recency (90-day half-life), so stale and deprecated memories sink while re-verified ones rise — but only within results that already match your query.

Mental model & deeper docs

Two concepts cover almost everything you capture:

Type (optional but recommended): decision · convention · gotcha · context · preference · runbook.

• Getting started — the full end-user onboarding guide
• AGENTS.md — orientation for AI agents working in a repo
• OpenAPI spec — the REST contract
• Dashboard — your capture activity
• Repositories — per-repo setup & status