searching-apple-notes

# searching-apple-notes — semantic search for Apple Notes, built for Claude Code  > Talk to Claude Code in plain English or Chinese, and it answers from your Apple Notes archive — semantically, locally, with no API keys and no MCP setup required. Drop-in skill, fully private, optimized for Chinese-English mixed content via BGE-M3. > [English](#english) | --- ## English ### What is this? `searching-apple-notes` turns your Apple Notes into a second brain that Claude Code can read and write. You ask a question in natural language, Claude semantically searches your notes (BGE-M3 embeddings + ChromaDB, all local on your Mac), reads the relevant ones, and answers with citations. You never type a search query, you never see a tool call, you never leave your conversation. When you tell Claude to capture an insight, it writes a properly formatted note back into Apple Notes — hashtags and all. The whole thing runs on your Mac. No API keys. No third-party servers. No data leaving your machine. The only network traffic the project ever generates is the one-time download of BGE-M3 from Hugging Face during initial setup.  ### Features - **Claude Code Skill** *(recommended)*: Drop-in skill that lets Claude Code search and write your Apple Notes from any conversation, with built-in search strategy and dialogue-to-note workflow - **Semantic Search**: Understands meaning, not just keywords - **Chinese Optimized**: BGE-M3 embedding model handles Chinese-English mixed content natively - **Multi-language**: Supports 100+ languages - **Privacy First**: All data stays local — no API keys, no third-party servers - **MCP Server** *(alternative)*: For Claude Desktop and Poke AI users who don't use Claude Code ### Install **Option 1: Claude Code Plugin (recommended)** ``` /plugin marketplace add yinanli1917-cloud/searching-apple-notes /plugin install searching-apple-notes@searching-apple-notes ``` Then run the one-time index build: ```bash pip install -r requirements.txt python scripts/indexer.py ``` **Option 2: Manual skill install** ```bash git clone https://github.com/yinanli1917-cloud/searching-apple-notes.git ~/.claude/skills/searching-apple-notes cd ~/.claude/skills/searching-apple-notes pip install -r requirements.txt python scripts/indexer.py ``` ### Two ways to use this **1. As a Claude Code Skill — recommended.** This is the primary path. The skill teaches Claude Code *when* to search, *how* to phrase queries, *how* to interpret results, and *when* to save new insights back into Apple Notes. You install it once, then talk to Claude normally — no commands, no tool calls, no search box. → **[Read the skill docs and install instructions](skills/searching-apple-notes/README.md)** **2. As an MCP server — for non-Claude-Code users.** If you use Claude Desktop, Cursor, or Poke AI on iMessage, the MCP server in `scripts/server.py` exposes the same search functionality as MCP tools. The MCP path is no longer my primary use case — I still accept PRs and bug reports, but new development happens in the Skill. See the Claude Desktop and Poke AI sections below for MCP setup. ### What it feels like to use Once installed, the skill is invisible. You just talk to Claude in English or Chinese: > **You:** Did I take any notes about that book on attention I read last month? > > **Claude:** *(silently runs `vector_search.py "attention book notes" --after 2026-03-01`)* > > Yes — you have a note titled "Stolen Focus, chapters 1–3" from March 14, and another titled "fragmented attention vs flow" from March 22. The first captures your reaction to the argument about social media disrupting deep reading. The second is your own elaboration where you note that flow states require a particular kind of friction-free attention that… > **You:** > > **Claude:** *(silently runs `vector_search.py ""`)* > > > **You:** Save this whole conversation as a note tagged #strategy > > **Claude:** *(silently runs `create_note.py "Notes on attention and flow" "..." --folder "Notes"`)* > > Saved as a new note in your Notes folder with the #strategy tag. You'll see it in Apple Notes within a few seconds. You never see the tool calls. You just ask, and Claude answers from your actual prior thinking — and writes new thinking back into the same archive. ### FAQ **How does it search my notes?** Your notes are exported to a local SQLite database, then each note is converted into a 1024-dimensional vector by the BGE-M3 embedding model. When you ask a question, your query gets embedded the same way, and ChromaDB finds the notes whose vectors are closest in meaning. This is called *semantic search* — searching for "burnout" finds notes about "exhaustion," and "running on fumes" even when none of those exact words appear in the query. **Does it send my notes to OpenAI or any other cloud service?** No. Everything runs on your Mac. The BGE-M3 model is downloaded once from Hugging Face during initial setup (about 2 GB), then runs entirely offline. There are no API keys, no telemetry, no third-party servers, and no usage charges. The only cloud component is the *optional* Cloudflare Worker for the Poke-AI-via-iMessage path, which most users don't need. **Why BGE-M3 instead of OpenAI's text-embedding-3-large?** Three reasons. (1) It's free and runs locally. (2) It's bilingual — BGE-M3 was trained heavily on Chinese and outperforms English-only embedders by a wide margin on mixed Chinese-English content. If you take notes in any language other than English, this matters. (3) Privacy — your notes never leave your Mac. **Does it work with Chinese, Japanese, Korean, or other non-English notes?** Yes. BGE-M3 supports 100+ languages and is particularly strong at Chinese and Chinese-English mixed content. You can ask in one language and find notes written in another. **How is this different from Apple's built-in Notes search?** Apple's search is keyword-based — it only finds notes that contain the exact words you typed. This skill is *semantic* — it understands that "" and are related, and that a question about should match a note about . Apple's search will miss all of these. **Do I need Claude Desktop, or does Claude Code work?** The recommended path is **Claude Code** with the Skill. Claude Desktop works via the MCP server but the MCP path is no longer the primary use case — see the "Two ways to use this" section above. **How do I keep the index in sync as I add new notes?** The skill includes a `sync_index.py` helper that re-exports from Notes.app and incrementally updates the vector index. Only notes modified since the last sync get re-embedded, so it usually finishes in seconds. You can run it manually, schedule it via launchd, or just tell Claude "refresh my notes index" and it will run it for you. **What about Notion, Evernote, Obsidian, or other note apps?** Currently Apple Notes only. The export pipeline depends on AppleScript, which is Apple Notes specific. PRs for other backends are welcome — the search and skill layers are app-agnostic. **Is it really free?** Yes. Free, MIT licensed, no API charges, no subscription. The only cost is disk space (about 2 GB for the BGE-M3 model and another ~50 MB per 1000 notes for the vector index). ### Quick Start **Requirements:** - macOS - Python 3.10+ - Basic terminal knowledge (or ask AI like Claude to help!) **Installation (5 minutes):** ```bash # Clone the repo git clone https://github.com/yinanli1917-cloud/searching-apple-notes.git cd searching-apple-notes # Install dependencies pip3 install -r requirements.txt # Export your notes cd scripts && python3 export_notes_fixed.py ``` # Build search index (takes 3-5 minutes first time) python3 indexer.py ``` **Use with Claude Desktop:** 1. Edit Claude's config file: ```bash open ~/Library/Application\ Support/Claude/claude_desktop_config.json ``` 2. Add this configuration (update the path): ```json { "mcpServers": { "apple-notes": { "command": "python3", "args": ["/Users/YOUR_USERNAME/searching-apple-notes/scripts/server.py"] } } } ``` 3. Restart Claude Desktop 4. Try searching: `Search for "funny content" in my notes` 👉 [Learn more about configuring MCP servers](https://modelcontextprotocol.io/quickstart/user) **Use with Poke AI (iMessage):** Search your notes directly from iMessage using Poke AI! 1. Install [Poke AI](https://poke.com) on your iPhone 2. Start the services on your Mac: ```bash cd ~/searching-apple-notes/scripts ./start_poke_services.sh ``` 3. Configure Poke AI with the MCP server URL: ``` https://apple-notes-mcp.yinanli1917.workers.dev/sse ``` 4. Search via iMessage: "Search my notes for funny jokes" 👉 [Full Poke AI Setup Guide](docs/POKE_INTEGRATION.md) ### Cost **Local (Free):** - All data stays on your Mac - Complete privacy - No internet required (except downloading models) **Cloud Deploy (Optional):** - Cloudflare: Free plan is enough - Fly.io: ~$2-3/month - Railway: ~$5/month - Access from anywhere with your phone ### Tech Stack **Core Search:** - **BGE-M3**: Chinese-optimized embedding model (1024-dim) - **ChromaDB**: Vector database - **Python 3.12** **Integrations:** - **FastMCP**: MCP protocol framework (Claude Desktop) - **Cloudflare Workers**: Serverless platform (Poke AI) - **Cloudflare Tunnel**: Secure local-to-cloud bridge ### Documentation - [Poke AI Integration Guide](docs/POKE_INTEGRATION.md) - Search via iMessage - [Auto-Sync Guide](docs/AUTO_SYNC.md) - Keep your index up-to-date automatically - [Cloudflare Tunnel Setup](docs/CLOUDFLARE_TUNNEL.md) - Local-to-cloud bridge - [Cloud Deployment Guide](docs/DEPLOY.md) - Deploy to Fly.io/Railway - [Project Status](STATUS.md) - Current features and roadmap - [Technical Details](docs/PROJECT_LOG.md) - Development log ### Contributing Contributions welcome! Feel free to: - Report bugs - Suggest features - Improve documentation - Submit pull requests ### License MIT License 2025 [Yinan Li](https://github.com/yinanli1917-cloud) **Made with by [Yinan Li](https://github.com/yinanli1917-cloud) & [Claude Code](https://claude.ai/claude-code)** ---