Семантический поиск

Семантический поиск по файлам markdown. Находите связанные заметки по смыслу, а не просто по ключевым словам. Обнаруживайте дубликаты перед созданием новых заметок.

Поддерживает два серверных транспорта:

• stdio MCP — для интеграции с Claude Code (один процесс на сессию)

• HTTP — комбинированный MCP-over-HTTP + REST на одном порту; один «разогретый» процесс, общий для всех клиентов

Возможности

• Семантический поиск с использованием sentence-transformers

• Обнаружение дубликатов/похожих заметок

• Автоматическое обновление индекса с помощью отслеживания файлов

• Поддержка нескольких директорий

• Извлечение встроенных тегов (#tag-name)

Установка

Установка только для CPU — рекомендуется для macOS (любой Mac, Apple Silicon или Intel) и Linux/Windows без видеокарты NVIDIA. Экономит ~5 ГБ бинарных файлов CUDA. На macOS графический процессор Apple (MPS) по-прежнему автоматически обнаруживается и используется через встроенный бэкенд MPS в PyTorch — метка «CPU» относится только к отсутствию CUDA, а не к вычислительному устройству во время выполнения.

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

Установка CUDA — только для Linux/Windows с выделенной видеокартой NVIDIA. Не применимо к macOS (NVIDIA CUDA не поддерживается на Mac).

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

Обновление

uv tool upgrade semantic-search

Режимы сервера

stdio MCP (Claude Code для каждой сессии)

Запускает один процесс на каждую сессию Claude Code. Просто, но каждая сессия загружает свою копию модели объемом ~400 МБ–1 ГБ.

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

Доступные инструменты:

• search_related(query, top_k=5) — поиск семантически связанных заметок

• check_duplicates(file_path) — обнаружение дубликатов/похожих заметок

HTTP (общий для всех клиентов)

Один долгоживущий процесс обслуживает MCP-over-HTTP по адресу /mcp плюс REST по адресам /search, /duplicates, /health, /reindex. Все сессии Claude Code и REST-клиенты используют один общий «разогретый» индекс.

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

Укажите его в конфигурации MCP для Claude Code:

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

REST-эндпоинты:

Примеры запросов:

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

Запуск в фоновом режиме

Для использования в продакшене запустите semantic-search-http как фоновую службу, чтобы каждая сессия Claude Code (и любой REST-клиент) использовали один «разогретый» процесс.

Краткий пример (macOS):

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

Краткий пример (Linux):

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

CLI-команды

Разовые команды без запуска сервера:

# 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

Бинарные файлы

Конфигурация

Переменные окружения

Несколько директорий

Индексируйте несколько директорий, разделив пути запятыми:

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

Все директории индексируются вместе и ищутся как единый индекс.

Как это работает

При первом запуске загружается небольшая модель эмбеддингов (~90 МБ) и индексируются ваши markdown-файлы (<1 с для типичных хранилищ). Индекс автоматически обновляется при изменении файлов через отслеживание файловой системы.

Индексируемый контент

Каждый markdown-файл индексируется с учетом весовых коэффициентов компонентов:

Разработка

# 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

Лицензия

BSD 2-Clause License — см. LICENSE.