@disco_trooper/apple-notes-mcp 1.3.0 → 1.4.0

package/README.md

@@ -19,12 +19,14 @@ MCP server for Apple Notes with semantic search and CRUD operations. Claude sear
 - **Incremental Indexing** - Re-embed only changed notes
 - **Dual Embedding** - Local HuggingFace or OpenRouter API
 
-## What's New in 1.3
+## What's New in 1.4
 
-- **Parent Document Retriever** - Splits long notes into 500-char chunks with 100-char overlap. Searches match specific sections, returns full notes.
+- **Smart Refresh** - Search auto-reindexes changed notes. No manual `index-notes` needed.
+- **Batch Operations** - Delete or move multiple notes by title or folder.
+- **Purge Index** - Clear all indexed data when switching models or fixing corruption.
+- **Parent Document Retriever** - Splits long notes into 500-char chunks with 100-char overlap.
 - **60x faster cached queries** - Query embedding cache eliminates redundant API calls.
-- **Auto-filters Base64/encoded content** - Skips images and attachments during indexing.
-- **4-6x faster indexing** - Parallel processing and optimized chunk generation.
+- **4-6x faster indexing** - Parallel processing and batch embeddings.
 
 ## Installation
 
@@ -178,6 +180,33 @@ title: "My Note"
 folder: "Archive"
 ```
 
+#### `batch-delete`
+Delete multiple notes at once.
+
+```
+titles: ["Note 1", "Note 2"]  # OR folder: "Old Project"
+confirm: true                 # required for safety
+```
+
+#### `batch-move`
+Move multiple notes to a target folder.
+
+```
+titles: ["Note 1", "Note 2"]  # OR sourceFolder: "Old"
+targetFolder: "Archive"       # required
+```
+
+### Index Management
+
+#### `purge-index`
+Clear all indexed data. Use when switching embedding models or to fix corrupted index.
+
+```
+confirm: true   # required for safety
+```
+
+After purging, run `index-notes` to rebuild.
+
 ### Knowledge Graph
 
 #### `list-tags`
@@ -285,6 +314,9 @@ bun run check
 # Run tests
 bun run test
 
+# Run with coverage
+bun run test:coverage
+
 # Run with debug logging
 DEBUG=true bun run start
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@disco_trooper/apple-notes-mcp",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "MCP server for Apple Notes with semantic search and CRUD operations",
   "type": "module",
   "main": "src/index.ts",
@@ -10,7 +10,8 @@
     "dev": "bun --watch run src/index.ts",
     "check": "bun run tsc --noEmit",
     "test": "vitest run",
-    "test:watch": "vitest"
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
     "@clack/prompts": "^0.8.0",
@@ -27,6 +28,7 @@
   "devDependencies": {
     "@types/bun": "^1.1.0",
     "@types/turndown": "^5.0.0",
+    "@vitest/coverage-v8": "^4.0.16",
     "typescript": "^5.7.0",
     "vitest": "^4.0.16"
   },

package/src/db/lancedb.ts

@@ -597,6 +597,34 @@ export class ChunkStore {
     });
     debug("ChunkStore: FTS index rebuilt");
   }
+
+  /**
+   * Delete chunks for multiple notes at once.
+   */
+  async deleteChunksByNoteIds(noteIds: string[]): Promise<void> {
+    if (noteIds.length === 0) return;
+
+    const table = await this.ensureTable();
+    for (const noteId of noteIds) {
+      const escapedNoteId = escapeForFilter(noteId);
+      await table.delete(`note_id = '${escapedNoteId}'`);
+    }
+    debug(`ChunkStore: Deleted chunks for ${noteIds.length} notes`);
+  }
+
+  /**
+   * Add chunks to existing table (for incremental updates).
+   */
+  async addChunks(chunks: ChunkRecord[]): Promise<void> {
+    if (chunks.length === 0) return;
+
+    const table = await this.ensureTable();
+    await table.add(chunks);
+    debug(`ChunkStore: Added ${chunks.length} chunks`);
+
+    // Rebuild FTS index after adding
+    await this.rebuildFtsIndex();
+  }
 }
 
 // Singleton instance for ChunkStore

package/src/index.ts

@@ -26,11 +26,12 @@ import { validateEnv } from "./config/env.js";
 // Import implementations
 import { getVectorStore, getChunkStore } from "./db/lancedb.js";
 import { getNoteByTitle, getAllFolders } from "./notes/read.js";
-import { createNote, updateNote, deleteNote, moveNote, editTable } from "./notes/crud.js";
+import { createNote, updateNote, deleteNote, moveNote, editTable, batchDelete, batchMove } from "./notes/crud.js";
 import { searchNotes } from "./search/index.js";
 import { indexNotes, reindexNote } from "./search/indexer.js";
 import { fullChunkIndex, hasChunkIndex } from "./search/chunk-indexer.js";
 import { searchChunks } from "./search/chunk-search.js";
+import { refreshIfNeeded } from "./search/refresh.js";
 import { listTags, searchByTag, findRelatedNotes } from "./graph/queries.js";
 import { exportGraph } from "./graph/export.js";
 
@@ -125,6 +126,28 @@ const EditTableSchema = z.object({
   })).min(1).max(100),
 });
 
+const BatchDeleteSchema = z.object({
+  titles: z.array(z.string().max(MAX_TITLE_LENGTH)).optional(),
+  folder: z.string().max(200).optional(),
+  confirm: z.literal(true),
+}).refine(
+  (data) => (data.titles && !data.folder) || (!data.titles && data.folder),
+  { message: "Specify either titles or folder, not both" }
+);
+
+const BatchMoveSchema = z.object({
+  titles: z.array(z.string().max(MAX_TITLE_LENGTH)).optional(),
+  sourceFolder: z.string().max(200).optional(),
+  targetFolder: z.string().min(1).max(200),
+}).refine(
+  (data) => (data.titles && !data.sourceFolder) || (!data.titles && data.sourceFolder),
+  { message: "Specify either titles or sourceFolder, not both" }
+);
+
+const PurgeIndexSchema = z.object({
+  confirm: z.literal(true),
+});
+
 // Knowledge Graph tool schemas
 const ListTagsSchema = z.object({});
 
@@ -229,6 +252,17 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
           required: ["title"],
         },
       },
+      {
+        name: "purge-index",
+        description: "Delete all indexed data (notes and chunks). Use when switching embedding models or to fix corrupted index.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            confirm: { type: "boolean", description: "Must be true to confirm deletion" },
+          },
+          required: ["confirm"],
+        },
+      },
       {
         name: "list-notes",
         description: "Count how many notes are indexed",
@@ -334,6 +368,52 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
           required: ["title", "edits"],
         },
       },
+      {
+        name: "batch-delete",
+        description: "Delete multiple notes at once. Requires confirm: true for safety.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            titles: {
+              type: "array",
+              items: { type: "string" },
+              description: "Note titles to delete (supports folder/title and id:xxx formats)",
+            },
+            folder: {
+              type: "string",
+              description: "Delete ALL notes in this folder",
+            },
+            confirm: {
+              type: "boolean",
+              description: "Must be true to confirm deletion",
+            },
+          },
+          required: ["confirm"],
+        },
+      },
+      {
+        name: "batch-move",
+        description: "Move multiple notes to a target folder at once.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            titles: {
+              type: "array",
+              items: { type: "string" },
+              description: "Note titles to move (supports folder/title and id:xxx formats)",
+            },
+            sourceFolder: {
+              type: "string",
+              description: "Move ALL notes from this folder",
+            },
+            targetFolder: {
+              type: "string",
+              description: "Target folder to move notes to",
+            },
+          },
+          required: ["targetFolder"],
+        },
+      },
       // Knowledge Graph tools
       {
         name: "list-tags",
@@ -405,6 +485,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       case "search-notes": {
         const params = SearchNotesSchema.parse(args);
 
+        // Smart refresh: check for changes before search
+        const refreshed = await refreshIfNeeded();
+        if (refreshed) {
+          debug("Index refreshed before search");
+        }
+
         // Use chunk-based search if chunk index exists (better for long notes)
         const useChunkSearch = await hasChunkIndex();
 
@@ -483,6 +569,17 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         return textResponse(`Reindexed note: "${params.title}"`);
       }
 
+      case "purge-index": {
+        PurgeIndexSchema.parse(args);
+        const store = getVectorStore();
+        const chunkStore = getChunkStore();
+
+        await store.clear();
+        await chunkStore.clear();
+
+        return textResponse("Index purged. Run index-notes to rebuild.");
+      }
+
       case "list-notes": {
         const store = getVectorStore();
         const noteCount = await store.count();
@@ -578,6 +675,35 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         return textResponse(`Updated ${params.edits.length} cell(s) in table ${params.table_index}`);
       }
 
+      case "batch-delete": {
+        const params = BatchDeleteSchema.parse(args);
+        const result = await batchDelete({
+          titles: params.titles,
+          folder: params.folder,
+        });
+
+        let message = `Deleted ${result.deleted} notes.`;
+        if (result.failed.length > 0) {
+          message += `\nFailed to delete: ${result.failed.join(", ")}`;
+        }
+        return textResponse(message);
+      }
+
+      case "batch-move": {
+        const params = BatchMoveSchema.parse(args);
+        const result = await batchMove({
+          titles: params.titles,
+          sourceFolder: params.sourceFolder,
+          targetFolder: params.targetFolder,
+        });
+
+        let message = `Moved ${result.moved} notes to "${params.targetFolder}".`;
+        if (result.failed.length > 0) {
+          message += `\nFailed to move: ${result.failed.join(", ")}`;
+        }
+        return textResponse(message);
+      }
+
       // Knowledge Graph tools
       case "list-tags": {
         ListTagsSchema.parse(args);

package/src/notes/crud.test.ts

@@ -28,7 +28,7 @@ vi.mock("./tables.js", () => ({
 }));
 
 import { runJxa } from "run-jxa";
-import { checkReadOnly, createNote, updateNote, deleteNote, moveNote, editTable } from "./crud.js";
+import { checkReadOnly, createNote, updateNote, deleteNote, moveNote, editTable, batchDelete, batchMove } from "./crud.js";
 import { resolveNoteTitle } from "./read.js";
 import { findTables, updateTableCell } from "./tables.js";
 
@@ -290,3 +290,124 @@ describe("editTable", () => {
     );
   });
 });
+
+describe("batchDelete", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    delete process.env.READONLY_MODE;
+  });
+
+  it("should throw if both titles and folder provided", async () => {
+    await expect(
+      batchDelete({ titles: ["Note"], folder: "Folder" })
+    ).rejects.toThrow("Specify either titles or folder, not both");
+  });
+
+  it("should throw if neither titles nor folder provided", async () => {
+    await expect(batchDelete({})).rejects.toThrow("Specify either titles or folder");
+  });
+
+  it("should throw in readonly mode", async () => {
+    process.env.READONLY_MODE = "true";
+    await expect(batchDelete({ titles: ["Note"] })).rejects.toThrow("read-only mode");
+  });
+
+  it("should delete all notes in a folder", async () => {
+    vi.mocked(runJxa).mockResolvedValue(JSON.stringify({ deletedCount: 5 }));
+
+    const result = await batchDelete({ folder: "Old Project" });
+
+    expect(result.deleted).toBe(5);
+    expect(result.failed).toEqual([]);
+  });
+
+  it("should delete individual notes by title", async () => {
+    vi.mocked(resolveNoteTitle)
+      .mockResolvedValueOnce({ success: true, note: { id: "1", title: "Note 1", folder: "Work" } })
+      .mockResolvedValueOnce({ success: true, note: { id: "2", title: "Note 2", folder: "Work" } });
+    vi.mocked(runJxa).mockResolvedValue("ok");
+
+    const result = await batchDelete({ titles: ["Note 1", "Note 2"] });
+
+    expect(result.deleted).toBe(2);
+    expect(result.failed).toEqual([]);
+  });
+
+  it("should track failed deletions", async () => {
+    vi.mocked(resolveNoteTitle)
+      .mockResolvedValueOnce({ success: true, note: { id: "1", title: "Note 1", folder: "Work" } })
+      .mockResolvedValueOnce({ success: false, error: "Note not found" });
+    vi.mocked(runJxa).mockResolvedValue("ok");
+
+    const result = await batchDelete({ titles: ["Note 1", "Missing Note"] });
+
+    expect(result.deleted).toBe(1);
+    expect(result.failed).toEqual(["Missing Note"]);
+  });
+});
+
+describe("batchMove", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    delete process.env.READONLY_MODE;
+  });
+
+  it("should throw if targetFolder missing", async () => {
+    await expect(
+      batchMove({ titles: ["Note"], targetFolder: "" })
+    ).rejects.toThrow("targetFolder is required");
+  });
+
+  it("should throw if both titles and sourceFolder provided", async () => {
+    await expect(
+      batchMove({ titles: ["Note"], sourceFolder: "Folder", targetFolder: "Archive" })
+    ).rejects.toThrow("Specify either titles or sourceFolder, not both");
+  });
+
+  it("should throw if neither titles nor sourceFolder provided", async () => {
+    await expect(
+      batchMove({ targetFolder: "Archive" })
+    ).rejects.toThrow("Specify either titles or sourceFolder");
+  });
+
+  it("should throw in readonly mode", async () => {
+    process.env.READONLY_MODE = "true";
+    await expect(batchMove({ sourceFolder: "Temp", targetFolder: "Archive" })).rejects.toThrow("read-only mode");
+  });
+
+  it("should move all notes from source folder", async () => {
+    vi.mocked(runJxa).mockResolvedValue(JSON.stringify({ movedCount: 3 }));
+
+    const result = await batchMove({
+      sourceFolder: "Temp",
+      targetFolder: "Archive",
+    });
+
+    expect(result.moved).toBe(3);
+    expect(result.failed).toEqual([]);
+  });
+
+  it("should move individual notes by title", async () => {
+    vi.mocked(resolveNoteTitle)
+      .mockResolvedValueOnce({ success: true, note: { id: "1", title: "Note 1", folder: "Work" } })
+      .mockResolvedValueOnce({ success: true, note: { id: "2", title: "Note 2", folder: "Work" } });
+    vi.mocked(runJxa).mockResolvedValue("ok");
+
+    const result = await batchMove({ titles: ["Note 1", "Note 2"], targetFolder: "Archive" });
+
+    expect(result.moved).toBe(2);
+    expect(result.failed).toEqual([]);
+  });
+
+  it("should track failed moves", async () => {
+    vi.mocked(resolveNoteTitle)
+      .mockResolvedValueOnce({ success: true, note: { id: "1", title: "Note 1", folder: "Work" } })
+      .mockResolvedValueOnce({ success: false, error: "Note not found" });
+    vi.mocked(runJxa).mockResolvedValue("ok");
+
+    const result = await batchMove({ titles: ["Note 1", "Missing Note"], targetFolder: "Archive" });
+
+    expect(result.moved).toBe(1);
+    expect(result.failed).toEqual(["Missing Note"]);
+  });
+});

package/src/notes/crud.ts

@@ -342,3 +342,210 @@ export async function editTable(
 
   debug(`Table ${tableIndex} updated in note: "${title}"`);
 }
+
+/**
+ * Result of a batch operation.
+ */
+export interface BatchResult {
+  /** Number of notes successfully processed */
+  deleted: number;
+  /** Notes that failed to process */
+  failed: string[];
+}
+
+/**
+ * Options for batch delete.
+ */
+export interface BatchDeleteOptions {
+  /** List of note titles (supports folder/title and id:xxx formats) */
+  titles?: string[];
+  /** Delete all notes in this folder */
+  folder?: string;
+}
+
+/**
+ * Delete multiple notes at once.
+ *
+ * @param options - Either titles array OR folder name (not both)
+ * @returns BatchResult with deleted count and failed notes
+ * @throws Error if READONLY_MODE is enabled
+ * @throws Error if both titles and folder provided
+ * @throws Error if neither titles nor folder provided
+ */
+export async function batchDelete(options: BatchDeleteOptions): Promise<BatchResult> {
+  checkReadOnly();
+
+  const { titles, folder } = options;
+
+  if (titles && folder) {
+    throw new Error("Specify either titles or folder, not both");
+  }
+
+  if (!titles && !folder) {
+    throw new Error("Specify either titles or folder");
+  }
+
+  const result: BatchResult = { deleted: 0, failed: [] };
+
+  if (folder) {
+    // Delete all notes in folder via single JXA call
+    debug(`Batch deleting all notes in folder: "${folder}"`);
+
+    const escapedFolder = JSON.stringify(folder);
+    const jxaResult = await runJxa(`
+      const app = Application('Notes');
+      const folderName = ${escapedFolder};
+
+      const folders = app.folders.whose({name: folderName})();
+      if (folders.length === 0) {
+        throw new Error("Folder not found: " + folderName);
+      }
+
+      const folder = folders[0];
+      const notes = folder.notes();
+      let deletedCount = 0;
+
+      // Delete in reverse order to avoid index shifting
+      for (let i = notes.length - 1; i >= 0; i--) {
+        try {
+          notes[i].delete();
+          deletedCount++;
+        } catch (e) {
+          // Continue on individual failures
+        }
+      }
+
+      return JSON.stringify({ deletedCount });
+    `);
+
+    const { deletedCount } = JSON.parse(jxaResult as string);
+    result.deleted = deletedCount;
+  } else if (titles) {
+    // Delete individual notes
+    debug(`Batch deleting ${titles.length} notes by title`);
+
+    for (const title of titles) {
+      try {
+        await deleteNote(title);
+        result.deleted++;
+      } catch (error) {
+        result.failed.push(title);
+        debug(`Failed to delete "${title}":`, error);
+      }
+    }
+  }
+
+  debug(`Batch delete complete: ${result.deleted} deleted, ${result.failed.length} failed`);
+  return result;
+}
+
+/**
+ * Result of a batch move operation.
+ */
+export interface BatchMoveResult {
+  /** Number of notes successfully moved */
+  moved: number;
+  /** Notes that failed to move */
+  failed: string[];
+}
+
+/**
+ * Options for batch move.
+ */
+export interface BatchMoveOptions {
+  /** List of note titles (supports folder/title and id:xxx formats) */
+  titles?: string[];
+  /** Move all notes from this folder */
+  sourceFolder?: string;
+  /** Target folder (required) */
+  targetFolder: string;
+}
+
+/**
+ * Move multiple notes to a target folder.
+ *
+ * @param options - Either titles array OR sourceFolder (not both) + targetFolder
+ * @returns BatchMoveResult with moved count and failed notes
+ * @throws Error if READONLY_MODE is enabled
+ * @throws Error if both titles and sourceFolder provided
+ * @throws Error if neither titles nor sourceFolder provided
+ * @throws Error if targetFolder is empty
+ */
+export async function batchMove(options: BatchMoveOptions): Promise<BatchMoveResult> {
+  checkReadOnly();
+
+  const { titles, sourceFolder, targetFolder } = options;
+
+  if (!targetFolder) {
+    throw new Error("targetFolder is required");
+  }
+
+  if (titles && sourceFolder) {
+    throw new Error("Specify either titles or sourceFolder, not both");
+  }
+
+  if (!titles && !sourceFolder) {
+    throw new Error("Specify either titles or sourceFolder");
+  }
+
+  const result: BatchMoveResult = { moved: 0, failed: [] };
+
+  if (sourceFolder) {
+    // Move all notes from source folder via single JXA call
+    debug(`Batch moving all notes from "${sourceFolder}" to "${targetFolder}"`);
+
+    const escapedSource = JSON.stringify(sourceFolder);
+    const escapedTarget = JSON.stringify(targetFolder);
+    const jxaResult = await runJxa(`
+      const app = Application('Notes');
+      const sourceName = ${escapedSource};
+      const targetName = ${escapedTarget};
+
+      const sourceFolders = app.folders.whose({name: sourceName})();
+      if (sourceFolders.length === 0) {
+        throw new Error("Source folder not found: " + sourceName);
+      }
+
+      const targetFolders = app.folders.whose({name: targetName})();
+      if (targetFolders.length === 0) {
+        throw new Error("Target folder not found: " + targetName);
+      }
+
+      const source = sourceFolders[0];
+      const target = targetFolders[0];
+      const notes = source.notes();
+      let movedCount = 0;
+
+      // Move in reverse order to avoid index shifting
+      for (let i = notes.length - 1; i >= 0; i--) {
+        try {
+          notes[i].move({to: target});
+          movedCount++;
+        } catch (e) {
+          // Continue on individual failures
+        }
+      }
+
+      return JSON.stringify({ movedCount });
+    `);
+
+    const { movedCount } = JSON.parse(jxaResult as string);
+    result.moved = movedCount;
+  } else if (titles) {
+    // Move individual notes
+    debug(`Batch moving ${titles.length} notes to "${targetFolder}"`);
+
+    for (const title of titles) {
+      try {
+        await moveNote(title, targetFolder);
+        result.moved++;
+      } catch (error) {
+        result.failed.push(title);
+        debug(`Failed to move "${title}":`, error);
+      }
+    }
+  }
+
+  debug(`Batch move complete: ${result.moved} moved, ${result.failed.length} failed`);
+  return result;
+}

package/src/search/chunk-indexer.ts

@@ -205,3 +205,50 @@ export async function hasChunkIndex(): Promise<boolean> {
     return false;
   }
 }
+
+/**
+ * Update chunks for specific notes (used by smart refresh).
+ * Deletes old chunks for these notes and creates new ones.
+ *
+ * @param notes - Notes to update chunks for
+ * @returns Number of chunks created
+ */
+export async function updateChunksForNotes(notes: NoteDetails[]): Promise<number> {
+  if (notes.length === 0) return 0;
+
+  debug(`Updating chunks for ${notes.length} notes...`);
+
+  // Chunk all notes
+  const allChunks: InternalChunkRecord[] = [];
+  for (const note of notes) {
+    const noteChunks = chunkNote(note);
+    allChunks.push(...noteChunks);
+  }
+
+  if (allChunks.length === 0) {
+    debug("No chunks to update");
+    return 0;
+  }
+
+  // Generate embeddings
+  debug(`Generating embeddings for ${allChunks.length} chunks...`);
+  const chunkTexts = allChunks.map((chunk) => chunk.content);
+  const vectors = await getEmbeddingBatch(chunkTexts);
+
+  // Combine with vectors
+  const indexedAt = new Date().toISOString();
+  const completeChunks: ChunkRecord[] = allChunks.map((chunk, i) => ({
+    ...chunk,
+    vector: vectors[i],
+    indexed_at: indexedAt,
+  }));
+
+  // Delete old chunks for these notes and add new ones
+  const chunkStore = getChunkStore();
+  const noteIds = notes.map((n) => n.id);
+  await chunkStore.deleteChunksByNoteIds(noteIds);
+  await chunkStore.addChunks(completeChunks);
+
+  debug(`Updated ${completeChunks.length} chunks for ${notes.length} notes`);
+  return completeChunks.length;
+}

package/src/search/refresh.test.ts

@@ -0,0 +1,173 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+vi.mock("../notes/read.js", () => ({
+  getAllNotes: vi.fn(),
+}));
+
+vi.mock("../db/lancedb.js", () => ({
+  getVectorStore: vi.fn(),
+}));
+
+vi.mock("./indexer.js", () => ({
+  incrementalIndex: vi.fn(),
+}));
+
+describe("checkForChanges", () => {
+  beforeEach(() => {
+    vi.resetModules();
+    vi.clearAllMocks();
+  });
+
+  it("should return true if notes were modified after indexing", async () => {
+    const { getAllNotes } = await import("../notes/read.js");
+    const { getVectorStore } = await import("../db/lancedb.js");
+
+    vi.mocked(getAllNotes).mockResolvedValue([
+      { title: "Note 1", folder: "Work", created: "2026-01-01", modified: "2026-01-10T12:00:00Z" },
+    ]);
+
+    vi.mocked(getVectorStore).mockReturnValue({
+      getAll: vi.fn().mockResolvedValue([
+        { title: "Note 1", folder: "Work", indexed_at: "2026-01-09T12:00:00Z" },
+      ]),
+    } as any);
+
+    const { checkForChanges } = await import("./refresh.js");
+    const hasChanges = await checkForChanges();
+
+    expect(hasChanges).toBe(true);
+  });
+
+  it("should return false if no changes", async () => {
+    const { getAllNotes } = await import("../notes/read.js");
+    const { getVectorStore } = await import("../db/lancedb.js");
+
+    vi.mocked(getAllNotes).mockResolvedValue([
+      { title: "Note 1", folder: "Work", created: "2026-01-01", modified: "2026-01-08T12:00:00Z" },
+    ]);
+
+    vi.mocked(getVectorStore).mockReturnValue({
+      getAll: vi.fn().mockResolvedValue([
+        { title: "Note 1", folder: "Work", indexed_at: "2026-01-09T12:00:00Z" },
+      ]),
+    } as any);
+
+    const { checkForChanges } = await import("./refresh.js");
+    const hasChanges = await checkForChanges();
+
+    expect(hasChanges).toBe(false);
+  });
+
+  it("should return true if new note added", async () => {
+    const { getAllNotes } = await import("../notes/read.js");
+    const { getVectorStore } = await import("../db/lancedb.js");
+
+    vi.mocked(getAllNotes).mockResolvedValue([
+      { title: "Note 1", folder: "Work", created: "2026-01-01", modified: "2026-01-08T12:00:00Z" },
+      { title: "New Note", folder: "Work", created: "2026-01-10", modified: "2026-01-10T12:00:00Z" },
+    ]);
+
+    vi.mocked(getVectorStore).mockReturnValue({
+      getAll: vi.fn().mockResolvedValue([
+        { title: "Note 1", folder: "Work", indexed_at: "2026-01-09T12:00:00Z" },
+      ]),
+    } as any);
+
+    const { checkForChanges } = await import("./refresh.js");
+    const hasChanges = await checkForChanges();
+
+    expect(hasChanges).toBe(true);
+  });
+
+  it("should return true if note deleted", async () => {
+    const { getAllNotes } = await import("../notes/read.js");
+    const { getVectorStore } = await import("../db/lancedb.js");
+
+    vi.mocked(getAllNotes).mockResolvedValue([]);
+
+    vi.mocked(getVectorStore).mockReturnValue({
+      getAll: vi.fn().mockResolvedValue([
+        { title: "Note 1", folder: "Work", indexed_at: "2026-01-09T12:00:00Z" },
+      ]),
+    } as any);
+
+    const { checkForChanges } = await import("./refresh.js");
+    const hasChanges = await checkForChanges();
+
+    expect(hasChanges).toBe(true);
+  });
+
+  it("should return true if no index exists and notes exist", async () => {
+    const { getAllNotes } = await import("../notes/read.js");
+    const { getVectorStore } = await import("../db/lancedb.js");
+
+    vi.mocked(getAllNotes).mockResolvedValue([
+      { title: "Note 1", folder: "Work", created: "2026-01-01", modified: "2026-01-08T12:00:00Z" },
+    ]);
+
+    vi.mocked(getVectorStore).mockReturnValue({
+      getAll: vi.fn().mockRejectedValue(new Error("Table not found")),
+    } as any);
+
+    const { checkForChanges } = await import("./refresh.js");
+    const hasChanges = await checkForChanges();
+
+    expect(hasChanges).toBe(true);
+  });
+});
+
+describe("refreshIfNeeded", () => {
+  beforeEach(() => {
+    vi.resetModules();
+    vi.clearAllMocks();
+  });
+
+  it("should trigger incremental index if changes detected", async () => {
+    const { incrementalIndex } = await import("./indexer.js");
+    const { getAllNotes } = await import("../notes/read.js");
+    const { getVectorStore } = await import("../db/lancedb.js");
+
+    vi.mocked(getAllNotes).mockResolvedValue([
+      { title: "New Note", folder: "Work", created: "2026-01-10", modified: "2026-01-10T12:00:00Z" },
+    ]);
+
+    vi.mocked(getVectorStore).mockReturnValue({
+      getAll: vi.fn().mockResolvedValue([]),
+    } as any);
+
+    vi.mocked(incrementalIndex).mockResolvedValue({
+      total: 1,
+      indexed: 1,
+      errors: 0,
+      timeMs: 100,
+    });
+
+    const { refreshIfNeeded } = await import("./refresh.js");
+    const refreshed = await refreshIfNeeded();
+
+    expect(refreshed).toBe(true);
+    expect(incrementalIndex).toHaveBeenCalled();
+  });
+
+  it("should not trigger index if no changes", async () => {
+    const { incrementalIndex } = await import("./indexer.js");
+    const { getAllNotes } = await import("../notes/read.js");
+    const { getVectorStore } = await import("../db/lancedb.js");
+
+    vi.mocked(getAllNotes).mockResolvedValue([
+      { title: "Note 1", folder: "Work", created: "2026-01-01", modified: "2026-01-08T12:00:00Z" },
+    ]);
+
+    vi.mocked(getVectorStore).mockReturnValue({
+      getAll: vi.fn().mockResolvedValue([
+        { title: "Note 1", folder: "Work", indexed_at: "2026-01-09T12:00:00Z" },
+      ]),
+    } as any);
+
+    const { refreshIfNeeded } = await import("./refresh.js");
+    const refreshed = await refreshIfNeeded();
+
+    expect(refreshed).toBe(false);
+    expect(incrementalIndex).not.toHaveBeenCalled();
+  });
+});

package/src/search/refresh.ts

@@ -0,0 +1,151 @@
+/**
+ * Smart refresh: check for note changes before search.
+ * Triggers incremental index if notes have been modified.
+ * Also updates chunk index for changed notes.
+ */
+
+import { getAllNotes, getNoteByFolderAndTitle, type NoteInfo } from "../notes/read.js";
+import { getVectorStore, getChunkStore } from "../db/lancedb.js";
+import { incrementalIndex } from "./indexer.js";
+import { updateChunksForNotes, hasChunkIndex } from "./chunk-indexer.js";
+import { createDebugLogger } from "../utils/debug.js";
+
+const debug = createDebugLogger("REFRESH");
+
+/**
+ * Detected changes in notes.
+ */
+interface DetectedChanges {
+  hasChanges: boolean;
+  added: NoteInfo[];
+  modified: NoteInfo[];
+  deleted: string[]; // note IDs
+}
+
+/**
+ * Check for note changes and return details about what changed.
+ */
+export async function detectChanges(): Promise<DetectedChanges> {
+  debug("Checking for changes...");
+
+  const currentNotes = await getAllNotes();
+  const store = getVectorStore();
+
+  let existingRecords;
+  try {
+    existingRecords = await store.getAll();
+  } catch {
+    // No index exists yet
+    debug("No existing index found");
+    return {
+      hasChanges: currentNotes.length > 0,
+      added: currentNotes,
+      modified: [],
+      deleted: [],
+    };
+  }
+
+  // Build lookup maps
+  const existingByKey = new Map<string, { indexed_at: string; id: string }>();
+  for (const record of existingRecords) {
+    const key = `${record.folder}/${record.title}`;
+    existingByKey.set(key, { indexed_at: record.indexed_at, id: record.id });
+  }
+
+  const added: NoteInfo[] = [];
+  const modified: NoteInfo[] = [];
+  const deleted: string[] = [];
+
+  // Check for new or modified notes
+  for (const note of currentNotes) {
+    const key = `${note.folder}/${note.title}`;
+    const existing = existingByKey.get(key);
+
+    if (!existing) {
+      debug(`New note detected: ${key}`);
+      added.push(note);
+    } else {
+      const noteModified = new Date(note.modified).getTime();
+      const recordIndexed = new Date(existing.indexed_at).getTime();
+
+      if (noteModified > recordIndexed) {
+        debug(`Modified note detected: ${key}`);
+        modified.push(note);
+      }
+    }
+  }
+
+  // Check for deleted notes
+  const currentKeys = new Set(currentNotes.map((n) => `${n.folder}/${n.title}`));
+  for (const [key, { id }] of existingByKey) {
+    if (!currentKeys.has(key)) {
+      debug(`Deleted note detected: ${key}`);
+      deleted.push(id);
+    }
+  }
+
+  const hasChanges = added.length > 0 || modified.length > 0 || deleted.length > 0;
+  debug(`Changes: ${added.length} added, ${modified.length} modified, ${deleted.length} deleted`);
+
+  return { hasChanges, added, modified, deleted };
+}
+
+/**
+ * Check if any notes have been modified since last index.
+ * @returns true if changes detected, false otherwise
+ */
+export async function checkForChanges(): Promise<boolean> {
+  const changes = await detectChanges();
+  return changes.hasChanges;
+}
+
+/**
+ * Refresh index if changes are detected.
+ * Updates both main index AND chunk index.
+ *
+ * @returns true if index was refreshed, false if no changes
+ */
+export async function refreshIfNeeded(): Promise<boolean> {
+  const changes = await detectChanges();
+
+  if (!changes.hasChanges) {
+    return false;
+  }
+
+  // Update main index
+  debug("Changes detected, running incremental index...");
+  const result = await incrementalIndex();
+  debug(`Main index refresh: ${result.indexed} notes updated in ${result.timeMs}ms`);
+
+  // Update chunk index if it exists and there are changes
+  const hasChunks = await hasChunkIndex();
+  if (hasChunks && (changes.added.length > 0 || changes.modified.length > 0)) {
+    debug("Updating chunk index for changed notes...");
+
+    // Fetch full content for changed notes
+    const changedNotes = [...changes.added, ...changes.modified];
+    const notesWithContent = await Promise.all(
+      changedNotes.map(async (n) => {
+        const note = await getNoteByFolderAndTitle(n.folder, n.title);
+        return note;
+      })
+    );
+
+    // Filter out nulls (notes that couldn't be fetched)
+    const validNotes = notesWithContent.filter((n) => n !== null);
+
+    if (validNotes.length > 0) {
+      const chunksCreated = await updateChunksForNotes(validNotes);
+      debug(`Chunk index refresh: ${chunksCreated} chunks for ${validNotes.length} notes`);
+    }
+
+    // Delete chunks for deleted notes
+    if (changes.deleted.length > 0) {
+      const chunkStore = getChunkStore();
+      await chunkStore.deleteChunksByNoteIds(changes.deleted);
+      debug(`Deleted chunks for ${changes.deleted.length} notes`);
+    }
+  }
+
+  return true;
+}