claude-memory-fts

Claude Code를 위한 장기 기억 MCP 서버입니다. 하이브리드 검색(FTS5 + 의미론적 벡터 유사도)과 자동 컨텍스트 주입 기능을 갖춘 로컬 SQLite 데이터베이스에 사실 정보를 저장합니다.

주요 기능

• 하이브리드 검색 — FTS5 키워드 검색과 의미론적 벡터 유사도를 결합하여 RRF(Reciprocal Rank Fusion)로 병합

• 의미론적 이해 — 단순 키워드가 아닌 의미 기반으로 기억을 검색 (all-MiniLM-L6-v2 임베딩 기반)

• 자동 컨텍스트 주입 — 훅(hook)을 통해 가장 중요한 상위 30개의 기억을 모든 프롬프트에 자동으로 주입

• 중요도 랭킹 — 액세스 빈도, 최신성 감쇠, 카테고리 가중치에 따라 사실 정보 순위 지정

• 액세스 추적 — 각 기억에 얼마나 자주 액세스하는지 추적

• 업서트(Upsert) — 중복 생성 대신 기존 사실 정보를 자동으로 업데이트

• 카테고리 분류 — 유형별 정리: 선호도(preference), 결정(decision), 기술(technical), 프로젝트(project), 워크플로우(workflow), 개인(personal), 일반(general)

• MCP 리소스 — 세션 컨텍스트를 위한 memory://context 리소스 노출

• 제로 구성 — 즉시 사용 가능하며 ~/.claude/memory.db에 데이터 저장

설치

# Add to Claude Code
claude mcp add memory -- npx claude-memory-fts

# Auto-configure context injection hook (recommended)
npx claude-memory-fts --setup-hook

--setup-hook 명령은 자동으로 다음을 수행합니다:

1. ~/.claude/scripts/memory-context.sh 생성

2. ~/.claude/settings.json에 UserPromptSubmit 훅 추가

3. 상위 30개의 기억이 모든 프롬프트에 자동으로 주입됨

CLI 명령어

구성

사용자 지정 경로 예시:

claude mcp add memory -e MEMORY_DB_PATH=/path/to/my/memory.db -- npx claude-memory-fts

도구

memory_save

장기 기억에 사실 정보를 저장합니다.

memory_search

하이브리드 검색: FTS5와 의미론적 검색을 병렬로 실행하고 RRF로 결과를 병합합니다. 부분 일치의 경우 LIKE 검색으로 대체됩니다.

memory_update

ID를 사용하여 기억의 내용이나 카테고리를 업데이트합니다.

memory_list

카테고리별로 그룹화된 모든 저장된 기억을 나열합니다.

memory_delete

ID를 사용하여 기억을 삭제합니다.

리소스

memory://context

중요도 점수에 따라 순위가 매겨진 상위 30개의 사실 정보를 노출하는 MCP 리소스:

• 액세스 빈도 — 자주 액세스하는 사실 정보가 더 높은 점수를 받음 (최대 20점)

• 최신성 — 최근에 업데이트된 사실 정보가 더 높은 점수를 받음 (10점, 90일에 걸쳐 감쇠)

• 카테고리 가중치 — 선호도/결정(3), 워크플로우/기술(2), 프로젝트/개인(1), 일반(0)

작동 원리

검색 파이프라인

1. FTS5 + BM25 및 의미론적 벡터 유사도가 병렬로 실행됨

2. 결과는 RRF(Reciprocal Rank Fusion) (k=60)를 사용하여 병합 및 중복 제거됨

3. 두 목록 모두에 나타나는 사실 정보는 자연스럽게 가중치가 부여됨

4. 둘 다 결과가 없는 경우 LIKE 부분 문자열 일치로 대체됨

5. 검색 히트 시마다 액세스 횟수가 추적됨

임베딩

• 모델: all-MiniLM-L6-v2 (384 차원, 약 23MB)

• @xenova/transformers를 통해 로컬에서 생성 — API 호출 없음, 데이터가 기기 외부로 유출되지 않음

• 임베딩은 저장 시 생성되며 서버 시작 시 백필(backfill)됨

• 노이즈 필터링을 위해 0.3 임계값의 코사인 유사도 사용

저장소

• 빠른 동시 읽기/쓰기를 위한 WAL 모드의 SQLite

• 실시간 전문 검색 인덱싱을 위해 트리거를 통해 동기화되는 FTS5 가상 테이블

• 사실 정보와 함께 BLOB 열로 저장되는 임베딩

개발

git clone https://github.com/kurovu146/claude-memory-mcp.git
cd claude-memory-mcp
npm install
npm run build
npm test

라이선스

MIT