brain

Shared, durable memory for Claude — across Claude Code, Claude Desktop and Claude.ai — backed by one small Supabase Edge Function and a Postgres database.

Claude clients don't share memory with each other, and within a single client, context resets between sessions. Agents re-derive decisions that were already made, or forget them outright, because the reasoning behind a choice never made it into the code — it lived in a chat that's gone. brain is an MCP server that gives Claude a place to save durable facts — decisions, preferences, project context — and recall them later, from any client, scoped to projects that can be team-wide or personal. It runs as a single Supabase Edge Function; there's nothing to install locally to use it, only an endpoint + token to register with your MCP client.

Quickstart

Requires Docker (supabase start runs Postgres + the Edge Functions runtime locally) and the Supabase CLI.

git clone https://github.com/Caricalia/mcp-brain.git
cd mcp-brain
cp .env.example supabase/functions/.env
supabase start
supabase db reset                     # applies migrations + seed data
supabase functions serve --no-verify-jwt brain --env-file supabase/functions/.env

Issue yourself a token from the local Studio SQL editor (http://localhost:54323). The seed data includes a ready-to-use dev@example.com admin:

select issue_api_key('dev@example.com', 'laptop');

This prints a brain_<hex> token once, in plain text — copy it now. The local endpoint is http://localhost:54321/functions/v1/brain/mcp.

Connect Claude Code

claude mcp add brain --transport http \
  http://localhost:54321/functions/v1/brain/mcp \
  --header "Authorization: Bearer <token>"

Add --scope user if you want brain available in every project, not just the current one.

Connect Claude Desktop / claude.ai custom connector

Claude's own dialogs reserve the Authorization header and won't let you set it by hand, so brain also accepts the token as x-api-key. If the connector dialog lets you add a custom header, use:

x-api-key: <token>

Otherwise, bridge through mcp-remote in claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "brain": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "<url>",
        "--header",
        "Authorization: Bearer <token>"
      ]
    }
  }
}

Replace <url> with your endpoint and <token> with your token, then restart the client.

Verify it's connected

Ask the model: "who am I in brain?" — it should call whoami and answer with your identity, admin status, and whether search is running in text or semantic mode.

For the full walkthrough (recommended prompt text for CLAUDE.md / Claude Desktop preferences, a first-week checklist) see ONBOARDING.md. For running your own production instance, see DEPLOY.md.

Related MCP server: claude-brain

Architecture

• Postgres (Supabase) holds users, projects, memories and api_keys, plus the SQL functions that enforce visibility (memory_visible, project_scope, match_memories, ...).

• pgvector stores an embedding per memory when semantic search is enabled, for recall and duplicate detection.

• One Edge Function (supabase/functions/brain) is the entire server: a small Hono app wraps an mcp-lite MCP server exposing 14 tools over Streamable HTTP, authenticated by a per-user API key.

• mcp-lite also serves a bundled single-file HTML "MCP App" (open_memory_manager) — an interactive memory browser rendered inside Claude Desktop/Claude.ai, built separately under app/.

No ORM, no background workers, no separate API server: request in, SQL out, JSON back.

Tools

Permission / visibility model

• A project is team (owner_id is null, visible to everyone) or personal (visible only to its owner). Only admins can create team projects.

• A memory is shared (visible to anyone who can see its project) or private (visible only to its author). Default: private in personal projects, shared in team projects.

• A memory is editable by its author, or by anyone with project access if it's shared.

• Projects nest at most two levels (parent/child); recall on a child also searches the parent.

• Application code enforces all of this: every tool goes through one shared set of scope/visibility helpers (tools/access.ts). The Edge Function itself connects with the Postgres service role, which bypasses Row-Level Security by design (see SECURITY.md for why). Postgres RLS policies mirroring the same rules are also applied directly (supabase/migrations/20260915180143_lock_down_tables.sql) as a second, independent layer for a path the Edge Function doesn't use: direct PostgREST access with the anon/authenticated key. In this token-auth release, nothing populates users.auth_user_id, so app_user_id() resolves to null and every one of those policies evaluates to false for every row — PostgREST is simply closed end-to-end today, not "the same rules enforced a second time" against real per-user data. That's the correct, fail-closed outcome for a deployment that doesn't use Supabase Auth, but it means the RLS layer isn't currently exercised as a live second opinion; supabase/tests/rls_test.sql proves the policies are correct, not that they're presently doing live work.

Search: text vs. semantic

By default recall runs Postgres full-text search — no external dependency, no cost. Setting OPENAI_API_KEY switches it to semantic search (text-embedding-3-small) with near-duplicate detection on remember. Cost is trivial: the model is $0.02 per million input tokens, no output cost; even heavy daily use across a whole team runs a few cents a month. See "Enable semantic search" in DEPLOY.md for the exact steps.

Text mode is hardwired to Spanish (to_tsvector('spanish', content) / websearch_to_tsquery('spanish', ...) in the SQL functions, from this project's original deployment) even though this repository and its docs are in English. If you deploy a fresh instance and rely on recall in text mode (no OPENAI_API_KEY) with English content, keyword search quality will suffer — Spanish stemming doesn't match English words well. Workarounds until this is made configurable: enable semantic search (OPENAI_API_KEY), which doesn't use tsvector at all, or edit the 'spanish' regconfig in supabase/migrations/20260915000000_init.sql's memories.fts column and search_memories_text() function to 'english' in your own fork before your first deploy (the fts column is a stored generated column, so changing it after data exists requires a migration that rewrites the table).

Deploy

See DEPLOY.md for the full procedure (migrations, seed, deploy, tokens, embedding backfill, smoke test). Uses your own Supabase project; there is no shared hosted instance.

Benchmark

bench/ contains an optional bring-your-own-data benchmark for retrieval, LLM answers, and agent workflows. It publishes the harness and fictional placeholders only; it does not publish experiment results or project-specific data. See bench/README.md for setup instructions.

Limitations & anonymization

• No web UI beyond the MCP App, no hybrid text+semantic search, no automatic memory summarization/compaction, no local embeddings (OpenAI only, optional).

• The benchmark requires you to provide your own synthetic or approved dataset; do not commit real customer, business, or project data.

• This has been used by one small team, not battle-tested at scale — expect rough edges.

Authentication status

Token-based auth is the supported authentication flow in this release. OAuth login is not included.

Project layout

supabase/
  functions/brain/
    index.ts          # Hono app: /health and /mcp, resolves the credential
    auth.ts            # API key verification (Authorization or x-api-key)
    server.ts           # registers tools on mcp-lite
    db.ts                 # Supabase client (service role)
    embeddings.ts          # OpenAI embeddings call (optional)
    tools/
      projects.ts            # whoami, list_projects, create_project
      memories.ts              # remember, update_memory, forget
      search.ts                  # recall, search_by_tag, list_recent, get_project_context
      access.ts                    # shared visibility/permission helpers
      app.ts                         # open_memory_manager + app-only tools
      util.ts                          # ok()/fail() MCP response helpers
    ui/
      manager_html.ts                    # bundled memory-manager HTML, built from app/
  migrations/            # schema + SQL functions (RLS, search, dedup, counts)
  tests/rls_test.sql       # standalone RLS proof (not run by db reset/push - see CONTRIBUTING.md)
  seed.sql                   # example users/projects for local dev
scripts/
  backfill-embeddings.ts      # one-off embedding backfill after enabling OPENAI_API_KEY
bench/                          # bring-your-own-data benchmark harness
app/                               # memory manager MCP App (separate Vite build)

License

MIT.