claude-brain

A persistent memory layer for Claude. Every prompt/response exchange is logged to a Postgres database (Supabase), and an MCP server exposes tools so Claude itself can save and recall that history on demand — with full-text search.

Why

LLM conversations are ephemeral by default — close the session and the context is gone. This project gives Claude a durable, queryable memory: a database it can write to and search through the Model Context Protocol, plus (in progress) a web interface for browsing that history as a human.

Related MCP server: SharedMemory MCP Server

Architecture

flowchart LR
    A[Claude Desktop / Claude Code] -- "MCP (stdio)" --> B[claude-brain server]
    B -- "@supabase/supabase-js" --> C[(Supabase Postgres)]
    D[Web interface, Claude Design] -.planned.-> C

• src/server.ts — the MCP server, built on @modelcontextprotocol/sdk. Registers four tools:

  Tool	Purpose
  save_memory	Store one message (role, content, model, metadata) under a session id
  search_memory	Full-text search across everything ever stored
  get_recent_memory	Most recent messages, optionally scoped to a session
  list_conversations	List known sessions

• supabase/migrations/0001_init.sql — schema: conversations (one row per session) and prompt_logs (one row per message, with a generated tsvector column powering search).

• src/tools/ — one module per tool, thin and independently testable wrappers around the Supabase client.

• tests/ — Vitest suite covering input validation (Zod schemas) for every tool.

Tech stack

TypeScript · Node.js · Model Context Protocol SDK · Supabase (Postgres) · Zod · Vitest · GitHub Actions

Setup

1. Create a Supabase project at supabase.com.

2. Run the migration in supabase/migrations/0001_init.sql against it (via the SQL editor, or supabase db push if you link the project with the Supabase CLI).

3. Copy .env.example to .env and fill in your project's URL and service role key (Project Settings → API).

4. Install, build, and run:

   npm install
   npm run build
   npm run dev

Testing

npm run typecheck    # tsc --noEmit
npm test             # vitest — schema/validation coverage
npm run build        # compiles to dist/
npm run smoke-test   # spawns the real server over MCP and exercises every tool against Supabase

The first three run in CI on every push (see .github/workflows/ci.yml). smoke-test needs a real .env and isn't run in CI, but is the fastest way to sanity-check a deployment end-to-end.

Connecting to Claude

Add this server to your MCP client config (e.g. Claude Desktop's claude_desktop_config.json, or a Claude Code MCP config):

{
  "mcpServers": {
    "claude-brain": {
      "command": "node",
      "args": ["C:/Users/admin/projects/claude-brain/dist/server.js"],
      "env": {
        "SUPABASE_URL": "https://your-project-ref.supabase.co",
        "SUPABASE_SERVICE_ROLE_KEY": "your-service-role-key"
      }
    }
  }
}

Run npm run build first so dist/server.js exists.

Roadmap

• Deploy a read/search web interface (Vercel) designed with Claude Design

• Auto-log every Claude Code/Desktop session without manual tool calls

• Tagging / categorization of stored memories

• Row-level security policies if the interface is ever exposed beyond local use

License

MIT — see LICENSE.