project-memory MCP — 사용 사례, 설치 & 라이브 데모

왜 쓰나요

핵심 기능

4개 파일 캐논: bugs.md, Decisions.md, key_facts.md, Issues.md
Claude는 아키텍처 변경을 제안하기 전에 이를 읽습니다.
세 가지 설치 범위: 전역(~/.claude/skills), 프로젝트(.claude/skills), 작업 공간
skilz (pip) 또는 일반 복사본을 통해 설치 가능
데이터베이스 없음 — 마크다운만 비교 및 검토 가능

라이브 데모

실제 사용 모습

project-memory-skill.replay ▶ 준비됨

0/0

설치

클라이언트 선택

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "project-memory-skill": {
      "command": "pip",
      "args": [
        "install",
        "skilz",
        "&&",
        "skilz",
        "install",
        "SpillwaveSolutions_project-memory/project-memory"
      ],
      "_inferred": false
    }
  }
}

Claude Desktop → Settings → Developer → Edit Config 열기. 저장 후 앱 재시작.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "project-memory-skill": {
      "command": "pip",
      "args": [
        "install",
        "skilz",
        "&&",
        "skilz",
        "install",
        "SpillwaveSolutions_project-memory/project-memory"
      ],
      "_inferred": false
    }
  }
}

Cursor는 Claude Desktop과 동일한 mcpServers 스키마 사용. 프로젝트 설정이 전역보다 우선.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "project-memory-skill": {
      "command": "pip",
      "args": [
        "install",
        "skilz",
        "&&",
        "skilz",
        "install",
        "SpillwaveSolutions_project-memory/project-memory"
      ],
      "_inferred": false
    }
  }
}

Cline 사이드바의 MCP Servers 아이콘 클릭 후 "Edit Configuration" 선택.

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "project-memory-skill": {
      "command": "pip",
      "args": [
        "install",
        "skilz",
        "&&",
        "skilz",
        "install",
        "SpillwaveSolutions_project-memory/project-memory"
      ],
      "_inferred": false
    }
  }
}

Claude Desktop과 같은 형식. Windsurf 재시작 후 적용.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "project-memory-skill",
      "command": "pip",
      "args": [
        "install",
        "skilz",
        "&&",
        "skilz",
        "install",
        "SpillwaveSolutions_project-memory/project-memory"
      ]
    }
  ]
}

Continue는 맵이 아닌 서버 오브젝트 배열 사용.

~/.config/zed/settings.json

{
  "context_servers": {
    "project-memory-skill": {
      "command": {
        "path": "pip",
        "args": [
          "install",
          "skilz",
          "&&",
          "skilz",
          "install",
          "SpillwaveSolutions_project-memory/project-memory"
        ]
      }
    }
  }
}

context_servers에 추가. 저장 시 Zed가 핫 리로드.

claude mcp add project-memory-skill -- pip install skilz && skilz install SpillwaveSolutions_project-memory/project-memory

한 줄 명령. claude mcp list로 확인, claude mcp remove로 제거.

사용 사례

실전 활용법: project-memory

기존 코드베이스의 부트스트랩 프로젝트 메모리

👤 에이전트에게 동일한 맥락을 다시 설명하는 데 지친 팀 ⏱ ~15 min beginner

언제 쓸까: 이 저장소에서 Claude Code를 사용했지만 컨텍스트는 모든 세션을 재설정합니다.

사전 조건

skilz 설치 프로그램용 Python 3.10+ — pyenv 또는 시스템 Python

흐름

프로젝트 범위에 설치

pip install skilz && skilz install SpillwaveSolutions_project-memory/project-memory --scope 프로젝트✓ 복사됨

→ .claude/skills/project-memory/SKILL.md가 나타납니다.
부트스트랩 명령 실행

/project-memory — 이 저장소에 대한 4개의 파일을 초기화합니다.✓ 복사됨

→ docs/project_notes/ 4개의 정식 파일로 생성됨
2~3개의 알려진 선택 사항이 있는 시드 결정.md

ORM 선택, 오류 처리 규칙 및 CI 실행기에 대한 ADR을 추가합니다.✓ 복사됨

→ 깔끔한 ADR 항목 3개

결과: 이제 Claude는 이 저장소에 대해 지속적이고 검토 가능한 두뇌를 갖게 되었습니다.

함정

비밀을 사용하여 key_facts.md 커밋 — 이 기술은 key_facts.md를 '민감하지 않음'으로 명시적으로 플래그 지정합니다. 여기에 자격 증명을 입력하지 마세요.

함께 쓰기: memory-bank-mcp

버그의 근본 원인을 파악하여 다시는 발생하지 않도록 합니다.

👤 대기 중인 엔지니어가 화재를 진압하고 있습니다. ⏱ ~5 min beginner

언제 쓸까: 방금 까다로운 문제를 해결했고 수업이 지속되기를 원합니다.

흐름

클로드에게 녹음을 요청하세요

이것을 bugs.md에 추가하십시오. billing.retry에서 NoneType 오류가 발생했습니다. 근본 원인: 오래된 멱등성 키 캐시; 예방: 캐시의 TTL.✓ 복사됨

→ 근본 원인 + 예방 기능이 포함된 새로운 bugs.md 항목

결과: 다음에 유사한 증상이 나타날 때 배당금을 지불하는 버그 카탈로그입니다.

함정

원인 대신 증상을 쓴다. — 항목에 '내가 해결한 것'뿐만 아니라 '근본 원인' 및 '예방' 섹션을 포함하도록 강제합니다.

함께 쓰기: github

리팩토링을 제안하기 전에 Claude가 Decision.md를 참조하도록 하세요.

👤 에이전트와 확정된 선택에 대해 다시 소송을 제기하는 것을 싫어하는 팀 ⏱ ~10 min beginner

언제 쓸까: 에이전트가 팀에서 이미 거부한 프레임워크/패턴을 계속 제안합니다.

흐름

Decisions.md에 결정이 있는지 확인하세요.

Record: '우리는 Active Record가 아닌 Repository 패턴을 사용합니다. 근거: <x>.'✓ 복사됨

→ Decisions.md에서 ADR 지우기
리팩터링을 요청하세요

src/billing/의 리팩터링을 제안합니다 — 우리의cision.md를 존중하세요.✓ 복사됨

→ 제안은 저장소 결정을 참조하며 Active Record를 제안하지 않습니다.

결과: 검토에서 거부되는 막다른 제안이 줄어듭니다.

함께 쓰기: git

조합

다른 MCP와 조합해 10배 효율

project-memory-skill + memory-bank-mcp

큐레이트된 표준 4개 파일에는 프로젝트 메모리를 사용하고, 프로젝트 전체의 자유 형식 작업 메모리에는 memory-bank-mcp를 사용합니다.

Decision.md에 구조화된 ADR을 작성합니다. 원시 세션 노트를 메모리 뱅크에 덤프합니다.✓ 복사됨

project-memory-skill + github

PR을 병합한 후 PR 설명의 일부로 Decision.md 및 Issue.md를 업데이트하세요.

PR을 열고 설명에 Decision.md diff를 포함하세요.✓ 복사됨

project-memory-skill + git

메모리 차이를 정직하게 유지하기 위해 커밋하기 전에 검토하세요.

git diff docs/project_notes/ — 커밋하기 전에 읽어보세요. 오해의 소지가 있는 부분을 수정하세요.✓ 복사됨

도구

이 MCP가 노출하는 것

도구	입력	언제 호출	비용
/project-memory	subcommand: init\|add-bug\|add-decision\|add-fact\|log-issue	파일을 부트스트랩하고 새 항목을 기록합니다.	0

비용 및 제한

운영 비용

API 쿼터: 없음
호출당 토큰: Claude가 로드하는 4개의 파일 중 얼마나 많은지에 따라 다릅니다. 항목을 짧게 유지하세요
금액: 무료
팁: 긴 설명보다 짧고 날짜가 적힌 항목을 선호합니다. Claude는 매 세션마다 항목을 스캔하므로 크기가 중요합니다.

보안

권한, 시크릿, 파급범위

자격 증명 저장: Explicitly: key_facts.md is for non-sensitive config only. 여기가 아닌 환경이나 저장소에 비밀을 유지하세요.

데이터 외부 송신: 로컬 파일 기술 자체에서는 네트워크 활동이 없습니다.

docs/project_notes/를 공개 저장소에 커밋하는 경우 Claude가 내부 세부 정보를 기록했을 수 있다는 점을 기억하세요. 푸시하기 전에 검토하세요.
상담원이 검토 없이 Decision.md에 자동으로 추가하도록 허용하지 마세요. 오래되거나 잘못된 컨텍스트가 전체 시스템을 부식시키는 곳이 바로 여기입니다.

문제 해결

자주 발생하는 오류와 해결

/project-memory 명령이 인식되지 않습니다.

스킬이 예상 범위에 설치되지 않았습니다. skilz를 다시 설치하고 Claude를 다시 시작하십시오.

확인: ls ~/.claude/skills/project-memory/ or .claude/skills/project-memory/

클로드는 결정을 무시합니다.md

Decision.md에 'Decision' 및 'Rationale' 헤더가 포함된 명확한 ADR 스타일 항목이 있는지 확인하세요. 모호한 글머리 기호는 생략됩니다.

확인: head docs/project_notes/decisions.md

파일이 계속 증가함

분기별 보관 — 이전 항목을 docs/project_notes/archive/로 이동하여 활성 파일을 계속 검색할 수 있도록 하세요.

확인: wc -l docs/project_notes/*.md

대안

project-memory 다른 것과 비교

대안	언제 쓰나	단점/장점
memory-bank-mcp	파일이 아닌 도구로 프로젝트 간 메모리에 액세스할 수 있기를 원합니다.	유연성이 향상되고 PR 리뷰에서 눈에 덜 띄게 됩니다.
codebase-memory	서술형 메모가 아닌 코드의 기호 그래프를 원합니다.	다양한 메모리 계층
marm-systems	좀 더 정교한 메모리 프레임워크를 원합니다.	더 무거운 설정

project-memory