Documentation

# Agent Onboarding: Brainbase

> **For:** Any MCP-compatible AI agent
> **Brainbase URL:** `https://brainbase.belweave.ai`
> **API Key:** `BB_API_KEY_PLACEHOLDER` ← **replace before use**

---

## 1. What You Have Access To

You are an autonomous agent with **persistent memory** via Brainbase — a polyglot knowledge graph combining Supabase Postgres + pgvector (system of record) with Neo4j (graph projection). Every user gets an isolated brain that stores everything your team learns, reads, and decides.

**Your job:** Read from the brain before answering. Write to the brain when you learn something new. Link related concepts so the graph stays connected.

---

## 2. Authentication

All write operations (and MCP calls) require an API key:

```
Authorization: Bearer ***
```

**Base URL:** `https://brainbase.belweave.ai/api/mcp`

**Multi-brain support:** If you need to access a brain other than your default, add:
```
X-Brain-Id: <brain-uuid>
```

---

## 3. MCP Tools (23 Available)

Connect via JSON-RPC 2.0 to `POST /api/mcp`.

### Read Tools (no quota cost)

| Tool | Purpose | Key Params |
|------|---------|------------|
| `search` | Full-text search pages | `query: string` |
| `query` | Natural language search | `question: string` |
| `get_page` | Get full page content + links + timeline | `slug: string` |
| `get_links` | Outgoing links from a page | `slug: string` |
| `get_backlinks` | Pages that link TO this page | `slug: string` |
| `get_timeline` | Timeline entries for a page | `slug: string` |
| `get_health` | Brain stats + score | — |
| `get_stats` | Detailed stats by type | — |
| `get_graph` | Full graph (nodes + edges) | — |
| `list_pages` | List pages with filters | `type?, written_by?, limit?, offset?` |
| `traverse_graph` | Walk the graph from a page | `slug, depth?, direction?, link_type?` |
| `list_triggers` | List active trigger rules | — |
| `pagerank` | Most central pages (Neo4j GDS or fallback) | `limit?` |
| `communities` | Louvain community detection | `limit?` |
| `shortest_path` | Shortest path between two pages | `from, to, max_depth?` |
| `similar_pages` | Pages similar by link structure | `slug, limit?` |

### Write Tools (quota-limited)

| Tool | Purpose | Key Params |
|------|---------|------------|
| `put_page` | Create/update a page | `slug, title, type?, content?, frontmatter?, written_by?` |
| `delete_page` | Remove a page | `slug` |
| `add_link` | Create typed link | `from, to, link_type?, written_by?` |
| `remove_link` | Remove a link | `from, to` |
| `add_timeline_entry` | Add event to timeline | `slug, date, summary, detail?, source?, written_by?` |
| `upsert_trigger` | Create automation rule | `name, conditions, actions, enabled?, cooldown_minutes?` |
| `run_triggers` | Manually fire rules on page | `slug, title, type?, content?` |

### Enrichment (REST API)

Brainbase's enrichment pipeline creates rich, sourced pages for people and companies with
a single API call. Uses Brave Search + OpenAI formatting.

`POST /api/brain/enrich` — See [Enrichment API](#enrichment) section below.

---

## 4. How to Think About the Brain

### Page Structure
Every page has:
- **slug** — unique ID (e.g., `people/garry-tan`, `projects/brainbase`)
- **type** — `person`, `company`, `project`, `concept`, `email`, `idea`, etc.
- **content** — markdown body
- **links** — typed connections to other pages (`related`, `works_at`, `invested_in`, `founded`, etc.)
- **timeline** — dated events
- **embeddings** — OpenAI text-embedding-3-small vector for semantic search

### Your Read Pattern (ALWAYS DO THIS FIRST)

```
1. User asks a question
2. SEARCH the brain first → get relevant slugs
3. GET_PAGE on the most relevant result → read full context
4. GET_LINKS / TRAVERSE_GRAPH → explore connections
5. Answer the user WITH citations to brain pages
```

### Your Write Pattern

```
1. You learn something new (from email, web, conversation)
2. PUT_PAGE with proper frontmatter:

   ---
   type: email | person | company | concept | project
   date: YYYY-MM-DD
   source: agentmail | web | conversation
   tags: [newsletter, security, ai]
   ---

3. If related pages exist → ADD_LINK to connect them
4. If dates mentioned → ADD_TIMELINE_ENTRY
```

---

## 5. Example Workflows

### Example 1: Answer a question about someone
```json
// 1. Search
{"method": "tools/call", "params": {"name": "search", "arguments": {"query": "Garry Tan"}}}

// 2. Get page
{"method": "tools/call", "params": {"name": "get_page", "arguments": {"slug": "people/garry-tan"}}}

// 3. Get connections
{"method": "tools/call", "params": {"name": "get_links", "arguments": {"slug": "people/garry-tan"}}}

// 4. Find most connected people
{"method": "tools/call", "params": {"name": "pagerank", "arguments": {"limit": 10}}}
```

### Example 2: Ingest a security alert
```json
// 1. Write the page
{"method": "tools/call", "params": {"name": "put_page", "arguments": {
  "slug": "security/cve-2025-1234",
  "title": "CVE-2025-1234: Critical RCE in OpenSSL",
  "type": "concept",
  "content": "# CVE-2025-1234...",
  "frontmatter": {"date": "2025-04-29", "severity": "critical", "source": "nist"}
}}}

// 2. Link to affected project
{"method": "tools/call", "params": {"name": "add_link", "arguments": {
  "from": "security/cve-2025-1234",
  "to": "projects/brainbase",
  "link_type": "affects"
}}}
```

### Example 3: Set up a trigger
```json
{"method": "tools/call", "params": {"name": "upsert_trigger", "arguments": {
  "name": "cve-alert",
  "conditions": {"pageType": "concept", "contentContains": ["CVE", "vulnerability"]},
  "actions": [{"type": "notify", "message": "🚨 CVE detected: {slug}"}],
  "enabled": true
}}}
```

### Example 4: Graph intelligence
```json
// Find shortest path between two entities
{"method": "tools/call", "params": {"name": "shortest_path", "arguments": {
  "from": "people/garry-tan",
  "to": "companies/anthropic",
  "max_depth": 4
}}}

// Find similar pages by link structure
{"method": "tools/call", "params": {"name": "similar_pages", "arguments": {
  "slug": "people/garry-tan",
  "limit": 10
}}}
```

---

## 6. Important Rules

### DO
- **Search the brain first** before using external APIs or claiming ignorance
- Use descriptive slugs: `people/first-last`, `companies/company-name`, `projects/project-name`
- Include frontmatter with `type`, `date`, and `source`
- Link related pages — isolated pages are useless
- Write in markdown with headers for structure
- Use timeline entries for dated events
- Use `written_by` parameter to track which agent created content

### DON'T
- Don't write pages without checking if they already exist (search first)
- Don't create generic slugs like `page-1` or `untitled`
- Don't dump raw data — summarize and structure it
- Don't forget to link — the graph is the value
- Don't expose the API key in logs or user-facing output

---

## 7. Page Types & Conventions

| Type | Use For | Example Slug |
|------|---------|--------------|
| `person` | People your team knows | `people/jane-doe` |
| `company` | Companies, orgs | `companies/openai` |
| `project` | Code projects, initiatives | `projects/brainbase` |
| `concept` | Ideas, frameworks, CVEs | `concepts/rag-pipeline` |
| `email` | Ingested emails | `email/team/2026-04-29/subject` |
| `idea` | Raw thoughts, brainstorming | `ideas/agent-email-integration` |
| `place` | Locations, venues | `places/san-francisco` |

---

## 8. Troubleshooting

| Issue | Fix |
|-------|-----|
| `401 Unauthorized` | API key missing or invalid |
| `403 Forbidden` | You don't have access to that brain |
| `404 Page not found` | Slug doesn't exist — create it or check spelling |
| Quota exceeded | Write operations are rate-limited; wait or contact your admin |
| Graph empty | Brain has < 2 pages or no links — start adding content |
| `neo4j_not_configured` | Graph intelligence requires Neo4j; falls back to Postgres for some ops |

---

## 9. Architecture Notes

- **Database:** Polyglot — Supabase Postgres + pgvector (system of record) + Neo4j (graph projection)
- **Search:** Hybrid full-text + semantic (embeddings), RRF fusion, 7-stage pipeline
- **Graph:** Typed wikilinks stored as edge rows, projected to Neo4j for intelligence
- **Pipeline:** `put_page` → embeddings → auto-extract (wikilinks + dates + semantic links) → triggers → actions
- **Graph Backend:** Set `BRAINBASE_GRAPH_BACKEND=auto|postgres|neo4j` to control routing
- **Hosting:** Vercel, edge-cached reads

---

**Last updated:** 2026-05-03