Flywheel

Flywheel turns your Obsidian vault into safe local memory for AI agents.

Search your notes with real context, write back safely, and keep your Markdown on your machine.

Get Started · See It Work · What It Does · Skills + Flywheel · Benchmarks · Testing · Documentation · License

Flywheel is a local-first memory layer for AI agents working over Obsidian and plain Markdown. It gives agents grounded search across your notes, safe bounded writes back into the vault, and local indexes that stay on your machine.

Built for people who want AI to work over real notes without handing their vault to a cloud app. Your files stay readable Markdown, semantic search is optional and local, and every write is inspectable and reversible.

• Grounded search — find the notes that matter, plus the linked context around them, without making the model trawl through a pile of files.
• Safe reversible writes — update a live vault through bounded operations that preserve Markdown structure and can be undone.
• Local-first by default — keep your notes on disk, use plain Markdown as the source of truth, and add local semantic search only if you want it.

Raw file access gives an agent text, not memory. Flywheel adds better ranking across notes, linked context that helps the model stay grounded, and write operations that are bounded enough to trust inside a live vault.

From the carter-strategy demo:

1. Ask: "How much have I billed Acme Corp?"
2. Flywheel searches the right notes, returns connected context, and answers from the vault.
3. If you want to act on the result, the same session can log follow-ups or update the right note as a visible, bounded change.

git clone https://github.com/velvetmonkey/flywheel-memory.git
cd flywheel-memory/demos/carter-strategy && claude

Then ask: "How much have I billed Acme Corp?"

Add .mcp.json to your vault root:

{
  "mcpServers": {
    "flywheel": {
      "command": "npx",
      "args": ["-y", "@velvetmonkey/flywheel-memory"]
    }
  }
}

cd /path/to/your/vault && claude

Flywheel watches the vault, maintains local indexes, and serves structured context to MCP clients. Your source of truth stays in Markdown. If you delete .flywheel/state.db, Flywheel rebuilds from the vault.

The agent preset (default) provides a focused set of core tools. Use power for tier 1+2 (adds wikilinks, corrections, note-ops, schema), full to expose the entire tool surface immediately, or auto for the full surface plus the informational discover_tools helper.

Claude Code note: the memory merged tool is suppressed under Claude Code (CLAUDECODE=1) because Claude Code ships its own memory plane. Agent preset exposes 12 tools under Claude Code instead of 13; the briefing entrypoint still works as memory(action: "brief").

Compose bundles for custom configurations:

{
  "mcpServers": {
    "flywheel": {
      "command": "npx",
      "args": ["-y", "@velvetmonkey/flywheel-memory"],
      "env": {
        "FLYWHEEL_TOOLS": "agent,graph"
      }
    }
  }
}

Browse all tools -> | Preset recipes ->

Serve more than one vault from a single Flywheel instance with FLYWHEEL_VAULTS:

{
  "mcpServers": {
    "flywheel": {
      "command": "npx",
      "args": ["-y", "@velvetmonkey/flywheel-memory"],
      "env": {
        "FLYWHEEL_VAULTS": "personal:/home/you/obsidian/Personal,work:/home/you/obsidian/Work"
      }
    }
  }
}

Search automatically spans all vaults and tags each result with its source vault. Each vault keeps separate indexes, graph state, file watchers, and config.

Full multi-vault configuration -> | Client setup examples ->

If you use Cursor, Windsurf, VS Code, OpenClaw, or another client, see docs/SETUP.md for client-specific configuration. For OpenClaw, use the dedicated OpenClaw integration guide.

From the carter-strategy demo: log a call by voice, watch wikilinks and suggestions appear, accept and reject a few, then log again — the suggestions improve immediately.

> Log that Stacy reviewed the security checklist before the Beta Corp kickoff

flywheel -> edit_section action=add
  path: "daily-notes/2026-01-04.md"
  section: "Log"
  suggestOutgoingLinks: true
  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]]"

You type a normal sentence. Flywheel resolves known entities, detects prospective entities (proper nouns, acronyms, CamelCase terms), and adds wikilinks and suggests related links based on aliases, co-occurrence, graph structure, and semantic context. Suggested outgoing links are optional and off by default. Enable them where you want the graph to grow naturally, such as daily notes, meeting logs, or voice capture. Configuration guide ->

• Writes happen through visible tool calls.
• Changes stay within the vault unless you explicitly point a tool somewhere else.
• Git commits are opt-in.
• Proactive linking can be disabled.

Reproduce it yourself: The carter-strategy demo includes a run-demo-test.sh script that runs the full sequence end to end with claude -p, checking tool usage and vault state between steps.

> Create a policy that finds overdue invoices and logs follow-up tasks in today's daily note

flywheel -> policy action=author
  description: "Find invoices with status:sent, create follow-up task list in daily note"
  ✓ Saved to .flywheel/policies/overdue-invoice-chaser.yaml

> Preview the overdue-invoice-chaser policy

flywheel -> policy action=preview name=overdue-invoice-chaser
  Step 1: vault_search: query "type:invoice status:sent" in invoices/ -> 3 results
  Step 2: edit_section: would append to daily-notes/2026-03-31.md#Tasks
  (no changes made; preview only)

> Execute it

flywheel -> policy action=execute name=overdue-invoice-chaser
  ✓ 2 steps executed, 1 note modified, committed as single git commit

One search call returns enough context for the model to answer grounded questions: frontmatter, section-aware snippets, dates, and linked notes that matter. Keyword search (BM25) handles exact terms. Optional local semantic search helps when the right note is related but not explicitly linked yet. Together they reduce file-hopping and make answers more reliable over a real vault. How search works ->

Every mutation is conflict-detected with a SHA-256 content hash and reversible with one undo. Writes preserve Markdown structure, so edits do not corrupt tables, callouts, code blocks, frontmatter, links, comments, or math. Auto-wikilinks stay deterministic and traceable. For one-off edits, use the direct write tools. For repeatable workflows that search the vault and act on the results, use policies, saved YAML workflows that branch on vault state and run multiple write steps as a single atomic operation. How scoring works -> | Policies guide ->

Every accepted link strengthens the graph. Every rejected link updates the scorer. Every write adds more context for the next read. memory(action: "brief") assembles a token-budgeted summary of recent activity, and memory persists observations with confidence decay. The graph can be exported through graph(action: "export") as GraphML for visualization in tools like Gephi or NetworkX — see the carter-strategy demo for an example. Configuration ->

Skills encode methodology: how to do something. Flywheel encodes knowledge: what you know. They are complementary layers:

An agent calling a proposal-writing skill works better when it can also search your vault for the client's history, past invoices, project notes, and team relationships. Skills tell agents how to work. Flywheel tells them what you know.

OpenClaw skills and Flywheel connect through MCP. OpenClaw routes intent and manages session flow; Flywheel provides the structured context and safe writes that make responses accurate. Integration guide ->

Flywheel Memory is the core memory engine. Flywheel Crank is the Obsidian plugin that visualizes the same local graph and workflows. Flywheel Engine is the service layer that calls Flywheel over MCP. Start with Flywheel Memory; add the other layers when you want UI or automation around the same vault.

Agent-first tools should prove their claims. Flywheel ships with reproducible benchmarks against academic retrieval standards:

• HotpotQA full end to end: 90.0% document recall on 50 questions / 4,960 docs. Latest artifact: April 10, 2026. Cost in that run: $0.083/question.
• LoCoMo full end to end: 81.9% evidence recall and 54.0% answer accuracy on 695 scored questions / 272 sessions. Latest artifact: April 10, 2026. Final token F1: 0.431.
• LoCoMo unit retrieval: 84.8% Recall@5 and 90.4% Recall@10 on the full non-adversarial retrieval set.

Every number below ties back to a checked-in report or reproducible harness in the repo.

Multi-hop retrieval vs. academic baselines (HotpotQA, 500 questions, 4,960 documents):

Conversational memory retrieval (LoCoMo, 1,531 scored retrieval queries, 272 session notes):

E2E with Claude Sonnet (latest checked-in 695-question run): 97.4% single-hop evidence recall, 73.7% multi-hop evidence recall, 81.9% overall evidence recall, and 54.0% answer accuracy (Claude Haiku judge). Full methodology and caveats ->

Directional, not apples-to-apples. Test settings, sample sizes, retrieval pools, and metrics differ. Flywheel searches 4,960 pooled docs, which is harder than the standard HotpotQA distractor setting of 10 docs and much smaller than fullwiki. Academic retrievers are trained on the benchmark; Flywheel uses no benchmark training data. Expect about 1 percentage point of run-to-run variance from LLM non-determinism. Full caveats ->

demos/hotpotqa/ · demos/locomo/ · Full methodology ->

3,292 defined tests across 185 test files and about 64.4k lines of test code. CI runs focused jobs on Ubuntu, plus a full matrix on Ubuntu and Windows across Node 22 and 24.

• Graph quality: Latest generated report shows balanced-mode 50.6% precision / 66.7% recall / 57.6% F1 on the primary synthetic vault, along with multi-generation, archetype, chaos, and regression coverage. Report ->
• Live AI testing: Real claude -p sessions verify tool adoption end to end, not just handler logic.
• Write safety: Git-backed conflict detection, atomic rollback, and 100 parallel writes with zero corruption in the checked-in test suite.
• Security: Coverage includes SQL injection, path traversal, Unicode normalization, and permission bypass cases.

Full methodology and results ->

Apache-2.0. See LICENSE for details.