Flaiwheel

Самохостируемый уровень памяти и управления для AI-агентов программирования. Превратите каждое исправление бага в постоянное знание. Никаких облаков. Никакой привязки к вендору.

🚀 Зачем нужен Flaiwheel

AI-агенты программирования забывают всё между сессиями. Это приводит к повторным багам, потере архитектурных решений и деградации знаний.

Flaiwheel гарантирует, что:

• Агенты ищут информацию перед написанием кода

• Агенты документируют изменения после исправления

• Коммиты автоматически фиксируют знания

• Память накапливается со временем

Каждый исправленный баг делает следующий баг дешевле.

Related MCP server: MCP VectorStore Server

🧠 Чем Flaiwheel отличается

• Постоянная AI-память, которая накапливается — знания не сбрасываются между сессиями.

• Автоматизация на базе Git — коммиты автоматически становятся структурированными знаниями.

• Управление, а не просто хранение — контроль качества + принудительная документация.

• Гибридный поиск + переранжирование — высокоточный контекст для реальных кодовых баз.

• Полностью самохостируемое решение — один Docker-контейнер, никакой внешней инфраструктуры.

• Отсутствие привязки — все знания хранятся в виде структурированных плоских файлов в Git.

✅ Для кого Flaiwheel

• Инженерные команды, использующие AI-ассистентов в реальных проектах

• Кодовые базы, где повторные баги обходятся дорого

• Команды, требующие полного контроля над данными

• AI-ориентированные среды разработки

❌ Не подходит для

• Небольших хобби-проектов объемом в несколько тысяч строк

• Разработчиков, которым нужно только улучшенное автодополнение

• Чистых SaaS-рабочих процессов без интереса к самохостингу

🆚 Где место Flaiwheel

• AI-инструменты генерируют код.

• RAG-инструменты извлекают документы.

• Flaiwheel управляет и накапливает структурированные инженерные знания внутри вашей собственной инфраструктуры.

Он не заменяет вашего AI-ассистента. Он делает его надежным в масштабе.

📄 Whitepaper (PDF) — Глубокий обзор видения, архитектуры и дизайна.

⚙️ Ключевые технические особенности

Flaiwheel — это автономный Docker-сервис, работающий на трех уровнях: Pull — агенты ищут перед написанием кода (search_docs, get_file_context) Push — агенты документируют в процессе работы (write_bugfix_summary, write_architecture_doc, …) Capture — git-хук post-commit автоматически фиксирует знания, даже без AI-агента

• Индексирует документацию вашего проекта (.md, .pdf, .html, .docx, .rst, .txt, .json, .yaml, .csv) в векторную базу данных

• Предоставляет MCP-сервер, к которому подключаются AI-агенты (Cursor, Claude Code, VS Code Copilot)

• Гибридный поиск — сочетает семантический векторный поиск с ключевым поиском BM25 через Reciprocal Rank Fusion (RRF) для лучшего из обоих миров

• Cross-encoder reranker — опциональный этап переранжирования, который переоценивает кандидатов с помощью модели cross-encoder для значительно более высокой точности при запросах с несовпадением лексики

• Поведенческие директивы — AI-агенты молча ищут в Flaiwheel перед каждым ответом, автоматически документируют после каждой задачи и переиспользуют знания вместо создания новых — без дополнительных запросов

• get_file_context(filename) — предварительно загружает пространственные знания для любого файла, который агент собирается редактировать (дополняет get_recent_sessions для полного временного + пространственного контекста)

• post-commit git hook — автоматически фиксирует каждый коммит fix:, feat:, refactor:, perf:, docs: как структурированный документ знаний

• Живая архитектура — AI-агенты получают инструкции поддерживать самообновляемые диаграммы Mermaid.js для системных компонентов и потоков

• Исполняемые тестовые сценарии — сценарии тестирования документируются в машиночитаемом формате BDD/Gherkin (Given, When, Then) для автоматизации QA

• Обучение на исправлениях багов — агенты пишут резюме исправлений, которые мгновенно индексируются

• Инструменты структурированной записи — 7 специализированных инструментов (исправление бага, архитектура, API, лучшие практики, настройка, журнал изменений, тест-кейс), обеспечивающих качество у источника

• Валидация pre-commit — validate_doc() проверяет markdown произвольной формы перед попаданием в базу знаний

• Контроль качества при приеме — файлы с критическими проблемами автоматически пропускаются при индексации (никогда не удаляются — вы владеете своими файлами)

• Автосинхронизация через Git — извлекает И отправляет данные в выделенный репозиторий знаний

• Телеметрия инструментов (постоянная) — отслеживает каждый вызов MCP для каждого проекта (поиски, записи, пропуски, паттерны), обнаруживает пробелы в знаниях и подталкивает агентов к документированию — сохраняется после перезагрузок и видна в Web UI

• API метрик влияния — /api/impact-metrics вычисляет примерное сэкономленное время + предотвращенные регрессии; CI-пайплайны могут отправлять результаты проверок в /api/telemetry/ci-guardrail-report

• Проактивные проверки качества — автоматически проверяет базу знаний после каждой переиндексации

• Bootstrap знаний — "This is the Way": анализирует беспорядочные репозитории, классифицирует файлы, обнаруживает дубликаты, предлагает план очистки, выполняет с одобрения пользователя (никогда не удаляет файлы)

• Анализатор кодовой базы "холодного старта" — analyze_codebase(path) сканирует директорию исходного кода полностью на стороне сервера (ноль токенов, ноль облака). Использует встроенный модуль Python ast для Python, regex для TypeScript/JavaScript, существующую модель эмбеддингов MiniLM для классификации и обнаружения дубликатов. Возвращает один bootstrap_report.md с распределением языков, картой категорий, топ-20 файлами для документирования в первую очередь (ранжированными по оценке документируемости), парами дубликатов и пробелами в покрытии. Снижает стоимость токенов холодного старта на ~90% на устаревших кодовых базах.

• Поддержка нескольких проектов — один контейнер управляет несколькими репозиториями знаний с изоляцией по проектам

• Включает Web UI для настройки, мониторинга и тестирования

Что нового в v3.9.29

• Исправление обнаружения инструментов Glama — AuthManager аварийно завершался при доступе к /data только для чтения до запуска MCP-сервера (истинная причина, почему Glama видела 0 инструментов). Пропущено в режиме холодного старта stdio.

• Zero print() в stdout — 36 оставшихся print() в наблюдателе, индексаторе, ридерах, bootstrap заменены на diag() (stderr). Проверено: полное рукопожатие MCP возвращает все 28 инструментов через stdio.

• config.save() устойчив — файловая система только для чтения логирует предупреждение вместо аварийного завершения.

Предыдущие версии: v3.9.28

• Исправление Glama / MCP stdio — весь диагностический вывод перемещен в stderr; stdout теперь только для JSON-RPC. Glama Inspector теперь правильно обнаруживает все 28 инструментов.

• Улучшенное обнаружение холодного старта — логика холодного старта stdio правильно обрабатывает пустые Docker-тома (нет bootstrap / загрузки модели во время инспекции Glama).

Предыдущие версии: v3.9.27

• Очистка лицензии — один файл LICENSE (BSL 1.1) для правильного обнаружения GitHub/Glama; все документы и заголовки указывают на LICENSE (не LICENSE.md).

• Инспекция Glama / stdio — опциональные зависимости [inspect] и путь stdio холодного старта для легких сборок каталога MCP.

Предыдущие версии: v3.9.26

• Навык Claude Cowork — рабочий процесс Flaiwheel теперь распространяется как нативный навык Claude. Установщик записывает .skills/skills/flaiwheel/SKILL.md в ваш проект. Когда вы открываете проект в Claude (Cowork), навык становится автоматически доступным — дополнительная настройка не требуется. Навык управляет восстановлением контекста при запуске сессии, поиском знаний перед кодированием, обязательной документацией после исправления багов и подведением итогов сессии.

• Исходный код навыка также закоммичен в skills/flaiwheel/SKILL.md в этом репозитории для справки и ручной установки.

Предыдущие версии: v3.9.25

• Автоматическая настройка WSL2 — WSL2 теперь обнаруживается автоматически, и выделенный блок предварительной проверки запускается перед основным потоком установщика. Ручные шаги не требуются:

  1. Переключает iptables на legacy-бэкенд (исправляет ошибки сети Docker / DNAT)

  2. Добавляет текущего пользователя в группу docker (больше никаких permission denied)

  3. Запускает демон Docker через service (нет systemd в WSL2)

  4. Добавляет фрагмент автозапуска Docker в ~/.bashrc (идемпотентно, запускается при каждом входе в WSL2)

• Разрозненные проверки WSL2 по всему скрипту объединены в единый блок предварительной проверки.

Предыдущие версии: v3.9.24

• Исправление: автоустановка python3, если отсутствует — установщик активно использует python3 для манипуляций с JSON. На минимальных системах Linux/WSL2 без python3 запись файлов конфигурации молча завершалась неудачей (/dev/fd/63: line N: python3: command not found). python3 теперь проверяется как предварительное условие №0 и автоматически устанавливается через apt/dnf/yum/pacman/brew, если отсутствует.

Предыдущие версии: v3.9.23

• Исправление: запуск демона Docker на WSL2 с iptables-legacy — Docker на WSL2 часто не запускается молча, потому что бэкенд iptables-nft по умолчанию не поддерживается. Установщик теперь переключается на iptables-legacy через update-alternatives перед запуском Docker. Также автоматически добавляет текущего пользователя в группу docker.

• Все команды установки обновлены до bash <(curl ...) — каждая отображаемая команда установки/перезапуска во всем скрипте (сообщения об ошибках, AGENTS.md, правила Cursor и т.д.) теперь использует подстановку процессов, чтобы избежать проблем с пайпами WSL2.

Предыдущие версии: v3.9.22

• Исправление: ошибки записи пайпа curl | bash на WSL2 — curl | bash может завершиться с ошибкой curl: (23) Failure writing output на WSL2 из-за проблем с правами доступа к пайпам/tmp. Основная команда установки в README теперь bash <(curl ...) (подстановка процессов), что полностью исключает пайп. Блок перезапуска также пытается использовать $HOME в качестве резервной временной директории, когда запись в /tmp не удается. Сообщение об ошибке явно рекомендует форму bash <(curl ...).

Предыдущие версии: v3.9.21

• Исправление: защита sudo перемещена перед блоком перезапуска — когда использовался sudo curl | bash, ошибка пайпа curl: (23) обрезала скрипт до того, как была достигнута предыдущая защита sudo (которая была после цветов/функций). Защита теперь является самой первой исполняемой строкой (помимо set -euo pipefail), поэтому она срабатывает даже при обрезанной загрузке. Дублирующая защита после цветов удалена.

Предыдущие версии: v3.9.20

• Исправление: опрос запуска демона Docker на WSL2 — вместо фиксированной паузы в 5 секунд установщик теперь опрашивает docker info каждые 2 секунды в течение до 30 секунд после service docker start. Также показывает фактический вывод service docker start, чтобы ошибки запуска были видны, а не молча поглощались.

Предыдущие версии: v3.9.19

• Исправление: запуск демона Docker на WSL2 — в WSL2 обычно нет systemd, поэтому systemctl start docker молча завершался неудачей. Установщик теперь обнаруживает WSL2 через /proc/version и использует sudo service docker start. Если Docker все еще не запущен после установки, отображается четкая ошибка, специфичная для WSL2, с точной командой исправления и советом добавить ее в ~/.bashrc для автозапуска при входе.

Предыдущие версии: v3.9.18

• Исправление: блокировка sudo curl | bash и sudo bash install.sh — запуск установщика от имени root через sudo ломает аутентификацию GitHub CLI: gh auth сохраняет учетные данные в /root/.config/gh/ вместо домашней директории реального пользователя, из-за чего каждый последующий вызов gh завершается неудачей. Также вызывало ошибки пайпа curl: (23) Failure writing output на WSL. Установщик теперь обнаруживает SUDO_USER при запуске и немедленно завершает работу с четким сообщением, предлагающим пользователю перезапустить без sudo. Повышение привилегий для установки пакетов обрабатывается внутренне.

Предыдущие версии: v3.9.17

• Исправление: gh auth login нельзя запускать с sudo — после автоустановки gh на Linux/WSL установщик теперь явно говорит пользователю запускать gh auth login без sudo. Если аутентификация ранее выполнялась с sudo, учетные данные оказывались в /root/.config/gh/ и были невидимы для текущего пользователя, что приводило к сбою проверки аутентификации. Сообщения об ошибках как на этапе после установки, так и на этапе проверки аутентификации теперь четко предупреждают: не используйте sudo для gh auth.

Предыдущие версии: v3.9.16

• Исправление: установщик работает на WSL и Linux без root — все команды менеджера пакетов Linux (apt-get, dnf, yum, zypper, pacman), скрипт удобства Docker и вызовы systemctl теперь автоматически используют