AI 어시스턴트가 몇 주간의 개발 과정에서 모든 아키텍처 결정, 버그 수정, 리팩토링 세션을 기억한다면 어떨까요? Claude-mem은 도구 사용 관찰을 자동으로 캡처하고, 이를 의미론적 요약으로 압축하며, 모든 새로운 Claude Code 세션에 관련 기록을 주입하여 컨텍스트 손실로 인한 마찰을 제거합니다.
문제: AI 지원 개발에서의 컨텍스트 기억 상실증
모든 Claude Code 세션은 백지 상태에서 시작됩니다. 터미널을 닫거나 세션 연결을 끊으면 Claude는 모든 것을 잊어버립니다. 프로젝트 구조, 최근 리팩토링 결정, 디버깅 발견 사항, 아키텍처 패턴 등 말이죠. 이는 코드베이스를 반복적으로 설명하게 만들어 불필요한 컨텍스트에 토큰을 낭비하고 워크플로우 연속성을 저해합니다.
개발자들은 현재 CLAUDE.md 파일을 수동으로 관리하거나, 별도의 문서에 메모를 작성하거나, 매 세션 시작 시 프로젝트 컨텍스트를 다시 설명하는 방식으로 이 문제를 해결하고 있습니다. 이러한 접근 방식은 취약하고 시간이 많이 소요되며, 개발 이력의 모든 풍부한 내용을 담아내지 못합니다. Claude-mem은 모든 도구 호출을 자동으로 관찰하고, 출력을 검색 가능한 의미론적 메모리로 압축하며, 필요할 때 관련 컨텍스트를 지능적으로 검색함으로써 이 문제를 해결합니다.
개발팀이 최고의 생산성으로 함께 작업할 수 있는 통합된 올인원 플랫폼을 원하십니까?
Apidog은 귀하의 모든 요구사항을 충족하며, 훨씬 더 저렴한 가격에 Postman을 대체합니다!
Claude-mem의 아키텍처 이해
Claude-mem은 Claude Code의 수명 주기에 연결되는 영구 메모리 압축 시스템으로 작동합니다. 일반적으로 1,000에서 10,000 토큰에 달하는 도구 출력을 캡처하여 Claude의 Agent SDK를 사용하여 약 500 토큰의 의미론적 관찰로 압축합니다. 이러한 관찰은 유형(결정, 버그 수정, 기능, 리팩토링, 발견, 변경)별로 분류되고 관련 개념 및 파일 참조로 태그가 지정되며, 전체 텍스트 검색 기능이 있는 로컬 SQLite 데이터베이스에 저장됩니다.
이 시스템은 컨텍스트를 캡처하기 위해 다섯 가지 수명 주기 후크를 사용합니다.
- SessionStart: 시작 시 이전 세션의 컨텍스트를 주입합니다.
- UserPromptSubmit: 패턴 인식을 위해 사용자의 쿼리를 캡처합니다.
- PostToolUse: 모든 도구 실행 및 해당 출력을 관찰합니다.
- Stop: Claude가 응답을 마치면 세션 요약을 생성합니다.
- SessionEnd: 세션 저장 및 정리를 완료합니다.
이 아키텍처는 점진적 공개(progressive disclosure)를 가능하게 합니다. 이는 커버리지와 토큰 효율성의 균형을 맞추는 계층형 메모리 검색 시스템입니다. Claude-mem은 전체 기록을 컨텍스트에 한꺼번에 쏟아붓는 대신, 관찰 내용을 계층적으로 검색하여 수동 컨텍스트 관리와 비교하여 세션당 약 2,250 토큰을 절약합니다.
설치 및 시스템 요구사항
Claude-mem은 Node.js 18.0.0 이상, 플러그인 지원이 있는 최신 Claude Code, 그리고 JavaScript 런타임 및 프로세스 관리자로서 Bun(누락 시 자동 설치됨)을 필요로 합니다. SQLite 3은 영구 저장을 위해 번들로 제공됩니다. 이 플러그인은 Windows, macOS, Linux에서 크로스 플랫폼으로 작동합니다.
빠른 시작 설치
두 가지 명령으로 플러그인 마켓플레이스에서 Claude-mem을 직접 설치합니다.
/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem
설치 후 Claude Code를 다시 시작합니다. 플러그인은 미리 빌드된 바이너리를 자동으로 다운로드하고, Bun 및 SQLite를 포함한 종속성을 설치하며, 세션 수명 주기 관리를 위한 후크를 구성하고, 첫 세션에서 워커 서비스를 자동으로 시작합니다.
소스에서 고급 설치
개발 또는 테스트를 위해 GitHub에서 소스를 클론하고 빌드합니다.
git clone https://github.com/thedotmack/claude-mem.git
cd claude-mem
npm install
npm run build
npm run worker:start
이 접근 방식은 플러그인을 수정하거나 Endless Mode와 같은 베타 기능을 실행해야 할 경우 유용합니다.
설치 후 확인
설치 후 모든 것이 제대로 작동하는지 확인합니다.
- 플러그인 설치 확인:
cat plugin/hooks/hooks.json
- 워커 서비스가 실행 중인지 확인:
curl http://localhost:37777/api/health
- 최근 워커 로그 보기:
npm run worker:logs
새 Claude Code 세션을 시작하여 컨텍스트 검색을 테스트합니다. 초기 프롬프트에 이전 세션의 컨텍스트가 자동으로 로드되는 것을 볼 수 있습니다.
데이터 저장 및 구성
Claude-mem은 모든 데이터를 로컬 `~/.claude-mem/`에 저장합니다.
- 데이터베이스:
~/.claude-mem/claude-mem.db(FTS5 검색 기능이 있는 SQLite) - PID 파일:
~/.claude-mem/.worker.pid - 포트 파일:
~/.claude-mem/.worker.port - 로그:
~/.claude-mem/logs/worker-YYYY-MM-DD.log - 설정:
~/.claude-mem/settings.json
환경 변수로 기본 데이터 디렉토리를 재정의합니다.
export CLAUDE_MEM_DATA_DIR=/custom/path
구성 옵션
설정은 ~/.claude-mem/settings.json에서 관리됩니다 (첫 실행 시 자동 생성). 주요 구성은 다음과 같습니다.
CLAUDE_MEM_CONTEXT_OBSERVATIONS: 세션 시작 시 주입되는 관찰 횟수 (기본값: 50)CLAUDE_MEM_FOLDER_INDEX_ENABLED: 폴더 내 자동 생성되는 CLAUDE.md 파일 활성화/비활성화- AI 기반 압축을 위한 모델 선택
- 워커 포트 및 호스트 설정
- 로그 레벨 구성
Claude-mem이 컨텍스트를 캡처하고 처리하는 방법
claude-mem이 활성화된 Claude Code를 사용하면 시스템은 모든 도구 호출을 자동으로 캡처합니다. Claude가 파일을 읽거나, bash 명령을 실행하거나, glob 패턴으로 검색하거나, 코드를 편집하는 등 어떤 작업을 하더라도 claude-mem은 입력과 출력을 관찰합니다.
워커 서비스는 이러한 관찰을 처리하고 다음을 추출합니다.
- 제목: 발생한 일에 대한 간략한 설명
- 부제목: 추가 컨텍스트
- 내러티브: 활동에 대한 자세한 설명
- 사실: 핵심 학습 내용을 글머리 기호로 표시
- 개념: 검색을 위한 관련 태그 및 카테고리
- 유형: 분류 (결정, 버그 수정, 기능, 리팩토링, 발견, 변경)
- 파일: 읽거나 수정된 파일
이 압축은 수동 개입 없이 자동으로 이루어집니다. 원시 도구 출력은 5,000 토큰일 수 있지만, 데이터베이스에 저장된 의미론적 관찰은 약 500 토큰으로, 노이즈를 제거하면서 의미를 보존합니다.
세션 요약
Claude가 응답을 마치면 (Stop 후크를 트리거), claude-mem은 자동으로 다음을 포함하는 세션 요약을 생성합니다.
- 요청: 사용자가 요청한 내용
- 조사됨: Claude가 답변하기 위해 탐색한 내용
- 학습됨: 주요 발견 및 통찰력
- 완료됨: 달성된 내용
- 다음 단계: 권장되는 후속 조치
이러한 요약은 개별 관찰과 함께 향후 세션에 주입되어 세부적인 정보와 높은 수준의 내러티브 컨텍스트를 모두 제공합니다.
MCP 검색 도구를 사용하여 메모리 쿼리하기
Claude-mem은 토큰 효율적인 3계층 워크플로우 패턴을 따르는 네 가지 MCP 도구를 제공합니다. 이 설계는 컨텍스트를 점진적으로 검색하여 토큰 사용량을 최소화하면서 관련성을 극대화합니다.
3계층 워크플로우
search: ID와 함께 간결한 인덱스 가져오기 (결과당 약 50-100 토큰)timeline: 흥미로운 결과 주변의 시간순 컨텍스트 가져오기get_observations: 필터링된 ID에 대해서만 전체 세부 정보 가져오기 (결과당 약 500-1,000 토큰)
이 접근 방식은 전체 세부 정보를 가져오기 전에 필터링하여 약 10배의 토큰 절약을 달성합니다.
사용 가능한 MCP 도구
search: 전체 텍스트 쿼리로 메모리 인덱스 검색. 유형, 날짜 또는 프로젝트별로 필터링합니다.timeline: 특정 관찰 또는 쿼리 주변의 시간순 컨텍스트를 가져옵니다. 특정 결정이나 버그 수정으로 이어진 내용을 이해하는 데 유용합니다.get_observations: ID별로 전체 관찰 세부 정보를 가져옵니다. 오버헤드를 최소화하기 위해 항상 단일 호출로 여러 ID를 일괄 처리합니다.__IMPORTANT: Claude에게 항상 표시되며 메모리 시스템을 효과적으로 사용하는 방법을 설명하는 워크플로우 문서.
사용 패턴 예시
특정 버그 수정 찾기:
// Step 1: Search for the bug
search(query="authentication bug", type="bugfix", limit=10)
// Step 2: Review index, identify relevant IDs (e.g., #123, #456)
// Step 3: Fetch full details for relevant observations
get_observations(ids=[123, 456])
최근 아키텍처 결정 탐색:
search(query="database schema", type="decision", limit=5)
특정 파일과 관련된 모든 항목 찾기:
search(query="worker-service.ts", limit=20)
자연어 쿼리
Claude에게 프로젝트 이력에 대해 자연스럽게 질문할 수 있습니다.
- "오류 처리에 대해 어떤 결정을 내렸나요?"
- "인증은 어떻게 구현했나요?"
- "API 레이어에서 어떤 버그를 수정했나요?"
- "데이터베이스 스키마 변경 사항을 보여주세요."
Claude는 관련 컨텍스트를 검색하기 위해 적절한 MCP 도구를 자동으로 호출하며, 특정 관찰을 참조하는 claude-mem:// URI 인용과 함께 결과를 제시합니다.
폴더 컨텍스트 파일 및 CLAUDE.md 자동 생성
Claude-mem은 프로젝트 폴더에 CLAUDE.md 파일을 자동으로 생성하여 글로벌 메모리 데이터베이스를 보완하는 활동 타임라인을 만듭니다.
폴더 컨텍스트 작동 방식
폴더의 파일로 작업할 때 claude-mem은 다음을 수행합니다.
- 접근된 파일에서 고유한 폴더 경로 식별
- 각 폴더와 관련된 최근 관찰 쿼리
- 활동의 형식화된 타임라인 생성
- 해당 폴더의 CLAUDE.md에 작성 ( 태그 내부)
각 폴더의 CLAUDE.md 파일에는 관찰 ID, 타임스탬프, 유형 지표(버그 수정, 기능, 발견), 간략한 제목 및 예상 토큰 수를 보여주는 최근 활동 섹션이 포함됩니다.
사용자 콘텐츠 보존
자동 생성된 콘텐츠는 `` 태그로 묶여 있습니다. 이 태그 외부에서 작성한 모든 콘텐츠는 파일이 재생성될 때 보존됩니다. 이를 통해 다음을 수행할 수 있습니다.
- 생성된 섹션 위나 아래에 자신만의 문서를 추가
- Claude를 위한 폴더별 지침 작성
- 아키텍처 노트 또는 규칙 포함
CLAUDE.md 구조 예시:
# Authentication Module
This folder contains all authentication-related code.
Follow the established patterns for new auth providers.
<claude-mem-context>
# Recent Activity
| ID | Time | Type | Title | Tokens |
|----|------|------|-------|--------|
| #1234 | 4:30 PM | 🔵 | Implemented user authentication | ~250 |
| #1235 | 4:45 PM | 🔴 | Fixed login redirect bug | ~180 |
</claude-mem-context>
## Manual Notes
- OAuth providers go in /providers/
- Session handling uses Redis
개인 정보 보호 제어 및 보안
Claude-mem은 민감한 데이터가 메모리 시스템에 유입되는 것을 방지하기 위한 세부적인 개인 정보 보호 제어를 제공합니다.
개인 콘텐츠 태그
민감한 콘텐츠를 `` 태그로 묶어 저장소에서 제외합니다.
<private>
API_KEY=sk-live-abc123xyz789
DATABASE_PASSWORD=supersecret456
</private>
엣지 처리는 개인 콘텐츠가 데이터베이스에 도달하지 않도록 보장합니다. 이는 API 키, 자격 증명 및 독점 로직에 매우 중요합니다.
이중 태그 개인 정보 보호 시스템
Claude-mem은 이중 태그 접근 방식을 사용합니다.
<private>: 민감한 콘텐츠에 대한 사용자 제어 개인 정보 보호<claude-mem-context>: 재귀적 관찰 저장을 방지하는 시스템 수준 태그
웹 뷰어 UI 및 실시간 모니터링
Claude-mem은 실시간 메모리 스트림 시각화를 위해 http://localhost:37777에서 웹 뷰어를 실행합니다. 인터페이스는 다음을 보여줍니다.
- 중요도를 나타내는 이모티콘 지표와 함께 실시간 관찰 스트림
- 시간순 마커가 있는 세션 타임라인
- 메모리 쿼리를 위한 검색 인터페이스
- 구성 조정을 위한 설정 패널
- 안정 및 베타 채널 간 버전 전환
이 UI는 기본 사용에는 선택 사항이지만, claude-mem이 무엇을 캡처하고 개발 이력을 어떻게 구성하는지 이해하는 데 매우 중요합니다.
베타 기능: Endless Mode
베타 채널은 확장된 세션을 위한 생체 모방 메모리 아키텍처인 Endless Mode를 제공합니다. 50번의 도구 사용 후 컨텍스트 제한에 도달하는 대신, Endless Mode는 약 1,000번의 사용(20배 증가)을 약속합니다. 이는 실시간으로 도구 출력을 압축하여 토큰을 약 95% 줄이고, O(N²) 이차에서 O(N) 선형으로 스케일링을 변경함으로써 달성됩니다.
장단점: 관찰 생성에는 도구 호출당 60-90초가 추가됩니다. 며칠 또는 몇 주에 걸쳐 진행되는 심도 있고 사려 깊은 코딩 세션의 경우 이 지연 시간은 허용될 수 있습니다. 그러나 빠른 도구 사용에는 방해가 될 수 있습니다.
웹 뷰어 UI `http://localhost:37777` → 설정 → 버전 채널에서 베타 기능을 활성화할 수 있습니다.
일반적인 문제 해결
워커 서비스 시작 안 됨
워커가 37777 포트에서 시작되지 않으면:
- 포트가 이미 사용 중인지 확인:
lsof -i :37777
- 대체 포트 구성:
export CLAUDE_MEM_WORKER_PORT=8080
- 수동으로 워커 시작:
bun plugin/scripts/worker-service.cjs
메모리가 저장되지 않음
Claude가 이전 세션을 기억하지 못한다면:
- 워커가 실행 중인지 확인:
npm run worker:status
- 데이터베이스 파일이 존재하는지 확인:
ls -la ~/.claude-mem/claude-mem.db
- 오류에 대한 워커 로그 검토:
npm run worker:logs
컨텍스트 주입 문제
세션 시작 시 너무 많거나 너무 적은 컨텍스트가 나타나면:
관찰 제한 조정:
export CLAUDE_MEM_CONTEXT_OBSERVATIONS=10 # 줄임
export CLAUDE_MEM_CONTEXT_OBSERVATIONS=100 # 늘림
빈 CLAUDE.md 파일
claude-mem이 프로젝트 전체에 빈 CLAUDE.md 파일을 생성하는 경우, 이는 v9.0.5의 알려진 문제입니다. 현재 해결 방법으로는 생성된 디렉토리를 수동으로 삭제하거나, `.gitignore`에 패턴을 추가하거나, 다음 릴리스에서 수정될 때까지 기다리는 것이 있습니다.
Claude Desktop 통합
Claude-mem은 MCP 서버 구성을 통해 Claude Desktop과 연동됩니다. Claude Desktop 구성에 mcp-search 서버를 추가하고, claude-mem 설치의 MCP 서버 스크립트를 가리킨 다음, Claude Desktop을 다시 시작하십시오.
구성되면 과거 작업에 대해 자연스럽게 질문하십시오.
- "지난 세션에서 무엇을 했나요?"
- "이 버그를 전에 수정했었나요?"
- "인증은 어떻게 구현했나요?"
localhost:37777의 웹 뷰어를 사용하여 메모리가 캡처되고 있는지 확인하고, 연결에 실패하면 Claude Desktop 로그를 확인하십시오.
수동 워커 관리 명령어
claude-mem 디렉토리에서 워커 서비스를 관리할 수 있습니다.
npm run worker:start # 워커 서비스 시작
npm run worker:stop # 워커 서비스 중지
npm run worker:restart # 워커 서비스 재시작
npm run worker:logs # 워커 로그 보기
npm run worker:status # 워커 상태 확인
결론
Claude-mem은 Claude Code를 상태 비저장 어시스턴트에서 시간 경과에 따라 코드베이스에 대한 지식을 축적하는 영구적인 개발 파트너로 변화시킵니다. 도구 사용을 자동으로 캡처하고, 관찰을 검색 가능한 메모리로 압축하며, 관련 컨텍스트를 지능적으로 검색함으로써 AI 지원 개발 속도를 저하시키는 반복적인 컨텍스트 구축 작업을 제거합니다.
이 시스템의 점진적 공개(progressive disclosure) 아키텍처(MCP 도구를 사용한 계층형 검색, 폴더 기반 CLAUDE.md 파일, 개인 정보 보호 제어)는 수동 컨텍스트 관리와 비교하여 약 10배의 토큰 효율성을 제공하며, 완전한 데이터 지역성과 보안을 유지합니다.
Claude-mem이 강화된 워크플로우에서 API를 구축하거나 외부 서비스와 작업할 때, Apidog으로 테스트를 간소화하십시오. Apidog은 지속적인 메모리 설정과 더불어 시각적 API 테스트, 자동 문서 생성 및 협업 디버깅을 제공합니다.