@disco_trooper/apple-notes-mcp 1.1.0 → 1.3.0

package/src/embeddings/cache.ts

@@ -0,0 +1,204 @@
+/**
+ * LRU Cache for query embeddings.
+ * Dramatically speeds up hybrid search by caching repeated queries.
+ */
+
+import { createDebugLogger } from "../utils/debug.js";
+
+const debug = createDebugLogger("EMBED_CACHE");
+
+/**
+ * Simple LRU Cache implementation for embeddings.
+ */
+class LRUCache<K, V> {
+  private cache = new Map<K, V>();
+  private readonly maxSize: number;
+
+  constructor(maxSize: number) {
+    this.maxSize = maxSize;
+  }
+
+  get(key: K): V | undefined {
+    const value = this.cache.get(key);
+    if (value !== undefined) {
+      // Move to end (most recently used)
+      this.cache.delete(key);
+      this.cache.set(key, value);
+    }
+    return value;
+  }
+
+  set(key: K, value: V): void {
+    // Delete if exists (to update position)
+    if (this.cache.has(key)) {
+      this.cache.delete(key);
+    }
+    // Evict oldest if at capacity
+    else if (this.cache.size >= this.maxSize) {
+      const firstKey = this.cache.keys().next().value;
+      if (firstKey !== undefined) {
+        this.cache.delete(firstKey);
+      }
+    }
+    this.cache.set(key, value);
+  }
+
+  has(key: K): boolean {
+    return this.cache.has(key);
+  }
+
+  clear(): void {
+    this.cache.clear();
+  }
+
+  get size(): number {
+    return this.cache.size;
+  }
+}
+
+/**
+ * Normalize query for better cache hit rate.
+ * - Lowercase
+ * - Trim whitespace
+ * - Collapse multiple spaces
+ */
+function normalizeQuery(query: string): string {
+  return query.toLowerCase().trim().replace(/\s+/g, " ");
+}
+
+/**
+ * Cache statistics for monitoring.
+ */
+export interface CacheStats {
+  hits: number;
+  misses: number;
+  size: number;
+  hitRate: number;
+}
+
+/**
+ * Embedding cache with LRU eviction.
+ */
+class EmbeddingCache {
+  private cache: LRUCache<string, number[]>;
+  private modelVersion: string;
+  private hits = 0;
+  private misses = 0;
+
+  constructor(maxSize = 1000, modelVersion = "default") {
+    this.cache = new LRUCache(maxSize);
+    this.modelVersion = modelVersion;
+    debug(`Embedding cache initialized (max: ${maxSize})`);
+  }
+
+  /**
+   * Create cache key from query and model version.
+   */
+  private makeKey(query: string): string {
+    const normalized = normalizeQuery(query);
+    return `${this.modelVersion}:${normalized}`;
+  }
+
+  /**
+   * Get cached embedding for query.
+   * Returns undefined if not cached.
+   */
+  get(query: string): number[] | undefined {
+    const key = this.makeKey(query);
+    const cached = this.cache.get(key);
+
+    if (cached) {
+      this.hits++;
+      debug(`Cache HIT for "${query.slice(0, 30)}..." (hits: ${this.hits})`);
+      return cached;
+    }
+
+    this.misses++;
+    return undefined;
+  }
+
+  /**
+   * Store embedding in cache.
+   */
+  set(query: string, embedding: number[]): void {
+    const key = this.makeKey(query);
+    this.cache.set(key, embedding);
+    debug(`Cached embedding for "${query.slice(0, 30)}..." (size: ${this.cache.size})`);
+  }
+
+  /**
+   * Get or compute embedding using provided function.
+   * This is the main API for cached embedding retrieval.
+   */
+  async getOrCompute(
+    query: string,
+    computeFn: (q: string) => Promise<number[]>
+  ): Promise<number[]> {
+    const cached = this.get(query);
+    if (cached) {
+      return cached;
+    }
+
+    const embedding = await computeFn(query);
+    this.set(query, embedding);
+    return embedding;
+  }
+
+  /**
+   * Invalidate cache (e.g., when model changes).
+   */
+  clear(): void {
+    this.cache.clear();
+    this.hits = 0;
+    this.misses = 0;
+    debug("Cache cleared");
+  }
+
+  /**
+   * Update model version and clear cache.
+   */
+  setModelVersion(version: string): void {
+    if (version !== this.modelVersion) {
+      debug(`Model version changed: ${this.modelVersion} -> ${version}`);
+      this.modelVersion = version;
+      this.clear();
+    }
+  }
+
+  /**
+   * Get cache statistics.
+   */
+  getStats(): CacheStats {
+    const total = this.hits + this.misses;
+    return {
+      hits: this.hits,
+      misses: this.misses,
+      size: this.cache.size,
+      hitRate: total > 0 ? this.hits / total : 0,
+    };
+  }
+}
+
+// Singleton instance
+let cacheInstance: EmbeddingCache | null = null;
+
+/**
+ * Get the embedding cache singleton.
+ */
+export function getEmbeddingCache(): EmbeddingCache {
+  if (!cacheInstance) {
+    // Max 1000 queries * ~1.5KB per embedding = ~1.5MB
+    cacheInstance = new EmbeddingCache(1000);
+  }
+  return cacheInstance;
+}
+
+/**
+ * Reset the cache (useful for testing).
+ */
+export function resetEmbeddingCache(): void {
+  if (cacheInstance) {
+    cacheInstance.clear();
+  }
+  cacheInstance = null;
+}

package/src/embeddings/index.ts

@@ -6,8 +6,8 @@
  * - Local HuggingFace (fallback)
  */
 
-import { getOpenRouterEmbedding, getOpenRouterDimensions } from "./openrouter.js";
-import { getLocalEmbedding, getLocalDimensions, getLocalModelName } from "./local.js";
+import { getOpenRouterEmbedding, getOpenRouterDimensions, getOpenRouterEmbeddingBatch } from "./openrouter.js";
+import { getLocalEmbedding, getLocalDimensions, getLocalModelName, getLocalEmbeddingBatch } from "./local.js";
 import { createDebugLogger } from "../utils/debug.js";
 
 // Debug logging
@@ -41,10 +41,9 @@ export function detectProvider(): EmbeddingProvider {
 
 /**
  * Get the current embedding provider.
- * Call detectProvider() first to ensure detection has occurred.
  */
 export function getProvider(): EmbeddingProvider {
-  return detectedProvider || detectProvider();
+  return detectedProvider ?? detectProvider();
 }
 
 /**
@@ -63,6 +62,23 @@ export async function getEmbedding(text: string): Promise<number[]> {
   }
 }
 
+/**
+ * Generate embeddings for multiple texts in batch.
+ * Uses native batch API for both OpenRouter and local providers.
+ *
+ * @param texts - Array of texts to embed
+ * @returns Promise resolving to array of embedding vectors
+ */
+export async function getEmbeddingBatch(texts: string[]): Promise<number[][]> {
+  const provider = getProvider();
+
+  if (provider === "openrouter") {
+    return getOpenRouterEmbeddingBatch(texts);
+  } else {
+    return getLocalEmbeddingBatch(texts);
+  }
+}
+
 /**
  * Get the embedding dimensions for the current provider.
  *
@@ -101,10 +117,12 @@ export function getProviderDescription(): string {
 export {
   getOpenRouterEmbedding,
   getOpenRouterDimensions,
+  getOpenRouterEmbeddingBatch,
 } from "./openrouter.js";
 
 export {
   getLocalEmbedding,
+  getLocalEmbeddingBatch,
   getLocalDimensions,
   getLocalModelName,
   isModelLoaded,

package/src/embeddings/local.ts

@@ -25,13 +25,12 @@ const debug = createDebugLogger("LOCAL");
 
 // Lazy-loaded pipeline
 type FeatureExtractionPipeline = (
-  text: string,
+  text: string | string[],
   options?: { pooling?: string; normalize?: boolean }
 ) => Promise<{ tolist: () => number[][] }>;
 
 let pipelineInstance: FeatureExtractionPipeline | null = null;
 let pipelinePromise: Promise<FeatureExtractionPipeline> | null = null;
-let resolvedModel: string | null = null;
 
 /**
  * Get the configured model name.
@@ -41,6 +40,27 @@ function getModelName(): string {
   return process.env.EMBEDDING_MODEL || DEFAULT_MODEL;
 }
 
+/**
+ * Check if the model is an E5 model that requires prefixed input.
+ */
+function isE5Model(): boolean {
+  return getModelName().toLowerCase().includes("e5");
+}
+
+/**
+ * Prepare text for embedding by adding E5 prefix if needed.
+ */
+function prepareText(text: string): string {
+  return isE5Model() ? `passage: ${text}` : text;
+}
+
+/**
+ * Prepare multiple texts for embedding by adding E5 prefix if needed.
+ */
+function prepareTexts(texts: string[]): string[] {
+  return isE5Model() ? texts.map(t => `passage: ${t}`) : texts;
+}
+
 /**
  * Lazy-load the HuggingFace transformers pipeline.
  * Only loads once, subsequent calls return the cached instance.
@@ -82,8 +102,6 @@ async function getPipeline(): Promise<FeatureExtractionPipeline> {
       debug(`Model loaded in ${loadTime}ms`);
 
       pipelineInstance = pipe;
-      resolvedModel = modelName;
-
       return pipe;
     } catch (error) {
       // Reset promise so next call retries
@@ -119,19 +137,11 @@ export async function getLocalEmbedding(text: string): Promise<number[]> {
   const startTime = Date.now();
 
   try {
-    // For e5 models, prepend "passage: " for document embedding
-    // or "query: " for search queries - using passage for general text
-    const modelName = getModelName();
-    const isE5Model = modelName.toLowerCase().includes("e5");
-    const inputText = isE5Model ? `passage: ${text}` : text;
-
-    // Run inference with mean pooling and normalization
-    const output = await pipe(inputText, {
+    const output = await pipe(prepareText(text), {
       pooling: "mean",
       normalize: true,
     });
 
-    // Extract the embedding vector
     const embedding = output.tolist()[0];
 
     const inferenceTime = Date.now() - startTime;
@@ -183,9 +193,39 @@ export function isModelLoaded(): boolean {
 }
 
 /**
- * Get the name of the actually loaded model.
- * Returns null if no model has been loaded yet.
+ * Generate embeddings for multiple texts in a single batch call.
+ * More efficient than calling getLocalEmbedding for each text individually.
+ *
+ * @param texts - Array of texts to embed
+ * @returns Promise resolving to array of embedding vectors
+ * @throws Error if model loading or inference fails
  */
-export function getLoadedModelName(): string | null {
-  return resolvedModel;
+export async function getLocalEmbeddingBatch(texts: string[]): Promise<number[][]> {
+  if (!texts || texts.length === 0) {
+    return [];
+  }
+
+  const pipe = await getPipeline();
+
+  debug(`Generating batch embeddings for ${texts.length} texts`);
+  const startTime = Date.now();
+
+  try {
+    const output = await pipe(prepareTexts(texts), {
+      pooling: "mean",
+      normalize: true,
+    });
+
+    const embeddings = output.tolist() as number[][];
+
+    const inferenceTime = Date.now() - startTime;
+    debug(`Batch embeddings generated in ${inferenceTime}ms (${embeddings.length} vectors, ${embeddings[0]?.length ?? 0} dims)`);
+
+    return embeddings;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    debug(`Batch embedding generation failed: ${message}`);
+
+    throw new Error(`Failed to generate batch embeddings: ${message}`);
+  }
 }

package/src/embeddings/openrouter.ts

@@ -108,6 +108,27 @@ class OpenRouterError extends Error {
   }
 }
 
+/** HTTP status codes that should not be retried */
+const NON_RETRYABLE_STATUS_CODES = [400, 401, 403, 404];
+
+/** Common headers for OpenRouter API requests */
+const API_HEADERS = {
+  "Content-Type": "application/json",
+  "HTTP-Referer": "https://github.com/apple-notes-mcp",
+  "X-Title": "Apple Notes MCP",
+} as const;
+
+/**
+ * Check if an error should trigger a retry or fail immediately.
+ * Returns true if the error is non-retryable.
+ */
+function isNonRetryableError(error: unknown): boolean {
+  if (error instanceof OpenRouterError && error.statusCode) {
+    return NON_RETRYABLE_STATUS_CODES.includes(error.statusCode);
+  }
+  return false;
+}
+
 /**
  * Get embedding vector for text using OpenRouter API
  *
@@ -157,9 +178,7 @@ export async function getOpenRouterEmbedding(text: string): Promise<number[]> {
         method: "POST",
         headers: {
           Authorization: `Bearer ${OPENROUTER_API_KEY}`,
-          "Content-Type": "application/json",
-          "HTTP-Referer": "https://github.com/apple-notes-mcp",
-          "X-Title": "Apple Notes MCP",
+          ...API_HEADERS,
         },
         body: JSON.stringify({
           model: EMBEDDING_MODEL,
@@ -224,17 +243,12 @@ export async function getOpenRouterEmbedding(text: string): Promise<number[]> {
           `Request timed out after ${OPENROUTER_TIMEOUT_MS}ms`,
           408
         );
-        // Don't throw - fall through to retry logic below
       } else {
         lastError = error instanceof Error ? error : new Error(String(error));
 
-        // Don't retry on non-retryable errors
-        if (error instanceof OpenRouterError && error.statusCode) {
-          const nonRetryable = [400, 401, 403, 404];
-          if (nonRetryable.includes(error.statusCode)) {
-            debug(`Non-retryable error (${error.statusCode}), failing immediately`);
-            throw error;
-          }
+        if (isNonRetryableError(error)) {
+          debug(`Non-retryable error, failing immediately`);
+          throw error;
         }
       }
 
@@ -283,3 +297,211 @@ export function clearEmbeddingCache(): void {
 export function getEmbeddingCacheSize(): number {
   return embeddingCache.size;
 }
+
+/**
+ * Batch size for embedding requests.
+ * OpenRouter supports up to 2048 inputs per request, but 50-100 is optimal.
+ */
+const BATCH_SIZE = 50;
+
+/**
+ * Number of concurrent batch API calls.
+ * Higher values increase throughput but may hit rate limits.
+ */
+const CONCURRENT_BATCHES = 3;
+
+/**
+ * Split an array into chunks of specified size.
+ */
+function chunk<T>(array: T[], size: number): T[][] {
+  const chunks: T[][] = [];
+  for (let i = 0; i < array.length; i += size) {
+    chunks.push(array.slice(i, i + size));
+  }
+  return chunks;
+}
+
+/**
+ * Process a single batch of texts and return embeddings.
+ * Internal helper for concurrent batch processing.
+ */
+async function processSingleBatch(
+  batchTexts: string[],
+  batchIndices: number[],
+  cacheKeys: string[],
+  results: (number[] | null)[],
+  batchNumber: number,
+  totalBatches: number
+): Promise<void> {
+  debug(`Processing batch ${batchNumber}/${totalBatches} (${batchTexts.length} texts)`);
+
+  let lastError: Error | null = null;
+
+  for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), OPENROUTER_TIMEOUT_MS * 2);
+
+    try {
+      const response = await fetch(API_URL, {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${OPENROUTER_API_KEY}`,
+          ...API_HEADERS,
+        },
+        body: JSON.stringify({
+          model: EMBEDDING_MODEL,
+          input: batchTexts,
+          dimensions: EMBEDDING_DIMS,
+        }),
+        signal: controller.signal,
+      });
+
+      if (response.status === 429) {
+        clearTimeout(timeoutId);
+        const waitTime = getBackoffDelay(attempt, RATE_LIMIT_BACKOFF_BASE_MS);
+        debug(`Batch ${batchNumber}: Rate limited (429), waiting ${waitTime}ms`);
+        await sleep(waitTime);
+        continue;
+      }
+
+      if (!response.ok) {
+        const errorBody = await response.text();
+        throw new OpenRouterError(
+          `OpenRouter API error: ${response.status} - ${errorBody}`,
+          response.status,
+          errorBody
+        );
+      }
+
+      const data = await response.json() as {
+        data?: Array<{ embedding?: number[]; index?: number }>;
+      };
+
+      if (!data?.data || data.data.length !== batchTexts.length) {
+        throw new OpenRouterError(
+          `Invalid API response: expected ${batchTexts.length} embeddings, got ${data?.data?.length ?? 0}`,
+          response.status,
+          JSON.stringify(data)
+        );
+      }
+
+      // Store results and cache them
+      for (let j = 0; j < data.data.length; j++) {
+        const embedding = data.data[j].embedding;
+        if (!embedding) {
+          throw new OpenRouterError(
+            `Missing embedding at index ${j}`,
+            response.status,
+            JSON.stringify(data)
+          );
+        }
+
+        results[batchIndices[j]] = embedding;
+        embeddingCache.set(cacheKeys[batchIndices[j]], embedding);
+      }
+
+      return; // Success
+
+    } catch (error) {
+      if (error instanceof Error && error.name === "AbortError") {
+        lastError = new OpenRouterError(
+          `Batch request timed out after ${OPENROUTER_TIMEOUT_MS * 2}ms`,
+          408
+        );
+      } else {
+        lastError = error instanceof Error ? error : new Error(String(error));
+
+        if (isNonRetryableError(error)) {
+          throw error;
+        }
+      }
+
+      if (attempt < MAX_RETRIES - 1) {
+        const waitTime = getBackoffDelay(attempt);
+        debug(`Batch ${batchNumber} error: ${lastError.message}, retrying in ${waitTime}ms`);
+        await sleep(waitTime);
+      }
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+
+  throw new OpenRouterError(
+    `Failed to get batch ${batchNumber} embeddings after ${MAX_RETRIES} attempts: ${lastError?.message}`
+  );
+}
+
+/**
+ * Get embedding vectors for multiple texts using concurrent batch API calls.
+ * Much faster than calling getOpenRouterEmbedding individually.
+ *
+ * @param texts - Array of input texts to embed
+ * @returns Promise resolving to array of embedding vectors
+ * @throws OpenRouterError if API call fails
+ */
+export async function getOpenRouterEmbeddingBatch(texts: string[]): Promise<number[][]> {
+  if (!OPENROUTER_API_KEY) {
+    throw new OpenRouterError(
+      "OPENROUTER_API_KEY environment variable is not set"
+    );
+  }
+
+  if (texts.length === 0) {
+    return [];
+  }
+
+  // Truncate all inputs and check cache
+  const truncatedTexts = texts.map(t => truncateForEmbedding(t));
+  const cacheKeys = truncatedTexts.map(t => getCacheKey(t));
+
+  // Separate cached and uncached
+  const results: (number[] | null)[] = new Array(texts.length).fill(null);
+  const uncachedIndices: number[] = [];
+  const uncachedTexts: string[] = [];
+
+  for (let i = 0; i < truncatedTexts.length; i++) {
+    const cached = embeddingCache.get(cacheKeys[i]);
+    if (cached) {
+      results[i] = cached;
+    } else {
+      uncachedIndices.push(i);
+      uncachedTexts.push(truncatedTexts[i]);
+    }
+  }
+
+  debug(`Batch: ${texts.length} total, ${uncachedIndices.length} uncached`);
+
+  if (uncachedTexts.length === 0) {
+    return results as number[][];
+  }
+
+  // Split into batches
+  const textBatches = chunk(uncachedTexts, BATCH_SIZE);
+  const indexBatches = chunk(uncachedIndices, BATCH_SIZE);
+  const totalBatches = textBatches.length;
+
+  debug(`Processing ${totalBatches} batches with ${CONCURRENT_BATCHES} concurrent requests`);
+
+  // Process batches with concurrency limit
+  const batchGroups = chunk(
+    textBatches.map((texts, i) => ({ texts, indices: indexBatches[i], batchNumber: i + 1 })),
+    CONCURRENT_BATCHES
+  );
+
+  for (const group of batchGroups) {
+    await Promise.all(
+      group.map(batch =>
+        processSingleBatch(
+          batch.texts,
+          batch.indices,
+          cacheKeys,
+          results,
+          batch.batchNumber,
+          totalBatches
+        )
+      )
+    );
+  }
+
+  return results as number[][];
+}

package/src/errors/index.test.ts

@@ -0,0 +1,64 @@
+// src/errors/index.test.ts
+import { describe, it, expect } from "vitest";
+import {
+  NoteNotFoundError,
+  ReadOnlyModeError,
+  DuplicateNoteError,
+  FolderNotFoundError,
+  TableOutOfBoundsError,
+} from "./index.js";
+
+describe("Error Classes", () => {
+  describe("NoteNotFoundError", () => {
+    it("should have correct name and message", () => {
+      const error = new NoteNotFoundError("My Note");
+      expect(error.name).toBe("NoteNotFoundError");
+      expect(error.message).toBe('Note not found: "My Note"');
+      expect(error.title).toBe("My Note");
+      expect(error instanceof Error).toBe(true);
+    });
+  });
+
+  describe("ReadOnlyModeError", () => {
+    it("should have correct name and message", () => {
+      const error = new ReadOnlyModeError();
+      expect(error.name).toBe("ReadOnlyModeError");
+      expect(error.message).toBe("Operation disabled in read-only mode");
+      expect(error instanceof Error).toBe(true);
+    });
+  });
+
+  describe("DuplicateNoteError", () => {
+    it("should have correct name and suggestions", () => {
+      const suggestions = [
+        { id: "id-1", folder: "Work", title: "Note", created: "2026-01-09T10:00:00.000Z" },
+        { id: "id-2", folder: "Personal", title: "Note", created: "2026-01-09T11:00:00.000Z" },
+      ];
+      const error = new DuplicateNoteError("Note", suggestions);
+      expect(error.name).toBe("DuplicateNoteError");
+      expect(error.title).toBe("Note");
+      expect(error.suggestions).toEqual(suggestions);
+      expect(error.message).toContain("Multiple notes found");
+      expect(error.message).toContain("id:id-1");
+      expect(error.message).toContain("id:id-2");
+    });
+  });
+
+  describe("FolderNotFoundError", () => {
+    it("should have correct name and message", () => {
+      const error = new FolderNotFoundError("Work");
+      expect(error.name).toBe("FolderNotFoundError");
+      expect(error.folder).toBe("Work");
+      expect(error.message).toBe('Folder not found: "Work"');
+    });
+  });
+
+  describe("TableOutOfBoundsError", () => {
+    it("should have correct name and message", () => {
+      const error = new TableOutOfBoundsError("Row 5 out of bounds (table has 3 rows)");
+      expect(error.name).toBe("TableOutOfBoundsError");
+      expect(error.message).toBe("Row 5 out of bounds (table has 3 rows)");
+      expect(error instanceof Error).toBe(true);
+    });
+  });
+});