시맨틱 검색

마크다운 파일에 대한 시맨틱 검색입니다. 키워드뿐만 아니라 의미를 기반으로 관련 노트를 찾습니다. 새 노트를 만들기 전에 중복을 감지합니다.

두 가지 서버 전송 방식을 지원합니다:

• stdio MCP — Claude Code 통합용 (세션당 하나의 프로세스)

• HTTP — 하나의 포트에서 MCP-over-HTTP와 REST를 결합; 모든 클라이언트가 공유하는 하나의 웜 프로세스

기능

• sentence-transformers를 사용한 시맨틱 검색

• 중복/유사 노트 감지

• 파일 감시자를 통한 자동 인덱스 업데이트

• 다중 디렉토리 지원

• 인라인 태그 추출 (#tag-name)

설치

CPU 전용 설치 — macOS(모든 Mac, Apple Silicon 또는 Intel) 및 NVIDIA GPU가 없는 Linux/Windows에 권장됩니다. 약 5GB의 CUDA 바이너리를 절약합니다. macOS에서는 Apple GPU(MPS)가 PyTorch의 내장 MPS 백엔드를 통해 자동으로 감지되어 사용됩니다. "CPU" 라벨은 CUDA가 없음을 의미할 뿐, 런타임 시 컴퓨팅 장치를 의미하지는 않습니다.

uv tool install --index https://download.pytorch.org/whl/cpu \
  git+https://github.com/bborbe/semantic-search

CUDA 설치 — 전용 NVIDIA GPU가 있는 Linux/Windows 전용입니다. macOS에는 적용되지 않습니다 (Mac에서는 NVIDIA CUDA가 지원되지 않음).

uv tool install git+https://github.com/bborbe/semantic-search

업그레이드

uv tool upgrade semantic-search

서버 모드

stdio MCP (세션별 Claude Code)

Claude Code 세션당 하나의 프로세스를 생성합니다. 간단하지만 각 세션이 약 400MB~1GB의 모델 복사본을 로드합니다.

claude mcp add -s project semantic-search \
  --env CONTENT_PATH=/path/to/vault \
  -- \
  uvx --from git+https://github.com/bborbe/semantic-search semantic-search-mcp

사용 가능한 도구:

• search_related(query, top_k=5) — 의미적으로 관련된 노트 찾기

• check_duplicates(file_path) — 중복/유사 노트 감지

HTTP (모든 클라이언트 간 공유)

단일 장기 실행 프로세스가 /mcp에서 MCP-over-HTTP를, /search, /duplicates, /health, /reindex에서 REST를 제공합니다. 모든 Claude Code 세션과 REST 클라이언트가 하나의 웜 인덱서를 공유합니다.

CONTENT_PATH=/path/to/vault semantic-search-http --host 127.0.0.1 --port 8321

MCP 설정을 통해 Claude Code를 연결하세요:

{
  "mcpServers": {
    "semantic-search": {
      "type": "http",
      "url": "http://127.0.0.1:8321/mcp"
    }
  }
}

REST 엔드포인트:

쿼리 예시:

# Search
curl 'http://127.0.0.1:8321/search?q=kubernetes+deployment'

# Find duplicates
curl 'http://127.0.0.1:8321/duplicates?file=notes/my-note.md'

# Health check
curl 'http://127.0.0.1:8321/health'

백그라운드 실행

프로덕션 스타일로 사용하려면 semantic-search-http를 백그라운드 서비스로 실행하여 모든 Claude Code 세션(및 모든 REST 클라이언트)이 하나의 웜 프로세스를 공유하도록 하세요.

빠른 예시 (macOS):

launchctl load ~/Library/LaunchAgents/com.github.bborbe.semantic-search-http.plist

빠른 예시 (Linux):

systemctl --user enable --now semantic-search-http.service

CLI 명령어

서버를 실행하지 않는 일회성 명령어:

# Search
CONTENT_PATH=/path/to/vault semantic-search search "kubernetes deployment"

# Find duplicates
CONTENT_PATH=/path/to/vault semantic-search duplicates path/to/note.md

바이너리

구성

환경 변수

다중 디렉토리

경로를 쉼표로 구분하여 여러 디렉토리를 인덱싱하세요:

CONTENT_PATH=/path/to/vault1,/path/to/vault2,/path/to/docs

모든 디렉토리는 함께 인덱싱되며 하나의 통합된 인덱스로 검색됩니다.

작동 원리

첫 실행 시 작은 임베딩 모델(~90MB)을 다운로드하고 마크다운 파일을 인덱싱합니다(일반적인 볼트의 경우 1초 미만). 파일 시스템 감시자를 통해 파일이 변경되면 인덱스가 자동으로 업데이트됩니다.

인덱싱된 콘텐츠

각 마크다운 파일은 가중치가 적용된 구성 요소로 인덱싱됩니다:

개발

# Clone
git clone https://github.com/bborbe/semantic-search
cd semantic-search

# Install dev dependencies
make install

# Run checks
make check

# Run tests
make test

라이선스

BSD 2-Clause 라이선스 — LICENSE를 참조하세요.