Flaiwheel is a self-hosted memory and governance layer designed specifically for AI coding agents, with the goal of turning every bug fix into permanent knowledge, achieving zero cloud dependency and zero lock-in.
[Purpose] AI coding agents forget everything between sessions, leading to repeated bugs, lost architectural decisions, and knowledge decay. Flaiwheel lets agents retrieve before coding and write documentation after fixing, with commits automatically capturing knowledge, so that memory compounds over time—every bug fixed makes the next bug cheaper. It does not replace AI assistants, but makes them reliable at scale.
[Main Capabilities]
- Persistent AI memory: knowledge is not reset between sessions.
- Git-native automation: commits are automatically transformed into structured knowledge.
- Governance rather than mere storage: quality gates + enforced documentation.
- Hybrid retrieval + reranking: high-precision context for real codebases.
- Fully self-hosted: a single Docker container, no external infrastructure.
- Zero lock-in: all knowledge is stored in Git as structured flat files.
[Technical Features] Flaiwheel is a self-contained Docker service that operates on three levels: Pull (agents retrieve before coding, using search_docs, get_file_context), Push (agents record while working, using write_bugfix_summary, write_architecture_doc, etc.), Capture (git commits automatically capture knowledge through a post-commit hook, effective even without an AI agent).
It indexes project documentation (.md, .pdf, .html, .docx, .rst, .txt, .json, .yaml, .csv) into a vector database and provides an MCP server for AI agents (Cursor, Claude Code, VS Code Copilot) to connect to. Hybrid retrieval combines semantic vector search with BM25 keyword search, achieving the best of both through Reciprocal Rank Fusion (RRF); an optional cross-encoder reranking step rescores candidate results with a cross-encoder model, significantly improving precision on queries with vocabulary mismatch.
Behavioral Directives let AI agents silently retrieve from Flaiwheel before every response, and every taskAutomatically recorded after tasks and reused before rebuilding, without manual requests. get_file_context(filename) preloads spatial knowledge for the file the agent is about to edit (complementing get_recent_sessions, providing complete temporal + spatial context). The post-commit git hook automatically captures fix:, feat:, refactor:, perf:, and docs: commits as structured knowledge documents. Living Architecture requires AI agents to maintain self-updating Mermaid.js system component and flow diagrams. Executable test flows record test scenarios in a machine-readable BDD/Gherkin format (Given, When, Then) for QA automation. After an agent writes a bugfix summary, it is indexed immediately.
Structured writing tools include 7 category-specific tools (bugfix, architecture, API, best-practice, setup, changelog, test case), enforcing quality at the source. Structured relations (v1) derive each project's knowledge graph from optional YAML frontmatter (id, replaces, depends_on, fixes, implements, status) in existing documents via relations() and timeline(), with no second store—markdown remains authoritative, and Git history is the validity window. pre-commit validation checks free-form markdown via validate_doc() before it enters the knowledge base, including warnings for unknown relation keys. The ingestion quality gate automatically skips files with serious issues at index time (never deletes—the files are yours). Automatic sync via Git pulls from and pushes to a dedicated knowledge repository.
Tool telemetry (persistent) tracks every MCP call per project (retrieval, writes, misses, patterns), detects knowledge gaps and prompts agents to record, persists across restarts, and is visible in the Web UI. The impact metrics API /api/impact-metrics calculates estimated time saved and regressions avoided; CI pipelines can submit guardrail results to /api/telemetry/ci-guardrail-report. Proactive quality checks automatically validate the knowledge base after each reindex. Knowledge Bootstrap ("This is the Way") analyzes messy repositories, classifies files, detects duplicates, proposes a cleanup plan, and executes it after user approval (never deletes files).
Cold-start codebase analyzer analyze_codebase(path) scans source code directories entirely server-side (zero tokens, zero cloud). It uses the built-in ast module for Python and regex for TypeScript/JavaScript, and uses the existing MiniLM embedding model for classification and duplicate detection. It returns a single bootstrap_report.md containing language distribution, category mapping, the top 20 priority files to document ranked by documentability score, duplicate pairs, and coverage gaps. It can reduce cold-start token costs by about 90% on legacy codebases.
Multi-project support: one container manages multiple knowledge repositories, isolated by project. Includes a Web UI for configuration, monitoring, and testing.
[Usage] Self-hosted deployment as a single Docker container, connected to AI coding agents via an MCP server. Uses a pure HTTP endpoint by default http://host:8081/sse，这是推荐配置，直到 The Web UI provides TLS activation, CA download, and operating system installation instructions. Updates preserve the existing mode unless FLAIWHEEL_TLS_AUTO=0 or 1 is explicitly set. Automatic TLS is an optional feature: after setting MCP_SSE_TLS_AUTO=true, Flaiwheel generates a private CA and server certificate on first startup, covering the configured hosts and loopback addresses; the material is persisted in /data/tls and reused when valid and still covering the requested names. However, the container cannot make another machine trust that CA, and the startup log prints the fingerprint and the NODE_EXTRA_CA_CERTS=... line required by the client environment block. Remote MCP requires no reverse proxy: set MCP_SSE_ALLOWED_HOSTS=flaiwheel.example.com to connect directly; for native TLS, set MCP_SSE_TLS_CERTFILE + MCP_SSE_TLS_KEYFILE to serve directly over HTTPS. TLS failure means shutdown: a half-configured or unreadable certificate aborts startup rather than silently serving plaintext.
[Applicable scenarios] Suitable for engineering teams using AI coding assistants in real projects, codebases where repeated bugs are costly, teams needing full data control, and AI-native development environments.
[Limitations] Not suitable for small hobby projects under a few thousand lines, nor for developers who only want better autocompletion, nor for pure SaaS workflows with no intention of self-hosting.
[Version highlights] v3.15.3: plain HTTP is still the default. v3.15.0: Flaiwheel issues its own TLS certificates, tests increased from 370 to 439. v3.14.0: remote MCP without a reverse proxy, tests increased from 335 to 370. v3.13.0: observability, check_divergence() compares HEAD with @{u} and classifies as synced / ahead / behind / diverged / no-upstream, /health adds divergence_status, commits_ahead, commits_behind, and last_divergence_at, tests increased from 316 to 335. v3.12.3: every dependency is constrained below the next major version.
