Personal Memory MCP Server

삶에 대한 팩트(fact)를 손실 없이 구조화하고 조회할 수 있게 저장하는 저장소로, Claude가 대화 중 언제든지 읽고 쓰는 공간입니다. 하나의 배포가 한 명의 사용자를 대상으로 합니다. Cloudflare 무료 요금제(Workers + D1 + KV)에서만 실행됩니다. 전체 사양은 requirements.md를 참조하세요.

• 팩트이지 문서가 아님. 모든 팩트는 출처(provenance)가 있는 하나의 날짜 기반 문장입니다.

• Append-only. 수정 사항은 새 팩트를 추가하고 포인터로 이전 팩트를 폐기합니다. 아무것도 삭제되지 않습니다.

• 인증: OAuth 2.1 + Dynamic Client Registration 사용, 신원은 GitHub을 통해 확인하며 단일 GitHub 계정에 고정됩니다.

• 전송: /mcp에서 Streamable HTTP(상태 비보존 createMcpHandler, Durable Objects 없음).

설정

1. Cloudflare 리소스 만들기

npm install
npx wrangler d1 create memory
npx wrangler kv namespace create OAUTH_KV

리턴된 D1 database_id와 KV 네임스페이스 id를 wrangler.jsonc에 넣은 다음, 마이그레이션을 적용하세요.

npx wrangler d1 migrations apply memory --remote

2. GitHub OAuth 앱 만들기

https://github.com/settings/developers → New OAuth App:

• Homepage URL: https://personal-memory-mcp.<your-subdomain>.workers.dev

• Authorization callback URL: https://personal-memory-mcp.<your-subdomain>.workers.dev/callback

<https://api.github.com/users/>(id 필드)에서 GitHub 숫자 ID를 확인하세요.

3. 시크릿(secrets) 설정

npx wrangler secret put GITHUB_CLIENT_ID
npx wrangler secret put GITHUB_CLIENT_SECRET
npx wrangler secret put COOKIE_ENCRYPTION_KEY   # e.g. openssl rand -hex 32
npx wrangler secret put OWNER_GITHUB_ID         # numeric id, not login

(Workers Builds CI/CD 로 배포하면, 이 값들을 Cloudflare 대시보드의 Worker 설정(Settings) → Variables에서 한 번만 설정하면 됩니다. 배포 후에도 유지됩니다.)

4. 배포

npm run deploy

또는 Cloudflare 대시보드(Workers Builds)에서 GitHub 저장소를 연결하면 푸시할 때마다 배포가 됩니다. 마이그레이션은 배포 시 자동으로 실행되지 않습니다. 계속 수동으로 적용하거나 Workers Builds 배포 명령(deply)을 다음 명령으로 설정하세요.

npx wrangler d1 migrations apply memory --remote && npx wrangler deploy

5. Claude.ai에서 연결

설정(Settings) → 커넥터(Connectors) → Add custom connector → URL https://personal-memory-memory.<your-subdomain>.workers.dev/mcp에 Client ID/Secret을 비워 둔 채로(Dynamic Client Registration) 설정합니다. GitHub 로그인을 거치게 되며, OWNER_GITHUB_ID가 아닌 계정은 403 오류를 받습니다. 그러면 커넥터는 Claude 웹, 데스크톱, iOS에서 작동합니다.

Claude.ai 프로필 환경설정에 다음을 추가하세요:

저는 "memory"라는 개인 메모리 MCP 서버를 운영합니다. 이 서버는 제 삶에 대한 진실의 원천이며 당신의 내장 메모리보다 우선됩니다. 개인적인 이야기를 할 때는 이를 참고하고 도구 설명대로 사용하세요. 서버에 연결할 수 없으면 알려주고, 응답이 최신 정보와 다를 수 있음을 알려주세요.

6. 시드(선택 사항)

1. Claude에게 해당 메모리에서 seed.json 초안을 요청하세요. [{topic, dimensions, fact_date?, tags?}] 형식으로 항목당 하나의 팩트입니다.

2. 검토한 후:

npm run seed              # validates seed.json, writes seed-import.sql
npx wrangler d1 execute memory --remote --file=seed-import.sql

첫 대화에서 Claude에게 초기 주제 요약(update_summary)을 작성하도록 요청하세요.

7. 개발

cp .dev.vars.example .dev.vars   # separate GitHub OAuth app with callback http://localhost:8788/callback
npx wrangler d1 migrations apply memory --local
npm run dev                      # http://localhost:8788/mcp
npm test                         # vitest (workers runtime, real D1 + FTS5)
npm run typecheck

MCP 인스펙터로 테스트하세요: npx @modelcontextprotocol/inspector@latest → http://localhost:8788/mcp에 연결합니다. 인스펙터의 localhost OAuth redirect는 ALLOW_LOCALHOST_REDIRECTS=1(.dev.vars에 설정, 프로덕션에는 설정하지 않아야 합니다)로만 작동합니다.

8. 참고 사항

• 백업: export 도구(markdown 또는 json 사용). FTS5 가상 테이블이 있는 동안 D1의 네이티브 export는 작동하지 않습니다. D1 Time Travel을 사용하면 특정 시점 복원(과금 요금제 30일, 무료 요금제는 더 짧으며 현재 상태 확인).

• 의도적으로 연기된 항목 (누락이 아니라 소유자 결정): §11 주간 백업 cron을(개인 GitHub repository)과 §12 /view 읽기 전용 뷰어. 크론이 만들어질 때까지 export를 정기적으로 실행하고 출력을 안전한 곳에 보관하세요.

• OAuth 승인 흐름은 claude.ai/claude.com 커넥터 콜백만 리디렉션 URI로 허용합니다(로컬은 위의 dev 전용 플래그가 필요합니다).

• 일반적인 운영 중에는 행을 삭제하지 않습니다. 소유자가 사실을 정정해야 할 때는 Claude에게 말하면 됩니다.