Búsqueda Semántica

Búsqueda semántica sobre archivos markdown. Encuentra notas relacionadas por significado, no solo por palabras clave. Detecta duplicados antes de crear nuevas notas.

Admite dos transportes de servidor:

• stdio MCP — Para integración con Claude Code (un proceso por sesión)

• HTTP — MCP-sobre-HTTP + REST combinados en un puerto; un proceso activo compartido por todos los clientes

Características

• Búsqueda semántica usando sentence-transformers

• Detección de notas duplicadas/similares

• Índice de actualización automática con monitor de archivos

• Soporte para múltiples directorios

• Extracción de etiquetas en línea (#tag-name)

Instalación

Instalación solo CPU — recomendado para macOS (cualquier Mac, Apple Silicon o Intel) y Linux/Windows sin una GPU NVIDIA. Ahorra ~5GB de binarios CUDA. En macOS, la GPU de Apple (MPS) se detecta y utiliza automáticamente a través del backend MPS integrado de PyTorch; la etiqueta "CPU" se refiere solo a la ausencia de CUDA, no al dispositivo de cómputo en tiempo de ejecución.

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

Instalación CUDA — solo para Linux/Windows con una GPU NVIDIA dedicada. No aplicable a macOS (NVIDIA CUDA no es compatible en Mac).

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

Actualización

uv tool upgrade semantic-search

Modos de Servidor

stdio MCP (Claude Code por sesión)

Genera un proceso por sesión de Claude Code. Es simple, pero cada sesión carga su propia copia del modelo de ~400 MB–1 GB.

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

Herramientas disponibles:

• search_related(query, top_k=5) — Encuentra notas semánticamente relacionadas

• check_duplicates(file_path) — Detecta notas duplicadas/similares

HTTP (compartido entre todos los clientes)

Un único proceso de larga ejecución sirve MCP-sobre-HTTP en /mcp además de REST en /search, /duplicates, /health, /reindex. Todas las sesiones de Claude Code y clientes REST comparten un indexador activo.

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

Configura Claude Code apuntando a él mediante la configuración de MCP:

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

Endpoints REST:

Ejemplos de consultas:

# 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'

Ejecutar en segundo plano

Para un uso en producción, ejecuta semantic-search-http como un servicio en segundo plano para que cada sesión de Claude Code (y cualquier cliente REST) comparta un proceso activo.

Ejemplo rápido (macOS):

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

Ejemplo rápido (Linux):

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

Comandos CLI

Comandos de ejecución única sin necesidad de ejecutar un servidor:

# 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

Binarios

Configuración

Variables de entorno

Múltiples directorios

Indexa múltiples directorios separando las rutas con comas:

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

Todos los directorios se indexan juntos y se buscan como un índice unificado.

Cómo funciona

La primera ejecución descarga un pequeño modelo de incrustación (~90MB) e indexa tus archivos markdown (<1s para bóvedas típicas). El índice se actualiza automáticamente cuando los archivos cambian mediante un monitor del sistema de archivos.

Contenido indexado

Cada archivo markdown se indexa con componentes ponderados:

Desarrollo

# 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

Licencia

Licencia BSD 2-Clause — ver LICENSE.