aigrep

AI-powered semantic search for markdown files and knowledge bases via MCP (Model Context Protocol).

Что это

aigrep — это умный grep с AI. Индексирует ваши markdown-файлы (Obsidian, заметки, документацию) и предоставляет быстрый семантический поиск через MCP. Агенты (Claude, Cursor) могут искать информацию в ваших vault'ах и использовать её для ответов.

Версия: 2.0.9 Статус: ✅ Production-ready

Основные возможности

🔍 Поиск

• 🎯 Adaptive Search v5: Автоматическое определение intent и выбор оптимальной стратегии поиска
• 📊 Document-level и chunk-level поиск с автоматическим выбором
• 🔍 Семантический поиск (векторный, полнотекстовый, гибридный)
• 🏷️ Расширенные фильтры (теги, даты, типы документов, связанные заметки)
• 🎨 Оптимизация для агентов (нормализация запросов, кэширование, re-ranking)
• ✨ Улучшенный UX результатов (группировка по файлам, дедупликация, метки релевантности)

📦 Индексация

• 🤖 Автоматическое индексирование и отслеживание изменений
• 🔄 Инкрементальная индексация (только изменённые файлы)
• 🎨 Markdown-aware chunking с поддержкой структуры документов
• ✨ LLM-обогащение для улучшения качества поиска (context prefix, document summary)
• 📊 Фоновая индексация через job queue
• 💾 Кэширование embeddings для ускорения повторной индексации

🔌 Multi-Provider Support

• 🏠 Ollama (локальный) — embeddings и chat completion
• ☁️ Yandex Cloud — YandexGPT (SDK/gRPC) и OpenAI-compatible модели (HTTP)
• 🔄 Унифицированное переключение провайдеров для embedding/chat/enrichment
• ⚡ Адаптивный rate limiting с автоматическим backoff
• 💰 Отслеживание стоимости использования

🛠️ Управление

• 📊 Мониторинг прогресса индексации
• 💰 Отчёты о затратах на LLM
• 📈 Метрики производительности и качества
• 🔍 Аудит индекса и покрытия
• 🧪 Тестирование качества поиска

Быстрый старт

1. Установка

# Установите uv (если не установлен)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Установите aigrep
uv pip install aigrep

Требования:

• Python 3.12+
• Один из провайдеров:
  • Ollama (локальный) с моделью mxbai-embed-large (см. INSTALLATION.md)
  • Yandex Cloud с API-ключом или IAM-токеном (см. docs/configuration/providers.md)

2. Настройка

# Добавьте vault в конфигурацию
uv run aigrep config add-vault --name "my-vault" --path "/path/to/vault"

# Проиндексируйте vault
uv run aigrep index-all

3. Интеграция с Claude Desktop

# Примените конфигурацию автоматически
uv run aigrep claude-config --apply

# Перезапустите Claude Desktop

После этого агент сможет использовать инструменты search_vault и search_multi_vault для поиска в ваших заметках.

Подробнее: См. QUICK_START.md для пошаговой инструкции

Использование

Через агента (MCP)

После настройки Claude Desktop агент автоматически получает доступ к инструментам:

Поиск:

• search_vault("my-vault", "Python async programming") — поиск в одном vault'е
• search_multi_vault(["vault1", "vault2"], "query") — поиск по нескольким vault'ам

Управление индексацией:

• index_documents("my-vault") — индексация изменённых документов
• reindex_vault("my-vault", confirm=True) — полная переиндексация
• index_status("my-vault") — статус индексации

Управление провайдерами:

• list_providers() — список доступных провайдеров с их статусом
• list_yandex_models() — список доступных chat моделей Yandex Cloud
• set_provider("yandex", provider_type="embedding", model="text-search-doc/latest") — переключение провайдера
• set_provider("yandex", provider_type="chat", model="qwen") — отдельно для chat (поддерживает алиасы)
• test_provider("ollama") — тестирование провайдера

Анализ качества:

• index_coverage("my-vault") — анализ покрытия индекса
• test_retrieval("my-vault", queries=["query1", "query2"]) — тестирование поиска
• cost_report(days=7) — отчёт о затратах

Агент может использовать расширенные фильтры:

• search_vault("vault", "Python tags:python async") — поиск с фильтром по тегам
• search_vault("vault", "created:>2024-01-01 type:протокол") — поиск по датам и типу

Через CLI

# Поиск
uv run aigrep search --vault "my-vault" --query "Python async"

# Индексация
uv run aigrep index-all                    # Индексация всех vault'ов
uv run aigrep index --vault "my-vault"     # Индексация одного vault'а
uv run aigrep reindex --vault "my-vault"   # Переиндексация

# Статистика
uv run aigrep stats --vault "my-vault"

# Диагностика
uv run aigrep doctor

Подробнее: См. примеры и руководство

Документация

Начало работы

• QUICK_START.md — быстрый старт
• INSTALLATION.md — установка и настройка

Руководство пользователя

• Использование — CLI и MCP инструменты
• Примеры — примеры использования
• Расширенный поиск — синтаксис запросов
• Лучшие практики — рекомендации
• FAQ — часто задаваемые вопросы

Настройка

• Конфигурация — настройки
• Провайдеры — Ollama, Yandex Cloud
• Индексация — процесс индексации

Интеграция

• MCP интеграция — интеграция с агентами

Для разработчиков

• Архитектура — архитектура проекта
• API документация — API reference
• Руководство разработчика — contributing guide
• Схема БД — структура данных

Помощь

• Решение проблем — troubleshooting
• CONTRIBUTING.md — как внести вклад

Архитектура

aigrep построен на модульной архитектуре:

src/aigrep/
├── core/                  # Базовые компоненты (TTLCache, DataNormalizer, DBConnectionManager)
├── storage/
│   ├── builders/          # Построители записей (ChunkRecordBuilder, DocumentRecordBuilder)
│   └── indexing/          # Сервис индексации (IndexingService)
├── search/                # Поисковые сервисы (VectorSearchService, SearchService)
├── providers/             # LLM провайдеры (Ollama, Yandex)
├── enrichment/            # Стратегии обогащения (BaseEnrichmentStrategy)
├── mcp/tools/             # MCP инструменты (SearchVaultTool, IndexVaultTool)
└── lance_db.py            # Фасад для LanceDB (~476 строк)

Ключевые компоненты:

• Multi-Provider Support — поддержка Ollama и Yandex Cloud
• Hybrid Indexing Pipeline — markdown-aware chunking и LLM-обогащение
• VectorSearchService — векторный, полнотекстовый и гибридный поиск
• IndexingService — управление индексацией документов
• MetadataService — работа с метаданными документов
• Background Job Queue — фоновая индексация с мониторингом прогресса
• Cost Tracking — отслеживание затрат на использование LLM

Подробнее: См. docs/developer/architecture.md для детального описания архитектуры

Статус проекта

Версия: 2.0.7.1 (HOTFIX: Document Lookup Fix) Тесты: 1026+ unit/integration тестов (все проходят) Покрытие: ≥85% для критических модулей Статус: ✅ Production-ready

Версии пакетов

• PyPI (Production):
• GitHub Releases: Последний релиз

Основные изменения v2.0.7.1

• 🐛 Критическое исправление "Document not found" — исправлен баг, когда 95% результатов поиска терялось
• 💾 Dual-Write в SQLite — данные теперь записываются параллельно в LanceDB и SQLite
• ✅ Consistency Check — проверка согласованности данных между SQLite и LanceDB
• 🔄 Миграция данных — скрипт для исправления пустых created_at полей

Подробнее: См. CHANGELOG.md для полного списка изменений

Лицензия

MIT