Docs

Getting started

Two ways to run the same brain: hosted at brainz.brownmatter.ai (free, remote MCP over HTTP) or local-first from a folder of markdown (open source CLI, MCP over stdio). Both expose the identical nine tools, so your orchestrator doesn't care which one it's talking to.

Hosted: remote MCP in two minutes

Sign up — it's free — and create a vault.
In the vault's settings, create an API key. Keys look like bz_…, are scoped to that one vault, and are shown exactly once — store it like a secret.
Add the server to your MCP client. In a project's .mcp.json:

{
  "mcpServers": {
    "brainz": {
      "type": "http",
      "url": "https://brainz.brownmatter.ai/mcp",
      "headers": { "Authorization": "Bearer bz_..." }
    }
  }
}

Or with the Claude Code CLI:

claude mcp add --transport http brainz https://brainz.brownmatter.ai/mcp \
  --header "Authorization: Bearer bz_..."

That's the whole integration. Your orchestrator can now call vault_stats to orient itself, search_concepts to explore, and get_context to brief subagents.

An orchestrator doesn't need a pre-made account. Point it at https://brainz.brownmatter.ai/mcp without an Authorization header and it gets a public MCP server exposing a single signup tool (the nine vault tools stay behind authentication):

# 1. connect UNAUTHENTICATED — no Authorization header
#    initialize → tools/list shows exactly one tool: signup

# 2. call it with your human's email
→ tools/call signup { "email": "you@company.com", "vaultName": "Acme brain" }

# 3. the result is everything the agent needs
← {
    "apiKey":    "bz_…",                                  // keep this — works immediately
    "claimUrl":  "https://brainz.brownmatter.ai/claim/…",  // deliver this to your human
    "vaultSlug": "acme-brain",
    "email":     "you@company.com"
  }

The apiKey works immediately — the agent reconnects to the same endpoint with Authorization: Bearer bz_… and can start seeding the vault right away. The claimUrl is for the human: opening it shows the account email and a set-password form, then signs them into the dashboard. Claim links are single-use and expire after 7 days; an unclaimed account keeps working for the agent — only the claim link expires. Password sign-in stays disabled until the account is claimed, and signups are rate-limited to 5 per hour per IP.

Onboard your product

A fresh vault is an empty brain. The onboard tool fixes that without you writing a single note: your orchestrator calls onboard with {"action": "start"} and receives a playbook — fan subagents out over the codebase, distill what they find into the product ontology, and write it back with upsert_concept.

The ontology is ten concept types, and five of them carry the structure: domain (high-level product areas — the top of the graph), feature (concrete capabilities, part_of a domain), story (user stories, realized_by the features that deliver them), spec (the rules that govern features and stories), and workflow (multi-step journeys across features) — plus the classics: concept, decision, constraint, pattern, glossary. Every concept can carry code_areas — rough paths or globs pointing at where that knowledge lives in the codebase — so a subagent briefed by get_context learns the rules and where to apply them.

When the graph is written (20–60 concepts for a mid-size product), the agent calls onboard with {"action": "complete", "summary"}. Until then, search_concepts and get_context responses carry a one-line reminder — a nudge, never a wall. Local vaults get the same flow via brainz onboard.

Local-first: a vault is just a folder

The open-source CLI runs the same engine against a directory of markdown. Notes are plain files with YAML frontmatter; the search index is derived SQLite in .brainz/ — gitignored, safe to delete, rebuilt from your files.

# scaffold a vault (config + concepts/ + a sample note)
npx brainz init my-vault

# add concepts and link them
npx brainz add "Billing Engine" --vault my-vault --type feature --body "Handles invoicing."
npx brainz add "Ledger" --vault my-vault --body "Double-entry ledger."
npx brainz link billing-engine ledger --relation depends_on --vault my-vault

# query it
npx brainz search "billing" --vault my-vault
npx brainz context --query "billing" --budget 800 --vault my-vault

Serve the vault to your agents over stdio MCP:

{
  "mcpServers": {
    "brainz": {
      "command": "npx",
      "args": ["brainz", "mcp", "--vault", "/absolute/path/to/my-vault"]
    }
  }
}

The vault directory can also be set via the BRAINZ_VAULT environment variable. Search is hybrid (full-text + embeddings, fused by reciprocal rank); if an embedding provider isn't configured or available, it degrades gracefully to keyword-only.

The nine MCP tools

These names and descriptions are the exact text your orchestrator sees — lifted from the tool registry that both the hosted and local servers register from, so they never drift.

Tool	Description
`search_concepts` Search concepts	Search the product knowledge vault by free-text query. Use this first, whenever you need product knowledge but don't yet know which concept ids exist — e.g. before planning work that touches a feature, decision, or constraint. Returns ranked hits (id, title, type, score, snippet) only; follow up with get_concept for one full note or get_context for an injectable bundle. Never errors on odd queries — an empty hit list just means nothing matched.
`get_concept` Get concept	Fetch one concept by exact id: full markdown body, metadata, and its direct graph neighbors (each with the relation that connects it). Use after search_concepts or when another note wiki-links an id you need in full. The neighbors list tells you what to fetch next. If you don't know the id, use search_concepts instead.
`get_related` Get related concepts	Walk the knowledge graph outward from a concept and return everything within `depth` hops, with distance and the edge path that reached it. Use to map the blast radius before changing a feature (what depends on it, what constrains it, which decisions apply) or to discover structure that keyword search misses. Filter by relation names (e.g. depends_on) to follow only one kind of edge.
`get_context` Assemble context bundle	THE tool to call before delegating a coding task: assembles a ready-to-inject markdown briefing of the most relevant concepts (seeded by a search query and/or explicit ids, expanded through the graph) trimmed to a token budget. Paste the returned markdown straight into a subagent's prompt so it gets curated product knowledge without you relaying individual notes. The final JSON line reports which concept ids were included, whether the bundle was truncated, and its approximate token count. Provide at least one of `query` or `ids`.
`upsert_concept` Create or update concept	Write a concept note into the vault (creates or overwrites the markdown file, then reindexes it). Use to capture new product knowledge discovered during a task — a decision made, a constraint hit, a pattern adopted — so future agents can find it. Omit `id` to derive a slug from the title; pass an existing id to update that note. Body is markdown; [[wiki-links]] to other concept ids create graph edges. Returns the saved concept's metadata.
`link_concepts` Link concepts	Add a typed, directed edge between two existing concepts by editing the `from` note's frontmatter (e.g. lead-scoring depends_on contact-model). Use when you notice a relationship the vault is missing. Both concepts should already exist; use upsert_concept first if not.
`list_concepts` List concepts	Enumerate concept metadata (no bodies), optionally filtered by product, type, or a single tag. Use to get the lay of the land in an unfamiliar vault, to audit what exists (e.g. all decisions for a product), or when search vocabulary isn't matching. For content, follow up with get_concept or get_context.
`vault_stats` Vault stats	Cheap orientation call: counts of concepts and edges, the products and tags in use, a breakdown by concept type, and whether semantic search is available. Call once when connecting to an unfamiliar vault to calibrate how much knowledge is here and which product/tag filters exist.
`onboard` Onboard this vault	Step 1 on any new vault: onboarding turns an existing product's codebase into the knowledge graph your whole agent fleet shares. Call {action: "start"} to receive the onboarding playbook — instructions for fanning subagents out over the codebase and distilling product knowledge (domains, features, stories, specs, workflows, decisions, constraints) into concepts via upsert_concept, each anchored to the code with codeAreas. When the graph is written, call {action: "complete", summary} to mark the vault onboarded and store the summary. {action: "status"} reports onboarded state and concept counts. Until onboarding completes, search_concepts and get_context results carry a reminder to run it.

One convention worth knowing: get_context responds with two text blocks — first the assembled markdown briefing (paste it straight into a subagent prompt), then a single-line JSON footer { included, truncated, approxTokens }. Every other tool responds with one JSON text block.

Where to go next

Create a free vault and point an orchestrator at it — the fastest way to feel the get_context loop.
Onboard your product: point your orchestrator at the vault and have it call the onboard tool — it maps your codebase into domains, features, stories, specs, and workflows, each anchored to the code that implements it.
Tell your orchestrator (e.g. in CLAUDE.md) to call get_context before delegating, and upsert_concept when it learns something worth keeping.

Hosted: remote MCP in two minutes

Agent-driven signup: no human in the loop

Onboard your product

Local-first: a vault is just a folder

The nine MCP tools

Where to go next