Flywheel Memory

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.

](https://www.npmjs.com/package/@velvetmonkey/flywheel-memory)  

开始使用 · 看到它工作 · 它的作用 · 技能+飞轮 · 基准测试 · 测试 · 文档 · 许可证

Flywheel是人工智能代理在黑曜石和普通Markdown上工作的本地第一存储层。它允许代理在您的笔记中进行有根据的搜索，安全地将内容写回保险库，并保留在您的计算机上的本地索引。

专为那些希望人工智能在不将金库交给云应用程序的情况下处理真实笔记的人而设计。你的文件保持可读性Markdown，语义搜索是可选的和本地的，每次写入都是可检查和可逆的。

• 接地搜索 --找到重要的笔记，以及它们周围的链接上下文，而无需让模型在一堆文件中搜索。
• 安全可逆写入 --通过保留Markdown结构且可撤消的有界操作更新实时vault。
• 默认情况下，本地优先 --将笔记保存在磁盘上，使用纯Markdown作为事实来源，并仅在需要时添加本地语义搜索。
• 结构便携 --注释文本和实体在Markdown中编辑土地。飞轮的学习状态（记忆、链接反馈、评分）在vault旁边本地存在 .flywheel/state.db。无需云，无需专有导出—— *是* 根据定义，你的笔记保持可读性。

为什么不进行原始文件访问或简单的RAG？

原始文件访问提供的是代理文本，而不是内存。Flywheel在笔记之间增加了更好的排名，链接的上下文有助于模型保持基础，并编写了足够有界的操作，以在实时保管库中信任。

30秒的工作流程

从 卡特战略 演示：

1. 问： *“我给Acme公司开了多少账单？”*
2. 飞轮搜索正确的笔记，返回连接的上下文，并从库中获取答案。
3. 如果你想对结果采取行动，同一会话可以记录后续行动或将正确的注释更新为可见的、有界的更改。

______________________________________________________________________

开始使用

快速开始

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

然后问： *“我给Acme公司开了多少账单？”*

准备好针对自己的笔记而不是演示使用飞轮了吗？在vault上安装：

您的保险库在2分钟内

将飞轮安装为 代理技能 （人工智能工具的标准入职培训-- npx skills 使用GitHub作为注册表）：

1. 安装技能。 从任何目录：

   npx -y skills add velvetmonkey/flywheel-memory -g

掉落 -g 在项目范围内安装(/.claude/skills/)而不是全球(~/.claude/skills/).该技能教代理何时使用飞轮，并自动引导用户完成接下来的两个步骤。

1. 连接MCP服务器。 从vault目录中：

   bash /.mcp.json`Windows用户： [`install.ps1`](skills/flywheel/scripts/install.ps1) --PowerShell的幂等合并。

1. **重新启动客户端** (`claude` / `codex`)从vault目录中。MCP服务器仅在启动时注册。

然后问一个问题。飞轮监视保险库，维护本地索引，并为MCP客户端提供结构化上下文。你的真相来源在Markdown中。如果你删除 `.flywheel/state.db`，飞轮从库中重建音符索引——学习状态（记忆、链接反馈）随着使用而再生。

Manual install (no installers — for Cursor, Windsurf, VS Code, Continue.dev, etc.)

如果你宁愿手工编辑 `.mcp.json` （例如，与非Claude Code客户端集成），将此块添加到客户端的MCP配置中：

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

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

在此路径中，技能本身是可选的——没有技能界面的客户仍然可以获得完整的MCP工具集。技能来源： [`skills/flywheel/`](skills/flywheel/).

### 可选：工具预设

这 `agent` 预设（默认）提供了一组集中的核心工具。使用 `power` 对于第1+2层（添加维基链接、更正、注释操作、模式）， `full` 立即暴露整个工具表面，或 `auto` 对于整个表面加上信息 `discover_tools` 帮手。

|预设|工具|类别|行为|
|--------|-------|------------|-----------|
| `agent` （默认）|13|搜索、读取、写入、任务、内存、诊断|聚焦的一级表面——搜索、读取，写入、任务，内存|
| `power` |17|搜索、读取、写入、任务、内存、诊断、维基链接、更正、注释操作、模式|第1+2层——代理+维基链接、纠正、注释操作和模式|
| `full` |19|搜索、读取、写入、任务、内存、诊断、维基链接、更正、注释操作、模式、图形、时态|启动时可见的所有类别|
| `auto` |20|搜索、读取、写入、图形、模式、维基链接、更正、任务、记忆、笔记操作、时态、诊断|全面+信息 `discover_tools` 助手|

> **克劳德代码注释：** 这 `memory` 合并工具在Claude代码下被抑制
> (`CLAUDECODE=1`)因为Claude Code有自己的内存平面。代理预设
> 在Claude Code下公开12个工具，而不是13个；
> 简报入口点仍然有效 `memory(action: "brief")`.

为自定义配置编写捆绑包：

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

[浏览所有工具->](docs/TOOLS.md) | [预设食谱->](docs/CONFIGURATION.md)

### 多个保险库

使用以下命令从单个飞轮实例中服务多个保险库 `FLYWHEEL_VAULTS`:

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

搜索会自动跨越所有vault，并用源vault标记每个结果。每个vault都保留单独的索引、图形状态、文件监视器和配置。

[完整的多保险库配置->](docs/CONFIGURATION.md#multi-vault) | [客户端设置示例->](docs/SETUP.md#multi-vault)

Windows users

如果你跑了 [`install.ps1`](skills/flywheel/scripts/install.ps1) 在上述步骤2中，Windows特定的配置(`cmd /c npx` 和 `FLYWHEEL_WATCH_POLL: "true"`)已写入您的 `.mcp.json` 自动-无需进一步操作。

如果你是手工编辑 `.mcp.json` 相反，macOS和Linux有三个不同之处：

1. 使用 **`cmd /c npx`** 而不是 `npx`在Windows上， `npx` 安装为 `.cmd` 脚本，不能直接生成。
1. 集 **`VAULT_PATH`** 转到vault的Windows路径。
1. 集 **`FLYWHEEL_WATCH_POLL: "true"`**。如果没有轮询，飞轮将无法可靠地接收Windows上黑曜石所做的更改。

看 [docs/CONFIGURATION.md#windows](docs/CONFIGURATION.md#windows) 对于完整的示例。

如果您使用Cursor、Windsurf、VS Code、OpenClaw或其他客户端，请参阅 [docs/SETUP.md](docs/SETUP.md) 用于客户端特定的配置。对于OpenClaw，请使用专用 [OpenClaw集成指南](docs/OPENCLAW.md).

______________________________________________________________________

## 看到它工作

### 声音：学习循环

从 [卡特战略](demos/carter-strategy/) 演示：通过语音记录通话，观看维基链接和建议的出现，接受和拒绝一些，然后再次记录——建议会立即得到改善。

https://github.com/user-attachments/assets/cb9e4945-7f0b-410d-85ef-0c42ffc18c6e

https://github.com/user-attachments/assets/bfdae034-6217-426e-bb1d-ff8e2f0d4bc3

https://github.com/user-attachments/assets/4a0635ff-dd73-4fb1-933d-bf384822e2ce

### 写：关于突变的自动维基链接

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

你键入一个正常的句子。飞轮解析已知实体，检测潜在实体（专有名词、缩略语、CamelCase术语），并添加维基链接，并根据别名、共现、图结构和语义上下文建议相关链接。建议的传出链接是可选的，默认情况下是关闭的。在您希望图形自然增长的地方启用它们，例如每日笔记、会议日志或语音捕获。 [配置指南->](docs/CONFIGURATION.md)

### 界限

- 写入是通过可见的工具调用进行的。
- 除非您明确地将工具指向其他位置，否则更改将保留在vault中。
- Git提交是可选的。
- 可以禁用主动链接。

> **自己复制：** 卡特战略演示包括 [`run-demo-test.sh`](demos/run-demo-test.sh) 以首尾相连的方式运行完整序列的脚本 `claude -p`，检查步骤之间的工具使用情况和vault状态。

Policy example: Search the vault, then act on it

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

策略搜索保险库，然后回写。用简单的语言编写它们，在运行前预览，并在需要时通过一次调用撤消。 [政策指南->](docs/POLICIES.md) | [示例->](docs/POLICY_EXAMPLES.md)

______________________________________________________________________

## 它的作用

### 按上下文搜索

一个搜索调用返回足够的上下文，使模型能够回答有根据的问题：重要的frontmatter、节感知片段、日期和链接注释。关键字搜索（BM25）处理精确的术语。当右音符相关但尚未明确链接时，可选的局部语义搜索会有所帮助。它们一起减少了文件跳跃，使答案在真正的保险库中更可靠。 [搜索是如何工作的->](docs/ARCHITECTURE.md)

### 安全写作

每个突变都会通过SHA-256内容哈希进行冲突检测，并且可以通过一次撤销来逆转。写入保留了Markdown结构，因此编辑不会损坏表、标注、代码块、前体、链接、注释或数学。自动维基链接保持确定性和可追溯性。对于一次性编辑，请使用直写工具。对于搜索vault并对结果采取行动的可重复工作流，请使用 **政策**，保存了在vault状态上分支并将多个写入步骤作为单个原子操作运行的YAML工作流。 [评分工作原理->](docs/ALGORITHM.md) | [政策指南->](docs/POLICIES.md)

### 随着时间的推移建立记忆

每一个被接受的链接都会加强图表。每个被拒绝的链接都会更新记分员。每次写入都会为下一次读取添加更多上下文。 `memory(action: "brief")` 汇编最近活动的代币预算摘要，以及 `memory` 以置信度衰减的方式持续观察。图形可以通过以下方式导出 `graph(action: "export")` 作为GraphML，用于在以下工具中进行可视化 [杰菲](https://gephi.org) 或NetworkX——请参阅 [卡特战略演示](demos/carter-strategy/) 举个例子。 [配置->](docs/CONFIGURATION.md)

______________________________________________________________________

## 技能+飞轮

技能编码方法论：如何做某事。飞轮编码知识：你所知道的。它们是互补层：

|层|它提供了什么|示例|
|---|---|---|
|技能|程序、模板、推理框架|“如何撰写客户提案”|
|飞轮|实体、关系、历史、背景|“你所知道的关于这个客户的一切”|

当代理人能够搜索您的保险库以查找客户的历史记录、过去的发票、项目笔记和团队关系时，调用提案写作技能会更好。技能告诉特工如何工作。飞轮告诉他们你所知道的。

代理上下文空间中的其他工具将知识视为技能执行的副作用：由线束编写的状态文件，其范围符合其约定。飞轮将知识视为运行在其上的基础技能——实体图、时间历史和扎根检索，任何线束中的任何技能都可以通过MCP读取。线束需要飞轮形状的状态才能准确；飞轮适用于任何线束。

有关安装步骤，请参阅 [您的保险库在2分钟内](#your-vault-in-2-minutes) 上面。技能来源和示例查询： [`skills/flywheel/`](skills/flywheel/).

______________________________________________________________________

## 飞轮套房

- **飞轮存储器** *（此回购）* --本地第一MCP服务器。混合BM25+语义搜索、知识图、黑曜石保险库上的安全写入。
- **[飞轮曲柄](https://github.com/velvetmonkey/flywheel-crank)** --黑曜石插件。内存图上的视觉层：侧边栏、保险库健康状况、语义搜索UI。
- **[飞轮想法](https://github.com/velvetmonkey/flywheel-ideas)** --可伪造的决策账簿。预先注册的假设、多模型人工智能委员会的异议、结果驱动的反驳传播。
- **[飞轮概念](https://github.com/velvetmonkey/flywheel-concept)** --关于跨模型激活是否揭示了结构化概念几何的研究计划。

______________________________________________________________________

## 基准测试

[![HotpotQA]()](docs/TESTING.md#retrieval-benchmark-hotpotqa)
[![LoCoMo]()](docs/TESTING.md#retrieval-benchmark-locomo)

代理优先的工具应该证明他们的主张。飞轮附带了可重复的学术检索标准基准：

- **HotpotQA完整端到端：** **90.0%的文件召回** 上 **50个问题/4960个文档**.最新工件： **2026年4月10日**。该运行成本： **0.083美元/个问题**.
- **LoCoMo完整端到端：** **81.9%的证据召回率** 和 **54.0%的回答准确率** 上 **695个评分问题/272次会议**.最新工件： **2026年4月10日**最终代币F1： **0.431**.
- **LoCoMo单元检索：** **84.8%Recall@5** 和 **90.4%Recall@10** 在完整的非对抗性检索集上。

下面的每个数字都与回购中的签入报告或可复制的线束相关联。

**多跳检索与学术基线** （HotpotQA，500个问题，4960份文件）：

|系统|召回|训练数据|
|---|---|---|
|BM25基线|~75%|无|
| [TF-IDF+实体](https://arxiv.org/abs/1809.09600) |约80%|无|
| [鲸须](https://arxiv.org/abs/2101.00436) （斯坦福大学）|~85%|HotpotQA|
| [MDR](https://arxiv.org/abs/2009.12756) （脸书）|~88%|HotpotQA|
| **飞轮** | **90.0%** | **无** |
| [光束回收](https://arxiv.org/abs/2308.08973) |~93%|端到端|

**会话记忆检索** ([LoCoMo](https://snap-research.github.io/locomo/)，1531个检索查询得分，272个会话笔记）：

|类别|Recall@5 | Recall@10 |
|---|---|---|
| **总体** | **84.8%** | **90.4%** |
|单跳|88.1%|91.7%|
|常识|95.4%|98.3%|
|多跳|58.1%|72.7%|
|时间|56.9%|67.4%|

E2E与克劳德·索内特（最新检查695题运行）： **97.4%** 单跳证据召回， **73.7%** 多跳证据召回， **81.9%** 全面证据召回，以及 **54.0%** 答案准确性（克劳德·海库评判）。 [完整的方法和注意事项->](docs/TESTING.md#retrieval-benchmark-locomo)

> **方向性，不是苹果对苹果。** 测试设置、样本大小、检索池和指标各不相同。Flywheel搜索4960个合并文档，这比标准的HotpotQA分心器设置的10个文档更难，也比fullwiki小得多。学术检索员接受基准培训；飞轮不使用基准训练数据。预计LLM非确定性的运行差异约为1个百分点。 [完整警告->](docs/TESTING.md#retrieval-benchmark-hotpotqa)

[`demos/hotpotqa/`](demos/hotpotqa/) · [`demos/locomo/`](demos/locomo/) · [完整的方法论->](docs/TESTING.md)

______________________________________________________________________

## 测试

3292个测试定义了185个测试文件和约64.4k行测试代码。CI在Ubuntu上运行集中作业，并在Node 22和24上运行Ubuntu和Windows上的完整矩阵。

- **图形质量：** 最新生成的报告显示平衡模式 **50.6%的准确率/66.6%的召回率/57.6%的F1** 在初级综合保险库上，以及多代、原型、混沌和回归覆盖。 [报告->](docs/QUALITY_REPORT.md)
- **实时AI测试：** 真实 `claude -p` 会话端到端验证工具的采用，而不仅仅是处理程序逻辑。
- **写安全：** Git支持的冲突检测、原子回滚和100次并行写入，在签入测试套件中没有损坏。
- **安全：** 覆盖范围包括SQL注入、路径遍历、Unicode规范化和权限绕过情况。

[完整的方法和结果->](docs/TESTING.md)

______________________________________________________________________

## 文档

|Doc|为什么要读它|
|---|---|
| [PROVE-IT.md](docs/PROVE-IT.md) |从这里开始，看到项目快速运行|
| [TOOLS.md](docs/TOOLS.md) |完整工具参考|
| [COOKBOOK.md](docs/COOKBOOK.md) |用例提示示例|
| [设置.md](docs/SETUP.md) |保险库的完整设置指南|
| [配置.md](docs/CONFIGURATION.md) |环境变量、预设和自定义工具集|
| [算法.md](docs/ALGORITHM.md) |链接评分和搜索排名详细信息|
| [建筑.md](docs/ARCHITECTURE.md) |索引、图形和自动维基链接设计|
| [测试.md](docs/TESTING.md) |基准、方法和测试覆盖率|
| [故障排除.md](docs/TROUBLESHOOTING.md) |诊断和恢复|
| [SHARING.md](docs/SHARING.md) |隐私说明、跟踪数据和可共享统计数据|
| [视觉.md](docs/VISION.md) |项目方向和长期目标|

## 许可证

阿帕奇-2.0。看 [许可证](./LICENSE) 了解详情。