Przejdź do treści
Biblioteka skilli
Produktywność osobista · Research

apple-notes-search

/apple-notes-search

Wyszukuje semantycznie i słowami kluczowymi w notatkach Apple Notes użytkownika przez serwer MCP apple-notes i odkrywa powiązane notatki, lokalnie na macOS.

Licencja
MIT
Ostatnia zmiana repozytorium
24.10.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
1
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
6
Przestarzałość

Brak sygnałów. Repozytorium zmienione 24.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Wyszukuje semantycznie i słowami kluczowymi w notatkach Apple Notes użytkownika przez serwer MCP apple-notes i odkrywa powiązane notatki, lokalnie na macOS.

Oryginalny opis (EN)

Semantic + keyword search and connection-discovery across the user's own Apple Notes via the apple-notes MCP server. Use when the user wants to find, recall, or synthesize something from their notes, or surface non-obvious bridges/related notes. macOS, on-device.

Jak działa

  1. When to Use This Skill
  2. First: is the MCP connected?
  3. Setup (walk the user through this — it's the skill's real value)
  4. Tool map — which tool for which job
  5. Ranking caveats (state these when results look off)
  6. Example
  7. Limitations
  8. Credits
Sekcje z nagłówków SKILL.md, w oryginale · 119 linii, 1 134 słów
Podgląd SKILL.md
---
name: apple-notes-search
description: "Semantic + keyword search and connection-discovery across the user's own Apple Notes via the apple-notes MCP server. Use when the user wants to find, recall, or synthesize something from their notes, or surface non-obvious bridges/related notes. macOS, on-device."
risk: critical
source: community
source_repo: connerkward/mcp-apple-notes
source_type: community
date_added: "2026-06-16"
author: connerkward
tags: [apple-notes, search, mcp, macos, semantic-search, knowledge]
tools: [claude-code]
license: "MIT"
license_source: "https://github.com/connerkward/mcp-apple-notes/blob/main/LICENSE"
plugin:
  targets:
    codex: blocked
    claude: blocked
  setup:
    type: manual
    summary: "Requires third-party MCP setup and macOS Full Disk Access; keep out of plugin-safe bundles."
    docs: SKILL.md
---

# Apple Notes search & connection-discovery

`apple-notes` is an MCP server for semantic search and connection-discovery across the
user's own Apple Notes — hybrid search, Swanson-ABC bridges, entity threads, and cited
synthesis over everything they've written. Embeddings, search, BM25, clustering, and
bridges run **on-device**; only **synthesis generation** calls an LLM (local OR cloud,
the user's choice).

This skill covers (1) the one-time setup you must walk the user through, and (2) which
tool to reach for, since the server exposes many.

## When to Use This Skill

- Use when the user wants to **find, recall, or look up** something from their own Apple
  Notes ("search my notes for X", "what did I write about X", "did I ever note Y").
- Use when the user wants to surface **non-obvious connections** across their notes
  ("find bridges/connections across my notes", "what links X and Y", "show related notes").
- Use when the user wants to **synthesize a position** from their notes ("summarize what I
  think about X from my notes", "pull together everything I've written on X").
- Also use for "index my Apple Notes", tag/folder queries, and "what's connected to X".
- Do **not** use for creating reminders, or for non-Apple-Notes note systems.

## First: is the MCP connected?

If `apple-notes` tools are not available, the server isn't registered yet — do the
**Setup** below before anything else. If tools exist but a search returns "not indexed"
or empty, run `index-notes` first (see Ranking caveats).

## Setup (walk the user through this — it's the skill's real value)

The server reads Apple Notes' SQLite store directly, so the **bun** binary needs Full
Disk Access. Steps, in order:

1. **Install bun** (if absent): `brew install oven-sh/bun/bun`
2. **Clone + install deps:**
   ```bash
   git clone https://github.com/connerkward/mcp-apple-notes
   cd mcp-apple-notes
   git checkout <reviewed-tag-or-commit>
   bun install --ignore-scripts
   ```
3. **Grant Full Disk Access to bun.** Run `which bun`, then open System Settings →
   Privacy & Security → Full Disk Access, click `+`, and add that exact `bun` binary
   path (commonly `/opt/homebrew/bin/bun` or `/usr/local/bin/bun`). Without this the
   server cannot read NoteStore.sqlite and every call fails with a permissions error.
   (Review all lifecycle scripts before any separate activation; do not run postinstall merely to open a settings pane.)
4. **Register the MCP server** (pick the user's client):
   - Claude Code: `claude mcp add apple-notes -- bun /absolute/path/to/mcp-apple-notes/index.ts --stdio`
   - Claude Desktop: add to `claude_desktop_config.json`:
     ```json
     { "mcpServers": { "apple-notes": {
         "command": "/Users/<you>/.bun/bin/bun",
         "args": ["/Users/<you>/mcp-apple-notes/index.ts", "--stdio"] } } }
     ```
   - As a Claude Code plugin (bundles this skill too): `/plugin marketplace add connerkward/ckw-skills` then `/plugin install apple-notes@connerkward`.
5. **Restart the client**, then tell the user to ask **"Index my Apple Notes"** (or call
   `index-notes`). First index of ~1,800 notes takes a few seconds.

## Tool map — which tool for which job

| Tool | Use when |
|------|----------|
| `index-notes` | First run, or to force a rebuild. Background job with live progress. |
| `search-notes` | **Default search.** Hybrid semantic + BM25, re-ranked. Optional `folder`, `modifiedAfter`, `modifiedBefore`. "What did I write about X." |
| `find-notes` | Exact substring match (like the Apple Notes search box). Use when the user wants a literal string, not meaning. Optional `folder`, date range. |
| `get-note` | Fetch one full note by title (fuzzy fallback). |
| `list-notes` | Notes by recency. Optional `folder`, date range, `limit`. |
| `list-folders` | All folders + note counts. |
| `list-tags` / `search-by-tag` | `#hashtag` inventory / notes carrying a given tag. |
| `related-notes` | Notes related to a given one via shared tags, `[[wikilinks]]`, and vector similarity. "Show me related notes." |
| `bridge-notes` | **Swanson-ABC bridges** — non-obvious connections: pairs (A, C) not directly similar but both strongly tied to a shared intermediary B. "Find non-obvious connections across my notes." Optional `folder`, `limit`. No LLM. |
| `feed` | Ranked evidence-first connection stream (bridges + abstraction pairs + entity threads) as JSON. Optional `limit`. |
| `entity-notes` / `list-entities` | "Where else do I talk about Mercedes?" Entity chips → notes by mention weight. **Needs the optional entity graph db** (`~/.mcp-apple-notes/layered_graph.db`); if absent these report how to generate it. |
| `get-tables` | Pull pipe/tab tables out of a note. |
| `create-note` / `update-note` | Create or edit a note. |
| `check-changes` | Did notes change since last index? (does not trigger re-index) |
| `index-health` | Sync status, last-indexed time, note count. Run this if results seem stale. |

For "synthesize what I think about X" the synthesis lives in the **web app** endpoint
(`GET /api/synthesize?q=` at `http://localhost:3741/` when run with `bun index.ts`),
which writes a grounded answer with inline `[n]` citations back to source notes.

## Ranking caveats (state these when results look off)

- **Index before the first search.** No index → empty/garbage results; run `index-notes`.
- **Auto re-index:** each search does ~1ms change detection and kicks ONE background
  incremental index if notes changed — search returns immediately from the current index
  and catches up when the job lands. If a just-edited note is missing, it's the catch-up
  lag; re-run the search.
- **Score:** `score = RRF(vector, BM25) × title_boost × recency_factor`.
- **Temporal queries** (`recent`, `latest`, `today`) auto-shift to a 1-day recency
  half-life at 70% weight; normal queries keep relevance primary (90-day half-life, 10%).
- **Synthesis is the only cloud-capable part.** It needs an LLM: local via LM Studio /
  Ollama (`SYNTH_BASE_URL=http://localhost:1234/v1 SYNTH_MODEL=<model> OPENAI_API_KEY=local`,
  notes stay on-device) or real OpenAI (funded `OPENAI_API_KEY`, defaults to `gpt-4o-mini`).
  Everything else — embeddings, search, BM25, clustering, bridges, entities — is on-device.

## Example

**User request:**

> Use @apple-notes-search for this task: Semantic + keyword search and connection-discovery across the user's own Apple Notes via the apple-notes MCP server.

## Limitations

- macOS and Apple Notes only; it does not search Obsidian, Notion, Google Docs, or other note stores.
- The MCP server needs local filesystem permissions to read Apple Notes data, so setup cannot be completed purely inside a remote shell.
- Search quality depends on a fresh local index. Recently edited notes may require `check-changes`, `index-health`, or a rerun after background indexing catches up.
- Entity tools require the optional layered graph database; without it, use hybrid search, exact search, related notes, or bridges instead.

## Credits

Fork of [RafalWilinski/mcp-apple-notes](https://github.com/RafalWilinski/mcp-apple-notes);
this fork reads SQLite + protobuf directly and adds bridges, entities, feed, and synthesis.
Authored by [Conner K Ward](https://github.com/connerkward). License MIT.

Pin and stage the complete external server/dependency tree, inspect executable and lifecycle entry points before activation, and explain the exact process receiving Full Disk Access. Granting broad filesystem permission requires the user’s informed action. Indexes persist note contents/embeddings: choose access, retention and deletion scope. Cloud-assisted synthesis sends selected notes to the configured provider and requires explicit private-data transfer scope; “on-device” indexing does not make cloud queries local.

Wersje

RepozytoriumWynikLicencja
Ta strona · sickn33/agentic-awesome-skills100MIT
FrancoStino/opencode-skills-collection100MIT
LiHongwei-cn/lihongwei-cn100MIT

Migawka bazy z 13.11.2026 · wersja paczki 0476e6d3eabe (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 2 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100apple-notes
    Obsługuje Apple Notes na macOS: tworzy, przeszukuje, aktualizuje i porządkuje notatki oraz foldery przez narzędzia MCP.
  • 90apple-notes
    Tworzy, przegląda, edytuje, przenosi i eksportuje notatki Apple Notes z terminala na macOS przez CLI memo.
  • 100apple-notes
    Zarządza Apple Notes na macOS przez CLI memo: tworzy, wyświetla, edytuje, usuwa, wyszukuje, przenosi i eksportuje notatki.
  • 86apple-notes
    Zarządza Apple Notes na macOS przez CLI memo: tworzy, przegląda, edytuje, usuwa, wyszukuje, przenosi i eksportuje notatki oraz porządkuje foldery.
  • 100apple-notes
    Czyta i zapisuje notatki Apple na macOS, wyciąga z nich obrazy i pilnuje układu katalogów inbox, ready, done i docs.
  • 100apple-notes
    Zarządza Apple Notes na macOS: listuje, wyszukuje, czyta, tworzy, dopisuje, przenosi, usuwa i eksportuje notatki oraz zarządza folderami, lokalnie w Notes.app.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.