MISAMA Search 1.0

MISAMA Search is a Windows-first, fully local semantic search engine that only reads file and folder names. It does not depend on Everything and does not open file contents.

What It Can Do

• Exact names, substrings, Chinese bigram fuzzy matching, and parent-directory context ranking;

• Local semantic retrieval with BGE-small-zh-v1.5, e.g. "award experience" finds "resume";

• USearch HNSW Int8 million-scale vector index, falling back to Float32 exact search when the native module is missing;

• Stable uint64 file IDs with incremental vector updates for additions, deletions, and renames;

• watch automatically monitors subdirectory changes without requiring administrator privileges;

• serve provides a resident HTTP service that only listens on 127.0.0.1, loading the model only once;

• The MCP stdio Server and the MISAMA Agent Harness Tool share the same index;

• An optional Windows MFT service handles high-speed scanning of entire NTFS volumes; administrator privileges are only needed to install the service and read raw volumes.

Related MCP server: ragi

Privacy Boundary

The index contains names, paths, types, and local vectors, but not file contents. Scanning, embedding, and ranking are all performed on the local machine. MCP hands selected results to the MCP caller; the MISAMA cloud model adapter is off by default, and only after the user runs /privacy files on does it return at most 10 relative paths, names, types, and scores—never absolute paths, the full index, or vectors.

Quick Start (Source)

Requires Node.js 24+ and 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 '原神角色文件夹'

The model is about 23.3 MiB. After downloading, you can set MISAMA_OFFLINE=1 to work fully offline; MISAMA_MODEL_DIR can point to a custom or portable model directory. npm.cmd run model:verify validates the fixed SHA-256 of the four model files.

Auto-Update and Resident Service

.\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 search: POST /v1/search with JSON {"query":"award experience","limit":5,"semantic":true}. The service refuses to bind to non-loopback addresses.

MCP

MCP client launch command:

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

Environment variables: MISAMA_SEARCH_INDEX, MISAMA_SEARCH_EXE; if connecting to a resident service, also set MISAMA_SEARCH_URL and optional MISAMA_SEARCH_TOKEN. The tool name is semantic_file_search.

Optional MFT Service

For ordinary workspaces, use walk + watch directly—no service needed. Only when building a high-speed index over an entire NTFS volume, run in an administrator terminal:

.\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

The service name is MISAMASearchMFT. It only performs file-name metadata scanning and index refresh; it does not run cloud models, MCP, or Agent.

Install, Upgrade, and Uninstall

After extracting from the release archive:

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

Running the same install command again upgrades; the separate DataDir is not overwritten. Uninstall keeps the index by default; only an explicit -RemoveData deletes it:

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

Verified Facts

• 100 frozen Chinese scenarios: Recall@5 99%, MRR 0.945;

• Million-scale 512-dim Int8 HNSW: P95 4.82 ms, Recall@10 95.5%;

• Resident semantic service hot query: P95 4.54 ms;

• Resident name-only service hot query: P95 0.252 ms;

• npm production dependency audit: 0 vulnerabilities (2026-08-20).

Hardware, methodology, and limitations are in BENCHMARKS.md. The Chinese quality set is a hand-written simulation of real-world scenarios, not actual user hard-drive data; the synthetic million-vector results also do not equal Chinese semantic quality.

Known Limitations

• The Windows native MFT backend only supports NTFS and requires administrator privileges; on failure, auto falls back to directory traversal;

• watch performs name-metadata reconciliation after changes; large directories can later be upgraded to update directly from USN events;

• When HNSW capacity is exhausted, a full rebuild happens automatically; dual-index zero-downtime switching is not yet implemented;

• The first model download requires network access; offline releases can distribute the verified models directory separately.

License: project source is MIT. Third-party components are listed in THIRD_PARTY_NOTICES.md.