Semantische Suche

Semantische Suche über Markdown-Dateien. Finden Sie verwandte Notizen nach Bedeutung, nicht nur nach Schlüsselwörtern. Erkennen Sie Duplikate, bevor Sie neue Notizen erstellen.

Unterstützt zwei Server-Transporte:

• stdio MCP — Für die Claude Code-Integration (ein Prozess pro Sitzung)

• HTTP — Kombiniertes MCP-over-HTTP + REST auf einem Port; ein warmer Prozess, der von allen Clients geteilt wird

Funktionen

• Semantische Suche mittels sentence-transformers

• Erkennung von doppelten/ähnlichen Notizen

• Automatische Aktualisierung des Index durch Dateiüberwachung

• Unterstützung für mehrere Verzeichnisse

• Inline-Tag-Extraktion (#tag-name)

Installation

CPU-only Installation — empfohlen für macOS (jeder Mac, Apple Silicon oder Intel) und Linux/Windows ohne NVIDIA GPU. Spart ca. 5 GB an CUDA-Binärdateien. Unter macOS wird die Apple GPU (MPS) weiterhin automatisch erkannt und über das integrierte MPS-Backend von PyTorch genutzt — das Label "CPU" bezieht sich nur auf das Fehlen von CUDA, nicht auf das Rechengerät zur Laufzeit.

uv tool install --index https://download.pytorch.org/whl/cpu \
  git+https://github.com/bborbe/semantic-search

CUDA Installation — nur für Linux/Windows mit einer dedizierten NVIDIA GPU. Nicht anwendbar auf macOS (NVIDIA CUDA wird auf dem Mac nicht unterstützt).

uv tool install git+https://github.com/bborbe/semantic-search

Upgrade

uv tool upgrade semantic-search

Server-Modi

stdio MCP (pro Sitzung Claude Code)

Startet einen Prozess pro Claude Code-Sitzung. Einfach, aber jede Sitzung lädt ihre eigene ~400 MB–1 GB Modellkopie.

claude mcp add -s project semantic-search \
  --env CONTENT_PATH=/path/to/vault \
  -- \
  uvx --from git+https://github.com/bborbe/semantic-search semantic-search-mcp

Verfügbare Tools:

• search_related(query, top_k=5) — Findet semantisch verwandte Notizen

• check_duplicates(file_path) — Erkennt doppelte/ähnliche Notizen

HTTP (geteilt über alle Clients)

Ein einzelner, langlebiger Prozess bedient MCP-over-HTTP unter /mcp sowie REST unter /search, /duplicates, /health, /reindex. Alle Claude Code-Sitzungen und REST-Clients teilen sich einen warmen Indexer.

CONTENT_PATH=/path/to/vault semantic-search-http --host 127.0.0.1 --port 8321

Verweisen Sie Claude Code über die MCP-Konfiguration darauf:

{
  "mcpServers": {
    "semantic-search": {
      "type": "http",
      "url": "http://127.0.0.1:8321/mcp"
    }
  }
}

REST-Endpunkte:

Beispielabfragen:

# Search
curl 'http://127.0.0.1:8321/search?q=kubernetes+deployment'

# Find duplicates
curl 'http://127.0.0.1:8321/duplicates?file=notes/my-note.md'

# Health check
curl 'http://127.0.0.1:8321/health'

Im Hintergrund ausführen

Für den produktiven Einsatz führen Sie semantic-search-http als Hintergrunddienst aus, damit jede Claude Code-Sitzung (und jeder REST-Client) einen warmen Prozess teilt.

Kurzes Beispiel (macOS):

launchctl load ~/Library/LaunchAgents/com.github.bborbe.semantic-search-http.plist

Kurzes Beispiel (Linux):

systemctl --user enable --now semantic-search-http.service

CLI-Befehle

Einmalige Befehle ohne laufenden Server:

# Search
CONTENT_PATH=/path/to/vault semantic-search search "kubernetes deployment"

# Find duplicates
CONTENT_PATH=/path/to/vault semantic-search duplicates path/to/note.md

Binärdateien

Konfiguration

Umgebungsvariablen

Mehrere Verzeichnisse

Indexieren Sie mehrere Verzeichnisse, indem Sie die Pfade durch Kommas trennen:

CONTENT_PATH=/path/to/vault1,/path/to/vault2,/path/to/docs

Alle Verzeichnisse werden zusammen indexiert und als ein einheitlicher Index durchsucht.

Funktionsweise

Der erste Durchlauf lädt ein kleines Embedding-Modell (~90 MB) herunter und indexiert Ihre Markdown-Dateien (<1s für typische Vaults). Der Index aktualisiert sich automatisch, wenn Dateien über den Dateisystem-Watcher geändert werden.

Indexierte Inhalte

Jede Markdown-Datei wird mit gewichteten Komponenten indexiert:

Entwicklung

# Clone
git clone https://github.com/bborbe/semantic-search
cd semantic-search

# Install dev dependencies
make install

# Run checks
make check

# Run tests
make test

Lizenz

BSD 2-Clause License — siehe LICENSE.