---
name: Search private files on the phone
description: >-
  Teach an edge engineer an honest on-device retrieval stack: chunking,
  BM25 you own, Core AI embeddings, rerank, plus SpotlightSearchTool
  as Apple's local RAG tool. iOS 27 and macOS 27 only.
---
# Search private files on the phone

Use this course to search notes on the device. Apple ships `SpotlightSearchTool` for local RAG over Core Spotlight. That is not BM25 plus dense plus rerank. If you need that stack, you build the pieces and stay honest about which API is whose. Mac indexing and BM25 stats may use Python. On-device query, Spotlight, and `LanguageModelSession` stay Swift.

## End-to-end agent recipe

1. Start with [lesson 01](01-keep-search-on-the-phone.llms.md) to separate SpotlightSearchTool from a stack you own.
2. Use [lesson 02](02-chunk-private-notes.llms.md) to chunk notes with stable ids. Swift on device, Python on a Mac for a first index.
3. Use [lesson 03](03-bm25-for-words.llms.md) to score lexical overlap in Swift and build stats in Python. There is no Apple BM25 type.
4. Use [lesson 04](04-dense-search-core-ai.llms.md) for a Core AI catalog embedder, with an honest fallback if the SDK has no embedder.
5. Use [lesson 05](05-rerank-and-hand-off.llms.md) to merge lists, rerank, and hand a small pack to a Dynamic Profile.
6. Use human HTML for reading and `.llms.md` files for agent execution.

## Constraints

- iOS 27 and macOS 27 only. No public cloud search.
- Do not invent an Apple BM25 API.
- `SpotlightSearchTool` is named as Apple's tool, not as BM25.
- Mac indexing and BM25 build may use Python. Query, SpotlightSearchTool, and session hand-off stay Swift.
- No Mermaid. No em dashes. No LangChain.
- Cite [WWDC26 246](https://developer.apple.com/videos/play/wwdc2026/246/) and Core AI lightly.

## Key concepts

- Two honest paths: Apple `SpotlightSearchTool`, or a stack you own.
- The owned stack is chunk, BM25, Core AI dense search, rerank, then hand off.
- Index and query stay on iOS 27 and macOS 27. No public cloud search.
- Mac Python can build a first index. Swift on the device runs query and session hand-off.

## Takeaways

- You can find a private note with words, meaning, or Spotlight and say which API did the work.
- You can hand reranked hits to the context packer as search-lane slices.
- You can use Spotlight for a fast product path and the owned stack for files Spotlight should not see.

## Acceptance checks

- Every human lesson HTML has **Key concepts** and **Takeaways** sections before lesson-nav. The course home has the same two headings for the whole course.
- Five lessons and five briefs exist.
- Honesty about Spotlight versus owned stack is in lesson 01 and 04.
- Course index lists SKILL.md and all briefs.

## Environment setup

Xcode 27. iOS 27 or macOS 27. Foundation Models, Core Spotlight, and Core AI as needed. Optional Mac Python 3.11+ for offline chunk and BM25 index files.