ir

name	ir
description	Local markdown search engine CLI (BM25/Vector/Hybrid). Use when searching notes, querying documents, managing collections, indexing, embedding, or retrieving document content.
allowed-tools	Bash(ir:*)

ir - Local Markdown Search Engine

로컬 마크다운 문서를 인덱싱하고 검색하는 CLI 도구. Collection 기반 관리, BM25/Vector/Hybrid 검색 지원.

Status

!ir status 2>/dev/null || echo "ir not available"

CLI Quick Reference

Search

ir search "question"                    # Hybrid (기본, 최고 품질)
ir search --mode bm25 "keywords"        # BM25 only (빠름, no LLM)
ir search --mode vector "question"      # Vector only

Search Options

--mode <MODE>         # bm25 | vector | hybrid [default: hybrid]
-n <num>              # 결과 개수 (기본 10)
--min-score <num>     # 점수 임계값
-c, --collection <name>  # 특정 컬렉션만 검색
--full                # 전체 문서 내용
--files               # docid,score,filepath,context 출력
--json                # JSON 출력
--md                  # Markdown 출력
--csv                 # CSV 출력
--all                 # 전체 결과 (최대 4096)
-v, --verbose         # 파이프라인 결정 및 타이밍

Document Retrieval

ir get "#abc123"                        # By docid
ir get notes/meeting.md:50 -l 100      # 특정 라인부터

Collection Management

ir collection list                          # 목록
ir collection add ~/notes --name notes      # 추가
ir collection remove <name>                 # 삭제
ir collection rename <old> <new>            # 이름 변경
ir collection set-path <name> <path>        # 경로 변경

Indexing & Embedding

ir update                              # 전체 재인덱싱
ir update <collection>                 # 특정 컬렉션만
ir update --pull                       # git pull 후 재인덱싱
ir embed                               # 벡터 임베딩 생성
ir embed <collection>                  # 특정 컬렉션만

Daemon & MCP

ir daemon start                        # 검색 데몬 시작 (모델 warm)
ir daemon stop                         # 데몬 중지
ir daemon status                       # 데몬 상태
ir mcp                                 # MCP 서버 시작
ir mcp --http <PORT>                   # HTTP MCP 서버

Examples

노트에서 정보 검색

User: "배포 관련 노트 찾아줘"
-> ir search "배포 방법 deploy" -n 10
-> 결과 요약 -> 필요 시 ir get "#docid"로 상세 조회

컬렉션 추가 후 인덱싱

User: "이 프로젝트 문서도 검색되게 해줘"
-> ir collection add ~/pj-foo/docs --name pj-foo
-> ir update pj-foo && ir embed pj-foo
-> ir status 로 확인

특정 컬렉션 스코프 검색

User: "회의록에서 프로젝트 타임라인 찾아줘"
-> ir search "프로젝트 일정과 마일스톤" -c meetings -n 10

Principles

1. 검색 모드: 빠른 키워드 -> --mode bm25, 최고 품질 -> 기본 hybrid
2. 점수 해석: 0.8+ 매우 관련, 0.5-0.8 적당, 0.5 미만 약함
3. 컬렉션 스코핑: -c 옵션으로 범위를 좁히면 노이즈 감소
4. 인덱스 갱신: 문서 추가/수정 후 ir update && ir embed 실행
5. 파이프라인: --json/--files 출력으로 후처리 연결