FLAIWHEEL
A self-improving knowledge base for AI coding agents. Self-hosted. MCP-native. Knowledge compounds automatically.
// HOW THE FLYWHEEL WORKS
AI agents write. Flaiwheel remembers. If they forget, Flaiwheel nudges them. Everything stays local.
Cursor / Claude Code / Copilot
+ SMART NUDGES
Self-hosted & Private
THE CYCLE NEVER STOPS. KNOWLEDGE ONLY GROWS.
// SEARCH PIPELINE
Five stages. Configurable at every step. Optional reranker for maximum precision.
ChromaDB + HNSW cosine similarity. Finds semantically related content even when words differ.
Exact keyword matching with TF-IDF weighting. Catches results that share specific terms.
Reciprocal Rank Fusion with configurable k and vector/BM25 weights. Docs found by both methods get boosted.
Reads each (query, doc) pair together for precise relevance scoring. Solves vocabulary mismatch. +50ms, +10-25% precision.
Configurable minimum threshold. Only the most relevant chunks reach the AI agent. Zero noise.
// FEATURES
HYBRID SEARCH + RERANKER
Semantic vectors + BM25 keywords merged via RRF. Optional cross-encoder reranker rescores candidates for 10-25% higher precision — "auth bypass" finds "client-side auth flag".
STRUCTURED WRITE TOOLS
7 category-specific write tools enforce quality at the source. Bugfixes, architecture, API docs, best practices, setup guides, changelogs, test cases.
QUALITY GATE
Pre-commit validation + ingest-time quality checks. Bad docs are skipped, never deleted. You own your files.
GIT AUTO-SYNC
Pulls and pushes to a dedicated knowledge repo. Write a bugfix summary — it's committed, pushed, and indexed automatically.
TELEMETRY & SMART NUDGES
Tracks every MCP call. If an agent fixes a bug but forgets to document it, Flaiwheel injects an in-band prompt nudge directly into the tool response, forcing the LLM to write the summary before it replies to you.
SELF-HOSTED
Runs in a single Docker container on your machine. No cloud, no API keys required, no data leaves your network.
MULTI-REPO
Manage multiple projects from a single Flaiwheel instance. One container, one MCP endpoint, one embedding model in RAM — per-project isolation for collections, watchers, and quality checks.
MODEL HOT-SWAP
Switch embedding models without downtime. Background migration re-indexes all projects while searches keep working on the old model.
9 INPUT FORMATS
Index MD, TXT, PDF, HTML, RST, DOCX, JSON, YAML, and CSV files. All formats are converted to markdown internally — one pipeline, no format lock-in.
LIVING ARCHITECTURE & BDD
Agents generate auto-updating Mermaid.js UML diagrams for system components and executable BDD test flows (Given/When/Then). Your documentation becomes input for automated QA testing.
"THIS IS THE WAY"
Knowledge Bootstrap — classify files by content + embeddings, detect near-duplicates, propose a cleanup plan. Never deletes files. User approves every action. Also triggered by saying "42".
COLD-START ANALYZER
analyze_codebase(path) — scan a legacy source directory entirely server-side. Zero tokens. Zero cloud. Uses ast + regex + local MiniLM to extract structure, classify files, detect duplicates, and rank the top 20 files to document first. Report is cached in /data/ for instant reads on every subsequent agent session. ~90% token reduction vs. agent-driven file reading.
// 28 MCP TOOLS
Works with Cursor, Claude Code, VS Code Copilot — any MCP-compatible AI agent.
| TOOL | PURPOSE |
|---|---|
| set_project | Bind session to a project (call first!) |
| setup_project | Register + index a new project from the agent |
| get_active_project | Show which project is currently bound |
| list_projects | List all registered projects with stats |
| search_docs | Semantic search across all documentation |
| search_bugfixes | Search only bugfix summaries |
| search_by_type | Filter by type (architecture, api, bugfix, etc.) |
| write_bugfix_summary | Document a bugfix (auto-pushed + reindexed) |
| write_architecture_doc | Document architecture decisions |
| write_api_doc | Document API endpoints |
| write_best_practice | Document coding standards |
| write_setup_doc | Document setup/deployment |
| write_changelog_entry | Document release notes |
| write_test_case | Document test cases (auto-pushed + reindexed) |
| search_tests | Search test cases for coverage and patterns |
| validate_doc | Validate markdown before committing |
| git_pull_reindex | Pull latest from knowledge repo + re-index |
| get_index_stats | Show index statistics |
| reindex | Re-index all documentation |
| check_knowledge_quality | Validate knowledge base consistency |
| check_update | Check for a newer Flaiwheel version |
| analyze_knowledge_repo | Analyse knowledge repo structure and quality |
| execute_cleanup | Execute approved cleanup actions (never deletes files) |
| classify_documents | "This is the Way" — classify project docs for knowledge migration |
| save_session_summary | Save session context for next-session continuity |
| get_recent_sessions | Retrieve recent session summaries (newest first) |
| analyze_codebase | Cold-start scan of a source directory — zero tokens, zero cloud. Cached in /data/ for instant reads. Pass force=True to refresh. Returns ranked documentation plan. |
| get_file_context | Pre-load spatial knowledge for a file the agent is about to edit |
All tools accept an optional project parameter for multi-repo targeting.
// WHY FLAIWHEEL IS DIFFERENT
AI coding tools accelerate code generation. They don't preserve engineering knowledge. Flaiwheel is the memory and governance layer that closes that gap — so every session builds on the last.
PERSISTENT MEMORY THAT COMPOUNDS
AI agents normally reset every session. Flaiwheel turns every bug fix, architecture decision, and test case into permanent structured knowledge — so your AI gets smarter over time instead of starting from zero.
SELF-HOSTED — ZERO CLOUD, ZERO LOCK-IN
Single Docker container. No external services, no API keys, no data leaves your network. All knowledge lives as flat files in your own Git repository — stop using Flaiwheel and you keep everything.
HYBRID SEARCH + RERANKING
Not just a vector DB. Semantic search, BM25 keyword matching, RRF fusion, optional cross-encoder reranking, and relevance filtering — delivering high-precision context to AI agents in serious codebases.
AUTOMATIC CAPTURE VIA GIT + MCP
Every fix:, feat:, and refactor: workflow is captured in context. Agents search before coding and document after fixes. Zero manual prompting — knowledge compounds automatically.
STRUCTURED KNOWLEDGE + QUALITY GATES
Seven category-specific write tools enforce consistency across bugfixes, architecture, API docs, tests, and more. Pre-commit validation and ingest checks ensure high-quality memory — bad docs are skipped, never deleted.
ENTERPRISE-READY BY DESIGN
Multi-repo support, model hot-swap without downtime, telemetry and impact metrics, living architecture diagrams (Mermaid.js), and executable BDD flows. Built for serious codebases — not hobby projects.
// AT A GLANCE
| CAPABILITY | AI CODING TOOLS | GENERIC RAG / MEMORY | FLAIWHEEL |
|---|---|---|---|
| Persistent team memory | ✗ | ✓ | ✓ |
| Knowledge capture enforced | ✗ | ✗ | ✓ |
| Git-native flat-file storage | ✗ | ✗ | ✓ |
| Knowledge quality gates | ✗ | ✗ | ✓ |
| Hybrid retrieval + reranking | Partial | Sometimes | ✓ |
| Fully self-hosted | Rare | Sometimes | ✓ |
| Zero lock-in (flat files in Git) | ✗ | Rare | ✓ |
| AI workflow guardrails | ✗ | ✗ | ✓ |
| Telemetry & impact metrics | ✗ | ✗ | ✓ |
| Local cold-start codebase analysis — no LLM tokens for parsing, embedding, or classification | ✗ | ✗ | ✓ |
Flaiwheel does not replace your AI coding assistant. It makes it reliable at scale.
// PRICING
COMMUNITY
Forever
- Non-commercial use
- Teams up to 10 people
- All 28 MCP tools
- Unlimited docs & searches
- Self-hosted, fully private
- Community support (GitHub)
BETA
Free through December 31, 2026 — join with email
- Commercial use without team limit
- License through December 31, 2026 (see BSL)
- All 28 MCP tools
- Commercial rights for the beta period
- No payment — email only
ENTERPRISE
Production, teams 11+, custom terms
- Teams of 11+
- Enterprise & long-term commercial
- Priority support
- Custom licensing & invoicing
- Multi-project roadmap input
- Invoice & PO available
Solo and Team plans launching 2027. Join the beta to lock in early pricing.
Licensed under Business Source License 1.1. Converts to Apache 2.0 on February 25, 2030.
// ONE COMMAND INSTALL
Prerequisites: GitHub CLI authenticated, Docker running.
| OS | STATUS | HOW TO START |
|---|---|---|
| macOS | ✓ native | Open Terminal, paste the install command |
| Linux | ✓ native | Open any terminal, paste the install command |
| Windows | ✓ via WSL | Install WSL, enable Docker WSL 2 backend, run from WSL terminal |
RUN FROM YOUR PROJECT DIRECTORY:
bash <(curl -sSL https://raw.githubusercontent.com/dl4rce/flaiwheel/main/scripts/install.sh)
Click to copy. Sets up everything: knowledge repo, Docker container, Cursor config, AI agent instructions.
// ALSO BY 4RCE
Your entire AI stack. One secure workspace.
300+ AI models in one interface — GPT-5, Claude, Gemini, Grok, Llama, and more. Upload 1,000-page scanned PDFs, ask questions, get precise cited answers. Build knowledge bases, collaborate in shared workspaces, run web searches, execute code, generate images.
HTTP error pages that don’t suck.
35 fully playable arcade games — one per HTTP error code. 404, 500, 502, 503 and everything in between. Drop-in HTML files. Zero dependencies. No build step, no npm, no framework.
// LEGAL
IMPRINT (IMPRESSUM)
4rce.com Digital Technologies GmbH
Grafentraubach 9
84082 Laberweinting
Germany
Managing Director: Volker Geith
Email: info@4rce.com
Web: 4rce.com
Court of Registration: Amtsgericht Straubing
Registration Number: HRB 13771
VAT ID: DE459375923
EDITORIALLY RESPONSIBLE
Volker Geith (address as above)
EU DISPUTE RESOLUTION
The European Commission provides a platform for online dispute resolution (OS): https://ec.europa.eu/consumers/odr/. We are not willing or obliged to participate in dispute resolution proceedings before a consumer arbitration board.
PRIVACY
This website uses Google Analytics (gtag.js) for anonymized usage statistics. Google Fonts is used for typography. See Google’s privacy policy for details. The Flaiwheel software runs entirely on your infrastructure — no data ever leaves your network.
LICENSE
Flaiwheel is licensed under the Business Source License 1.1. Free for non-commercial use and teams of up to 10 individuals. Commercial use beyond these limits requires a paid license. See LICENSE.md for full terms.