mcp-mem0

Qdrant 기반의 mem0(셀프 호스팅 / 오픈 소스)용 MCP 서버입니다. 각 요청은 HTTP 헤더로 이름이 지정된 Qdrant 컬렉션을 대상으로 하므로, 동일한 이름을 보내는 클라이언트는 메모리를 공유하고 다른 이름은 격리됩니다.

도구

Related MCP server: mem0-open-mcp

컬렉션 라우팅 작동 방식

• 컬렉션 이름은 HTTP 헤더(기본값 X-Collection)에서 읽어 Qdrant 컬렉션 mem0_<name>에 매핑됩니다(접두사는 설정 가능하며, 비워 두면 값을 그대로 사용합니다). 헤더 값은 ^[A-Za-z0-9_-]{1,64}$에 대해 검증됩니다.

• 공유: 동일한 컬렉션 이름을 보내는 모든 클라이언트는 동일한 메모리를 공유합니다. 다른 이름은 격리됩니다.

• 컬렉션별로 하나의 AsyncMemory 인스턴스가 생성되어 캐시됩니다.

• 컬렉션은 오직 헤더에 의해서만 선택됩니다. user_id / agent_id / run_id는 어떤 컬렉션이 사용되는지에 영향을 주지 않으며, 컬렉션 내부에서만 범위를 좁히고 선택 사항입니다. 이 중 아무것도 없이 검색/목록을 하면 전체 컬렉션을 대상으로 합니다.

• add_memory는 저장을 위해 여전히 하나의 ID가 필요합니다(mem0 요구 사항). 호출자가 쓰기 시 세 가지를 모두 생략하면 기본 user_id(MEM0_DEFAULT_USER_ID)가 적용됩니다.

빠른 시작

# 1. Start Qdrant
docker compose up -d qdrant

# 2. Configure
cp .env.example .env
# edit .env: set OPENAI_API_KEY (or switch to the Ollama block for a key-free setup)

# 3. Run the server (streamable-HTTP on :8080/mcp)
uv run -m mcp_mem0

헬스 체크: curl localhost:8080/health

Docker

Dockerfile은 두 개의 타깃(runtime(서버)과 test(테스트 스위트))을 가진 멀티 스테이지입니다.

docker compose 사용(권장)

cp .env.example .env          # set OPENAI_API_KEY (or the Ollama block)

# Qdrant + server together
docker compose up -d --build qdrant server
curl localhost:8080/health

# Run unit tests (no Qdrant / keys needed)
docker compose run --rm tests

# End-to-end smoke against the running server (needs an embedder key)
docker compose run --rm tests python tests/smoke.py

compose 네트워크 내부에서 서버는 QDRANT_HOST=qdrant(자동 설정)로 Qdrant에 도달하고, 테스트는 MCP_URL=http://server:8080/mcp로 서버에 도달합니다.

일반 docker 사용

# Service image
docker build --target runtime -t mcp-mem0 .
docker run --rm -p 8080:8080 --env-file .env -e QDRANT_HOST=host.docker.internal mcp-mem0

# Test image
docker build --target test -t mcp-mem0-test .
docker run --rm mcp-mem0-test            # pytest -q

검증

# Unit tests (no Qdrant needed)
uv run pytest -q

# End-to-end smoke test (server + Qdrant + embedder must be running)
uv run python tests/smoke.py

# Confirm per-client collections were created
curl localhost:6333/collections

구성

모든 설정은 환경 변수 / .env에서 가져옵니다 — .env.example 참조. 주요 항목: MEM0_COLLECTION_HEADER, MEM0_COLLECTION_PREFIX, QDRANT_HOST/QDRANT_PORT(또는 QDRANT_URL+QDRANT_API_KEY), MEM0_EMBEDDING_DIMS(임베더와 일치해야 함), 그리고 MEM0_LLM_* / MEM0_EMBEDDER_* 공급자 블록(openai / ollama / …).