Flaiwheel

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.11.0

• Telemetry now survives docker volume rm flaiwheel-data. A per-project summary slice is mirrored from the Docker volume into each knowledge repo at <docs_path>/.flaiwheel/telemetry.json. On the next cold start, hydrate_from_mirrors() rebuilds the in-memory state from these files so the Tool Telemetry dashboard does not reset to zero. Hot tier wins when both exist; mirror writes are rate-limited to 60s/project to avoid one Git commit per tool call. Events stay in the volume only (too noisy for the knowledge repo). Don't want it committed? Add .flaiwheel/ to your knowledge repo's .gitignore — Flaiwheel will still read/write the file locally.
• Reset Telemetry button on every per-project tile in the Web UI. Zeroes summary counters across both storage tiers via the new POST /api/telemetry/reset?project=<name> endpoint. The 30-day impact-metrics window keeps working because events history is preserved.
• Agent instructions taught the relations workflow. AGENTS.md and both install.sh templates now include a "Structured Relations Workflow" section with three concrete rules (when to add fixes, when to add replaces, when to add depends_on) so agents actually use the v3.10.x graph machinery instead of ignoring it.
• Client Configuration's "VS Code" tab is now "VS Code + Copilot" with explicit help text pointing at GitHub Copilot agent mode. The .vscode/mcp.json file Flaiwheel emits already works for Copilot — no separate snippet needed.
• Tests: 292 → 300 (8 new tests in test_telemetry.py for mirror writes, rate limiting, cold-start hydration, hot-tier authority, and reset semantics).

Previous: v3.10.1

• Every structured writer now auto-emits frontmatter. write_bugfix_summary, write_architecture_doc, write_api_doc, write_best_practice, write_setup_doc, write_changelog_entry, and write_test_case prepend id / type / status: active + empty relation lists to every new doc. Every doc you create from now on is automatically a graph node — no manual frontmatter editing required. IDs are derived from the existing filename slugs (e.g. adr-2026-05-22-payment-service-architecture, bugfix-2026-05-22-fix-race-condition, api-create-user-endpoint).
• New helper flaiwheel.frontmatter.emit() with stable, deterministic key order so same-day overwrites produce minimal diffs.

Previous: v3.10.0

• Structured relations (v1) — two new read-only MCP tools, relations(entity_id) and timeline(entity_id), derive a per-project knowledge graph from YAML frontmatter on existing markdown docs. No new persistent store and no graph_add / invalidate writes: markdown stays the single source of truth and Git history is the validity window. Recognised relation keys: replaces, depends_on, fixes, implements. Scalar keys: id, type, status, superseded_at.
• Frontmatter-aware quality checks — validate_doc() now warns on unknown relation keys (info severity) and invalid status values (warning severity); heading-structure checks strip the leading --- block first so frontmatter does not confuse the "first heading is h1" rule.
• GitWatcher.log_for_file() — read-only helper returning newest-first commits (hash, author, ISO date, subject); backs the timeline() tool.
• Zero new dependencies — frontmatter parsing is stdlib-only (flaiwheel.frontmatter). No python-frontmatter / PyYAML added.
• Total tools: 28 → 30.

Note: the SQLite ER store (graph_add / graph_invalidate / valid_from / valid_to columns) originally proposed for this feature is deferred as v2, gated on a real query becoming measurably too slow on v1. AST-driven code↔symbol edges (v3) remain merged with the feature_ideas_backlog #13 track.

Previous: v3.9.40

• Installer: claude-md no longer fails on repeat runs — claude mcp add non-zero exits (e.g. MCP already registered) no longer abort the parallel phase under set -e; registration output is captured safely.
• Installer: correct release version from GitHub — _FW_VERSION is refreshed from main pyproject.toml when reachable so Docker rebuild / version checks stay aligned with the package even if raw install.sh on main lags at the CDN.

Previous: v3.9.29

• Glama tool detection fix — AuthManager crashed on read-only /data before the MCP server could start (the real reason Glama saw 0 tools). Skipped in stdio cold-start mode.
• Zero print() on stdout — 36 remaining print() in watcher, indexer, readers, bootstrap replaced with diag() (stderr). Verified: full MCP handshake returns all 28 tools over stdio.
• config.save() resilient — read-only filesystem logs warning instead of crashing.

Previous: v3.9.28

• Glama / MCP stdio fix — all diagnostic output moved to stderr; stdout is now JSON-RPC only. Glama Inspector now detects all 28 tools correctly.
• Improved cold-start detection — stdio cold-start logic handles empty Docker volumes correctly (no bootstrap / model download during Glama inspection).

Previous: v3.9.27

• License cleanup — one LICENSE file (BSL 1.1) for correct GitHub/Glama detection; all docs and headers point to LICENSE (not LICENSE.md).
• Glama / stdio inspection — optional [inspect] deps and cold-start stdio path for lightweight MCP directory builds.

Previous: v3.9.26

• Claude Cowork skill — the Flaiwheel workflow is now distributed as a native Claude skill. The installer writes .skills/skills/flaiwheel/SKILL.md to your project. When you open the project in Claude (Cowork), the skill is auto-available — no extra setup needed. The skill drives session-start context restore, pre-coding knowledge search, mandatory post-bugfix documentation, and session-end summarisation.
• Skill source also committed to skills/flaiwheel/SKILL.md in this repo for

…