# Второй мозг (personal-kb-agent)

> Собирайте, Strukturujte и используйте знания из Telegram и YouTube — вместе со своим ИИ-агентом.

[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-green.svg)](https://python.org)
[![Obsidian](https://img.shields.io/badge/Obsidian-compatible-blueviolet)](https://obsidian.md)
[![MCP Ready](https://img.shields.io/badge/MCP-ready-orange)](https://modelcontextprotocol.io)

---

## 🎯 Что это и зачем нужно

### Проблема, которую решает kb-agent

Ежедневно получаете поток полезной информации из Telegram-каналов, YouTube, сайтов и своих файлов. Часть материалов теряется, часть забывается, а связей между разными источниками почти не остаётся. Чтобы найти нужную мысль, приходится перечитывать десятки постов вручную.

**kb-agent** решает эту проблему: он автоматически собирает материалы из выбранных вами источников, суммаризирует их через LLM и сохраняет структурированные заметки в ваш Obsidian vault. Все заметки связаны между собой, проиндексированы и доступны для поиска — как вам, так и любому ИИ-агенту (Cursor, Claude Code, Hermes, OpenCode и др.).

### JTBD (Задачи, которые решает пользователь)

| Как раньше | С kb-agent |
|------------|------------|
| Вручную перечитывать каналы и видео, чтобы не упустить полезное | Автоматический сбор новых постов и видео по расписанию (cron) |
| Записывать важные мысли в разные файлы, теряя связь между ними | Структурированные заметки со связями (`[[ссылки]]`) и тематической организацией |
| Долго искать, где именно вы читали про какую-то тему | Поиск по всей базе знаний за секунды (FTS5) |
| Забывать, какие инсайты вы уже открывали | Автоматические инсайты — повторяющиеся темы, противоречия, скрытые зависимости |
| Не знать, с чего начать формирование базы знаний | Вводное интервью — agent помогает определить цели, темы и источники |

---

## 💡 Что вы получаете

### Для человека (пользователя Obsidian / KB)

| Выгода | Как это работает |
|--------|------------------|
| **Ничего не теряется** | Каждый пост и видео попадает в очередь → суммаризация → заметка в vault |
| **Видеть связи между источниками** | Заметки получают теги, темы и `[[ссылки]]` на связанные материалы |
| **Быстро находить нужное** | Полнотекстовый поиск (FTS5) по всем заметкам + команда `kb-agent ask` |
| **Получать инсайты без усилий** | Agent находит повторяющиеся темы, конфликты и скрытые закономерности |
| **Управлять потоком информации** | Добавляйте/удаляйте источники одной командой, без правки кода |
| **Контроль качества** | Оцените каждую заметку (1–5), agent подстроится под ваши предпочтения |

### Для ИИ-агентов (Cursor, Claude Code, Hermes, OpenCode, Kimi Claw и др.)

| Выгода | Как это работает |
|--------|------------------|
| **Чтение вашей базы знаний** | MCP-сервер `kb-agent mcp-serve` даёт инструменты `kb_search`, `kb_get_note`, `kb_get_insights` |
| **Поиск по вашим заметкам** | FTS5-поиск через `kb_search <запрос>` |
| **Получение инсайтов** | `kb_get_insights` возвращает связи и повторяющиеся темы |
| **Настройка без кода** | `kb-agent confirm <id>` для добавления/удаления источников через подтверждение человека |

---

## 🚀 Быстрый старт

### 1. Установка

```bash
# Клонируйте репозиторий
git clone https://github.com/DenisZakharov2/personal-kb-agent.git
cd personal-kb-agent

# Установите зависимости
pip install -e .

# Проверьте установку
kb-agent --version
```

### 2. Настройка (.env)

```bash
cp .env.example .env
# Отредактируйте .env — укажите путь к vault, каналы, ключ LLM
```

| Переменная | Что указать | Пример |
|------------|-------------|--------|
| `KB_VAULT_PATH` | Путь к вашему Obsidian vault | `/home/user/Documents/KB` |
| `KB_TELEGRAM_CHANNELS` | Каналы Telegram через запятую | `ragnarokzone,paragonzone,rubiconzone` |
| `KB_YOUTUBE_CHANNELS` | YouTube каналы (полные URL) | `https://youtube.com/@amorev,https://youtube.com/@rubiconzone` |
| `KB_LLM_PROVIDER` | Провайдер LLM | `openai`, `kimi`, `ollama`, `openrouter` |
| `KB_OPENAI_API_KEY` | Ваш API-ключ | `sk-...` |
| `KB_OPENAI_BASE_URL` | URL API провайдера | `https://api.openai.com/v1` |

### 3. Первое интервью (обязательно перед стартом)

```bash
kb-agent interview init
```

Агент задаст несколько вопросов о целях, темах, источниках и частоте сбора — и создаст ваш `user_profile.yaml`.

### 4. Запуск конвейера

```bash
# Собрать материалы из всех источников и суммаризировать в vault
kb-agent process run

# Или получить дайджест запуска
kb-agent process digest
```

### 5. Работа с базой знаний

```bash
# Задать вопрос и получить ответ со ссылками на заметки
kb-agent ask "Что я накопил по теме ИИ-агентов?"

# Поиск заметок (список)
kb-agent search "автоматизация n8n"

# Инсайты — повторяющиеся темы и связи
kb-agent insights

# Проверка на дубликаты
kb-agent update check
```

### 6. Управление источниками

```bash
# Список всех источников
kb-agent sources list

# Добавить канал Telegram
kb-agent sources add telegram https://t.me/s/novyikanal

# Добавить YouTube канал
kb-agent sources add youtube https://youtube.com/@novyykanal

# Включить/выключить источник
kb-agent sources enable tg_ragnarokzone
kb-agent sources disable yt_staryykanal

# Удалить источник
kb-agent sources remove tg_staryykanal
```

> ⚠️ Все изменения источников проходят через stages «pending → confirm» — вам нужно подтвердить применение через `kb-agent confirm <id>`.

### 7. MCP-сервер для AI-агентов

```bash
# Запустить сервер (один раз, в терминале или как сервис)
kb-agent mcp-serve
```

Подключите в вашем AI-агенте (например, в `.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "kb-agent": {
      "command": "kb-agent",
      "args": ["mcp-serve"]
    }
  }
}
```

Теперь ваш агент может:
- Искать по вашим заметкам: `kb_search("ИИ-агенты")`
- Читать содержимое заметки: `kb_get_note("note_id")`
- Получать инсайты: `kb_get_insights()`

---

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

```
┌─────────────────────────────────────────────────────────┐
│                       ЧЕЛОВЕК                            │
│  Цели • Вопросы • Обратная связь • Управление источниками │
└──────────────────────┬───────────────────────────────────┘
                       │ CLI / MCP
┌──────────────────────▼───────────────────────────────────┐
│                    kb-agent CLI / MCP                     │
│  ask • search • insights • sources • process • feedback   │
│  self-improve • interview • mcp-serve                     │
└──────────────────────┬───────────────────────────────────┘
                       │
┌──────────────────────▼───────────────────────────────────┐
│              Конвейер (Pipeline)                          │
│  Сбор → Relevance Gate → LLM суммаризация → Vault        │
└──────────────────────┬───────────────────────────────────┘
                       │
    ┌──────────────────┼──────────────────┐
    ▼                  ▼                  ▼
 raw_queue        notes_fts (FTS5)   note_links
 (SQLite)         (полнотекстовый     (связи между
                  поиск)              заметками)
```

**Стек:** Python 3.10+, SQLite + FTS5, Pydantic v2, Typer, Rich, httpx, MCP, PyYAML.

---

## 📋 Возможности по этапам

| Этап | Что сделано | Статус |
|------|-------------|--------|
| **Этап 1** | Основа, интервью, импорт ядра, SQLite схема | ✅ |
| **Этап 2** | Надёжный конвейер наполнения (сбор + суммаризация + vault) | ✅ |
| **Этап 3** | Поиск, ответы, дубликаты, инсайты | ✅ |
| **Этап 4** | MCP-сервер, `--json` для CLI, управление источниками | ✅ |
| **Этап 5** | Обратная связь, самоулучшение, ежемесячное интервью | ✅ |

---

## 🔄 Как конвейер работает под капотом

1. **Сбор** — novos посты из Telegram и видео из YouTube попадают в `raw_queue`
2. **Relevance Gate** — материал проверяется на соответствие вашим целям и темам из профиля
3. **Суммаризация** — LLM restructures сырый текст в структурированную заметку (суть, идеи, инструменты, выводы, теги)
4. **Запись** — заметка сохраняется в тематическую папку vault с YAML frontmatter и `[[ссылками]]`
5. **Индексация** — заметка добавляется в FTS5-индекс для поиска
6. **Каталог** — `Каталог.md` пересобирается автоматически
7. **Дайджест** — `Дайджест.md` в vault со статистикой запуска

---

## 🔐 Безопасность и приватность

- **Все данные остаются локально** — notes, база состояния, профиль хранятся на вашем компьютере
- **Исходный текст изолируется от системных инструкций** LLM — защита от промпт-инъекций
- **MCP-сервер read-only** в первой версии — агенты могут только читать, не менять конфигурацию
- **Подтверждение человека** требуется для любых изменений источников (add/remove/enable/disable)

---

## 📊 Обратная связь и самоулучшение

```bash
# Оценить заметку (1–5)
kb-agent feedback rate <note_id> 5 --comment "Отличная суммаризация"

# Оставить произвольное сообщение
kb-agent feedback tell "Нужно больше примеров кода"

# Посмотреть метрики качества
kb-agent feedback metrics

# Посмотреть предложения по улучшению промптов
kb-agent self-improve
```

Agent собирает ваши оценки, считает среднюю оценку и предлагает улучшения промптов — но применяет их только с вашего подтверждения.

---

## 🤝 Участие в развитии

Проект развивается открыто. Вы можете:

- Сообщать о багах и предлагать функции через GitHub Issues
- Присылать Pull Requests с улучшениями
- Добавлять новые источники (наследуйте `BaseSource` из `kb_agent/sources/base.py`)

Все изменения в коде — под лицензией MIT.

---

## 📄 Лицензия

MIT — см. [`LICENSE`](LICENSE).

---

## 🔗 Связанные проекты

- [Obsidian](https://obsidian.md) — хранилище заметок (vault)
- [Model Context Protocol (MCP)](https://modelcontextprotocol.io) — стандарт для AI-агентов
- [yt-dlp](https://github.com/yt-dlp/yt-dlp) — сбор YouTube метаданных и субтитров

---

*Сделано с ❤️ для осознанного управления знаниями. Если вам помог этот проект — поставьте ⭐️ и поделитесь с коллегами.*