claude-memory

Claude Code용 메모리 + 프로젝트 추적. MCP 서버 하나로.

• 모든 과거 Claude Code 대화 기록에 대한 의미론적 검색 — 새 세션이 이전 세션을 기억, 컨텍스트 창을 훨씬 넘어섬

• 영구 메모(remember) — 프로젝트별 또는 전역

• 구조화된 추적: 프로젝트 → 마일스톤 → 에픽 → 티켓 → 할 일, 로드맵으로 렌더링

• 추적 항목이 동일한 벡터 공간에 포함 — 티켓이 의미론적 검색에 표시됨

• 프로젝트별 시스템 프롬프트, DB에 저장, 세션 시작 시 주입 가능

스택: Voyage AI 임베딩 + Qdrant 벡터 DB + SQLite + FastMCP. 모두 무료: Voyage 무료 티어는 개인 사용에 충분, Qdrant Cloud 무료 티어는 100만 벡터 보관(또는 로컬 docker 실행). 운영 비용 $0.

설정

키 두 개:

• Voyage → https://dashboard.voyageai.com

• Qdrant → https://cloud.qdrant.io에서 무료 클러스터, 또는 docker run -p 6333:6333 qdrant/qdrant

git clone https://github.com/mathis-sperlich/claude-memory
cd claude-memory
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
cp .env.example .env
# fill VOYAGE_API_KEY, QDRANT_URL, QDRANT_API_KEY

ingest.py의 SCAN_PROJECTS를 대화 기록 디렉터리로 지정하세요 (Claude Code는 ~/.claude/projects/<encoded-project-dir>/*.jsonl에 기록).

수집

.venv/bin/python ingest.py --dry-run   # sanity-check chunking
.venv/bin/python ingest.py             # embed + upsert

멱등적 — 재실행 시 새 청크만 임베딩. cron 작업으로 안전. 시간별 launchd 템플릿: launchd/com.mathis.claude-memory.plist (경로 수정 후 ~/Library/LaunchAgents/로 cp, launchctl load).

CLI에서 검색 테스트:

.venv/bin/python query.py "how did the auth token refresh bug get fixed?"

결과가 나쁜가요? ingest.py의 MAX_CHUNK_CHARS를 낮추거나, .env에서 더 큰 EMBED_MODEL을 시도하고 --reset으로 재수집하세요.

Claude Code에 연결

~/.claude/settings.json:

{
  "mcpServers": {
    "claude-memory": {
      "command": "/path/to/claude-memory/.venv/bin/python",
      "args": ["/path/to/claude-memory/mcp_server.py"]
    }
  }
}

Claude Code 재시작. 완료 — 이제 Claude는 query_history, remember, 추적 도구, 시스템 프롬프트 도구를 보유.

도구

메모리

추적

계층: 프로젝트 → 마일스톤(선택) → 에픽 → 티켓 → 할 일.

status: open / in_progress / done. priority: P0–P3.

시스템 프롬프트

set_system_prompt(content, project=) / get_system_prompt(project=) / list_system_prompts() / delete_system_prompt(project=). 전역 + 프로젝트별 레이어, 읽을 때 합성. tracking.db에 저장. 설정되지 않으면 docs/usage.md로 대체.

훅 (선택, 결정적)

MCP 도구는 모델이 결정할 때 실행. 훅은 항상 실행. hooks/session_start.py는 매 세션 시작 시 현재 프로젝트의 열린 티켓 + 시스템 프롬프트를 주입:

{
  "hooks": {
    "SessionStart": [{
      "matcher": "*",
      "hooks": [{
        "type": "command",
        "command": "/path/to/claude-memory/.venv/bin/python /path/to/claude-memory/hooks/session_start.py"
      }]
    }]
  }
}

원격 접근 (선택)

기본 = 로컬 stdio, 네트워크 없음. claude.ai나 다른 머신에서 같은 메모리를 원하나요? HTTP 전송 + Cloudflare 터널 + 로그인 허용 목록이 있는 GitHub OAuth:

.venv/bin/python mcp_server.py --transport http --port 8765

launchd 서비스 + 자가 복구 워치독 포함 전체 가이드: CLOUD_SETUP.md.

참고

• 개인정보: Voyage는 임베딩 시 텍스트를 봄 (TOS에 따라 고객 데이터 학습 없음), Qdrant Cloud는 벡터 + 페이로드 저장. 둘 다 우려된다면 → 로컬 Qdrant + 로컬 임베더, 동일한 코드.

• 중단된 임베딩 요청은 VOYAGE_TIMEOUT / VOYAGE_MAX_RETRIES 환경 변수로 제한 (기본 20초 / 2).