Manual setup required. The maintainer's config contains paths only you know - edit the placeholders below before adding it to Claude Code.
1
Prepare the server locally
Run this once before adding it to Claude Code.
git clone https://github.com/dl4rce/flaiwheel
cd flaiwheelThen follow the repository README for any remaining dependency or build steps.
2
Register it in Claude Code
claude mcp add -e "FLAIWHEEL_DATA_PATH=${FLAIWHEEL_DATA_PATH}" flaiwheel -- docker run -i --rm -v /path/to/your/repo:/data dl4rce/flaiwheelReplace any placeholder paths in the command with the real path on your machine.
Required:
FLAIWHEEL_DATA_PATH3
Make your agent remember this setup
flaiwheel's config, env vars, and the gotchas you hit — recalled in every future Claude Code, Cursor, and Codex session.
npx conare@latestFree · one command · indexes the sessions already on disk. Set up in the browser instead →
What it does
- Hybrid search combining semantic vector search and BM25 keyword search.
- Git-native knowledge capture via post-commit hooks.
- Structured write tools for bugfixes, architecture, and API documentation.
- Cross-encoder reranking for high-precision retrieval.
- Automated impact metrics tracking for time saved and regressions avoided.
Tools 6
search_docsPerforms hybrid semantic and keyword search across project documentation.get_file_contextRetrieves spatial knowledge and context for a specific file.write_bugfix_summaryDocuments a bug fix into the knowledge base.write_architecture_docCreates or updates architectural documentation.analyze_codebaseScans a source code directory server-side for analysis.validate_docChecks markdown documentation for quality before ingestion.Environment Variables
FLAIWHEEL_DATA_PATHrequiredPath to the directory containing the knowledge base and git repository.Try it
→Search the documentation for the current authentication flow implementation.
→Get the file context for user_controller.py before I start refactoring.
→Write a bugfix summary for the memory leak issue I just resolved in the database module.
→Analyze the current codebase to identify potential architectural improvements.
→Validate my new architecture documentation before I commit it to the knowledge base.
Original README from dl4rce/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 (complementsget_recent_sessionsfor 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
- Pre-commit validation —
validate_doc()checks freeform markdown before it enters the knowledge base - 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-metricscomputes 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