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 어시스턴트를 대체하지 않습니다. 규모에 맞게 신뢰할 수 있도록 만듭니다.

📄 백서 (PDF) — 비전, 아키텍처 및 설계를 심층적으로 다룹니다.

⚙️ 주요 기술적 특징

Flaiwheel은 세 가지 수준에서 작동하는 독립형 Docker 서비스입니다: Pull — 에이전트가 코딩 전 검색 (search_docs, get_file_context) Push — 에이전트가 작업 중 문서화 (write_bugfix_summary, write_architecture_doc, …) Capture — AI 에이전트 없이도 post-commit 훅을 통해 git 커밋이 지식을 자동 캡처

• 프로젝트 문서(.md, .pdf, .html, .docx, .rst, .txt, .json, .yaml, .csv)를 벡터 데이터베이스로 인덱싱

• AI 에이전트(Cursor, Claude Code, VS Code Copilot)가 연결할 수 있는 MCP 서버 제공

• 하이브리드 검색 — 의미론적 벡터 검색과 BM25 키워드 검색을 RRF(Reciprocal Rank Fusion)를 통해 결합하여 최상의 검색 결과 제공

• Cross-encoder 리랭커 — 어휘 불일치 쿼리에서 훨씬 높은 정밀도를 위해 크로스 인코더 모델로 후보를 재점수화하는 선택적 리랭킹 단계

• 행동 지침 — AI 에이전트가 모든 응답 전 Flaiwheel을 조용히 검색하고, 모든 작업 후 자동 문서화하며, 재생성 전 재사용하도록 유도 (요청 없이 수행)

• get_file_context(filename) — 에이전트가 편집하려는 파일에 대한 공간적 지식을 미리 로드 (전체 시간적 + 공간적 컨텍스트를 위해 get_recent_sessions 보완)

• post-commit git hook — 모든 fix:, feat:, refactor:, perf:, docs: 커밋을 구조화된 지식 문서로 자동 캡처

• 살아있는 아키텍처 — AI 에이전트가 시스템 구성 요소 및 흐름에 대한 Mermaid.js 다이어그램을 스스로 업데이트하도록 지시

• 실행 가능한 테스트 흐름 — QA 자동화를 위해 테스트 시나리오를 기계 판독 가능한 BDD/Gherkin 형식(Given, When, Then)으로 문서화

• 버그 수정 학습 — 에이전트가 작성한 버그 수정 요약이 즉시 인덱싱됨

• 구조화된 쓰기 도구 — 소스에서 품질을 강제하는 7가지 카테고리별 도구 (버그 수정, 아키텍처, API, 모범 사례, 설정, 변경 로그, 테스트 케이스)

• 커밋 전 검증 — validate_doc()이 지식 베이스에 들어가기 전 자유 형식 마크다운을 검사

• 수집 품질 게이트 — 심각한 문제가 있는 파일은 인덱싱 중 자동으로 건너뜀 (삭제되지 않음 — 파일 소유권은 사용자에게 있음)

• Git을 통한 자동 동기화 — 전용 지식 저장소로 Pull 및 Push

• 도구 원격 측정 (지속적) — 프로젝트별 모든 MCP 호출(검색, 쓰기, 누락, 패턴)을 추적하고, 지식 격차를 감지하며, 에이전트에게 문서화를 유도 — 재시작 후에도 유지되며 웹 UI에서 확인 가능

• 영향력 지표 API — /api/impact-metrics가 절약된 예상 시간 + 방지된 회귀를 계산; CI 파이프라인은 가드레일 결과를 /api/telemetry/ci-guardrail-report로 게시 가능

• 사전 품질 검사 — 모든 재인덱싱 후 지식 베이스를 자동으로 검증

• 지식 부트스트랩 — "This is the Way": 복잡한 저장소를 분석하고, 파일을 분류하며, 중복을 감지하고, 정리 계획을 제안하며, 사용자 승인 하에 실행 (파일 삭제 절대 안 함)

• 콜드 스타트 코드베이스 분석기 — analyze_codebase(path)가 서버 측에서 소스 코드 디렉토리를 완전히 스캔 (토큰 제로, 클라우드 제로). Python의 내장 ast 모듈, TypeScript/JavaScript용 정규식, 분류 및 중복 감지를 위한 기존 MiniLM 임베딩 모델 사용. 언어 분포, 카테고리 맵, 문서화 가능성 점수별 상위 20개 파일, 중복 쌍, 커버리지 격차가 포함된 bootstrap_report.md를 반환. 레거시 코드베이스에서 콜드 스타트 토큰 비용을 약 90% 절감.

• 다중 프로젝트 지원 — 하나의 컨테이너가 프로젝트별 격리를 통해 여러 지식 저장소를 관리

• 설정, 모니터링 및 테스트를 위한 웹 UI 포함

v3.9.29의 새로운 기능

• Glama 도구 감지 수정 — MCP 서버가 시작되기 전에 AuthManager가 읽기 전용 /data에서 충돌하던 문제 해결 (Glama가 도구를 0개로 보던 실제 이유). stdio 콜드 스타트 모드에서는 건너뜀.

• stdout에 print() 제로화 — 감시자, 인덱서, 리더, 부트스트랩에 남아있던 36개의 print()를 diag()(stderr)로 교체. 확인됨: 전체 MCP 핸드셰이크가 stdio를 통해 28개 도구를 모두 반환.

• config.save() 복원력 — 읽기 전용 파일 시스템에서 충돌 대신 경고 로그 기록.

이전: v3.9.28

• Glama / MCP stdio 수정 — 모든 진단 출력을 stderr로 이동; stdout은 이제 JSON-RPC 전용. Glama Inspector가 이제 28개 도구를 모두 올바르게 감지.

• 콜드 스타트 감지 개선 — stdio 콜드 스타트 로직이 빈 Docker 볼륨을 올바르게 처리 (Glama 검사 중 부트스트랩/모델 다운로드 없음).

이전: v3.9.27

• 라이선스 정리 — 올바른 GitHub/Glama 감지를 위해 하나의 LICENSE 파일(BSL 1.1) 사용; 모든 문서와 헤더가 LICENSE.md가 아닌 LICENSE를 가리킴.

• Glama / stdio 검사 — 경량 MCP 디렉토리 빌드를 위한 선택적 [inspect] 종속성 및 콜드 스타트 stdio 경로.

이전: 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를 레거시 백엔드로 전환 (Docker 네트워킹 / DNAT 오류 수정)

  2. 현재 사용자를 docker 그룹에 추가 (더 이상 permission denied 없음)

  3. service를 통해 Docker 데몬 시작 (WSL2에는 systemd 없음)

  4. ~/.bashrc에 Docker 자동 시작 스니펫 추가 (멱등성, 모든 WSL2 로그인 시 실행)

• 스크립트 전체에 흩어져 있던 WSL2 검사를 단일 사전 비행 블록으로 통합.

이전: v3.9.24

• 수정: 누락 시 python3 자동 설치 — 설치 프로그램은 JSON 조작을 위해 python3를 광범위하게 사용함. python3가 없는 최소 Linux/WSL2 시스템에서 설정 파일 쓰기가 조용히 실패하던 문제 해결. python3가 이제 필수 조건 #0으로 확인되며 누락 시 apt/dnf/yum/pacman/brew를 통해 자동 설치됨.

이전: v3.9.23

• 수정: iptables-legacy를 사용하는 WSL2에서 Docker 데몬 시작 — WSL2의 Docker는 기본 iptables-nft 백엔드가 지원되지 않아 조용히 시작에 실패하는 경우가 많음. 설치 프로그램이 이제 Docker를 시작하기 전에 update-alternatives를 통해 iptables-legacy로 전환함. 또한 현재 사용자를 docker 그룹에 자동으로 추가.

• 모든 설치 명령을 bash <(curl ...)로 업데이트 — 스크립트 전체에 표시된 모든 설치/재실행 명령(오류 메시지, AGENTS.md, Cursor 규칙 등)이 이제 WSL2 파이프 문제를 피하기 위해 프로세스 대체를 사용.

이전: v3.9.22

• 수정: WSL2에서 curl | bash 파이프 쓰기 실패 — curl | bash는 WSL2에서 파이프/tmp 권한 문제로 인해 curl: (23) Failure writing output 오류가 발생할 수 있음. README의 기본 설치 명령이 이제 파이프를 완전히 피하는 bash <(curl ...)(프로세스 대체)로 변경됨. 재실행 블록은 /tmp 쓰기가 실패할 때 대체 임시 디렉토리로 $HOME을 시도함. 오류 메시지는 bash <(curl ...) 형식을 명시적으로 권장.

이전: v3.9.21

• 수정: sudo 가드를 재실행 블록 앞으로 이동 — sudo curl | bash가 사용될 때 curl: (23) 파이프 오류가 이전 sudo 가드(색상/함수 뒤에 있었음)에 도달하기 전에 스크립트를 잘라버림. 가드가 이제 첫 번째 실행 가능한 줄( set -euo pipefail 제외)이 되어 잘린 다운로드에서도 실행됨. 색상 뒤의 중복 가드 제거.

이전: v3.9.20

• 수정: WSL2에서 Docker 데몬 시작 폴링 — 고정된 5초 대기 대신 설치 프로그램이 이제 service docker start 후 최대 30초 동안 2초마다 docker info를 폴링함. 또한 service docker start의 실제 출력을 표시하여 시작 오류가 조용히 묻히지 않고 보이도록 함.

이전: v3.9.19

• 수정: WSL2에서 Docker 데몬 시작 — WSL2는 일반적으로 systemd가 없으므로 systemctl start docker가 조용히 실패함. 설치 프로그램이 이제 /proc/version을 통해 WSL2를 감지하고 대신 sudo service docker start를 사용함. 설치 후에도 Docker가 실행되지 않으면 정확한 수정 명령과 로그인 시 자동 시작을 위해 ~/.bashrc에 추가하라는 팁이 포함된 명확한 WSL2 전용 오류가 표시됨.

이전: v3.9.18

• 수정: sudo curl | bash 및 sudo bash install.sh 차단 — sudo를 통해 루트로 설치 프로그램을 실행하면 GitHub CLI 인증이 깨짐: gh auth가 실제 사용자의 홈이 아닌 /root/.config/gh/에 자격 증명을 저장하여 이후의 모든 gh 호출이 실패함. 또한 WSL에서 curl: (23) Failure writing output 파이프 오류를 유발함. 설치 프로그램이 이제 시작 시 SUDO_USER를 감지하고 sudo 없이 다시 실행하라는 명확한 메시지와 함께 즉시 종료됨. 패키지 설치를 위한 권한 상승은 내부적으로 처리됨.

이전: v3.9.17

• 수정: gh auth login은 sudo로 실행하면 안 됨 — Linux/WSL에 gh를 자동 설치한 후 설치 프로그램이 이제 사용자에게 sudo 없이 gh auth login을 실행하라고 명시적으로 알림. 이전에 sudo로 인증을 수행한 경우 자격 증명이 /root/.config/gh/에 저장되어 현재 사용자에게 보이지 않게 되어 인증 확인이 실패함. 설치 후 및 인증 확인 단계의 오류 메시지 모두 gh auth에 sudo를 사용하지 말라고 명확하게 경고함.

이전: v3.9.16

• 수정: 설치 프로그램이 WSL 및 비루트 Linux에서 작동 — 모든 Linux 패키지 관리자 명령(apt-get, dnf, yum, zypper, pacman), Docker 편의 스크립트 및 systemctl 호출이 이제 설치 프로그램이 루트로 실행되지 않을 때 자동으로 sudo를 사용함. 루트 설치는 영향을 받지 않음. WSL 및 표준 Linux 데스크탑 사용자의 Permission denied / 잠금 파일 오류를 수정.

이전: v3.9.15

• 콜드 스타트 보고서가 /data/에 캐시됨