QMD

로컬 마크다운 문서를 인덱싱하고 검색하는 CLI 도구(qmd)의 래퍼입니다.

Instructions

워크플로우 1: 검색

사용자가 노트/문서에서 정보를 찾으려 할 때:

1. 검색 모드 선택

   상황	명령어	특징
   키워드 정확 매칭	qmd search	BM25, 빠름
   의미 유사성	qmd vsearch	벡터 검색
   최고 품질	qmd query	하이브리드 + LLM 재순위

2. 검색 실행

   # 기본 검색
   qmd search "검색어"
   
   # 의미 기반 검색
   qmd vsearch "검색어"
   
   # 최고 품질 (쿼리 확장 + 재순위)
   qmd query "검색어"

3. 유용한 옵션

   • -n <수>: 결과 개수 (기본 5)
   • -c <컬렉션>: 특정 컬렉션만
   • --full: 전체 문서 내용 표시
   • --json: JSON 출력 (파이프라인용)
   • --md: Markdown 출력
   • --files: 파일 경로 + 점수 출력
   • --min-score <값>: 점수 임계값 필터링

워크플로우 2: 문서 조회

검색 결과에서 특정 문서를 가져올 때:

1. 단일 문서 조회

   # 파일 경로로
   qmd get notes/meeting.md
   
   # docid로
   qmd get "#abc123"
   
   # 특정 라인부터
   qmd get notes/meeting.md:50 -l 100

2. 다중 문서 조회

   qmd multi-get "journals/2025-05*.md"
   qmd multi-get --json "docs/*.md"

워크플로우 3: 컬렉션 관리

새 문서 디렉토리를 추가하거나 인덱스를 관리할 때:

1. 컬렉션 추가

   qmd collection add ~/notes --name notes
   qmd context add qmd://notes "개인 노트"

2. 인덱싱

   qmd embed         # 벡터 임베딩 생성
   qmd update        # 재인덱싱
   qmd update --pull # git pull 후 재인덱싱

3. 상태 확인

   qmd status
   qmd cleanup       # 캐시 정리

중요 원칙

1. 검색 모드 선택: 빠른 키워드 → search, 의미 검색 → vsearch, 최고 품질 → query
2. 점수 해석: 0.8+ 매우 관련, 0.5-0.8 적당, 0.2-0.5 약간, 0.2 미만 낮음
3. 컬렉션 스코핑: -c 옵션으로 검색 범위를 좁히면 노이즈 감소
4. JSON 출력: 파이프라인이나 후처리 시 --json 활용

Examples

노트에서 정보 검색

User: "배포 관련 노트 찾아줘"
→ qmd query "배포 방법" -n 10
→ 결과 요약 제공
→ 필요 시 qmd get으로 상세 조회

특정 컬렉션에서 검색

User: "회의록에서 프로젝트 타임라인 찾아줘"
→ qmd search "프로젝트 타임라인" -c meetings --full
→ 결과 제공

새 컬렉션 추가

User: "~/Documents/research를 qmd에 추가해줘"
→ qmd collection add ~/Documents/research --name research
→ qmd context add qmd://research "연구 자료"
→ qmd embed
→ qmd status로 확인

Technical Details

상세 아키텍처와 고급 사용법은 REFERENCE.md를 참조하세요.