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 | |---

... View full README on GitHub