A knowledge graph engine that reads, writes, and learns.
Graph intelligence. Safe writes. A feedback loop that learns from every interaction.
Zero cloud. Your Obsidian vault becomes a queryable second brain.
See It Work · Try It · What Makes It Different · Benchmarked · Docs
If you use AI with an Obsidian vault, this is for you. By default, AI agents reach for the filesystem — reading files one at a time, writing raw text, losing context between sessions. Flywheel is an MCP server that runs locally alongside your vault, giving any MCP-compatible AI a pre-indexed knowledge graph, enriched search, safe writes with auto-wikilinks, and persistent memory — so it can answer questions about your notes in milliseconds instead of reading every file.
Six lines of JSON config. No cloud. Your data never leaves your machine. Primarily tested with Claude (Code + Desktop), also works with Cursor, Windsurf, VS Code + Copilot, Continue, and any MCP client.
| Without Flywheel | With Flywheel | |
|---|---|---|
| "What's overdue?" | Read every file | Indexed query, <10ms |
| "What links here?" | Grep for name, flat list | Backlink graph, pre-indexed |
| "Add a meeting note" | Raw write, no linking | Auto-wikilinks on every mutation |
| "What should I link?" | Not possible | 10-dimension scoring + semantic search |
| Token cost | ~800-2,000 per query | ~50-200 per query (53x savings measured on brief) |
69 tools. 6-line config. Zero cloud.
From the carter-strategy demo -- a solo consultant with 3 clients, 5 projects, and $27K in invoices.
CarterStrategy.mp4
One search call returned everything -- frontmatter with amounts and status, backlink lists, outlink lists. Zero file reads needed. Without Flywheel, the AI would grep for "Acme" and scan every matching file.
❯ Log that I finished the Acme strategy deck
● flywheel › vault_add_to_section
path: "daily-notes/2026-01-04.md"
section: "Log"
content: "finished the [[Acme Corp|Acme]] strategy deck"
↑ "Acme" auto-linked to [[Acme Corp]] (alias match, no brackets typed)
You typed a plain sentence. Flywheel recognized "Acme" as an alias for Acme Corp.md and linked it — no brackets, no lookup, no manual work. That link is now a graph edge — it's why the read example above works. The section: "Log" wasn't hardcoded either — "Log" was inferred from the verb. Flywheel prefers structured notes with sections, but works fine with unstructured vaults too — it'll append to the note body if there are no headings to target.
Three layers fire on every write:
Known entity linking — Flywheel scans every entity name and alias in the vault index. Matching is deterministic — same input always produces the same links. That's the [[Acme Corp|Acme]] above.
Implicit entity detection — When implicit_detection is enabled (default), Flywheel also detects potential entities that don't have backing notes yet: proper nouns, CamelCase, quoted terms, acronyms. These become dead wikilinks — signals that "this could be a note." They're future graph edges: if you later create Marcus Johnson.md, every note that mentioned him is already linked.
Contextual suggestions — After linking, Flywheel appends → [[Entity1]], [[Entity2]] — entities the scoring engine thinks are relevant based on how your vault is structured right now. An audit note gets linked to a related client project because they co-occur across your past notes. Six months later, those → links are a snapshot of what was contextually relevant when you wrote that entry — context that would otherwise be lost. Suggestions evolve: links you keep strengthen future scoring, links you edit out get suppressed, and recency decay fades stale connections. What gets suggested reflects your vault as it is, not as it was.
Here's a richer write that triggers all three layers:
❯ Log that Stacy reviewed the security checklist before the Beta Corp kickoff
● flywheel › vault_add_to_section
path: "daily-notes/2026-01-04.md"
section: "Log"
content: "[[Stacy Thompson|Stacy]] reviewed the [[API Security Checklist|security checklist]]
before the [[Beta Corp Dashboard|Beta Corp]] kickoff
→ [[GlobalBank API Audit]], [[Acme Data Migration]]"
↑ 3 known entities auto-linked ("Stacy" resolved via alias)
→ 2 suggested links: entities co-occurring with Stacy + security across past notes
Try it yourself: cd demos/carter-strategy && claude
git clone https://github.com/velvetmonkey/flywheel-memory.git
cd flywheel-memory/demos/carter-strategy && claudeThen ask: "How much have I billed Acme Corp?"
| Demo | You are | Ask this |
|---|---|---|
| carter-strategy | Solo consultant | "How much have I billed Acme Corp?" |
| artemis-rocket | Rocket engineer | "What's blocking propulsion?" |
| startup-ops | SaaS co-founder | "What's our MRR?" |
| nexus-lab | PhD researcher | "How does AlphaFold connect to my experiment?" |
| solo-operator | Content creator | "How's revenue looking?" |
| support-desk | Support agent | "What's Sarah Chen's situation?" |
| zettelkasten | Zettelkasten student | "How does spaced repetition connect to active recall?" |
Add .mcp.json to your vault root:
{
"mcpServers": {
"flywheel": {
"command": "npx",
"args": ["-y", "@velvetmonkey/flywheel-memory"]
}
}
}cd /path/to/your/vault && claude| Preset | Tools | What you get |
|---|---|---|
default |
16 | search, read, write, tasks |
agent |
16 | search, read, write, memory |
full |
66 | Everything — all 12 categories |
Start with default (16 tools). Add bundles as you need them: graph, schema, wikilinks, temporal, diagnostics, and more.
{ "env": { "FLYWHEEL_TOOLS": "default,graph" } }Browse all 69 tools → | Preset recipes →
Windows users — read this before you start. Three things differ from macOS/Linux:
cmd /c npxinstead ofnpx— Windows installs npx as a.cmdbatch script that can't be spawned directlyVAULT_PATH— set this to your vault's Windows pathFLYWHEEL_WATCH_POLL: "true"— required. Without this, Flywheel won't pick up changes you make in Obsidian. Your search results go stale the moment you edit a note outside Claude. This is the most common source of Windows issues.See docs/CONFIGURATION.md#windows for the full config example.
Using Cursor, Windsurf, VS Code, or another editor? See docs/SETUP.md for your client's config.
Clients: Works with any MCP-compatible client. Primarily tested with Claude (Code + Desktop) via stdio. Cursor, Windsurf, VS Code + Copilot, and Continue connect via HTTP transport (
FLYWHEEL_TRANSPORT=http, port3111by default). See docs/SETUP.md for setup guides.
Every search result comes back enriched — frontmatter, ranked backlinks, ranked outlinks, and content snippets, all from an in-memory index. That's how one call answers a billing question: the search finds Acme Corp.md with its frontmatter totals, and the backlinks surface every invoice and project that wikilinks to it — each with its own frontmatter. The graph did the joining, not the AI reading files one by one.
With semantic embeddings enabled, "login security" finds notes about authentication without that exact keyword. Everything runs locally.
Those → suggestions aren't random. Ask why Flywheel suggested [[Marcus Johnson]]:
Entity Score Match Co-oc Type Context Recency Cross Hub Feedback Semantic Edge
──────────────────────────────────────────────────────────────────────────────────────────────────────
Marcus Johnson 34 +10 +3 +5 +5 +5 +3 +1 +2 0 0
10 scoring dimensions, every number traceable to vault usage. Recency came from what you last wrote. Co-occurrence came from notes you've written before. Hub came from eigenvector centrality — not just how many notes link there, but how important those linking notes are. The score learns as you use it.
See docs/ALGORITHM.md for how scoring works.
The links and suggestions above aren't static — they learn from how you interact with them.
- Co-occurrence builds over time — two entities appearing in 20 notes form a statistical bond
- Edge weights accumulate — links that survive edits gain influence
- Suppression learns — connections you repeatedly break stop being suggested
Static tools give you the same results on day 1 and day 100. Flywheel's suggestions on day 100 are informed by everything you've written and edited since day 1. No retraining, no configuration, no manual curation.
This isn't aspirational — the F1 scores below are measured under realistic noise, and they hold steady after 50 generations of accumulated feedback. See Graph Quality for the numbers.
Your AI knows what you were working on yesterday without you re-explaining it.
brief— startup context: what happened recently, what's active, what needs attentionrecall— retrieves across notes, entities, memories, and semantic search in one callmemory— stores observations that persist across sessions, with automatic decay
No session is a blank slate.
Complex vault workflows shouldn't be ad-hoc. Describe what you want in plain language — the AI creates the policy, saves it, and executes it on demand. No YAML knowledge required.
❯ Create a policy that generates a weekly review note, pulls open tasks,
and updates project frontmatter with hours logged
● flywheel › policy action=author
→ Saved .claude/policies/weekly-review.yaml
❯ Run the weekly review for this week
● flywheel › policy action=execute name=weekly-review
variables: { week: "2026-W12" }
→ Created weekly-notes/2026-W12.md
→ Updated 3 project frontmatter files
→ All steps committed atomically
Policies chain vault tools into atomic operations — all steps succeed or all roll back, committed as a single git commit. Describe the workflow once, run it whenever.
Try it yourself: cd demos/carter-strategy && claude
Every claim below is measured, reproducible, and published with source. No other MCP memory tool publishes retrieval benchmarks on standard academic datasets.
Flywheel is benchmarked on two standard retrieval datasets — one for multi-hop document retrieval, one for long-term conversational memory.
| Benchmark | What it tests | Questions | Key result |
|---|---|---|---|
| HotpotQA | Multi-hop document retrieval (Wikipedia) | 200 | 84.8% document recall |
| LoCoMo | Conversational memory across sessions | 1,531 | 90.4% Recall@10 |
HotpotQA (200 hard multi-hop questions, 1,993 documents) — End-to-end via real claude -p sessions. 82.1% on bridge (multi-hop) questions. 99.5% partial recall — only 1 of 200 questions had zero supporting docs found. $0.061/question. Beats BM25 baseline (~75%) by +10pp with zero training. Within 3pp of purpose-built ML retrievers trained on HotpotQA.
LoCoMo (10 conversations, 272 session notes, 5 question categories) — Each conversation session stored as a vault note with frontmatter dates. Unit-level retrieval: 84.8% Recall@5, 90.4% Recall@10. End-to-end (50 questions via Claude + Flywheel MCP): 71.2% evidence recall, with 91.7% on single-hop questions.
Document retrieval (HotpotQA):
| System | Type | Recall | Notes |
|---|---|---|---|
| Flywheel | MCP vault tool | 84.8% | Zero training, end-to-end via Claude |
| BM25 baseline | IR baseline | ~70-75% | Standard academic baseline |
| Baleen | Trained retriever | ~85% | Stanford, 2021. Trained on HotpotQA |
| MDR | Trained retriever | ~88% | Facebook, 2021. Trained on HotpotQA |
Conversational memory (LoCoMo):
| System | Type | Single-hop | Multi-hop | Infrastructure |
|---|---|---|---|---|
| Flywheel | MCP vault tool | 91.7% | 62.8% | Local (SQLite + markdown) |
| Ori Mnemos | Graph memory | 37.7 | 29.3 | Local (markdown) |
| Mem0 | Cloud memory | 38.7 | 28.6 | Redis + Qdrant |
| Zep | Cloud memory | 35.7 | 19.4 | Cloud service |
| LangMem | Memory framework | 35.5 | 26.0 | Varies |
| MemGPT/Letta | Agent memory | 26.7 | — | Cloud/local |
Flywheel's numbers are evidence recall (did the system find the right notes?). Ori Mnemos and others report answer accuracy (LLM-as-judge). Different metrics — evidence recall is a prerequisite for answer accuracy. Flywheel tests 1,531 questions (unit) / 50 questions (E2E). Ori Mnemos tests 695 questions.
Full benchmark methodology + comparisons →
Run them yourself: demos/hotpotqa/ | demos/locomo/
Most MCP servers ship unit tests for their handlers. Flywheel also tests whether the AI actually picks the right tool, gets the answer, and moves on — using real claude -p sessions against demo vaults with --strict-mcp-config (no filesystem, no web).
| Test | Sessions | Result |
|---|---|---|
| Per-tool coverage | 69 (1 per tool) | 100% adoption |
| Bundle adoption | 36 (12 bundles × 3) | 11/12 at 100% |
| Sequential workflow | 7 beats (cumulative state) | 7/7 passed |
| HotpotQA retrieval | 200 questions | 84.8% recall |
| LoCoMo retrieval | 1,531 questions | 90.4% Recall@10 |
Every session is captured as stream-json JSONL, analyzed by Python scripts, and reported with tool sequences and category breakdowns. Nothing is mocked. Full methodology and results
The feedback loop claim isn't asserted — it's measured. We build a test vault with known-correct links, strip them out, and measure how well the engine rediscovers them. CI locks these baselines and fails if quality regresses.
| Mode | Precision | Recall | F1 |
|---|---|---|---|
| Conservative | 51.2% | 71.7% | 59.7% |
| Balanced | 27.5% | 76.7% | 40.5% |
| Aggressive | 26.1% | 76.7% | 39.0% |
Precision = "of the links suggested, how many were correct?" (100% = never suggests a wrong link). Recall = "of the links that should exist, how many were found?" F1 = the balance of both — higher is better.
Measured against a 96-note/61-entity ground truth vault.
- 50-generation stress test — suggest → accept/reject (85% correct, 15% noise) → mutate vault → rebuild index → repeat. F1 holds steady — the feedback loop doesn't degrade under realistic noise.
- 7 vault archetypes — hub-and-spoke, hierarchical, dense-mesh, sparse-orphan, bridge-network, small-world, chaos
- 13 scoring layers individually ablated, contribution measured (including retrieval co-occurrence)
- Regression gate — CI fails if any mode's F1/precision/recall drops >5pp from baseline
See docs/TESTING.md for full methodology. Auto-generated report: docs/QUALITY_REPORT.md.
2,541 tests. 124 test files. 47,000+ lines of test code.
| Operation | Threshold | Typical |
|---|---|---|
| 1k-line mutation | <100ms | ~15ms |
| 10k-line mutation | <500ms | -- |
| 100k-line mutation | <2s | -- |
- 100 parallel writes, zero corruption -- concurrent mutations verified under stress
- Property-based fuzzing -- 700+ randomized scenarios
- SQL injection prevention -- parameterized queries throughout
- Path traversal blocking -- all file paths validated against vault root
Every mutation is:
- Git-committed — one
vault_undo_last_mutationaway from reverting any change - Conflict-detected — SHA-256 content hash checked before every write; if the file changed since it was read, the mutation is rejected with a diagnostic showing exactly what changed and how to recover
- Policy-governed — configurable guardrails with warn/strict/off modes
- Dry-run preview — every write tool supports
dry_run: trueto see exactly what would change before touching disk - Precise — auto-wikilinks have 1.0 precision in production (never inserts a wrong link)
AST-protected wikilinks. Before inserting any link, Flywheel parses the Markdown AST to identify protected zones where links must never go — code blocks, inline code, YAML frontmatter, existing [[wikilinks]] and [markdown](links), bare URLs, HTML tags and comments, Obsidian callouts (including nested callouts), pipe tables, math expressions, and hashtags. Pure regex can't reliably handle nested callouts or multi-line HTML; the AST parser does, with a transparent regex fallback if parsing fails.
Feedback-driven suppression. Two layers keep bad links from recurring. The wikilink_feedback tool records explicit positive/negative feedback on any entity-note pair. If you simply delete a [[wikilink]] from a note, the watcher detects the removal and records implicit negative feedback — no manual action needed. Over time, entities that are consistently rejected or removed get suppressed via a Beta-Binomial posterior model — globally or per-folder. Deleted notes are handled cleanly: they don't generate false negative feedback against the entity.
See docs/PROVE-IT.md for a 5-minute walkthrough.
Most Obsidian AI tools are either simple MCP bridges (read/write files, no graph) or cloud-dependent embedding search (no local processing, no learning). Flywheel is neither:
| Capability | Flywheel Memory | Typical MCP bridge | Typical AI plugin |
|---|---|---|---|
| Backlink graph | Bidirectional, eigenvector centrality | No | No |
| Search | Local hybrid (BM25 + semantic) | Basic file read | Cloud embedding |
| Auto-wikilinks | Yes (alias resolution, 18 entity categories) | No | No |
| Schema intelligence | 9 analysis modes | No | No |
| Learns from usage | Feedback loop + suppression + co-occurrence | No | No |
| Agent memory | brief + recall + memory | No | No |
| Safe writes | Git + conflict detection + dry-run | No | N/A |
| Retrieval benchmarks | HotpotQA 84.8%, LoCoMo 90.4% | None published | None published |
| Tool count | 69 | ~5-15 | 0 (plugin) |
| Doc | Why read this |
|---|---|
| PROVE-IT.md | See it working in 5 minutes |
| TOOLS.md | All 69 tools documented |
| ALGORITHM.md | How the scoring works |
| COOKBOOK.md | Example prompts by use case |
| SETUP.md | Full setup guide for your vault |
| CONFIGURATION.md | Env vars, presets, custom tool sets |
| ARCHITECTURE.md | Index strategy, graph, auto-wikilinks |
| TESTING.md | Test methodology and benchmarks |
| TROUBLESHOOTING.md | Error recovery and diagnostics |
| VISION.md | Where this is going |
AGPL-3.0 — see LICENSE for details.