Experience Memory

사진이나 짧은 메모를 하나의 경험 기억으로 저장하고, 나중에 자연어로 다시 찾는 MCP 서버입니다.

이 MVP는 호출 LLM 위임형입니다. 카카오톡/ChatGPT/Claude 같은 대화 중인 LLM이 사진이나 메모를 보고 제목, 요약, 태그, 감정을 정리한 뒤 MCP tool을 호출합니다. MCP 서버는 AI API를 다시 호출하지 않고, 사진이 있으면 원본을 Google Drive에 저장하고 항상 Markdown 메모와 검색용 메타데이터를 저장합니다.

Submission name

• MCP 표시 이름: 기억메모리 Ver 2
• MCP 식별자: memoryv2
• MCP 설명: 사진과 짧은 메모를 Google Drive에 저장하고, 나중에 자연어로 다시 찾거나 수정/삭제할 수 있는 개인 경험 기억 MCP입니다. 호출 중인 LLM이 제목, 요약, 태그, 감정을 정리하고 기억메모리 Ver 2는 사용자의 Drive에 사진과 Markdown 메모를 저장합니다.

Tools

• saveExperienceMemory: 사진, 메모, 또는 사진+메모 경험 저장
• searchExperienceMemories: 자연어로 경험 검색
• updateExperienceMemory: 저장된 경험의 제목, 요약, 메모, 태그, 감정, 날짜, 활동, 장소 수정
• deleteExperienceMemory: 저장된 경험과 연결된 Google Drive 사진/Markdown 메모 삭제

PlayMCP OAuth 배포에서는 수동 연결 tool을 기본으로 숨깁니다. PlayMCP가 아닌 MCP host에서 actor header 기반 수동 Google Drive 연결이 필요할 때만 EXPERIENCE_MEMORY_ENABLE_MANUAL_DRIVE_CONNECT=true를 설정하면 connectGoogleDrive가 노출됩니다.

Search strategy

현재 버전은 OpenAI API key 없이 동작하는 metadata search입니다. 저장 시 호출 LLM이 넘긴 제목, 요약, 메모, 태그, 감정, 활동, 장소를 사용자별 저장소에 보관하고, 검색 tool은 이 텍스트 메타데이터를 기준으로 관련 기억을 찾습니다.

RAG형 semantic search로 확장하려면 저장 시 Markdown 메모를 chunk로 나누고 embedding을 생성해 pgvector 같은 vector store에 저장해야 합니다. 이 방식은 서버가 embedding을 직접 만들기 때문에 OPENAI_API_KEY 또는 다른 embedding provider key가 필요합니다. PlayMCP 제출용 MVP에서는 비용과 인증 복잡도를 줄이기 위해 호출 LLM 위임형 metadata search를 기본값으로 둡니다.

Setup

npm install
cp .env.example .env

.env에 Google Drive OAuth 값을 설정합니다. DATABASE_URL이 있으면 PostgreSQL을 사용하고, 없으면 PlayMCP in KC 제출용 local JSON 저장소를 사용합니다.

TOKEN_ENCRYPTION_KEY=
PORT=8000
MCP_HTTP_PATH=/mcp
HEALTH_PATH=/healthz
GOOGLE_OAUTH_CALLBACK_PATH=/oauth/google/callback
EXPERIENCE_MEMORY_DATA_DIR=/tmp/experience-memory
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=

PlayMCP 제출용 권장 방식은 PlayMCP 등록 화면의 OAuth 인증을 Google OAuth로 설정하는 것입니다. 그러면 PlayMCP가 tool call에 Authorization: Bearer ... access token을 전달하고, MCP 서버는 그 token으로 Google 사용자 id를 확인해 사용자별 저장소와 Google Drive 폴더를 선택합니다.

PlayMCP OAuth 입력값:

Client ID: GOOGLE_CLIENT_ID 값
Client Secret: GOOGLE_CLIENT_SECRET 값
Authorization Endpoint URL: https://accounts.google.com/o/oauth2/v2/auth
Token Endpoint URL: https://oauth2.googleapis.com/token
Scope: openid email profile https://www.googleapis.com/auth/drive.file
Grant Type: AUTHORIZATION_CODE

PlayMCP가 이메일로 보내는 Redirect URI는 Google Cloud Console의 OAuth Client에 Authorized redirect URI로 추가해야 합니다.

수동 Google Drive 연결도 fallback으로 지원합니다. EXPERIENCE_MEMORY_ENABLE_MANUAL_DRIVE_CONNECT=true로 켠 뒤 각 사용자가 connectGoogleDrive tool이 반환하는 Google OAuth URL을 열어 로그인하면, actor별 refresh token과 Drive root folder id가 암호화 저장됩니다.

단일 사용자 .env 방식도 로컬 테스트용으로만 지원합니다. 이 경우 GOOGLE_REFRESH_TOKEN, GOOGLE_DRIVE_ROOT_FOLDER_ID에 들어간 계정의 Drive에 저장되므로 public/multi-user 배포에는 사용하지 않습니다.

PlayMCP OAuth 방식이 아닌 fallback 연결에서는 Google Drive 연결 전 connectGoogleDrive로 사용자 개인 Drive를 먼저 연결해야 합니다.

Google Drive 연결

Google Cloud Console에서 OAuth Client를 만들고 Google Drive API를 활성화합니다. Authorized redirect URI에는 아래 값을 추가합니다.

http://localhost:53682/oauth2callback

.env에 GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, GOOGLE_REDIRECT_URI를 채운 뒤 아래 명령을 실행합니다.

npm run google:auth

브라우저에서 Google Drive 접근을 허용하면 터미널에 아래 값이 출력됩니다.

GOOGLE_REFRESH_TOKEN=...
GOOGLE_DRIVE_ROOT_FOLDER_ID=...

이 값을 .env에 추가하면 MCP가 해당 Google 계정의 Drive에 사진과 Markdown 메모를 저장합니다. 텍스트만 있는 경험은 Markdown 메모만 저장합니다. 권한은 전체 Drive 접근이 아니라 앱이 만든 파일 중심의 drive.file scope를 사용합니다.

다중 사용자 연결

actor별 Google Drive 연결을 로컬에서 저장하려면 .env에 TOKEN_ENCRYPTION_KEY, GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET을 설정한 뒤 아래처럼 실행합니다.

npm run google:auth -- --actor-provider kakao --actor-id kakao-user-id

연결이 완료되면 refresh token과 Drive root folder id가 저장소에 암호화 저장됩니다. MCP를 stdio로 해당 actor에 고정 실행할 때는 아래 환경변수를 지정합니다.

EXPERIENCE_MEMORY_ACTOR_PROVIDER=kakao
EXPERIENCE_MEMORY_ACTOR_ID=kakao-user-id

PlayMCP 같은 HTTP MCP host에서 사용자 식별값을 헤더로 전달하면 MCP 서버가 actor별 Drive 연결을 선택합니다. 기본 후보 헤더는 x-playmcp-user-id, x-kakao-user-id, x-mcp-user-id, x-user-id, mcp-user-id입니다. 실제 헤더명이 다르면 아래처럼 지정합니다. 단, PlayMCP OAuth의 Bearer token이 전달되면 Google OAuth 사용자 id를 우선 사용합니다.

EXPERIENCE_MEMORY_ACTOR_PROVIDER=kakao
EXPERIENCE_MEMORY_ACTOR_HEADER=x-playmcp-user-id

Run

npm run db:check
npm run dev
npm run build
npm start

기본 실행은 PlayMCP in KC 배포용 HTTP transport입니다.

GET  /
GET  /healthz
POST /
POST /mcp

로컬 Codex/Claude Desktop처럼 stdio transport가 필요하면 아래 명령을 사용합니다.

npm run dev:stdio
npm run start:stdio

PlayMCP in KC 배포

PlayMCP in KC의 "Git 소스 빌드" 방식으로 등록할 수 있습니다.

• Git URL: 이 저장소 URL
• 브랜치 / ref: 배포할 브랜치
• Dockerfile 경로: Dockerfile
• Endpoint path: 발급된 Endpoint URL 뒤의 /mcp
• Health check path: /healthz

Docker 컨테이너는 기본적으로 PORT=8000에서 HTTP MCP endpoint를 엽니다. PlayMCP in KC 등록 화면의 container_port도 8000으로 둡니다.

공모전 제출용 Docker 이미지는 외부 DB 없이 뜰 수 있도록 local JSON 저장소를 사용합니다.

EXPERIENCE_MEMORY_DATA_DIR=/tmp/experience-memory
EXPERIENCE_MEMORY_DEFAULT_ACTOR_ID=playmcp-demo

이 모드는 컨테이너 재시작/재배포 시 데이터가 유지된다는 보장이 없습니다. 실제 운영 또는 장기 유지 단계에서는 외부 PostgreSQL을 만들고 아래처럼 전환합니다.

DATABASE_URL=postgres://USER:PASSWORD@HOST:5432/experience_memory

PlayMCP in KC 입력 예시

기본 정보:

• MCP 서버 이름: experience-memory-mcp-v2
• 설명: 사진과 메모를 Google Drive에 저장하고 자연어로 경험 기억을 검색하는 MCP 서버
• Git URL: https://github.com/jih19984/experience-memory-mcp.git
• 브랜치 / ref: main
• Dockerfile 경로: Dockerfile
• PAT: public repo라 비움
• container_port: 8000

환경변수:

MCP_HTTP_PATH=/mcp
HEALTH_PATH=/healthz
GOOGLE_OAUTH_CALLBACK_PATH=/oauth/google/callback
EXPERIENCE_MEMORY_DATA_DIR=/tmp/experience-memory

시크릿:

TOKEN_ENCRYPTION_KEY=...
GOOGLE_CLIENT_ID=...
GOOGLE_CLIENT_SECRET=...

중요: GOOGLE_REFRESH_TOKEN과 GOOGLE_DRIVE_ROOT_FOLDER_ID는 PlayMCP in KC 등록 화면에 넣지 않습니다. PlayMCP OAuth 방식에서는 사용자의 access token으로 Drive에 접근하고, root folder는 사용자 Drive 안에 자동 생성/재사용합니다.

Endpoint URL이 발급되면 Google Cloud Console의 OAuth Client에 아래 Authorized redirect URI도 추가할 수 있습니다. 이 URI는 수동 connectGoogleDrive fallback용입니다. PlayMCP OAuth 자체에는 PlayMCP가 이메일로 보내는 Redirect URI를 추가해야 합니다.

https://<발급받은-endpoint-host>/oauth/google/callback

수동 fallback을 쓸 때는 EXPERIENCE_MEMORY_ENABLE_MANUAL_DRIVE_CONNECT=true를 설정한 뒤, 사용자가 처음 저장하려 할 때 connectGoogleDrive tool을 호출해 개인 Google Drive를 연결합니다. PlayMCP OAuth 배포에서는 이 값을 설정하지 않습니다.

MCP 설정 예시

stdio transport를 사용하는 MCP host에서는 아래처럼 설정합니다.

{
  "mcpServers": {
    "experience-memory": {
      "command": "node",
      "args": ["dist/index.js"],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "DATABASE_URL": "...",
        "GOOGLE_CLIENT_ID": "...",
        "GOOGLE_CLIENT_SECRET": "...",
        "GOOGLE_REFRESH_TOKEN": "...",
        "GOOGLE_DRIVE_ROOT_FOLDER_ID": "..."
      }
    }
  }
}

Example

{
  "imagePath": "/Users/me/Pictures/han-river.jpg",
  "userNote": "오늘 한강에서 뛰었는데 힘들었지만 야경이 좋아서 버텼어.",
  "title": "한강 야경 러닝",
  "summary": "힘들었지만 한강 야경 덕분에 끝까지 버틴 러닝 경험.",
  "tags": ["한강", "러닝", "야경"],
  "mood": ["힘듦", "만족", "개운함"],
  "occurredAt": "2026-07-08",
  "locationHint": "한강"
}

응답:

{
  "memoryId": "...",
  "title": "한강 야경 러닝",
  "summary": "힘들었지만 한강 야경 덕분에 끝까지 버틴 러닝 경험.",
  "tags": ["한강", "러닝", "야경"],
  "mood": ["힘듦", "만족", "개운함"],
  "driveUrl": "https://drive.google.com/...",
  "hasImage": true
}

수정 예시:

{
  "id": "5b37c7bc-d845-40b0-ae66-95ed1d327732",
  "title": "엄마와 함께 먹은 치킨",
  "summary": "오늘 엄마와 함께 바삭한 치킨을 먹으며 남긴 식사 기억.",
  "tags": ["엄마", "치킨", "식사", "가족"],
  "mood": ["따뜻함", "만족"]
}

삭제 예시:

{
  "id": "5b37c7bc-d845-40b0-ae66-95ed1d327732"
}

Notes

• 클라우드 환경에서는 imagePath보다 imageUrl 또는 imageBase64 입력이 안전합니다.
• 사진 없이 userNote만으로도 저장할 수 있습니다.
• 사진 원본을 Drive에 저장하려면 MCP 서버가 실제 이미지 bytes에 접근할 수 있어야 합니다.
• DB 저장 실패 시 업로드된 Drive 파일 삭제를 시도합니다.
• updateExperienceMemory는 사진 교체를 하지 않습니다. 사진 교체가 필요하면 새 경험 저장 또는 별도 사진 교체 tool 추가를 권장합니다.