Búsqueda Semántica

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

Admite dos modos de servidor:

• Modo MCP — Para integración con Claude Code

• Modo REST — Para OpenClaw, scripts y clientes HTTP

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

Solo CPU (recomendado — ahorra ~5GB, rendimiento idéntico para tamaños de bóveda típicos):

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

Con CUDA (solo si tienes una GPU dedicada):

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

Actualización

uv tool upgrade semantic-search

Modos de Servidor

Modo MCP (para 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

Herramientas disponibles:

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

• check_duplicates(file_path) — Detecta notas duplicadas/similares

Modo REST (para OpenClaw/HTTP)

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

Endpoints:

Consultas de ejemplo:

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

Comandos CLI

Comandos de ejecución única sin 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

Dos 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 el 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.