Flaiwheel

Self-hosted memory & governance layer for AI coding agents. Turn every bug fix into permanent knowledge. Zero cloud. Zero lock-in.

🚀 Why Flaiwheel Exists

AI coding agents forget everything between sessions. That leads to repeated bugs, lost architectural decisions, and knowledge decay.

Flaiwheel ensures:

• Agents search before coding
• Agents document after fixing
• Commits automatically capture knowledge
• Memory compounds over time

Every bug fixed makes the next bug cheaper.

🧠 How Flaiwheel Is Different

• Persistent AI Memory That Compounds — knowledge doesn't reset between sessions.
• Git-Native Automation — commits automatically become structured knowledge.
• Governance, Not Just Storage — quality gates + enforced documentation.
• Hybrid Search + Reranking — high-precision context for real codebases.
• Fully Self-Hosted — single Docker container, no external infrastructure.
• Zero Lock-In — all knowledge stored as structured flat files in Git.

✅ Who Flaiwheel Is For

• Engineering teams using AI coding assistants in real projects
• Codebases where repeated bugs are expensive
• Teams requiring full data control
• AI-native development environments

❌ Not For

• Small hobby projects under a few thousand lines
• Developers who just want better autocomplete
• Pure SaaS workflows with no interest in self-hosting

🆚 Where Flaiwheel Fits

• AI coding tools generate code.
• RAG tools retrieve documents.
• Flaiwheel governs and compounds structured engineering knowledge inside your own infrastructure.

It does not replace your AI assistant. It makes it reliable at scale.

📄 Whitepaper (PDF) — Vision, architecture, and design in depth.

⚙️ Key Technical Features

Flaiwheel is a self-contained Docker service that operates on three levels: Pull — agents search before they code (search_docs, get_file_context)
Push — agents document as they work (write_bugfix_summary, write_architecture_doc, …)
Capture — git commits auto-capture knowledge via a post-commit hook, even without an AI agent

• Indexes your project documentation (.md, .pdf, .html, .docx, .rst, .txt, .json, .yaml, .csv) into a vector database
• Provides an MCP server that AI agents (Cursor, Claude Code, VS Code Copilot) connect to
• Hybrid search — combines semantic vector search with BM25 keyword search via Reciprocal Rank Fusion (RRF) for best-of-both-worlds retrieval
• Cross-encoder reranker — optional reranking step that rescores candidates with a cross-encoder model for significantly higher precision on vocabulary-mismatch queries
• Behavioral Directives — AI agents silently search Flaiwheel before every response, auto-document after every task, and reuse before recreating — all without being asked
• get_file_context(filename) — pre-loads spatial knowledge for any file the agent is about to edit (complements get_recent_sessions for full temporal + spatial context)
• post-commit git hook — captures every fix:, feat:, refactor:, perf:, docs: commit as a structured knowledge doc automatically
• Living Architecture — AI agents are instructed to maintain self-updating Mermaid.js diagrams for system components and flows
• Executable Test Flows — test scenarios are documented in machine-readable BDD/Gherkin format (Given, When, Then) for QA automation
• Learns from bugfixes — agents write bugfix summaries that are instantly indexed
• Structured write tools — 7 category-specific tools (bugfix, architecture, API, best-practice, setup, changelog, test case) that enforce quality at the source
• Structured relations (v1) — relations() and timeline() derive a per-project knowledge graph from optional YAML frontmatter on existing docs (id, replaces, depends_on, fixes, implements, status). No second store — markdown stays canonical and Git history is the validity window
• Pre-commit validation — validate_doc() checks freeform markdown before it enters the knowledge base, including unknown-relation-key warnings
• Ingest quality gate — files with critical issues are automatically skipped during indexing (never deleted — you own your files)
• Auto-syncs via Git — pulls AND pushes to a dedicated knowledge repo
• Tool telemetry (persistent) — tracks every MCP call per project (searches, writes, misses, patterns), detects knowledge gaps, and nudges agents to document — persisted across restarts and visible in the Web UI
• Impact metrics API — /api/impact-metrics computes estimated time saved + regressions avoided; CI pipelines can post guardrail outcomes to /api/telemetry/ci-guardrail-report
• Proactive quality checks — automatically validates knowledge base after every reindex
• Knowledge Bootstrap — "This is the Way": analyse messy repos, classify files, detect duplicates, propose a cleanup plan, execute with user approval (never deletes files)
• Cold-Start Codebase Analyzer — analyze_codebase(path) scans a source code directory entirely server-side (zero tokens, zero cloud). Uses Python's built-in ast module for Python, regex for TypeScript/JavaScript, the existing MiniLM embedding model for classification and duplicate detection. Returns a single bootstrap_report.md with language distribution, category map, top 20 files to document first ranked by documentability score, duplicate pairs, and coverage gaps. Reduces cold-start token cost by ~90% on legacy codebases.
• Multi-project support — one container manages multiple knowledge repos with per-project isolation
• Includes a Web UI for configuration, monitoring, and testing

What’s New in v3.15.3 — Plain HTTP remains the default

• A new installation uses http://host:8081/sse. This is the recommended configuration until the Web UI provides TLS activation, CA download, and operating-system installation instructions. An update preserves its existing mode unless FLAIWHEEL_TLS_AUTO=0 or 1 is set explicitly.
• Automatic TLS remains available as an opt-in feature. The generated certificate is valid, but Cursor/Electron and other clients may require the Flaiwheel CA to be installed in the operating-system trust store.
• FLAIWHEEL_TLS_AUTO=0 now explicitly returns an existing TLS-enabled installation to HTTP while preserving its volumes and other MCP_* settings.
• Leaving FLAIWHEEL_TLS_AUTO unset during an update preserves the currently deployed mode.

v3.15.2 TLS caveat

v3.15.2 corrected endpoint schemes and certificate persistence, but its direct-SSE client guidance was incomplete. An env block containing NODE_EXTRA_CA_CERTS does not necessarily control TLS for a direct Cursor/Electron SSE connection. Direct clients may require the generated CA in the operating-system trust store. Use the default HTTP endpoint unless you have completed that trust step.

What’s New in v3.15.0 — Flaiwheel issues its own TLS certificate

• A LAN deployment can now be encrypted without the operator touching a certificate tool. No public CA will issue for 192.168.178.230, so the only previous options were openssl by hand or a proxy. Set MCP_SSE_TLS_AUTO=true and Flaiwheel generates a private CA plus a server certificate on first start, covering the configured hosts and loopback.
• Everything on Flaiwheel's side is automatic, and repeated starts are safe. Material is persisted in /data/tls and reused while it is valid and still covers the requested names — an upgrade does not change the fingerprint, so a client that pinned the CA stays valid. A certificate that has gone stale, stopped covering a host, or lost its matching key is re-issued, with the reason logged.
• One thing it genuinely cannot do: make another machine trust the CA. The container has no access to a client's trust store — the same boundary that forces mkcert to run a per-machine step. So the startup log prints the fingerprint and the exact NODE_EXTRA_CA_CERTS=... line for the client's env block. That is the floor, and it is real TLS: encryption and identity, with the CA pinned by trust-on-first-use.
• No NODE_TLS_REJECT_UNAUTHORIZED=0 anywhere in this path. The easy way to "make HTTPS work" is to disable verification, which defends against nothing; it is not offered as an option here.
• Opt-in, because turning it on is a protocol change. Auto-TLS flips the endpoint from http:// to https://, and doing that unasked during an upgrade would break every existing client — the same class of failure as an installer that refuses to upgrade. It fails closed too: if provisioning fails, startup aborts rather than quietly serving cleartext.
• Verified with a real TLS stack, not a fixture. A client trusting only the generated CA completes a TLSv1.3 handshake and gets a 200; an untrusting client is rejected. Both directions asserted.
• Tests: 370 → 439, covering SAN derivation, signature chain verification, idempotence, stale/mismatched material, key permissions and every fail-closed path.

What’s New in v3.14.0 — Remote MCP without a reverse proxy