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

npx wrangler login

2. Create the D1 database

npx wrangler d1 create personal-memory-db

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

Apply the schema:

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)

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

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

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)

npm run dev

In a second terminal:

npx @modelcontextprotocol/inspector

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

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:

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).