obsidian-kb 2.0.7.1
Local knowledge base for Obsidian vaults with vector search via MCP (Model Context Protocol)
License: MIT
Requires Python: >=3.12
Keywords: claude, embeddings, knowledge-base, lancedb, mcp, obsidian, ollama, semantic-search, vector-search

# obsidian-kb

[![PyPI version](https://badge.fury.io/py/obsidian-kb.svg)](https://badge.fury.io/py/obsidian-kb)
[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Tests](https://img.shields.io/badge/tests-1026%20passed-brightgreen.svg)](https://github.com/mdemyanov/obsidian-kb)
[![Status](https://img.shields.io/badge/status-production--ready-brightgreen.svg)](https://github.com/mdemyanov/obsidian-kb)

MCP-сервер для семантического поиска по Obsidian vault'ам. Используется с Claude Desktop, Cursor и другими агентами через Model Context Protocol.

## Что это

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

**Версия:** 1.0.1 (ConfigManager Singleton Hotfix)
**Статус:** ✅ 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. Установка

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

# Установите obsidian-kb
uv pip install obsidian-kb
```

**Требования:**
- Python 3.12+
- Один из провайдеров:
  - **Ollama** (локальный) с моделью `nomic-embed-text` (см. [INSTALLATION.md](INSTALLATION.md))
  - **Yandex Cloud** с API-ключом или IAM-токеном (см. [PROVIDERS.md](PROVIDERS.md))

### 2. Настройка

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

# Проиндексируйте vault
obsidian-kb index-all
```

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

```bash
# Примените конфигурацию автоматически
obsidian-kb claude-config --apply

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

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

> **Подробнее:** См. [QUICK_START.md](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

```bash
# Поиск
obsidian-kb search --vault "my-vault" --query "Python async"

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

# Статистика
obsidian-kb stats --vault "my-vault"

# Диагностика
obsidian-kb doctor
```

> **Подробнее:** См. [EXAMPLES.md](EXAMPLES.md) для примеров использования и [USAGE.md](USAGE.md) для полного руководства

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

### Основная документация
- [QUICK_START.md](QUICK_START.md) — быстрый старт для новых пользователей
- [INSTALLATION.md](INSTALLATION.md) — установка и настройка
- [CONFIGURATION.md](CONFIGURATION.md) — конфигурация и настройки
- [USAGE.md](USAGE.md) — использование CLI и MCP инструментов
- [EXAMPLES.md](EXAMPLES.md) — примеры использования MCP tools и CLI команд

### Интеграция и использование
- [MCP_INTEGRATION.md](MCP_INTEGRATION.md) — интеграция с агентами (с примерами)
- [PROVIDERS.md](PROVIDERS.md) — детальное описание провайдеров (Ollama, Yandex)
- [INDEXING.md](INDEXING.md) — детальное описание процесса индексации

### Оптимизация и лучшие практики
- [BEST_PRACTICES.md](BEST_PRACTICES.md) — рекомендации по эффективной работе
- [SEARCH_OPTIMIZATION.md](SEARCH_OPTIMIZATION.md) — оптимизация поиска
- [ADVANCED_SEARCH.md](ADVANCED_SEARCH.md) — расширенные возможности поиска

### Архитектура и разработка
- [ARCHITECTURE.md](ARCHITECTURE.md) — архитектура проекта
- [API_DOCUMENTATION.md](API_DOCUMENTATION.md) — документация API
- [DEVELOPER_GUIDE.md](DEVELOPER_GUIDE.md) — руководство для разработчиков
- [DATABASE_SCHEMA.md](DATABASE_SCHEMA.md) — схема базы данных

### Помощь и поддержка
- [FAQ.md](FAQ.md) — часто задаваемые вопросы
- [TROUBLESHOOTING.md](TROUBLESHOOTING.md) — решение проблем
- [CONTRIBUTING.md](CONTRIBUTING.md) — руководство по внесению вклада

## Архитектура

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

```
src/obsidian_kb/
├── 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

> **Подробнее:** См. [ARCHITECTURE.md](ARCHITECTURE.md) для детального описания архитектуры

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

**Версия:** 1.0.1 (ConfigManager Singleton Hotfix)
**Тесты:** 1026+ unit/integration тестов (все проходят)
**Покрытие:** ≥85% для критических модулей
**Статус:** ✅ Production-ready

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

- **PyPI (Production):** [![PyPI version](https://badge.fury.io/py/obsidian-kb.svg)](https://pypi.org/project/obsidian-kb/)
- **GitHub Releases:** [Последний релиз](https://github.com/mdemyanov/obsidian-kb/releases/latest)

### Основные изменения v1.0.1

- 🐛 **ConfigManager Singleton** — исправлена проблема с кэшированием конфигурации
- 📋 **Реестр моделей Yandex** — строгий список моделей с валидацией
- 🆕 **`list_yandex_models()`** — новый MCP инструмент для просмотра доступных моделей
- ✅ **Валидация моделей** — `set_provider` проверяет модель перед установкой

> **Подробнее:** См. [CHANGELOG.md](CHANGELOG.md) для полного списка изменений

## Лицензия

MIT