memory-mcp

AI 에이전트를 위한 영구적, 검색 가능, 버전 관리 메모리 — Valkey(Redis 호환) 기반으로 구축되었으며 HTTP를 통해 MCP 서버로 노출됩니다.

Claude Code, Cursor, VS Code 등 모든 MCP 호환 에이전트와 함께 작동합니다.

주요 기능

• 태그, 유형 및 프로젝트 범위가 지정된 명명된 메모리 항목 저장

• 태그 교집합 검색, 유형/프로젝트 필터링 및 부분 문자열 검색

• 히트 추적 (자주 액세스되는 항목이 상단으로 노출)

• 롤백을 포함한 전체 버전 기록

• Prometheus 메트릭 엔드포인트

• 선택적 Bearer 토큰 인증

빠른 시작

cp .env.example .env
# Optional: set MEMORY_MCP_AUTH_TOKEN in .env (see Auth section)
docker compose up -d

이 명령은 GHCR에서 사전 빌드된 이미지를 가져옵니다. 이제 MCP 서버를 http://127.0.0.1:3106/mcp에서 사용할 수 있습니다.

로컬에서 빌드하려면:

docker compose build
docker compose up -d

기존 Redis 또는 Valkey 사용

기본적으로 docker compose up -d는 번들로 제공되는 Valkey 컨테이너를 시작합니다. 대신 기존 Redis 또는 Valkey 인스턴스에 연결하려면 VALKEY_URL을 설정하고 memory-mcp 서비스만 시작하십시오:

# .env
VALKEY_URL=redis://your-host:6379

docker compose up -d memory-mcp

모든 Redis 호환 서버(Redis 6+, Valkey, KeyDB, rediss://를 통한 Upstash 등)가 작동합니다. 서버는 해시, 리스트, 세트와 같은 기본 데이터 구조만 사용합니다.

에이전트 설정

이 저장소의 AGENTS.md를 프로젝트 루트로 복사하십시오. 이 파일은 에이전트에게 메모리 도구를 사용하는 방법, 저장할 내용 및 시기를 알려줍니다.

그런 다음 에이전트 클라이언트에 MCP 서버를 등록하십시오:

Claude Code

# Without auth
claude mcp add memory --transport http http://127.0.0.1:3106/mcp

# With auth
claude mcp add memory --transport http http://127.0.0.1:3106/mcp \
  --header "Authorization: Bearer your-token"

또는 ~/.claude.json에 수동으로 추가하십시오:

{
  "mcpServers": {
    "memory": {
      "type": "http",
      "url": "http://127.0.0.1:3106/mcp",
      "headers": { "Authorization": "Bearer your-token" }
    }
  }
}

Cursor

~/.cursor/mcp.json(전역) 또는 .cursor/mcp.json(프로젝트)에 추가하십시오:

{
  "mcpServers": {
    "memory": {
      "url": "http://127.0.0.1:3106/mcp",
      "headers": { "Authorization": "Bearer your-token" }
    }
  }
}

VS Code (GitHub Copilot, MCP 확장)

프로젝트의 .vscode/mcp.json에 추가하십시오:

{
  "servers": {
    "memory": {
      "type": "http",
      "url": "http://127.0.0.1:3106/mcp",
      "headers": { "Authorization": "Bearer your-token" }
    }
  }
}

인증을 사용하지 않는 경우 구성에서 headers / Authorization 줄을 생략하십시오.

구성

.env.example을 .env로 복사하고 필요에 따라 편집하십시오.

인증

기본적으로 서버는 인증 없이 실행됩니다. 루프백(127.0.0.1)에 바인딩되고 로컬 머신에서만 액세스되는 경우 안전합니다.

인증을 활성화하려면:

# Generate a token
openssl rand -hex 32

# Add to .env
MEMORY_MCP_AUTH_TOKEN=your-generated-token

docker compose up -d

이후 POST /mcp에 대한 모든 요청에는 다음이 포함되어야 합니다:

Authorization: Bearer <token>

GET /health 및 GET /metrics는 항상 인증되지 않습니다.

사용 가능한 도구

메모리 유형

pattern, decision, reference, feedback, incident, project, entity, state

엔드포인트

데이터 모델

각 항목은 mem:<id>의 Redis 해시로 저장됩니다:

버전 기록은 memver:<id>의 Redis 리스트에 저장됩니다 (최신순, MAX_VERSIONS_PER_ENTRY로 제한).

태그, 유형 및 프로젝트 인덱스는 Redis 세트(tag:<name>, type:<name>, project:<name>)입니다.

라이선스

MIT