@pinkpixel/mem0-mcp MCP 서버 ✨

Mem0.ai 와 통합되어 LLM에 대한 영구 메모리 기능을 제공하는 모델 컨텍스트 프로토콜(MCP) 서버입니다. AI 에이전트가 여러 세션에서 정보를 저장하고 검색할 수 있도록 지원합니다.

이 서버는 핵심 기능에 mem0ai Node.js SDK를 사용합니다.

특징 🧠

도구

add_memory : 텍스트 콘텐츠를 특정 userId 와 연관된 메모리로 저장합니다.
- 입력: content (문자열, 필수), userId (문자열, 필수), sessionId (문자열, 선택 사항), agentId (문자열, 선택 사항), metadata (객체, 선택 사항)
- 제공된 텍스트를 저장하여 향후 상호작용 시 다시 사용할 수 있습니다.
search_memory : 자연어 쿼리를 기반으로 특정 userId 에 대한 저장된 메모리를 검색합니다.
- 입력: query (문자열, 필수), userId (문자열, 필수), sessionId (문자열, 선택), agentId (문자열, 선택), filters (객체, 선택), threshold (숫자, 선택)
- 의미적 유사성을 기반으로 관련 메모리를 검색합니다.
delete_memory : ID를 기준으로 특정 메모리를 저장소에서 삭제합니다.
- 입력: memoryId (문자열, 필수), userId (문자열, 필수), sessionId (문자열, 선택), agentId (문자열, 선택)
- 지정된 메모리를 영구적으로 제거합니다.
- 의미적 유사성을 기반으로 관련 메모리를 검색합니다.

필수 조건 🔑

이 서버는 두 가지 저장 모드를 지원합니다.

클라우드 스토리지 모드 ☁️ (권장)
- Mem0 API 키 ( MEM0_API_KEY 환경 변수로 제공됨)가 필요합니다.
- 메모리는 Mem0의 클라우드 서버에 지속적으로 저장됩니다.
- 로컬 데이터베이스가 필요하지 않습니다
로컬 스토리지 모드 💾
- OpenAI API 키 ( OPENAI_API_KEY 환경 변수로 제공됨)가 필요합니다.
- 메모리는 메모리 내 벡터 데이터베이스에 저장됩니다(기본적으로 비영구적).
- 영구 저장소를 위해 구성하지 않은 경우 서버가 다시 시작되면 데이터가 손실됩니다.

설치 및 구성 ⚙️

이 서버는 두 가지 주요 방법으로 실행할 수 있습니다.

1. `npx` 사용 (빠른 사용을 위해 권장)

npm을 사용하여 패키지를 전역적으로 설치합니다.

지엑스피1

npx 사용하여 서버를 실행하도록 MCP 클라이언트(예: Claude Desktop, Cursor, Cline, Roo Code 등)를 구성합니다.

클라우드 스토리지 구성(권장)

{
  "mcpServers": {
    "mem0-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@pinkpixel/mem0-mcp"
      ],
      "env": {
        "MEM0_API_KEY": "YOUR_MEM0_API_KEY_HERE",
        "DEFAULT_USER_ID": "user123"
      },
      "disabled": false,
      "alwaysAllow": [
        "add_memory",
        "search_memory"
      ]
    }
  }
}

참고: "YOUR_MEM0_API_KEY_HERE" 실제 Mem0 API 키로 바꾸세요.

로컬 스토리지 구성(대안)

{
  "mcpServers": {
    "mem0-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@pinkpixel/mem0-mcp"
      ],
      "env": {
        "OPENAI_API_KEY": "YOUR_OPENAI_API_KEY_HERE",
        "DEFAULT_USER_ID": "user123"
      },
      "disabled": false,
      "alwaysAllow": [
        "add_memory",
        "search_memory"
      ]
    }
  }
}

참고: "YOUR_OPENAI_API_KEY_HERE" 실제 OpenAI API 키로 바꾸세요.

2. 복제된 저장소에서 실행

참고: 이 방법을 사용하려면 먼저 저장소를 git clone해야 합니다.

저장소를 복제하고 종속성을 설치한 다음 서버를 빌드합니다.

git clone https://github.com/pinkpixel-dev/mem0-mcp 
cd mem0-mcp
npm install
npm run build

그런 다음, node 사용하여 빌드된 스크립트를 직접 실행하도록 MCP 클라이언트를 구성합니다.

{
  "mcpServers": {
    "mem0-mcp": {
      "command": "node",
      "args": [
        "/absolute/path/to/mem0-mcp/build/index.js" 
      ],
      "env": {
        "MEM0_API_KEY": "YOUR_MEM0_API_KEY_HERE",
        "DEFAULT_USER_ID": "user123"
        // OR use "OPENAI_API_KEY": "YOUR_OPENAI_API_KEY_HERE" for local storage
      },
      "disabled": false,
      "alwaysAllow": [
        "add_memory",
        "search_memory"
      ]
    }
  }
}

중요 참고 사항:

/absolute/path/to/mem0-mcp/ 복제된 저장소의 실제 절대 경로로 바꾸세요.
src/index.ts 파일이 아닌 build/index.js 파일을 사용하세요.
MCP 서버는 프로토콜 통신을 위해 깨끗한 stdout을 요구합니다. stdout에 쓰는 라이브러리나 코드는 프로토콜을 방해할 수 있습니다.

기본 사용자 ID(선택적 대체)

add_memory 도구와 search_memory 도구는 모두 메모리를 특정 사용자와 연결하기 위해 userId 인수가 필요합니다.

테스트 중이나 단일 사용자 시나리오에서 편의를 위해 서버를 시작할 때 DEFAULT_USER_ID 환경 변수를 선택적으로 설정할 수 있습니다. 이 변수가 설정되어 있고 search_memory 도구를 호출할 때 userId 인수가 생략 되면 서버는 검색에 DEFAULT_USER_ID 값을 사용합니다.

참고: 이러한 대안이 있는 경우 일반적으로 호출 에이전트(LLM)가 모호성을 피하기 위해 메모리 추가 및 검색에 대한 올바른 userId 명시적으로 제공하는 것이 좋습니다.

DEFAULT_USER_ID 사용한 구성 예:

{
  "mcpServers": {
    "mem0-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@pinkpixel/mem0-mcp"
      ],
      "env": {
        "MEM0_API_KEY": "YOUR_MEM0_API_KEY_HERE",
        "DEFAULT_USER_ID": "user123" 
      },
    }
  }
}

또는 node 로 직접 실행하는 경우:

git clone https://github.com/pinkpixel-dev/mem0-mcp 
cd mem0-mcp
npm install
npm run build

{
  "mcpServers": {
    "mem0-mcp": {
      "command": "node",
      "args": [
        "path/to/mem0-mcp/build/index.js"
      ],
      "env": {
        "OPENAI_API_KEY": "YOUR_OPENAI_API_KEY_HERE",
        "DEFAULT_USER_ID": "user123" 
      },
    }
  }
}

클라우드 vs. 로컬 스토리지 🔄

클라우드 스토리지(Mem0 API)

기본적으로 지속적 - 세션과 서버 재시작 시에도 메모리를 계속 사용할 수 있습니다.
로컬 데이터베이스가 필요하지 않습니다 . 모든 데이터는 Mem0 서버에 저장됩니다.
더 높은 검색 품질 - Mem0의 최적화된 검색 알고리즘을 사용합니다.
추가 필드 - agent_id 및 threshold 매개변수 지원
필요 - Mem0 API 키

로컬 스토리지(OpenAI API)

기본적으로 메모리 내 저장 - 데이터는 RAM에만 저장되며 장기적으로 유지되지 않습니다 . 일부 캐싱이 발생할 수 있지만, 이를 영구 저장으로 사용해서는 안 됩니다.
데이터 손실 위험 - 서버 재시작, 시스템 재부팅 또는 프로세스 종료 시 메모리 데이터가 손실됩니다.
권장 대상 - 개발, 테스트 또는 임시 사용에만 해당
영구 저장소의 경우 - 안정적인 장기 메모리가 필요한 경우 Mem0 API와 함께 Cloud Storage 옵션을 사용하세요.
OpenAI 임베딩 사용 - 벡터 검색 기능용
독립형 - 모든 데이터는 컴퓨터에 보관됩니다.
필요 - OpenAI API 키

개발 💻

저장소를 복제하고 종속성을 설치합니다.

git clone https://github.com/pinkpixel-dev/mem0-mcp 
cd mem0-mcp
npm install

서버를 빌드하세요:

npm run build

파일 변경 시 자동 재빌드를 사용하여 개발하는 경우:

npm run watch

디버깅 🐞

MCP 서버는 stdio를 통해 통신하므로 디버깅이 어려울 수 있습니다. 다음은 몇 가지 접근 방식입니다.

MCP Inspector 사용 : 이 도구는 MCP 프로토콜 통신을 모니터링할 수 있습니다.

npm run inspector

콘솔 로깅 : 콘솔 로그를 추가할 때는 항상 console.error() 대신 console.log() 사용하여 MCP 프로토콜을 방해하지 않도록 합니다.
환경 파일 : 로컬 개발을 위해 .env 파일을 사용하여 API 키 및 기타 구성 옵션 설정을 간소화합니다.

기술 구현 노트 🔧

고급 Mem0 API 매개변수

Mem0 API와 함께 클라우드 스토리지 모드를 사용하면 더욱 정교한 메모리 관리를 위해 추가 매개변수를 활용할 수 있습니다. 도구 스키마에 명시적으로 노출되어 있지는 않지만, 메모리를 추가할 때 metadata 객체에 이러한 매개변수를 포함할 수 있습니다.

`add_memory` 에 대한 고급 매개변수:

매개변수	유형	설명
`metadata`	물체	메모리에 대한 추가 컨텍스트(예: 위치, 시간, 식별자)를 저장합니다. 이는 검색 중 필터링에 사용될 수 있습니다.
`includes`	끈	메모리에 포함할 특정 선호사항.
`excludes`	끈	메모리에서 제외할 특정 기본 설정입니다.
`infer`	부울	메모리를 추론할지 아니면 메시지를 직접 저장할지 여부(기본값: true).
`output_format`	끈	형식 버전은 v1.0(기본값, 더 이상 사용되지 않음) 또는 v1.1(권장)입니다.
`custom_categories`	물체	이름과 설명이 있는 카테고리 목록입니다.
`custom_instructions`	끈	기억을 처리하고 정리하기 위한 프로젝트별 가이드라인입니다.
`immutable`	부울	메모리가 변경 불가능한지 여부(기본값: false).
`expiration_date`	끈	메모리가 만료되는 날짜(형식: YYYY-MM-DD).
`org_id`	끈	이 메모리와 연관된 조직 ID입니다.
`project_id`	끈	이 메모리와 관련된 프로젝트 ID입니다.
`version`	끈	메모리 버전(v1은 더 이상 사용되지 않으며, 새로운 애플리케이션에는 v2가 권장됨).

MCP 서버에서 이러한 매개변수를 사용하려면 add_memory 도구를 호출할 때 메타데이터 객체에 매개변수를 포함시키세요. 예:

{
  "content": "Important information to remember",
  "userId": "user123",
  "sessionId": "project-abc",
  "metadata": {
    "includes": "important context",
    "excludes": "sensitive data",
    "immutable": true,
    "expiration_date": "2025-12-31",
    "custom_instructions": "Prioritize this memory for financial questions",
    "version": "v2"
  }
}

`search_memory` 에 대한 고급 매개변수:

Mem0 v2 검색 API는 filters 매개변수를 통해 활용할 수 있는 강력한 필터링 기능을 제공합니다.

매개변수	유형	설명
`filters`	물체	논리 연산자와 비교 조건이 포함된 복잡한 필터
`top_k`	정수	반환할 상위 결과 수(기본값: 10)
`fields`	끈[]	응답에 포함할 특정 필드
`rerank`	부울	메모리를 다시 순위 매길지 여부(기본값: false)
`keyword_search`	부울	키워드 기준으로 검색할지 여부(기본값: false)
`filter_memories`	부울	메모리를 필터링할지 여부(기본값: false)
`threshold`	숫자	결과에 대한 최소 유사도 임계값(기본값: 0.3)
`org_id`	끈	메모리 필터링을 위한 조직 ID
`project_id`	끈	메모리 필터링을 위한 프로젝트 ID

filters 매개변수는 복잡한 논리 연산(AND, OR)과 다양한 비교 연산자를 지원합니다.

연산자	설명
`in`	지정된 값 중 하나와 일치합니다.
`gte`	이상 또는 같음
`lte`	이하
`gt`	보다 크다
`lt`	미만
`ne`	같지 않다
`icontains`	대소문자를 구분하지 않는 격리 검사

search_memory 도구로 복잡한 필터를 사용하는 예:

{
  "query": "What are Alice's hobbies?",
  "userId": "user123",
  "filters": {
    "AND": [
      {
        "user_id": "alice"
      },
      {
        "agent_id": {"in": ["travel-agent", "sports-agent"]}
      }
    ]
  },
  "threshold": 0.5,
  "top_k": 5
}

이 쿼리는 user_id가 "alice"이고 agent_id가 "travel-agent" 또는 "sports-agent"인 Alice의 취미와 관련된 메모리를 검색하여 유사도 점수가 최소 0.5인 최대 5개의 결과를 반환합니다.

이러한 매개변수에 대한 자세한 내용은 Mem0 API 설명서를 참조하세요.

세이프로거

MCP 서버는 MCP 프로토콜을 방해하지 않고 mem0ai 라이브러리에서 console.log 호출을 선택적으로 stderr로 리디렉션하는 SafeLogger 클래스를 구현합니다.

console.log 호출을 가로채고 스택 추적을 조사하여 소스를 확인합니다.
mem0ai 라이브러리나 자체 코드에서만 로그 호출을 리디렉션합니다.
MCP 프로토콜 통신을 위해 깨끗한 stdout을 유지합니다.
프로세스 종료 시 자동으로 리소스를 정리합니다.

이를 통해 유용한 디버그 정보를 유지하면서 MCP 클라이언트 내에서 적절한 기능이 작동할 수 있습니다.

환경 변수

서버는 동작을 제어하는 여러 환경 변수를 인식합니다.

MEM0_API_KEY : 클라우드 스토리지 모드에 대한 API 키
OPENAI_API_KEY : 로컬 스토리지 모드(임베딩)에 대한 API 키
DEFAULT_USER_ID : 메모리 작업을 위한 기본 사용자 ID

Pink Pixel에서 ❤️로 만들었습니다

mem0 Memory System

Integrations

@pinkpixel/mem0-mcp MCP 서버 ✨

특징 🧠

도구

필수 조건 🔑

설치 및 구성 ⚙️

1. `npx` 사용 (빠른 사용을 위해 권장)

클라우드 스토리지 구성(권장)

로컬 스토리지 구성(대안)

2. 복제된 저장소에서 실행

기본 사용자 ID(선택적 대체)

클라우드 vs. 로컬 스토리지 🔄

클라우드 스토리지(Mem0 API)

로컬 스토리지(OpenAI API)

개발 💻

디버깅 🐞

기술 구현 노트 🔧

고급 Mem0 API 매개변수

`add_memory` 에 대한 고급 매개변수:

`search_memory` 에 대한 고급 매개변수:

세이프로거

환경 변수

Tools

Related Resources

Appeared in Searches

Integrations

@pinkpixel/mem0-mcp MCP 서버 ✨

특징 🧠

도구

필수 조건 🔑

설치 및 구성 ⚙️

1. npx 사용 (빠른 사용을 위해 권장)

클라우드 스토리지 구성(권장)

로컬 스토리지 구성(대안)

2. 복제된 저장소에서 실행

기본 사용자 ID(선택적 대체)

클라우드 vs. 로컬 스토리지 🔄

클라우드 스토리지(Mem0 API)

로컬 스토리지(OpenAI API)

개발 💻

디버깅 🐞

기술 구현 노트 🔧

고급 Mem0 API 매개변수

add_memory 에 대한 고급 매개변수:

search_memory 에 대한 고급 매개변수:

세이프로거

환경 변수

Tools

Related Resources

Appeared in Searches

1. `npx` 사용 (빠른 사용을 위해 권장)

`add_memory` 에 대한 고급 매개변수:

`search_memory` 에 대한 고급 매개변수: