MISAMA Search 1.0

MISAMA Search ist ein Windows-orientierter, vollständig lokaler semantischer Sucher, der nur Datei- und Ordnernamen liest. Er ist nicht auf Everything angewiesen und öffnet keine Dateiinhalte.

Was es kann

• Exakte Namen, Teilzeichenfolgen, Fuzzy-Matching mit chinesischen Bigrammen und Sortierung nach übergeordnetem Verzeichniskontext;

• Lokale semantische Suche mit BGE-small-zh-v1.5, z. B. findet „Auszeichnungserfahrung“ den „Lebenslauf“;

• USearch HNSW Int8-Vektorindex für Millionen von Einträgen, mit Fallback auf exakte Float32-Suche, wenn das native Modul fehlt;

• Stabile uint64-Datei-IDs, inkrementelle Vektoraktualisierungen bei Hinzufügen, Löschen und Umbenennen;

• watch überwacht automatisch Unterverzeichnisänderungen, ohne Administratorrechte;

• serve bietet einen residenten HTTP-Dienst, der nur auf 127.0.0.1 lauscht, das Modell wird nur einmal geladen;

• MCP stdio Server und MISAMA Agent Harness Tool teilen sich denselben Index;

• Optionaler Windows-MFT-Dienst für schnelles Scannen ganzer NTFS-Volumes; Administratorrechte sind nur für die Installation des Dienstes und das Lesen des Rohvolumes erforderlich.

Related MCP server: ragi

Datenschutzgrenzen

Der Index enthält Namen, Pfade, Typen und lokale Vektoren, nicht aber den Dateiinhalt. Scannen, Einbetten und Sortieren erfolgen vollständig lokal. MCP übergibt die ausgewählten Ergebnisse an den MCP-Aufrufer; der MISAMA-Cloud-Modelladapter ist standardmäßig deaktiviert. Nur wenn der Benutzer /privacy files on ausführt, werden bis zu 10 relative Pfade, Namen, Typen und Bewertungen zurückgegeben; absolute Pfade, der vollständige Index oder Vektoren werden niemals zurückgegeben.

Schnellstart (Quellcode)

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

Das Modell ist etwa 23,3 MiB groß. Nach dem Download kann MISAMA_OFFLINE=1 für vollständigen Offline-Betrieb gesetzt werden; MISAMA_MODEL_DIR kann ein benutzerdefiniertes oder tragbares Modellverzeichnis angeben. npm.cmd run model:verify überprüft die festen SHA-256-Hashes der vier Modelldateien.

Automatische Updates und residenter Dienst

.\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-Suche: POST /v1/search, JSON ist {"query":"获奖经历","limit":5,"semantic":true}. Der Dienst lehnt die Bindung an Nicht-Loopback-Adressen ab.

MCP

MCP-Client-Startbefehl:

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

Umgebungsvariablen: MISAMA_SEARCH_INDEX, MISAMA_SEARCH_EXE; wenn eine Verbindung zum residenten Dienst hergestellt wird, zusätzlich MISAMA_SEARCH_URL und optional MISAMA_SEARCH_TOKEN. Der Tool-Name ist semantic_file_search.

Optionaler MFT-Dienst

Normale Arbeitsbereiche verwenden direkt walk + watch, ohne Dienst. Nur für das schnelle Indizieren ganzer NTFS-Volumes wird in einem Administrator-Terminal ausgeführt:

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

Der Dienstname ist MISAMASearchMFT. Er führt nur Dateinamen-Metadatenscans und Indexaktualisierungen durch; er führt keine Cloud-Modelle, MCP oder Agenten aus.

Installation, Upgrade und Deinstallation

Nach dem Entpacken des Release-Archivs:

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

Das erneute Ausführen desselben Installationsbefehls führt ein Upgrade durch; das unabhängige DataDir wird nicht überschrieben. Die Deinstallation behält den Index standardmäßig; nur mit explizitem -RemoveData wird er gelöscht:

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

Getestete Fakten

• 100 eingefrorene chinesische Szenarien: Recall@5 99 %, MRR 0,945;

• Millionen 512-dimensionale Int8-HNSW: P95 4,82 ms, Recall@10 95,5 %;

• Residenter semantischer Dienst, heiße Abfragen: P95 4,54 ms;

• Residenter reiner Namensdienst, heiße Abfragen: P95 0,252 ms;

• npm-Produktionsabhängigkeits-Audit: 0 Schwachstellen (2026-08-20).

Hardware, Methoden und Einschränkungen finden Sie in BENCHMARKS.md. Der chinesische Qualitätsdatensatz ist eine manuell erstellte Simulation realistischer Szenarien, keine echten Benutzerdaten; synthetische Millionen-Vektor-Ergebnisse entsprechen auch nicht der chinesischen semantischen Qualität.

Bekannte Einschränkungen

• Das native Windows-MFT-Backend unterstützt nur NTFS und erfordert Administratorrechte; bei Fehlern fällt auto auf Verzeichnisdurchlauf zurück;

• watch führt nach Änderungen einen Abgleich der Namensmetadaten durch; große Verzeichnisse können später auf direkte Aktualisierung über USN-Ereignisse erweitert werden;

• Wenn die HNSW-Kapazität erschöpft ist, wird automatisch ein vollständiger Neuaufbau durchgeführt; ein unterbrechungsfreier Wechsel mit doppeltem Index ist noch nicht implementiert;

• Der erste Modelldownload erfordert eine Internetverbindung; für Offline-Veröffentlichungen kann das verifizierte models-Verzeichnis separat verteilt werden.

Lizenz: Projektquellcode MIT. Drittanbieterkomponenten siehe THIRD_PARTY_NOTICES.md.