시맨틱 검색

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

두 가지 서버 모드를 지원합니다:

MCP 모드 — Claude Code 통합용
REST 모드 — OpenClaw, 스크립트 및 HTTP 클라이언트용

기능

sentence-transformers를 사용한 시맨틱 검색
중복/유사 노트 감지
파일 감시자를 통한 자동 인덱스 업데이트
다중 디렉토리 지원
인라인 태그 추출 (#tag-name)

설치

CPU 전용 (권장 — 약 5GB 절약, 일반적인 볼트 크기에서 성능 동일):

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

CUDA 사용 (전용 GPU가 있는 경우에만):

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

업그레이드

uv tool upgrade semantic-search

서버 모드

MCP 모드 (Claude Code용)

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 serve

사용 가능한 도구:

search_related(query, top_k=5) — 의미적으로 관련된 노트 찾기
check_duplicates(file_path) — 중복/유사 노트 감지

REST 모드 (OpenClaw/HTTP용)

CONTENT_PATH=/path/to/vault semantic-search-mcp serve --mode rest --port 8321

엔드포인트:

엔드포인트	메서드	설명
`/search?q=...&top_k=5`	GET	시맨틱 검색
`/duplicates?file=...&threshold=0.85`	GET	중복 노트 찾기
`/health`	GET	인덱스 통계가 포함된 상태 확인
`/reindex`	GET/POST	인덱스 강제 재구축

쿼리 예시:

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

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

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

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

두 가지 바이너리

바이너리	목적
`semantic-search-mcp`	서버 모드 — `serve` (MCP 또는 REST), `search` 및 `duplicates` 포함
`semantic-search`	CLI 전용 — `search` 및 `duplicates` 일회성 명령어, `serve` 없음

구성

환경 변수

변수	설명	기본값
`CONTENT_PATH`	인덱싱할 디렉토리 (여러 개인 경우 쉼표로 구분)	`./content`
`LOG_LEVEL`	로깅 레벨 (DEBUG, INFO, WARNING, ERROR)	`INFO`

다중 디렉토리

경로를 쉼표로 구분하여 여러 디렉토리를 인덱싱합니다:

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

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

작동 방식

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

인덱싱된 콘텐츠

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

구성 요소	가중치	참고
파일명	3x
프론트매터 `title`	3x
프론트매터 `tags`	2x	인라인 태그와 병합
프론트매터 `aliases`	2x
인라인 태그 (`#tag`)	2x	본문에서 추출
첫 번째 H1 제목	2x
본문 콘텐츠	1x	처음 500단어

개발

# 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를 참조하세요.

This server cannot be installed

-

security - not tested

A

license - permissive license

-

quality - not tested

How are these scores calculated?

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Appeared in Searches

A search for similar notes

Semantic Search MCP