# claude-brain

[![CI](https://github.com/s4239994/claude-brain/actions/workflows/ci.yml/badge.svg)](https://github.com/s4239994/claude-brain/actions/workflows/ci.yml)
![License](https://img.shields.io/badge/license-MIT-blue.svg)
![Node](https://img.shields.io/badge/node-%3E%3D22-brightgreen.svg)

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](https://modelcontextprotocol.io),
plus (in progress) a web interface for browsing that history as a human.

## Architecture

```mermaid
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](https://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):

```json
{
  "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](LICENSE).