# Personal Memory MCP Server

A remote MCP server that gives Claude (and ChatGPT/Gemini, once you add them) persistent
read/write access to your own memory: books, games, projects, notes, and freeform facts.
Runs on Cloudflare Workers' free tier. Storage is D1 (managed SQLite). Login is your GitHub
account, via the OAuth flow already wired up in `src/index.ts` / `src/github-handler.ts`.

This project was already scaffolded and typechecked for you. What's left is entirely steps
that require *your own* accounts (Cloudflare, GitHub) — nobody else can do these for you.

## Tools this server exposes

- `remember` — save/update a book, game, project, or note (title, status, rating, tags, body)
- `remember_fact` — save a freeform fact/preference
- `search_memory` — full-text search across everything
- `list_items` — structured filter, e.g. every book rated 4+
- `get_stats` — counts/average ratings per type, for recommendation-style questions

## One-time setup

### 1. Log into Cloudflare

```bash
npx wrangler login
```

### 2. Create the D1 database

```bash
npx wrangler d1 create personal-memory-db
```

Copy the `database_id` it prints into `wrangler.jsonc`, replacing `<Add-D1-ID>`.

Apply the schema:

```bash
npx wrangler d1 execute personal-memory-db --file=schema.sql --remote
```

### 3. Create the KV namespace (used by the OAuth flow to store session state)

```bash
npx wrangler kv namespace create OAUTH_KV
```

Copy the `id` it prints into `wrangler.jsonc`, replacing `<Add-KV-ID>`.

### 4. Create a GitHub OAuth App (this is how you'll log into your own connector)

GitHub → Settings → Developer settings → OAuth Apps → New OAuth App:
- **Homepage URL**: `https://personal-memory-mcp.<your-subdomain>.workers.dev` (you'll only know
  the exact subdomain after your first deploy in Step 6 below — deploy once, then come back and
  fix this field and the callback URL, then redeploy)
- **Authorization callback URL**: `https://personal-memory-mcp.<your-subdomain>.workers.dev/callback`

Save the Client ID, and generate + save a Client Secret.

### 5. Set your secrets

```bash
npx wrangler secret put GITHUB_CLIENT_ID
npx wrangler secret put GITHUB_CLIENT_SECRET
npx wrangler secret put COOKIE_ENCRYPTION_KEY   # paste output of: openssl rand -hex 32
```

### 6. Deploy

```bash
npx wrangler deploy
```

Note the URL it prints, e.g. `https://personal-memory-mcp.<you>.workers.dev`. Go back to Step 4
and make sure the homepage/callback URLs match exactly (including no trailing slash mismatches —
this is the #1 cause of "server unreachable" errors), then run `npx wrangler deploy` again if you
changed anything.

Your MCP endpoint is: `https://personal-memory-mcp.<you>.workers.dev/mcp`

### 7. Test locally before connecting a real client (optional but recommended)

```bash
npm run dev
```

In a second terminal:

```bash
npx @modelcontextprotocol/inspector
```

Point the inspector at your local dev URL and call `remember` a few times, then confirm rows
landed in D1:

```bash
npx wrangler d1 execute personal-memory-db --command "SELECT * FROM items" --remote
```

(Use `--local` instead of `--remote` if you want to check the local dev database instead.)

### 8. Connect it to Claude

Claude app or claude.ai → **Settings → Connectors → Add custom connector** → paste your `/mcp`
URL → authenticate with GitHub. Toggle it on in a chat (`+ → Connectors`) and try:
*"I started reading The Power of Now."*

### 9. (Optional) Enable the nightly GitHub backup

Create a private repo, e.g. `my-ai-memory`. Create a fine-grained GitHub personal access token
scoped to that repo's contents (read/write). Then:

```bash
npx wrangler secret put GITHUB_BACKUP_TOKEN
npx wrangler secret put GITHUB_BACKUP_REPO   # e.g. yourname/my-ai-memory
```

The cron trigger (already configured in `wrangler.jsonc`, runs daily at 2am UTC) exports every
item to a Markdown file in that repo — your fully portable, human-readable backup.

### 10. Add ChatGPT / Gemini later

Same server URL, same OAuth flow, added from each app's own connector/app settings. ChatGPT
requires Plus or higher with Developer Mode enabled.

## Known harmless typecheck quirk

`npx tsc --noEmit` reports two errors in `src/github-handler.ts` about `env.COOKIE_ENCRYPTION_KEY`
and `env.GITHUB_CLIENT_ID` via the `cloudflare:workers` ambient import — this is a pre-existing
quirk in how the generated Worker types interact with that import style, not something introduced
here, and it does not affect `wrangler dev` or `wrangler deploy` (both use esbuild, not `tsc`, to
build). Safe to ignore.

## Extending it

Add more tools the same way as the ones in `src/index.ts` — call `this.server.tool(name,
description, zodSchema, handler)`. Keep descriptions specific; the AI picks tools based on name
+ description, so vague descriptions mean it either guesses wrong or doesn't call the tool.
Ideas worth adding next: `delete_item`, `archive_item`, or restricting some tools to only your
own GitHub username (there's a commented-out `ALLOWED_USERNAMES` pattern you can bring back from
the original template if you ever share this server with anyone else).