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-Modi:

• MCP-Modus — Für die Integration in Claude Code

• REST-Modus — Für OpenClaw, Skripte und HTTP-Clients

Funktionen

• Semantische Suche mittels sentence-transformers

• Erkennung von doppelten/ähnlichen Notizen

• Automatische Aktualisierung des Index durch Dateiüberwachung

• Unterstützung für mehrere Verzeichnisse

• Extraktion von Inline-Tags (#tag-name)

Installation

Nur CPU (empfohlen — spart ca. 5 GB, identische Leistung bei typischen Vault-Größen):

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

Mit CUDA (nur wenn Sie eine dedizierte GPU haben):

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

Upgrade

uv tool upgrade semantic-search

Server-Modi

MCP-Modus (für Claude Code)

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 serve

Verfügbare Tools:

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

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

REST-Modus (für OpenClaw/HTTP)

CONTENT_PATH=/path/to/vault semantic-search-mcp serve --mode rest --port 8321

Endpunkte:

Beispielabfragen:

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

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

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

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

Zwei Binärdateien

Konfiguration

Umgebungsvariablen

Mehrere Verzeichnisse

Indizieren 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 indiziert und als ein einheitlicher Index durchsucht.

Funktionsweise

Der erste Durchlauf lädt ein kleines Embedding-Modell (~90 MB) herunter und indiziert Ihre Markdown-Dateien (<1s bei typischen Vaults). Der Index aktualisiert sich automatisch, wenn Dateien über die Dateisystemüberwachung geändert werden.

Indizierter Inhalt

Jede Markdown-Datei wird mit gewichteten Komponenten indiziert:

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.