{"id":41997062,"url":"https://github.com/velvetmonkey/flywheel","last_synced_at":"2026-02-12T13:44:00.322Z","repository":{"id":335696087,"uuid":"1145004773","full_name":"velvetmonkey/flywheel","owner":"velvetmonkey","description":"Graph intelligence for markdown vaults","archived":false,"fork":false,"pushed_at":"2026-02-09T18:22:10.000Z","size":7679,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-09T19:50:54.932Z","etag":null,"topics":["agentic-ai","ai-agents","backlinks","bounded-autonomy","claude-code","knowledge-graph","markdown","mcp","mcp-server","nodejs","obsidian","pkm","semantic-search","typescript","vault","workflow-orchestration"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/velvetmonkey.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-29T09:58:25.000Z","updated_at":"2026-02-09T18:22:06.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/velvetmonkey/flywheel","commit_stats":null,"previous_names":["velvetmonkey/flywheel"],"tags_count":49,"template":false,"template_full_name":null,"purl":"pkg:github/velvetmonkey/flywheel","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/velvetmonkey%2Fflywheel","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/velvetmonkey%2Fflywheel/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/velvetmonkey%2Fflywheel/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/velvetmonkey%2Fflywheel/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/velvetmonkey","download_url":"https://codeload.github.com/velvetmonkey/flywheel/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/velvetmonkey%2Fflywheel/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29367639,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-12T08:51:36.827Z","status":"ssl_error","status_checked_at":"2026-02-12T08:51:26.849Z","response_time":55,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-ai","ai-agents","backlinks","bounded-autonomy","claude-code","knowledge-graph","markdown","mcp","mcp-server","nodejs","obsidian","pkm","semantic-search","typescript","vault","workflow-orchestration"],"created_at":"2026-01-26T01:07:13.556Z","updated_at":"2026-02-12T13:44:00.317Z","avatar_url":"https://github.com/velvetmonkey.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003e Flywheel (51 read-only tools) + [Flywheel-Crank](https://github.com/velvetmonkey/flywheel-crank) (11 mutation tools) work together. See the [Platform Installation Guide](docs/INSTALL.md) for your OS.\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"header.png\" alt=\"Flywheel\" width=\"256\"/\u003e\n\u003c/div\u003e\n\n# Flywheel\n\n### MCP server for markdown vault intelligence\n\n[![MCP](https://img.shields.io/badge/MCP-Model%20Context%20Protocol-blueviolet.svg)](https://modelcontextprotocol.io/)\n[![CI](https://github.com/velvetmonkey/flywheel/actions/workflows/ci.yml/badge.svg)](https://github.com/velvetmonkey/flywheel/actions/workflows/ci.yml)\n[![npm version](https://img.shields.io/npm/v/@velvetmonkey/flywheel-mcp.svg)](https://www.npmjs.com/package/@velvetmonkey/flywheel-mcp)\n[![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0)\n[![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-blue.svg)](https://github.com/velvetmonkey/flywheel)\n[![Scale](https://img.shields.io/badge/scale-100k%20notes-brightgreen.svg)](./docs/SCALE_BENCHMARKS.md)\n\n**Stop burning tokens. Start building agents.** Give Claude graph intelligence over your Obsidian vault without reading files.\n\n## Verified Capabilities\n\n✅ **100k Note Scale** - Index building and queries tested at 100,000 notes\n✅ **51 Read-Only Tools** - Comprehensive graph intelligence without mutation risk\n✅ **Cross-Platform** - Tested on Ubuntu, Windows, macOS (Intel + ARM)\n✅ **Sub-Second Queries** - Graph traversal, backlinks, hub detection \u003c100ms\n✅ **Entity Detection** - Automatic extraction of people, projects, tech, acronyms\n\n---\n\nClaude reading files on every query? Those tokens add up fast.\n\nFlywheel queries an in-memory index instead of reading files. Graph queries (backlinks, tags, tasks) return structured results without touching file content.\n\n**The real win:** Your agents can now query your knowledge *hundreds of times* during long-running tasks without blowing up the context window.\n\n---\n\n## Quick Start\n\n**Prerequisites:** Node.js 18+, Claude Code or MCP client, an Obsidian vault (or any markdown folder)\n\n**1. Create `.mcp.json`** in your vault root:\n\n```json\n{\n  \"mcpServers\": {\n    \"flywheel\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@velvetmonkey/flywheel-mcp\"]\n    }\n  }\n}\n```\n\n\u003e **Windows:** Use `\"command\": \"cmd\", \"args\": [\"/c\", \"npx\", \"-y\", \"@velvetmonkey/flywheel-mcp\"]` with `\"env\": { \"FLYWHEEL_WATCH_POLL\": \"true\" }` for reliable file watching.\n\u003e\n\u003e **WSL:** Add `\"env\": { \"FLYWHEEL_WATCH_POLL\": \"true\" }` if your vault is on a Windows drive (`/mnt/c/...`). See [Configuration](docs/CONFIGURATION.md) for details.\n\n**2. Restart Claude Code** and verify with `claude mcp list` — you should see `flywheel ✓`\n\nThat's it. Flywheel uses the current directory as your vault—no config needed.\n\nSee [Configuration](docs/CONFIGURATION.md) for environment variables, tool filtering, and platform setup.\n\n---\n\n## See It In Action\n\n### Carter Consultancy: Meeting Prep in 30 Seconds\n\nYou're Carter, a solo consultant. Three active clients, $200K in annual revenue, and a meeting with Acme Corp in 10 minutes. You haven't looked at their file in weeks.\n\n**The Prompt:**\n```\nYou: What do I need to know about Acme Corp before this call?\n```\n\n**Claude Uses Flywheel:**\n```\n[search_notes: \"Acme Corp\"]\n[get_backlinks: \"clients/Acme Corp.md\"]\n[get_note_metadata: \"clients/Acme Corp.md\"]\n```\n\n**The Answer (2 seconds, ~200 tokens):**\n```\nAcme Corp - Quick Brief:\n━━━━━━━━━━━━━━━━━━━━━━━━\nContact: Sarah Mitchell, VP Technology\nStatus: Active - Phase 2 of data migration\n\nCurrent Project: [[Acme Data Migration]]\n  Budget: $75,000 | Billed: $42,000\n  Timeline: Oct 2025 - Mar 2026\n\nPending: [[INV-2025-048]] - $12,000 (December)\nOpportunity: [[Acme Analytics Add-on]] - $35,000 proposal\n\nLast touch: 2025-12-30\n```\n\n**Without Flywheel:** Claude reads 12 files (~6,000 tokens) to find this.\n**With Flywheel:** Graph query returns structured data. 30× more efficient.\n\n### Follow-Up: \"What If They Go Amber?\"\n\n```\nYou: If Acme delays to Q3, what happens to my Q1 revenue?\n\nClaude: [get_backlinks + frontmatter queries across projects/]\n\nImpact Analysis:\n━━━━━━━━━━━━━━━\nIf Acme Data Migration slips:\n  - Q1 gap: $33,000 (remaining Acme budget)\n  - Current Q1 pipeline: $42,000\n\nMitigation options:\n  - [[Beta Corp Dashboard]] needs React help (understaffed)\n  - [[Stacy Thompson]] at 40% utilization - available for reallocation\n\nYour Q1 stays green if Beta Corp accelerates.\n```\n\nThis is graph intelligence: backlinks, frontmatter queries, and relationship traversal—all without reading file contents.\n\n### The Complete Picture\n\nFlywheel gives you **eyes**: 51 read-only tools for querying your knowledge graph.\n\nBut reading isn't enough. When Carter finishes that call and needs to onboard a new project, update client files, and log the meeting—that's **writing**.\n\nFor mutations, see **[Flywheel-Crank](https://github.com/velvetmonkey/flywheel-crank)**: deterministic vault automation with auto-wikilinks, atomic commits, and policy-as-code.\n\n**Eyes + Hands = Complete vault intelligence.**\n\n---\n\n## Try a Demo\n\n5 production-ready vaults representing real knowledge work personas:\n\n| Demo | Persona | Notes | Try Asking |\n|------|---------|-------|------------|\n| **[carter-strategy](demos/carter-strategy/)** | Solo Consultant | 32 | \"How much have I billed Acme Corp?\" |\n| **[artemis-rocket](demos/artemis-rocket/)** | Aerospace Engineer | 65 | \"What's blocking the propulsion milestone?\" |\n| **[startup-ops](demos/startup-ops/)** | SaaS Co-Founder | 31 | \"Walk me through onboarding DataDriven\" |\n| **[nexus-lab](demos/nexus-lab/)** | PhD Researcher | 32 | \"How does AlphaFold connect to my experiment?\" |\n| **[solo-operator](demos/solo-operator/)** | Content Creator | 19 | \"What's my financial runway?\" |\n\n```bash\ngit clone https://github.com/velvetmonkey/flywheel.git\ncd flywheel/demos/artemis-rocket \u0026\u0026 claude\n```\n\n---\n\n## What This Unlocks\n\n- **Graph intelligence** — backlinks, orphans, hubs, connection paths\n- **Vault health monitoring** — find disconnected notes, stale hubs, broken links\n- **Connection discovery** — \"how does X relate to Y?\" answered in milliseconds\n- **Schema queries** on frontmatter without reading files\n- **Agentic workflows** that query your knowledge hundreds of times without token bloat\n\n---\n\n## Why Markdown + Graph?\n\n- **Git-native** — version-controlled knowledge\n- **Plain text** — future-proof, zero lock-in\n- **Privacy** — files stay local, only what you need gets sent\n- **Editor-agnostic** — Obsidian, VSCode, Cursor, vim, whatever\n- **AI-native** — 51 tools purpose-built for agent workflows\n\n---\n\n## Who Uses Flywheel?\n\n**You might be:**\n\n| Persona | Your Problem | Flywheel Gives You |\n|---------|--------------|-------------------|\n| 🧠 **PKM Practitioner** | Manual linking is tedious | Auto-wikilinks build connections as you write |\n| 🤖 **Agent Builder** | AI burns tokens reading files | 51 graph queries, zero file reads |\n| 🐵 **Chaos Monkey** | Markdown chaos, can't find anything | Structure emerges from motion |\n| 💻 **Developer** | Code notes scattered across projects | Queryable second brain |\n| 📊 **Knowledge Worker** | \"Where's that decision from last month?\" | Frontmatter + graph = instant retrieval |\n| ✍️ **Writer/Researcher** | Missing connections between sources | Backlinks reveal unexpected paths |\n| 👥 **Teams** | Shared vault coordination is messy | Multi-agent access to shared knowledge graph |\n| 🎙️ **Voice-to-Vault** | Mobile capture lands in chaos | Whisper → Crank → auto-linked notes |\n\n### Inspiration from Builders in Public\n\nPeople doing interesting work with markdown knowledge bases:\n\n- **Andy Matuschak** — [Evergreen notes](https://notes.andymatuschak.org/) on augmented cognition\n- **Simon Willison** — [TIL](https://til.simonwillison.net/) public learning, Datasette creator\n- **Maggie Appleton** — [Digital Gardeners](https://github.com/MaggieAppleton/digital-gardeners) community\n- **Kepano** — [Obsidian Skills](https://github.com/kepano/obsidian-skills) for agent automation\n- **Sonny Huynh** — [AI-Powered Second Brain](https://sonnyhuynhb.medium.com/i-built-an-ai-powered-second-brain-with-obsidian-claude-code-heres-how-b70e28100099) with Claude Code\n- **MarkdownDB** — [Markdown as database](https://github.com/datopian/markdowndb) philosophy\n\n### Get Involved\n\n- [Star on GitHub](https://github.com/velvetmonkey/flywheel) — helps others discover the project\n- [Report issues or share ideas](https://github.com/velvetmonkey/flywheel/issues) — bugs, features, workflow tips\n\n---\n\n## Prove It Yourself\n\nDon't trust marketing. Run the tests:\n\n```bash\n# Clone the ecosystem\ngit clone https://github.com/velvetmonkey/flywheel\ngit clone https://github.com/velvetmonkey/flywheel-crank\n\n# Run flywheel tests (432 tests - read tools, demos)\ncd flywheel \u0026\u0026 npm install \u0026\u0026 npm test\n\n# Run demo documentation tests\ncd flywheel \u0026\u0026 npm run test:demos\n\n# Run flywheel-crank tests (1,472 tests - mutations, scale, security)\ncd ../flywheel-crank \u0026\u0026 npm install \u0026\u0026 npm test\n```\n\n**Total: 1,904 tests** proving the ecosystem works.\n\n| Repo | Tests | Proves |\n|------|-------|--------|\n| **flywheel** | 432 | Graph queries, entity indexing, file watching |\n| **flywheel-crank** | 1,472 | Mutations at scale, format preservation, security |\n\n### Test Scripts\n\n| Script | Purpose |\n|--------|---------|\n| `npm test` | Run all tests |\n| `npm run test:demos` | Verify README examples against demo vaults |\n\n---\n\n## Docs\n\n- **[Installation Guide](docs/INSTALL.md)** — Platform-specific setup (Windows, macOS, Linux, WSL)\n- **[Configuration](docs/CONFIGURATION.md)** — Environment variables, tool presets, platform setup\n- **[MCP Tools Reference](docs/MCP_REFERENCE.md)** — All 51 tools\n- **[Query Guide](docs/QUERY_GUIDE.md)** — Patterns and examples\n- **[How It Works](docs/HOW_IT_WORKS.md)** — Architecture and token savings\n- **[Vault Health](docs/VAULT_HEALTH.md)** — Monitor and improve vault structure\n- **[Performance](docs/PERFORMANCE.md)** — Benchmarks and optimization\n- **[Privacy](docs/PRIVACY.md)** — Data handling and security\n- **[Troubleshooting](docs/TROUBLESHOOTING.md)** — Common issues and fixes\n\n---\n\nmacOS / Linux / WSL / Windows\n\nApache-2.0 License · [GitHub](https://github.com/velvetmonkey/flywheel) · [Issues](https://github.com/velvetmonkey/flywheel/issues)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvelvetmonkey%2Fflywheel","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvelvetmonkey%2Fflywheel","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvelvetmonkey%2Fflywheel/lists"}