personal-brain-mcp

A serious second brain for your personal life, exposed as a Model Context Protocol server. Drop it into Claude Desktop, Cursor, n8n, or any MCP client and ask your own life questions.

Claude Desktop / Cursor / n8n / your own agents
                │
                │  HTTPS + SSE + Bearer token
                ▼
        Cloudflare Worker  ◄────  iPhone Shortcuts (capture, health)
        (this repo)        ◄────  Telegram / Discord bots (chat capture)
                │
                │  Postgres + pgvector (service role)
                ▼
              Supabase
        (schema: brain)

What it is

A personal-life database with 47 tools + 4 HTTP ingest endpoints + inbound chat bots across 13 domains, with semantic search, hybrid retrieval (vector + keyword), and a four-layer memory model.

You stand it up once, then use it from any MCP-aware AI client. It's your brain; you own the data; it runs on free tiers.

Domains covered

| Domain | Tracks | |---|---| | Memory | Identity, durable facts, episodic journal, decisions, gratitudes | | Food | Recipes, meal plan, pantry, dietary prefs | | Home | Inventory, warranties, projects, maintenance, expenses, properties | | Vehicles | Fleet, mileage, service history, insurance/registration | | Pets | Health events, vet schedule, food brands | | People | Family, gifts, personal contacts, interactions, professionals | | Health | Workouts, medications, providers, wearable metrics | | Travel | Trip history, packing templates | | Hobbies | Reading list, content queue | | Finance | Subscriptions, tax docs, account directory | | Records | Documents, anniversaries, wishlist, emergency info, routines | | Projects | Personal projects, bucket list | | Composite | ask_brain, current_state, dashboard, briefings, capture, recall, proactive check |

Full catalog: TOOLS.md.

Why this exists

Memory you control. No vendor lock-in. The brain is just Postgres rows you can dump anytime.
One brain, many clients. Same data accessible from every AI client that speaks MCP.
Cheap. Cloudflare Workers free tier + Supabase free tier + ~$0.50/mo for OpenAI embeddings.
Opinionated. Schema and tools designed for a real personal life, not a generic note-taking app.

Quick start

If you know what you're doing:

git clone https://github.com/YOUR_GITHUB_USER/personal-brain-mcp.git
cd personal-brain-mcp
npm install
cp .dev.vars.example .dev.vars     # fill in real values
supabase link --project-ref <ref>
supabase db push
wrangler dev

If you want guidance, read SETUP.md. It walks the whole flow with the why behind each step.

Documentation

| File | What's in it | |---|---| | SETUP.md | Beginner-friendly end-to-end setup | | MEMORY.md | Four-layer memory architecture (identity, state, episodic, semantic) | | TOOLS.md | Full tool and endpoint catalog | | CRON.md | Scheduled jobs (daily proactive push to chat) | | system-prompt-template.md | Drop-in instructions for your LLM client | | shortcuts/README.md | iPhone Shortcuts for capture/health/expense | | bots/README.md | Telegram + Discord chat capture bots | | bots/telegram-setup.md | ~10 minute Telegram bot setup | | bots/discord-setup.md | ~20 minute Discord bot setup | | bots/whatsapp-setup.md | WhatsApp setup if you commit to it |

Stack

Cloudflare Workers — Worker + Cron Triggers (free tier handles personal use easily)
Supabase — Postgres + pgvector + RLS (free tier works for one user; upgrade for backups)
OpenAI — text-embedding-3-small for semantic search
TypeScript + MCP SDK + Zod — server-side
@supabase/supabase-js — typed DB client

What this is NOT

Not a calendar. Use your existing calendar (Google, Outlook, etc.). This brain has a query_external_data tool that points the LLM to your calendar connector when needed.
Not an email client. Same as calendar.
Not a balance tracker. It tracks which accounts exist, not balances. Use Plaid / your bank's portal for balances.
Not a habit tracker. Use TickTick, Habitica, Streaks, etc. — they're better at habits than a Postgres row would be.
Not for business data. Build a second MCP server for business context (the architecture supports this — just use a different Supabase schema like org_a and a separate Worker).

Architecture decisions worth understanding before you fork

MCP as the access layer, not the storage. The brain is just Postgres. MCP tools are the read/write API. You can always query the DB directly.
Service role from the Worker. RLS is enabled but no policies; the Worker is the trust boundary. Single-user assumption baked in. If you want multi-tenant, write proper RLS policies before deploying.
Append-immutable facts. Layer-4 facts use superseded_by chains. Old values are preserved.
Hybrid retrieval. ask_brain combines vector similarity with pg_trgm keyword match. Both contribute.
Source-agnostic chat capture. Adding a new platform = one adapter file. iMessage and Signal are explicitly NOT supported (see bots/README.md for reasoning).

Origin and credit

Inspired in part by Friday (a 24/7 assistant built on Claude Code), particularly its proactive-messaging pattern, control-plane-as-prompt approach, and hybrid retrieval. Architecture diverges where MCP-as-server and pgvector-as-store are the better fit.

License

MIT. See LICENSE.

Contributing

PRs welcome for:

Additional ingest sources (WhatsApp implementation, Slack, etc.)
Additional MCP clients beyond Claude Desktop
Schema or tool improvements that stay generic
More iPhone / Android Shortcuts patterns

Not welcome:

Personal-flavor changes (your spouse's name as the default test value, etc.)
Locking the design to a single LLM vendor
Bundling external dependencies that aren't justified

If your fork diverges significantly from "personal life brain," that's great — give it a different name and link back. This project will stay opinionated about scope.

MCP Servers