@disco_trooper/apple-notes-mcp 1.3.0 → 1.5.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
 
@@ -111,7 +113,19 @@ include_content: false   # include full content vs preview
 ```
 
 #### `list-notes`
-Count indexed notes.
+List notes with sorting and filtering. Without parameters, shows index statistics.
+
+```
+sort_by: "modified"      # created, modified, or title (default: modified)
+order: "desc"            # asc or desc (default: desc)
+limit: 10                # max notes to return (1-100)
+folder: "Work"           # filter by folder (case-insensitive)
+```
+
+**Examples:**
+- Get 5 newest notes: `{ sort_by: "created", order: "desc", limit: 5 }`
+- Recently modified: `{ sort_by: "modified", limit: 10 }`
+- Alphabetical in folder: `{ sort_by: "title", order: "asc", folder: "Projects" }`
 
 #### `list-folders`
 List all Apple Notes folders.
@@ -178,6 +192,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 +326,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.5.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

@@ -25,12 +25,13 @@ 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 { getNoteByTitle, getAllFolders, listNotes } from "./notes/read.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,39 @@ 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),
+});
+
+const ListNotesSchema = z.object({
+  sort_by: z.enum(["created", "modified", "title"]).default("modified"),
+  order: z.enum(["asc", "desc"]).default("desc"),
+  limit: z.number().min(1).max(100).optional(),
+  folder: z.string().max(200).optional(),
+});
+
+/** Exported type for listNotes options - derived from Zod schema (single source of truth)
+ * Using z.input to get the input type (with optionals) rather than z.infer (output with defaults applied) */
+export type ListNotesOptions = z.input<typeof ListNotesSchema>;
+
 // Knowledge Graph tool schemas
 const ListTagsSchema = z.object({});
 
@@ -229,12 +263,42 @@ 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",
+        description: "List notes from Apple Notes with sorting and filtering. Without parameters, shows index statistics.",
         inputSchema: {
           type: "object",
-          properties: {},
+          properties: {
+            sort_by: {
+              type: "string",
+              enum: ["created", "modified", "title"],
+              description: "Sort by date or title (default: modified)"
+            },
+            order: {
+              type: "string",
+              enum: ["asc", "desc"],
+              description: "Sort order (default: desc)"
+            },
+            limit: {
+              type: "number",
+              description: "Max notes to return (1-100)"
+            },
+            folder: {
+              type: "string",
+              description: "Filter by folder"
+            },
+          },
           required: [],
         },
       },
@@ -334,6 +398,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 +515,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,23 +599,46 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         return textResponse(`Reindexed note: "${params.title}"`);
       }
 
-      case "list-notes": {
+      case "purge-index": {
+        PurgeIndexSchema.parse(args);
         const store = getVectorStore();
-        const noteCount = await store.count();
-
-        let message = `${noteCount} notes indexed.`;
-
-        // Show chunk statistics if chunk index exists
-        const hasChunks = await hasChunkIndex();
-        if (hasChunks) {
-          const chunkStore = getChunkStore();
-          const chunkCount = await chunkStore.count();
-          message += ` ${chunkCount} chunks indexed for semantic search.`;
-        } else {
-          message += " Run index-notes with mode='full' to enable chunk-based search.";
+        const chunkStore = getChunkStore();
+
+        await store.clear();
+        await chunkStore.clear();
+
+        return textResponse("Index purged. Run index-notes to rebuild.");
+      }
+
+      case "list-notes": {
+        const params = ListNotesSchema.parse(args);
+
+        // No parameters provided: show index statistics (backwards compatible)
+        const hasFilteringParams =
+          params.limit !== undefined ||
+          params.folder !== undefined ||
+          (args && ("sort_by" in args || "order" in args));
+
+        if (!hasFilteringParams) {
+          const store = getVectorStore();
+          const noteCount = await store.count();
+          const hasChunks = await hasChunkIndex();
+
+          if (hasChunks) {
+            const chunkStore = getChunkStore();
+            const chunkCount = await chunkStore.count();
+            return textResponse(
+              `${noteCount} notes indexed. ${chunkCount} chunks indexed for semantic search.`
+            );
+          }
+
+          return textResponse(
+            `${noteCount} notes indexed. Run index-notes with mode='full' to enable chunk-based search.`
+          );
         }
 
-        return textResponse(message);
+        const notes = await listNotes(params);
+        return textResponse(JSON.stringify(notes, null, 2));
       }
 
       case "get-note": {
@@ -578,6 +717,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/notes/read.test.ts

@@ -6,7 +6,7 @@ vi.mock("run-jxa", () => ({
 }));
 
 import { runJxa } from "run-jxa";
-import { getAllNotes, getNoteByTitle, getAllFolders, resolveNoteTitle } from "./read.js";
+import { getAllNotes, getNoteByTitle, getAllFolders, resolveNoteTitle, listNotes } from "./read.js";
 
 describe("getAllNotes", () => {
   beforeEach(() => {
@@ -184,3 +184,164 @@ describe("getNoteByTitle with ID prefix", () => {
     expect(note).toBeNull();
   });
 });
+
+describe("listNotes", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  const mockNotes = [
+    { title: "Alpha", folder: "Work", created: "2024-01-01T00:00:00Z", modified: "2024-01-10T00:00:00Z" },
+    { title: "Beta", folder: "Personal", created: "2024-01-03T00:00:00Z", modified: "2024-01-05T00:00:00Z" },
+    { title: "Gamma", folder: "Work", created: "2024-01-02T00:00:00Z", modified: "2024-01-15T00:00:00Z" },
+  ];
+
+  it("should return all notes with default sorting (modified desc)", async () => {
+    vi.mocked(runJxa).mockResolvedValueOnce(JSON.stringify(mockNotes));
+
+    const notes = await listNotes();
+    expect(notes).toHaveLength(3);
+    // Most recently modified first
+    expect(notes[0].title).toBe("Gamma");
+    expect(notes[1].title).toBe("Alpha");
+    expect(notes[2].title).toBe("Beta");
+  });
+
+  it("should sort by created date ascending", async () => {
+    vi.mocked(runJxa).mockResolvedValueOnce(JSON.stringify(mockNotes));
+
+    const notes = await listNotes({ sort_by: "created", order: "asc" });
+    expect(notes[0].title).toBe("Alpha");
+    expect(notes[1].title).toBe("Gamma");
+    expect(notes[2].title).toBe("Beta");
+  });
+
+  it("should sort by created date descending", async () => {
+    vi.mocked(runJxa).mockResolvedValueOnce(JSON.stringify(mockNotes));
+
+    const notes = await listNotes({ sort_by: "created", order: "desc" });
+    expect(notes[0].title).toBe("Beta");
+    expect(notes[1].title).toBe("Gamma");
+    expect(notes[2].title).toBe("Alpha");
+  });
+
+  it("should sort by title alphabetically", async () => {
+    vi.mocked(runJxa).mockResolvedValueOnce(JSON.stringify(mockNotes));
+
+    const notes = await listNotes({ sort_by: "title", order: "asc" });
+    expect(notes[0].title).toBe("Alpha");
+    expect(notes[1].title).toBe("Beta");
+    expect(notes[2].title).toBe("Gamma");
+  });
+
+  it("should sort by title descending", async () => {
+    vi.mocked(runJxa).mockResolvedValueOnce(JSON.stringify(mockNotes));
+
+    const notes = await listNotes({ sort_by: "title", order: "desc" });
+    expect(notes[0].title).toBe("Gamma");
+    expect(notes[1].title).toBe("Beta");
+    expect(notes[2].title).toBe("Alpha");
+  });
+
+  it("should filter by folder", async () => {
+    vi.mocked(runJxa).mockResolvedValueOnce(JSON.stringify(mockNotes));
+
+    const notes = await listNotes({ folder: "Work" });
+    expect(notes).toHaveLength(2);
+    expect(notes.every(n => n.folder === "Work")).toBe(true);
+  });
+
+  it("should apply limit", async () => {
+    vi.mocked(runJxa).mockResolvedValueOnce(JSON.stringify(mockNotes));
+
+    const notes = await listNotes({ limit: 2 });
+    expect(notes).toHaveLength(2);
+  });
+
+  it("should combine folder filter and limit", async () => {
+    vi.mocked(runJxa).mockResolvedValueOnce(JSON.stringify(mockNotes));
+
+    const notes = await listNotes({ folder: "Work", limit: 1 });
+    expect(notes).toHaveLength(1);
+    expect(notes[0].folder).toBe("Work");
+  });
+
+  it("should return empty array when folder has no notes", async () => {
+    vi.mocked(runJxa).mockResolvedValueOnce(JSON.stringify(mockNotes));
+
+    const notes = await listNotes({ folder: "NonExistent" });
+    expect(notes).toHaveLength(0);
+  });
+
+  it("should handle empty notes array", async () => {
+    vi.mocked(runJxa).mockResolvedValueOnce("[]");
+
+    const notes = await listNotes();
+    expect(notes).toHaveLength(0);
+  });
+
+  it("should handle notes with empty date strings without crashing", async () => {
+    const notesWithEmptyDates = [
+      { title: "Valid", folder: "Work", created: "2024-01-01T00:00:00Z", modified: "2024-01-10T00:00:00Z" },
+      { title: "Empty", folder: "Work", created: "", modified: "" },
+    ];
+    vi.mocked(runJxa).mockResolvedValueOnce(JSON.stringify(notesWithEmptyDates));
+
+    const notes = await listNotes();
+    expect(notes).toHaveLength(2);
+    expect(notes[0].title).toBe("Valid");
+    expect(notes[1].title).toBe("Empty");
+  });
+
+  it("should sort notes with empty dates to the end (oldest)", async () => {
+    const notesWithEmptyDates = [
+      { title: "Empty", folder: "Work", created: "", modified: "" },
+      { title: "Valid", folder: "Work", created: "2024-01-01T00:00:00Z", modified: "2024-01-10T00:00:00Z" },
+    ];
+    vi.mocked(runJxa).mockResolvedValueOnce(JSON.stringify(notesWithEmptyDates));
+
+    const notes = await listNotes({ sort_by: "modified", order: "desc" });
+    expect(notes).toHaveLength(2);
+    // Valid note should come first (most recent)
+    expect(notes[0].title).toBe("Valid");
+    // Empty date should be last (treated as oldest)
+    expect(notes[1].title).toBe("Empty");
+  });
+
+  it("should handle mixing valid and empty dates correctly", async () => {
+    const mixedDates = [
+      { title: "Recent", folder: "Work", created: "2024-03-01T00:00:00Z", modified: "2024-03-15T00:00:00Z" },
+      { title: "Empty1", folder: "Work", created: "", modified: "" },
+      { title: "Old", folder: "Work", created: "2024-01-01T00:00:00Z", modified: "2024-01-10T00:00:00Z" },
+      { title: "Empty2", folder: "Work", created: "", modified: "" },
+      { title: "Middle", folder: "Work", created: "2024-02-01T00:00:00Z", modified: "2024-02-15T00:00:00Z" },
+    ];
+    vi.mocked(runJxa).mockResolvedValueOnce(JSON.stringify(mixedDates));
+
+    const notes = await listNotes({ sort_by: "modified", order: "desc" });
+    expect(notes).toHaveLength(5);
+    // Order should be: Recent, Middle, Old, Empty1, Empty2
+    expect(notes[0].title).toBe("Recent");
+    expect(notes[1].title).toBe("Middle");
+    expect(notes[2].title).toBe("Old");
+    // Empty dates at the end (treated as epoch)
+    expect(notes[3].title).toBe("Empty1");
+    expect(notes[4].title).toBe("Empty2");
+  });
+
+  it("should sort empty dates to the beginning when sorting ascending", async () => {
+    const mixedDates = [
+      { title: "Recent", folder: "Work", created: "2024-03-01T00:00:00Z", modified: "2024-03-15T00:00:00Z" },
+      { title: "Empty", folder: "Work", created: "", modified: "" },
+      { title: "Old", folder: "Work", created: "2024-01-01T00:00:00Z", modified: "2024-01-10T00:00:00Z" },
+    ];
+    vi.mocked(runJxa).mockResolvedValueOnce(JSON.stringify(mixedDates));
+
+    const notes = await listNotes({ sort_by: "modified", order: "asc" });
+    expect(notes).toHaveLength(3);
+    // Empty date should be first (oldest when ascending)
+    expect(notes[0].title).toBe("Empty");
+    expect(notes[1].title).toBe("Old");
+    expect(notes[2].title).toBe("Recent");
+  });
+});

package/src/notes/read.ts

@@ -434,3 +434,52 @@ export async function getAllFolders(): Promise<string[]> {
   debug(`Found ${folders.length} folders`);
   return folders;
 }
+
+// -----------------------------------------------------------------------------
+// List Notes with Sorting and Filtering
+// -----------------------------------------------------------------------------
+
+// Re-export ListNotesOptions from index.ts (derived from Zod schema - single source of truth)
+export type { ListNotesOptions } from "../index.js";
+
+// Import the type for internal use
+import type { ListNotesOptions } from "../index.js";
+
+/**
+ * List notes with sorting and filtering.
+ *
+ * @param options - Sorting and filtering options
+ * @returns Array of note metadata sorted and filtered as specified
+ */
+export async function listNotes(options: ListNotesOptions = {}): Promise<NoteInfo[]> {
+  const { sort_by = "modified", order = "desc", limit, folder } = options;
+
+  debug(`Listing notes: sort_by=${sort_by}, order=${order}, limit=${limit}, folder=${folder}`);
+
+  const allNotes = await getAllNotes();
+
+  // Filter by folder (case-insensitive for better UX)
+  const filtered = folder
+    ? allNotes.filter((n) => n.folder.toLowerCase() === folder.toLowerCase())
+    : allNotes;
+
+  filtered.sort((a, b) => {
+    let comparison: number;
+
+    if (sort_by === "title") {
+      comparison = a.title.localeCompare(b.title);
+    } else {
+      // Handle empty dates by treating them as epoch (0)
+      const aTime = a[sort_by] ? new Date(a[sort_by]).getTime() : 0;
+      const bTime = b[sort_by] ? new Date(b[sort_by]).getTime() : 0;
+      comparison = aTime - bTime;
+    }
+
+    return order === "desc" ? -comparison : comparison;
+  });
+
+  const result = limit ? filtered.slice(0, limit) : filtered;
+
+  debug(`Returning ${result.length} notes`);
+  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;
+}