Brainstem

Give your AI a second brain.

---

You maintain a personal knowledge base — notes, docs, references — in a GitHub repo. Maybe you use Obsidian, Logseq, or just plain markdown. Maybe you use Claude Code, ClawdBot, Codex, or another agent to help maintain it.

Brainstem connects that repo to your AI chat clients so you can search and retrieve your own knowledge from anywhere — your phone, your desktop, or any MCP-compatible tool.

Here's how it works:

1. You have a GitHub-hosted PKM (personal knowledge management) repo, public or private
2. You install the Brainstem GitHub App on that repo
3. Brainstem embeds your content and keeps its index up-to-date with every push
4. Brainstem exposes search & retrieval tools via MCP that you connect to any compatible AI client (Claude Mobile, Claude Desktop, Claude Code, etc.)

That's it. Push to GitHub, and your AI can search it within a minute.

Quick Start

1. Connect Your Repository

1. Visit brainstem.cc/setup
2. Click Connect Repository to install the GitHub App
3. Select your repository
4. Copy your unique MCP endpoint URL from the success page

2. Connect Your AI Client

Claude.ai (Web) — easiest

1. Go to Settings → Connectors → Add custom connector
2. Paste your MCP endpoint URL: https://brainstem.cc/mcp/{your-uuid}
3. Claude.ai handles authentication automatically via OAuth — no token needed

Claude Desktop / Claude Code

Add to your MCP config (Claude Desktop: claude_desktop_config.json, Claude Code: .mcp.json or via claude mcp add):

{
  "mcpServers": {
    "my-brain": {
      "url": "https://brainstem.cc/mcp/{your-uuid}"
    }
  }
}

OAuth authentication is handled automatically — you'll be prompted to authorize with GitHub on first use. No manual token needed.

MCP Tools

Brainstem exposes eight tools over MCP:

Tool	Description
search_brain	Semantic search across your knowledge base. Results include source links back to GitHub. The tool description dynamically reflects your actual content domains and topics.
get_document	Retrieve the full contents of a file by its path.
list_recent	List recently modified files, optionally filtered by path prefix.
list_folders	Browse the folder structure of your repo.
brain_inbox	Compose a note for your inbox. In Claude Desktop, opens an interactive composer with live markdown preview, 5-second auto-save countdown, and edit/cancel controls. Notes are saved to both GitHub and the search index.
brain_inbox_save	Save a note directly to the inbox (R2 + GitHub). Preferred for non-UI hosts and AI agents.
brain_account	Manage email-to-brain forwarding: verify senders, claim vanity aliases, check status.
about	Information about your Brainstem instance and available content.

How Sync Works

GitHub Push  → Webhook → Brainstem Worker → R2 Storage → AI Search (reindex)
Email        → Worker email() handler ↗
Web Clipper  → POST /api/clip ↗
Inbox Tools  → MCP tool call ↗

• When you push to your connected repo, GitHub sends a webhook to Brainstem
• Brainstem fetches the changed files via the GitHub API and stores them in Cloudflare R2
• A reindex is triggered on Cloudflare AI Search
• New content is searchable within ~1 minute

Sync is incremental — only changed files are fetched on each push.

Ways to Save

Beyond syncing your GitHub repo, there are three additional input paths:

Method	How It Works
Email forwarding	Forward emails to your @brainstem.cc address. Set up via the brain_account MCP tool.
Web clipper	Browser bookmarklet extracts articles and saves them to your inbox. Get it from your OAuth success page or /bookmarklet.
Inbox tools	Your AI can save notes directly via brain_inbox (interactive composer) or brain_inbox_save (direct save).

All saved content lands in your inbox/ folder and is searchable within a minute.

Architecture

Built on Cloudflare's stack:

• Cloudflare Workers with Durable Objects for MCP session state
• Cloudflare R2 for file storage
• Cloudflare D1 (SQLite) for installation and user tracking
• Cloudflare AI Search for semantic search and retrieval
• GitHub App for authentication, webhooks, and repo access

Security & Privacy

Your synced files are stored on Cloudflare R2, encrypted at rest with AES-256-GCM (Cloudflare-managed keys), and indexed by Cloudflare AI Search for semantic retrieval. All connections use TLS. Access to your data requires authentication via GitHub OAuth.

Tenant isolation: Each installation's data is stored under a unique R2 prefix (brains/{uuid}/) and search queries are scoped using folder metadata filters. This isolation has been verified with multiple live installations — searches, file listings, and document retrievals from one installation cannot access another installation's data. Debug endpoints enforce ownership checks. See the backlog for detailed test results.

The platform operator has technical access to stored content for operational purposes. This is the same trust model as most SaaS products — you are trusting both the infrastructure provider (Cloudflare) and the platform operator. Do not connect repositories containing secrets, credentials, or highly sensitive data you are not comfortable storing on a third-party service.

You can disconnect and delete all your synced data at any time by uninstalling the GitHub App from your repository settings. Uninstallation triggers automatic cleanup of all stored files and search index entries.

For a full analysis of the encryption and isolation model, see ADR-003: Encryption at Rest.

Documentation

• TROUBLESHOOTING.md — Common issues and solutions
• CLAUDE.md — Implementation details and development guide

License

ISC