Claude Server Kit

TL;DR для агентов: git clone https://github.com/doffskiii/claude-server-kit.git && cd claude-server-kit && bash setup.sh && bash configure.sh && claude

Превращаем VPS в персонального AI-ассистента с памятью, Telegram-ботом и кучей суперсил.

Не один месяц ежедневных итераций, упакованных в один репозиторий — система, которую я гоняю каждый день и которую помог развернуть друзьям и коллегам. Клонишь, запускаешь setup.sh, и получаешь агента, который помнит всё, управляет задачами, расшифровывает голосовые и общается с тобой в Telegram.

Подробная серия постов, где разобран каждый компонент: Курс молодого AI билдера

Что нового в 2.0

Кит подрос. С прошлой версии агент стал меньше косячить, лучше помнить и трезвее думать — за счёт инфра-слоя, а не новых тулзов. Главная идея: правила перестали жить просто текстом (который агент забывает после сжатия контекста) и стали кодом, который сервер соблюдает сам.

• Автопамять. Агент сам выцепляет важное из ваших диалогов и складывает в долгую память — без «запомни». А сама память стала аккуратным оглавлением-указателем, а не свалкой текста.
• Не забывает правила. Когда диалог разрастается, система его подрезает — раньше агент на этом терял свои же инструкции и начинал косячить. Теперь правила вшиты так, что сервер сам возвращает их на место после сжатия.
• Чувство времени. Агент знает, который час, когда начали и сколько реально наработали. Перестал путать чаты на стыке вчера/сегодня и плыть в датах.
• Меньше галлюнов. Цифры и даты берёт не из головы, а проверяет источник. Один агент насчитал — второй сверил. Меньше уверенного бреда.
• Адекватная оценка сроков. Агент теперь в курсе, что он эффективный агент, а не ленивый кожаный мешок — и не пишет «задача на 4 часа», когда делает её за 30 минут.
• База по мышлению. Не угадывать (лучше спросить), делать проще, не лезть куда не просили, держать цель.
• Дешевле в фоне. Задачи по расписанию больше не будят флагман впустую — рутину тащит модель попроще. Плюс «техосмотр» сервера: битые ссылки, упавшие процессы и прочее.
• По мелочи. Многоуровневые инструкции (агент не тонет в контексте) и дублирование критичных правил в коде, чтобы их нельзя было случайно потерять.

Уже на 1.0 или своей системе? Смотри Обновиться с 1.0.

Оглавление

• Что нового в 2.0
• Чо внутри
• Быстрый старт
• Обновиться с 1.0
• Что нужно для запуска
• Настройка кредов
• Структура репозитория
• Brain MCP — 20 инструментов
• Takopi (Telegram-бот)
• Конвенции хранилища
• Под капотом
• Создание скиллов
• Хуки-протоколы
• Временное осязание
• Как устроена память
• Авто-память (auto-distill)
• Мониторинг
• Бэкапы
• Библиотекарь

Чо внутри

• Brain MCP — 20 инструментов для работы с памятью: поиск (обычный + по смыслу), запись, дашборд, транскрибация аудио, календарь, мониторинг сервера
• Vault — Obsidian-хранилище с git-синком, мета-тегами, двусторонними ссылками и контекстным файлом в каждой папке
• Семантический поиск — находит документы по смыслу, а не только по словам. ONNX модель, работает на CPU
• Whisper — OpenAI-совместимый сервер транскрибации. Короткие аудио обрабатываются локально, длинные летят на Groq API
• Takopi — Telegram-бот для общения с агентом с телефона. Голосовые, файлы, мультисессии
• Мониторинг — алерты в Telegram когда CPU/RAM/диск на пределе или процесс упал
• Библиотекарь — еженедельный автономный аудит хранилища: находит сироток, битые ссылки, устаревшие файлы
• Dual-Channel Ask — вопросы одновременно в VS Code и Telegram. Кто первый ответил, тот и молодец
• Context7 — актуальная документация по любой библиотеке по запросу
• Скиллы — расширяемая система команд для повторяющихся задач
• Хуки-протоколы — реинжект правил после компакта, напоминалки, линт памяти, показ входящих из Telegram файлов. Всё fail-silent
• Временное осязание — агент знает, сколько прошло с прошлого сообщения, и режет историю на эпизоды
• Авто-память (auto-distill) — опциональная дистилляция авто-памяти в топик-файл по крону
• Многоуровневый CLAUDE.md — глобальный ~/CLAUDE.md плюс пер-проектный, чтобы каждый слой контекста оставался маленьким
• Two-layer надёжность — критичное правило живёт и в коде, и в промпте, чтобы компакт его не сломал
• Heartbeat-крон + --model — крон-агент сначала дёшево проверяет «есть ли работа», и крутит рутину на дешёвой модели
• Детерминированные librarian-чеки — read-only скрипты (битые ссылки, дрифт MCP, открытые порты) перед LLM-проходом библиотекаря
• Эскалирующие напоминалки — крон-ремайндеры, которые становятся настойчивее с каждым уровнем
• Интерактивный онбординг — агент сам проведёт новичка по всем шагам, без чтения документации

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

# 1. Клонируем
git clone https://github.com/doffskiii/claude-server-kit.git
cd claude-server-kit

# 2. Ставим всё (uv, Node.js, PM2, Brain, vault, ML модели)
bash setup.sh

# 3. Настраиваем креды (интерактивный визард)
bash configure.sh

# 4. Запускаем Claude Code и пишем "привет"
claude

Агент сам поймёт, что это первый запуск, и запустит интерактивный онбординг: познакомится, расскажет что умеет, настроит Telegram, голосовые, бэкапы, безопасность. Просто отвечай на вопросы.

Обновиться с 1.0

Уже разворачивал кит раньше (или собрал свою систему)? Заново ставить не нужно. Открой Claude Code в папке проекта и скажи примерно так:

«Вот репо claude-server-kit 2.0 — сравни с моей системой и подтяни апдейты, которых у меня нет»

Агент сам пройдётся по репозиторию и заберёт нужное:

• Хуки — templates/hooks/* плюс блок hooks в ~/.claude/settings.json
• Принципы мышления и временное осязание — блоки в ~/CLAUDE.md
• Протокол памяти (индекс + само-исправление) — MEMORY.md
• Автопамять — scripts/auto-distill.py (опционально, по крону)
• По мелочи — librarian/checks/, scripts/cron-agent-example.sh, templates/project-CLAUDE.md.example

Ничего твоего он не снесёт — добавит только то, что улучшает. А если хочешь с нуля, setup.sh идемпотентен и не перезатирает существующие конфиги.

Что нужно для запуска

• Ubuntu 20.04+ (или аналогичный Linux)
• 2+ GB RAM (4+ GB если хотите Whisper + эмбеддинги)
• Git, интернет
• setup.sh установит всё остальное: uv, Python 3.12+, Node.js, PM2, ffmpeg

Настройка кредов

Можно через визард bash configure.sh, а можно руками:

Takopi (Telegram-бот) — нужен для общения с телефона

uv tool install takopi && takopi

Groq API (опционально) — ускоряет транскрибацию длинных аудио

echo '{"api_key":"gsk_..."}' > ~/.groq-api-key.json && chmod 600 ~/.groq-api-key.json

Git-бэкап хранилища (опционально) — пушит vault в приватный репо каждые 5 минут

cd ~/vault && git remote add origin [email protected]:you/vault-private.git

Шифрованный бэкап (опционально) — ежедневный полный бэкап с GPG

echo 'your-passphrase' > ~/.backup-passphrase && chmod 600 ~/.backup-passphrase

Все чувствительные файлы — chmod 600 и в .gitignore.

claude-server-kit/
├── brain/                    # Brain MCP сервер (Python, FastMCP)
│   ├── src/brain/
│   │   ├── server.py         # 20 MCP инструментов
│   │   ├── config.py         # Конфигурация (env-driven)
│   │   ├── whisper_server.py # OpenAI-compatible Whisper API
│   │   ├── vault/            # Операции с хранилищем
│   │   ├── calendar/         # Календарь (SQLite)
│   │   └── server_tools/     # Мониторинг сервера
│   ├── scripts/              # Утилиты
│   └── ecosystem.config.cjs  # PM2 конфигурация
│
├── librarian/                # Автономный аудит хранилища
│   ├── SYSTEM.md             # Системный промпт агента
│   ├── CHECKLIST.md          # 10-секционный чеклист
│   └── run.sh                # Cron entry point
│
├── vault-template/           # Пустое хранилище с контекстными файлами
│   ├── dashboard.md          # Дашборд задач
│   ├── inbox/                # Входящие идеи
│   ├── conversations/        # Записи сессий
│   ├── decisions/            # Лог решений
│   ├── knowledge/            # Знания (проекты, личное, обучение)
│   ├── retro/                # Ретроспективы
│   └── templates/            # Шаблоны Obsidian
│
├── templates/                # Шаблоны конфигов Claude Code
│   ├── CLAUDE.md             # Инструкции агента (THE BRAIN)
│   ├── mcp.json              # Регистрация MCP серверов
│   ├── settings.json         # Конфигурация permissions
│   └── memory/MEMORY.md      # Бутстрап авто-памяти
│
├── scripts/                  # Серверная автоматизация
│   ├── backup.sh             # Шифрованный бэкап (GPG AES-256)
│   ├── git-push-all.sh       # Ежедневный пуш кода на GitHub
│   ├── calendar-sync.py      # Синхронизация календаря (hourly)
│   └── reminders/            # Эскалирующие напоминалки
│
├── skills/                   # Пример скиллов Claude Code
│   ├── onboarding/SKILL.md   # Интерактивный онбординг
│   ├── track/SKILL.md        # Умный роутинг задач
│   └── reflect/SKILL.md      # Дневная рефлексия
│
├── setup.sh                  # Установка в одну команду
├── configure.sh              # Интерактивный визард кредов
└── .gitignore

Хранилище: search_vault (полнотекстовый поиск) / semantic_search (поиск по смыслу) / read_vault / write_vault (с авто-мета и git-синком) / list_vault / update_dashboard (безопасное обновление, никогда не перезаписывает)

Ингест: ingest_audio (аудио в текст, локально или через Groq) / ingest_document (PDF/текст с авто-чанкингом)

Календарь: get_today (текущая дата + граница дня в 03:00 + неделя) / add_calendar_event / list_calendar_events / remove_calendar_event / update_calendar_event / queue_calendar_sync

Telegram: send_telegram_question (неблокирующий) / check_telegram_answer (поллинг) / cancel_telegram_question / ask_via_telegram (блокирующий, legacy)

Сервер: get_server_status (CPU/RAM/диск/PM2) / get_server_map (карта сервисов)

Takopi (Telegram-бот)

Takopi — open-source мост между Telegram и AI-агентами.

• Мульти-движок: Claude Code, Codex, OpenCode, DeepSeek
• Транскрибация голосовых (роутит на Brain Whisper)
• Передача файлов, мультисессии, стриминг
• Dual-channel Q&A сервер на порту 9877
• Установка: uv tool install -U takopi

Конвенции хранилища

• Контекстные файлы — в каждой папке есть FOLDER_NAME.md, который индексирует содержимое
• Фронтматтер — все файлы имеют YAML метаданные: title, tags, created, source
• Двусторонние ссылки — если A ссылается на B, то B обязан ссылаться на A
• Дашборд — только через update_dashboard(), никогда через write_vault("dashboard.md")
• Решения — значимые решения записываются в decisions/YYYY-MM-DD_slug.md
• Записи сессий — после работы в VS Code записываем в conversations/YYYY-MM-DD_slug.md
• Граница дня в 03:00 — для полуночников: логический день заканчивается в 3 утра, не в полночь

Debounced Git Sync — несколько записей за 30 секунд собираются в один коммит. Fire-and-forget, не блокирует ответ.

Инкрементальные эмбеддинги — при записи документа пересчитываются только его эмбеддинги. Полный ребилд индекса не нужен.

Thread-Safe ONNX — глобальный лок предотвращает конкурентный доступ к модели эмбеддингов. Безопасно для параллельных тул-коллов.

Fail-Safe Calendar Sync — события привязаны к таск-системам через source_type + source_id. Часовой крон проверяет завершённость задач перед удалением событий.

Эскалирующие напоминалки — 4 уровня: подробная статистика -> простой тычок -> последний шанс -> авто-выполнение. Маркер-файлы предотвращают повторный запуск.

Безопасность путей — все vault-пути валидируются от directory traversal и symlink-атак. .env, .ssh, токены заблокированы от ингеста.

Многоуровневый CLAUDE.md — Claude Code грузит глобальный ~/CLAUDE.md плюс пер-проектный CLAUDE.md внутри папки проекта. Глобальные правила — глобально, проектные — локально. Шаблон: templates/project-CLAUDE.md.example.

Two-layer надёжность — критичное правило живёт и в коде, и в промпте (CLAUDE.md/MEMORY.md), чтобы компакт промпта не сломал поведение молча. Пример: граница дня 03:00 в brain/calendar/tools.py (CLAUDE_DAY_BOUNDARY_HOUR) И в CLAUDE.md/MEMORY.md.

Heartbeat-крон + --model — крон-агент сначала дёшево проверяет «есть ли работа» (без вызова модели), и крутит рутину на дешёвой модели, а не на флагмане. Шаблон: scripts/cron-agent-example.sh; библиотекарь — LIBRARIAN_MODEL (по умолчанию sonnet).

Детерминированные librarian-чеки — librarian/checks/ (read-only, без зависимостей): битые ссылки + сироты памяти, дрифт .mcp.json vs settings.json, неожиданные открытые порты / устаревшие кроны / ошибки pm2. Библиотекарь гоняет их (--json) перед LLM-проходом. Подробнее — docs/FEATURES.md.

Создание скиллов

Скиллы — это файлы с инструкциями, которые расширяют возможности агента:

~/.claude/skills/my-skill/
├── SKILL.md      # Инструкции + триггеры
└── scripts/      # Вспомогательные скрипты (опционально)

Смотри skills/onboarding/SKILL.md для примера, skills/track/SKILL.md и skills/reflect/SKILL.md для боевых скиллов.

Хуки-протоколы

Набор из пяти хуков в templates/hooks/ (подключены через блок hooks в settings.json) автоматизирует то, что агент сам забывает. После компакта контекста ключевые правила реинжектятся обратно (context-anchor.sh), периодически всплывает напоминалка о памяти (memory-reminder.sh), запись в память линтуется на «роутинг-хук, а не контент» (lint-memory.py), хук показывает входящие из Telegram файлы (check-incoming-files.sh, путь + размер — не фильтрует и не блокирует), а пятый — inject-message-timestamp.py — подкладывает в каждое сообщение метку времени (см. раздел «Временное осязание»). Все хуки fail-silent — при ошибке выходят с кодом 0 и не ломают сессию; единственный, кто блокирует (код 2), — линт памяти, и только при реальном нарушении.

Временное осязание

Хук inject-message-timestamp.py подкладывает в каждое сообщение невидимый блок <message-meta> (текущее время, сколько прошло с прошлого сообщения, разбивка истории на эпизоды по порогу 45 минут и класс паузы). Так агент понимает, вернулись вы через 10 минут или через два дня, и подстраивает поведение. Часовой пояс задаётся через env CLAUDE_TZ. Подробности — в «Hooks & Time Awareness» в templates/CLAUDE.md.

Как устроена память

Claude Code хранит знания между сессиями в ~/.claude/projects/<project>/memory/:

• MEMORY.md — ключевые правила, всегда загружается в контекст (держи до 200 строк)
• Топик-файлы (whisper.md, trello.md) — детальные знания по доменам, подгружаются по необходимости
• Claude обновляет эти файлы сам по мере работы

Авто-память (auto-distill)

scripts/auto-distill.py дистиллирует накопленную авто-память в отдельный топик-файл memory/auto-distilled.md. Это opt-in — запускается по крону вручную и отключается через env CLAUDE_AUTODISTILL_DISABLE. Учтите стоимость: дистилляция — это лишний вызов модели, так что включайте, только если объём авто-памяти реально вырос.

Мониторинг

Brain Monitor (PM2 демон) шлёт алерты в Telegram когда:

• CPU > 80% три проверки подряд
• Свободная RAM < 1 GB
• Диск > 85%
• Любой PM2 процесс упал

Кулдаун 30 минут между одинаковыми алертами.

Бэкапы

Три слоя:

1. Git-синк хранилища (каждые 5 мин) — непрерывный бэкап знаний
2. Git-пуш кода (ежедневно) — все репозитории на GitHub
3. Шифрованный бэкап (ежедневно) — GPG AES-256 -> облако

Библиотекарь

Еженедельный автономный агент, который аудитит хранилище:

• Пропущенные контекстные файлы, сироты, битые ссылки
• Устаревшие записи, нарушения двусторонних ссылок
• Проблемы с фронтматтером, скоринг свежести
• Шлёт сжатый отчёт в Telegram

Крон: 0 4 * * 1 bash ~/librarian/run.sh (понедельник, 4 утра).

Credits

• Takopi by banteg — Telegram-мост для AI-агентов
• FastMCP — легковесный MCP фреймворк
• faster-whisper — CTranslate2 Whisper
• Obsidian — управление знаниями
• sentence-transformers — мультиязычные эмбеддинги

License

MIT

Понравилось? Поставь звёздочку — это помогает другим найти проект!