Flywheel

Persistent knowledge graph memory for AI agents. Structured vault with semantic search, read, and write tools. Works with Obsidian.

Why researchers plug it in

Your AI forgets everything between sessions. Flywheel gives it a persistent, compounding memory over your own notes, so every conversation builds on the last instead of starting from zero. Point any MCP client (Claude, Codex, Cursor) at your vault and the agent reads, searches, and writes it as ground truth.

What you get the moment you plug it in:

• Memory that compounds. The more you use it, the sharper retrieval gets. A self-correcting loop, not a static index.
• One call, a decision surface. A search returns ranked notes plus entities, backlinks, outlinks, provenance, and confidence. Not a pile of files to wade through.
• Your graph becomes the reasoning substrate. The agent thinks in your concepts, your links, your history.

It turns a flat pile of markdown into an exocortex your AI can actually pilot. That is the difference between an assistant that answers and one that remembers.

Features

• Hybrid search, three channels fused. Full-text (BM25), entity, and semantic vector search combined by Reciprocal Rank Fusion. Keyword precision and meaning recall in a single call.
• U-shaped result ordering. Best hits placed at the head and tail where LLMs actually read, beating the "lost in the middle" failure.
• 13-layer wikilink scoring. Auto-suggests [[entities]] with a transparent, ablatable score, then learns from which links survive.
• Self-correcting flywheel. Implicit feedback, survival tracking, edge-weight accumulation, and suppression. Day 1 it guesses; month 3 it knows your graph.
• Gravity ranking. Surfaces what matters now by pull, not just lexical match (Gravity Basin Protocol companion).
• Knowledge-graph queries. Backlinks, forward links, hub detection, shortest path between notes, orphan and dead-end detection.
• AST-driven mutations. Every structure-sensitive write runs over a real markdown syntax tree (mdast via micromark, with GFM, frontmatter, and math), not string-bashing. Protected zones (code, tables, frontmatter, math, callouts) are computed from the tree, so edits and auto-wikilinks never corrupt your documents. Regex fallback only if a file fails to parse.
• Structured read, safe write. Section-level reads and outlines; content-hash conflict detection on writes; move and rename that preserve links.
• Semantic over an open substrate. Embeddings with contextual prefixes and dual-granularity section expansion, all over plain markdown you own.
• Multi-vault, local-first, audited. One vault or many; every mutation logged; no lock-in, because it is just files.

Install

Flywheel runs from a git clone — it is not distributed via npm (the registry package is frozen; see docs/local-deploy.md).

git clone https://github.com/velvetmonkey/flywheel-memory
cd flywheel-memory
npm ci && npm run build

Then point your client's MCP config at the built server — e.g. <vault>/.mcp.json:

{
  "mcpServers": {
    "flywheel": {
      "command": "node",
      "args": ["/path/to/flywheel-memory/packages/mcp-server/dist/index.js"]
    }
  }
}

Windows: set FLYWHEEL_WATCH_POLL: "true". Multi-vault: FLYWHEEL_VAULTS=name1:/path1,name2:/path2. Full setup: docs/SETUP.md · docs/CONFIGURATION.md · versioned deploys: docs/local-deploy.md.

Documentation

Doc	Why read it
TOOLS.md	Tool reference
SETUP.md	Client setup
CONFIGURATION.md	Env vars and presets
ARCHITECTURE.md	Indexing and graph design
ALGORITHM.md	Scoring details
TESTING.md	Benchmarks and methodology

Philosophy

Flywheel is a research platform, not an Obsidian plugin. It writes Obsidian markdown on purpose: an open, human-readable format means the entire memory is transparent and inspectable with any third-party tooling (Obsidian, graph viewers, git, grep, plain text). Obsidian is a viewer, not the product. The knowledge graph (backlinks and wikilink nodes) is a free dividend of writing to an open substrate, not the reason the system exists.

The practical consequence: you can open the vault and trace any thread end to end without Flywheel's code in the loop. Transparency via an open format is the moat. Wikilinking is a retrieval and provenance mechanism over that open substrate, not a courtesy to a particular editor.

Related repositories

Part of the Flywheel suite — local-first knowledge infrastructure over a plain-markdown Obsidian vault:

• vault-core — Shared infrastructure for the Flywheel ecosystem.
• flywheel-memory (this repo) — Persistent knowledge-graph memory MCP server: semantic search, read, and write over your vault.
• flywheel-crank — Desktop window into your vault's Flywheel MCP server.
• flywheel-gravity — A compressed, reality-filtered context field over a vault.
• flywheel-ideas — Local-first decision ledger: falsifiable bets, accepted outcomes, reusable lessons.
• mega-monkey — Telegram-native AI research cockpit over an Obsidian vault.
• roundtable — Local MCP server for delegating tasks to multiple AI models.

Research and experiments:

• flywheel-concept — A falsifiable study of cross-model concept geometry.
• flywheel-geometry — A pre-registered study of cross-domain knowledge retrieval.
• flywheel-universe — Lean 4 / Mathlib-verified core of the descent argument.
• flywheel-velvetgram — Local widescreen Telegram reader for long-form reading.

Verified-cognition demo: mcp-seal (verified MCP approval gate) and canary (the seal demo host).

License

Apache-2.0.