MISAMA Search 1.0

MISAMA Search는 Windows 우선, 완전 로컬 방식으로 파일과 폴더 이름만 읽는 의미 검색기입니다. Everything에 의존하지 않으며 파일 본문도 열지 않습니다.

할 수 있는 일

• 정확한 이름, 부분 문자열, 중국어 바이그램(bigram) 퍼지 매칭 및 부모 디렉터리 컨텍스트 정렬을 지원합니다;

• BGE-small-zh-v1.5 로컬 의미 검색으로, 예를 들어 “수상 경력”으로 “이력서”를 찾습니다;

• USearch HNSW Int8 백만 규모 벡터 인덱스를 지원하며, 네이티브 모듈이 없으면 Float32 정밀 검색으로 폴백합니다;

• 안정적인 uint64 파일 ID를 사용하며, 추가, 삭제, 이름 변경 시 증분 벡터 업데이트를 수행합니다;

• watch가 하위 디렉터리 변경을 자동으로 감시하며 관리자 권한이 필요 없습니다;

• serve가 127.0.0.1만 수신하는 상주 HTTP 서비스를 제공하며, 모델은 한 번만 로드합니다;

• MCP stdio Server와 MISAMA Agent Harness Tool이 동일한 인덱스를 공유합니다;

• 선택적 Windows MFT 서비스가 전체 NTFS 볼륨의 고속 스캔을 담당하며, 서비스 설치와 원시 볼륨 읽기에만 관리자 권한이 필요합니다.

Related MCP server: ragi

프라이버시 경계

인덱스에는 이름, 경로, 유형 및 로컬 벡터가 포함되며 파일 본문은 포함되지 않습니다. 스캔, 임베딩, 정렬은 모두 로컬에서 수행됩니다. MCP는 선택된 결과를 MCP 호출자에게 전달합니다. MISAMA 클라우드 모델 어댑터는 기본적으로 꺼져 있으며, 사용자가 /privacy files on을 실행한 후에만 최대 10개의 상대 경로, 이름, 유형 및 점수를 반환합니다. 절대 경로, 전체 인덱스 또는 벡터는 절대 반환하지 않습니다.

빠른 시작(소스 코드)

Node.js 24+와 Go 1.24+가 필요합니다:

npm.cmd ci
npm.cmd run model:install
go build -trimpath -o .\bin\misama-search.exe .\cmd\misama-search

.\bin\misama-search.exe scan -backend walk -index .\data\my.idx 'D:\要索引的目录'
.\bin\misama-search.exe semantic-build -index .\data\my.idx
.\bin\misama-search.exe search -index .\data\my.idx '原神角色文件夹'

모델은 약 23.3 MiB입니다. 다운로드 후 MISAMA_OFFLINE=1을 설정하면 완전히 오프라인으로 사용할 수 있습니다. MISAMA_MODEL_DIR로 사용자 지정 또는 휴대용 모델 디렉터리를 지정할 수 있습니다. npm.cmd run model:verify는 네 개의 모델 파일의 고정 SHA-256을 검증합니다.

자동 업데이트 및 상주 서비스

.\bin\misama-search.exe refresh -index .\data\my.idx
.\bin\misama-search.exe watch -index .\data\my.idx
.\bin\misama-search.exe serve -index .\data\my.idx -addr 127.0.0.1:37421

HTTP 검색: POST /v1/search, JSON은 {"query":"获奖经历","limit":5,"semantic":true}입니다. 서비스는 루프백이 아닌 주소로의 바인딩을 거부합니다.

MCP

MCP 클라이언트 시작 명령:

node D:\路径\MISAMA-Search\semantic\mcp-server.mjs

환경 변수: MISAMA_SEARCH_INDEX, MISAMA_SEARCH_EXE. 상주 서비스에 연결하는 경우 MISAMA_SEARCH_URL과 선택적 MISAMA_SEARCH_TOKEN도 설정합니다. Tool 이름은 semantic_file_search입니다.

선택적 MFT 서비스

일반 작업 공간에서는 서비스 없이 walk + watch를 바로 사용합니다. 전체 NTFS 볼륨을 고속으로 인덱싱해야 하는 경우에만 관리자 터미널에서 실행합니다:

.\bin\misama-search.exe mft-service install -index 'D:\MISAMA-Data\whole-d.idx' 'D:\'
.\bin\misama-search.exe mft-service start
.\bin\misama-search.exe mft-service status
.\bin\misama-search.exe mft-service stop
.\bin\misama-search.exe mft-service uninstall

서비스 이름은 MISAMASearchMFT입니다. 이 서비스는 파일 이름 메타데이터 스캔과 인덱스 새로고침만 수행하며, 클라우드 모델, MCP 또는 Agent를 실행하지 않습니다.

설치, 업그레이드 및 제거

릴리스 압축 패키지에서 압축을 푼 후:

powershell -ExecutionPolicy Bypass -File .\scripts\install.ps1 -InstallDir 'D:\Apps\MISAMA Search' -DataDir 'D:\MISAMA Search Data' -AddToPath

동일한 설치 명령을 다시 실행하면 업그레이드되며, 독립된 DataDir은 덮어쓰이지 않습니다. 제거 시 기본적으로 인덱스가 유지되며, 명시적으로 -RemoveData를 추가한 경우에만 삭제됩니다:

powershell -ExecutionPolicy Bypass -File 'D:\Apps\MISAMA Search\scripts\uninstall.ps1' -InstallDir 'D:\Apps\MISAMA Search' -DataDir 'D:\MISAMA Search Data'

검증된 사실

• 동결 중국어 시나리오 100개: Recall@5 99%, MRR 0.945;

• 백만 개의 512차원 Int8 HNSW: P95 4.82 ms, Recall@10 95.5%;

• 상주 의미 서비스 핫 쿼리: P95 4.54 ms;

• 상주 순수 이름 서비스 핫 쿼리: P95 0.252 ms;

• npm 프로덕션 의존성 감사: 취약점 0개(2026-08-20).

하드웨어, 방법 및 제한 사항은 BENCHMARKS.md를 참조하세요. 중국어 품질 데이터셋은 사람이 작성한 실제 시나리오 시뮬레이션이며, 사용자의 실제 하드 디스크 데이터가 아닙니다. 합성 백만 벡터 결과 역시 중국어 의미 품질과 동일하지 않습니다.

알려진 제한 사항

• Windows 네이티브 MFT 백엔드는 NTFS만 지원하며 관리자 권한이 필요하고, 실패 시 auto는 디렉터리 순회로 폴백합니다;

• watch는 변경 사항을 수신하면 이름 메타데이터 대조를 수행하며, 대규모 디렉터리는 이후 USN 이벤트 기반 직접 업데이트로 계속 업그레이드할 수 있습니다;

• HNSW 용량이 모두 소진되면 자동으로 전체 재구축을 수행하지만, 이중 인덱스 무중단 전환은 아직 구현되지 않았습니다;

• 최초 모델 다운로드에는 인터넷 연결이 필요하며, 오프라인 릴리스에서는 검증된 models 디렉터리를 별도로 배포할 수 있습니다.

라이선스: 프로젝트 소스 코드는 MIT입니다. 타사 구성 요소는 THIRD_PARTY_NOTICES.md를 참조하세요.