Apple 备忘录搜索

apple-notes-search
分类通用
作者Agentic Awesome Skills 社区
许可MIT
评分4.90/5
使用14.0K

Apple Notes 搜索与关联发现

apple-notes 是一个 MCP 服务器，用于在用户的 Apple Notes 中进行语义搜索和关联发现 —— 支持混合搜索、Swanson-ABC 桥接、实体线程以及基于所有笔记内容的引用综合。向量嵌入（Embeddings）、搜索、BM25、聚类和桥接均在设备本地运行；仅综合生成阶段会调用 LLM（本地或云端，由用户选择）。

本技能涵盖：(1) 必须引导用户完成的一次性设置，以及 (2) 在服务器提供的众多工具中应选择哪一个。

何时使用此技能

  • 当用户想要查找、回忆或检索其 Apple Notes 中的内容时（例如：“在我的笔记中搜索 X”、“我关于 X 写了什么”、“我是否记录过 Y”）。
  • 当用户想要挖掘笔记之间非显而易见的关联时（例如：“在我的笔记中寻找桥接/关联”、“什么将 X 和 Y 联系在一起”、“显示相关笔记”）。
  • 当用户想要根据笔记综合形成观点时（例如：“根据我的笔记总结我对 X 的看法”、“汇总我写过的关于 X 的所有内容”）。
  • 同样适用于“索引我的 Apple Notes”、标签/文件夹查询以及“什么与 X 相关”。
  • 不要将其用于创建提醒事项，或用于非 Apple Notes 的笔记系统。

首先：MCP 是否已连接？

如果 apple-notes 工具不可用，说明服务器尚未注册 —— 请在执行任何操作前完成下方的设置。如果工具存在但搜索返回“未索引”或为空，请先运行 index-notes（参见排名注意事项）。

设置（请引导用户完成 —— 这是该技能的核心价值）

该服务器直接读取 Apple Notes 的 SQLite 数据库，因此 bun 二进制文件需要“全盘访问权限”。步骤如下：

1. 安装 bun（如果尚未安装）：brew install oven-sh/bun/bun
2. 克隆并安装依赖：

bash
git clone https://github.com/connerkward/mcp-apple-notes
   cd mcp-apple-notes
   git checkout <reviewed-tag-or-commit>
   bun install

3. 授予 bun 全盘访问权限。 运行 which bun，然后打开 系统设置 $\rightarrow$ 隐私与安全性 $\rightarrow$ 全盘访问权限，点击 +，并添加该 bun 二进制文件的确切路径（通常为 /opt/homebrew/bin/bun 或 /usr/local/bin/bun）。如果没有此权限，服务器无法读取 NoteStore.sqlite，所有调用都将因权限错误而失败。（bun install 的 postinstall 步骤会尝试自动打开此设置面板。）
4. 注册 MCP 服务器（根据用户使用的客户端选择）：
- Claude Code: claude mcp add apple-notes -- bun /absolute/path/to/mcp-apple-notes/index.ts --stdio
- Claude Desktop: 添加至 claude_desktop_config.json:
json
{ "mcpServers": { "apple-notes": {
json
"command": "/Users/<you>/.bun/bin/bun",
"args": ["/Users/<you>/mcp-apple-notes/index.ts", "--stdio"] } } }
``
- 作为 Claude Code 插件（同时包含此技能）：执行 /plugin marketplace add connerkward/ckw-skills 然后执行 /plugin install apple-notes@connerkward。
5. 重启客户端，然后告知用户询问 "Index my Apple Notes"（或调用 index-notes）。首次索引约 1,800 条笔记需要几秒钟。

工具映射 — 场景与工具对应表

| 工具 | 使用场景 |
|------|----------|
| index-notes | 首次运行或强制重建索引。后台任务，带实时进度显示。 |
| search-notes | 默认搜索。 混合语义 + BM25 检索并重新排序。可选 folder、modifiedAfter、modifiedBefore。例如：“关于 X 我写了什么。” |
| find-notes | 精确子字符串匹配（类似 Apple Notes 原生搜索框）。适用于用户需要字面匹配而非语义匹配时。可选 folder 和日期范围。 |
| get-note | 通过标题获取单篇完整笔记（支持模糊匹配回退）。 |
| list-notes | 按时间倒序列出笔记。可选 folder、日期范围、limit。 |
| list-folders | 列出所有文件夹及笔记数量。 |
| list-tags / search-by-tag | #标签 清单 / 查找带有特定标签的笔记。 |
| related-notes | 通过共享标签、[[wikilinks]] 和向量相似度查找与给定笔记相关的笔记。例如：“显示相关笔记。” |
| bridge-notes | Swanson-ABC 桥接 — 寻找非显而易见的联系：寻找不直接相似但都与同一个中间项 B 强相关的笔记对 (A, C)。例如：“在我的笔记中寻找非显而易见的联系。” 可选 folder、limit。不依赖 LLM。 |
| feed | 以 JSON 形式提供基于证据排序的联系流（桥接 + 抽象对 + 实体线程）。可选 limit。 |
| entity-notes / list-entities | “我在哪里还提到过梅赛德斯？” 实体芯片 $\rightarrow$ 按提及权重排序的笔记。需要可选的实体图数据库 (~/.mcp-apple-notes/layered_graph.db)；若缺失，将提示如何生成。 |
| get-tables | 从笔记中提取管道符/制表符分隔的表格。 |
| create-note / update-note | 创建或编辑笔记。 |
| check-changes | 检查自上次索引以来笔记是否发生变化（不会触发重新索引）。 |
| index-health | 同步状态、上次索引时间、笔记数量。如果结果看起来过时，请运行此工具。 |

对于“综合我关于 X 的看法”，综合功能位于 Web App 端点（运行 bun index.ts 时，访问 http://localhost:3741/ 的 GET /api/synthesize?q=），它会生成带有行内 [n] 引用源笔记的基于事实的回答。

排序注意事项（当结果异常时请说明）

  • 首次搜索前必须索引。 没有索引 $\rightarrow$ 结果为空或错误；请运行 index-notes。
  • 自动重新索引： 每次搜索都会进行约 1ms 的变更检测，如果笔记已更改，会触发一个后台增量索引任务 —— 搜索会立即从当前索引返回结果，并在任务完成后同步。如果刚编辑的笔记未出现，是由于同步延迟；请重新搜索。
  • 评分机制： score = RRF(vector, BM25) × title_boost × recency_factor。
  • 时间相关查询（如 recent, latest, today）会自动切换到 1 天的近期半衰期（权重 70%）；普通查询保持相关性优先（90 天半衰期，权重 10%）。
  • 综合 (Synthesis) 是唯一具备云端能力的部分。 它需要 LLM：可通过 LM Studio / Ollama 本地运行 (SYNTH_BASE_URL=http://localhost:1234/v1 SYNTH_MODEL=<model> OPENAI_API_KEY=local，笔记保留在设备上)，或使用真实的 OpenAI (需提供 OPENAI_API_KEY，默认使用 gpt-4o-mini)。其他所有功能 —— 嵌入 (embeddings)、搜索、BM25、聚类 —— 均在本地运行。
集群、桥接、实体 —— 均在设备本地运行。

局限性

  • 仅支持 macOS 和 Apple Notes；不支持搜索 Obsidian、Notion、Google Docs 或其他笔记库。
  • MCP 服务器需要本地文件系统权限才能读取 Apple Notes 数据，因此无法完全在远程 shell 中完成安装。
  • 搜索质量取决于本地索引的实时性。最近编辑的笔记可能需要运行 check-changes、index-health`，或在后台索引同步后重新运行。
  • 实体工具需要可选的分层图数据库；若未安装，请改用混合搜索、精确搜索、相关笔记或桥接功能。

致谢

本项目分叉自 RafalWilinski/mcp-apple-notes；
本版本直接读取 SQLite + protobuf，并新增了桥接、实体、馈送（feed）和综合（synthesis）功能。
作者：Conner K Ward。许可证：MIT。