memory-lancedb-pro 1.0.25 → 1.0.26

package/src/store.ts

@@ -4,7 +4,14 @@
 
 import type * as LanceDB from "@lancedb/lancedb";
 import { randomUUID } from "node:crypto";
-import { existsSync, accessSync, constants, mkdirSync, realpathSync, lstatSync } from "node:fs";
+import {
+  existsSync,
+  accessSync,
+  constants,
+  mkdirSync,
+  realpathSync,
+  lstatSync,
+} from "node:fs";
 import { dirname } from "node:path";
 
 // ============================================================================
@@ -36,16 +43,22 @@ export interface StoreConfig {
 // LanceDB Dynamic Import
 // ============================================================================
 
-let lancedbImportPromise: Promise<typeof import("@lancedb/lancedb")> | null = null;
+let lancedbImportPromise: Promise<typeof import("@lancedb/lancedb")> | null =
+  null;
 
-export const loadLanceDB = async (): Promise<typeof import("@lancedb/lancedb")> => {
+export const loadLanceDB = async (): Promise<
+  typeof import("@lancedb/lancedb")
+> => {
   if (!lancedbImportPromise) {
     lancedbImportPromise = import("@lancedb/lancedb");
   }
   try {
     return await lancedbImportPromise;
   } catch (err) {
-    throw new Error(`memory-lancedb-pro: failed to load LanceDB. ${String(err)}`, { cause: err });
+    throw new Error(
+      `memory-lancedb-pro: failed to load LanceDB. ${String(err)}`,
+      { cause: err },
+    );
   }
 };
 
@@ -83,8 +96,8 @@ export function validateStoragePath(dbPath: string): string {
       } catch (err: any) {
         throw new Error(
           `dbPath "${dbPath}" is a symlink whose target does not exist.\n` +
-          `  Fix: Create the target directory, or update the symlink to point to a valid path.\n` +
-          `  Details: ${err.code || ""} ${err.message}`
+            `  Fix: Create the target directory, or update the symlink to point to a valid path.\n` +
+            `  Details: ${err.code || ""} ${err.message}`,
         );
       }
     }
@@ -92,7 +105,10 @@ export function validateStoragePath(dbPath: string): string {
     // Missing path is OK (it will be created below)
     if (err?.code === "ENOENT") {
       // no-op
-    } else if (typeof err?.message === "string" && err.message.includes("symlink whose target does not exist")) {
+    } else if (
+      typeof err?.message === "string" &&
+      err.message.includes("symlink whose target does not exist")
+    ) {
       throw err;
     } else {
       // Other lstat failures — continue with original path
@@ -106,9 +122,9 @@ export function validateStoragePath(dbPath: string): string {
     } catch (err: any) {
       throw new Error(
         `Failed to create dbPath directory "${resolvedPath}".\n` +
-        `  Fix: Ensure the parent directory "${dirname(resolvedPath)}" exists and is writable,\n` +
-        `       or create it manually: mkdir -p "${resolvedPath}"\n` +
-        `  Details: ${err.code || ""} ${err.message}`
+          `  Fix: Ensure the parent directory "${dirname(resolvedPath)}" exists and is writable,\n` +
+          `       or create it manually: mkdir -p "${resolvedPath}"\n` +
+          `  Details: ${err.code || ""} ${err.message}`,
       );
     }
   }
@@ -119,9 +135,9 @@ export function validateStoragePath(dbPath: string): string {
   } catch (err: any) {
     throw new Error(
       `dbPath directory "${resolvedPath}" is not writable.\n` +
-      `  Fix: Check permissions with: ls -la "${dirname(resolvedPath)}"\n` +
-      `       Or grant write access: chmod u+w "${resolvedPath}"\n` +
-      `  Details: ${err.code || ""} ${err.message}`
+        `  Fix: Check permissions with: ls -la "${dirname(resolvedPath)}"\n` +
+        `       Or grant write access: chmod u+w "${resolvedPath}"\n` +
+        `  Details: ${err.code || ""} ${err.message}`,
     );
   }
 
@@ -172,7 +188,7 @@ export class MemoryStore {
       const message = err.message || String(err);
       throw new Error(
         `Failed to open LanceDB at "${this.config.dbPath}": ${code} ${message}\n` +
-        `  Fix: Verify the path exists and is writable. Check parent directory permissions.`
+          `  Fix: Verify the path exists and is writable. Check parent directory permissions.`,
       );
     }
 
@@ -188,7 +204,9 @@ export class MemoryStore {
       try {
         const sample = await table.query().limit(1).toArray();
         if (sample.length > 0 && !("scope" in sample[0])) {
-          console.warn("Adding scope column for backward compatibility with existing data");
+          console.warn(
+            "Adding scope column for backward compatibility with existing data",
+          );
         }
       } catch (err) {
         console.warn("Could not check table schema:", err);
@@ -198,7 +216,9 @@ export class MemoryStore {
       const schemaEntry: MemoryEntry = {
         id: "__schema__",
         text: "",
-        vector: Array.from({ length: this.config.vectorDim }).fill(0) as number[],
+        vector: Array.from({ length: this.config.vectorDim }).fill(
+          0,
+        ) as number[],
         category: "other",
         scope: "global",
         importance: 0,
@@ -228,7 +248,7 @@ export class MemoryStore {
       const existingDim = sample[0].vector.length;
       if (existingDim !== this.config.vectorDim) {
         throw new Error(
-          `Vector dimension mismatch: table=${existingDim}, config=${this.config.vectorDim}. Create a new table/dbPath or set matching embedding.dimensions.`
+          `Vector dimension mismatch: table=${existingDim}, config=${this.config.vectorDim}. Create a new table/dbPath or set matching embedding.dimensions.`,
         );
       }
     }
@@ -238,7 +258,10 @@ export class MemoryStore {
       await this.createFtsIndex(table);
       this.ftsIndexCreated = true;
     } catch (err) {
-      console.warn("Failed to create FTS index, falling back to vector-only search:", err);
+      console.warn(
+        "Failed to create FTS index, falling back to vector-only search:",
+        err,
+      );
       this.ftsIndexCreated = false;
     }
 
@@ -250,8 +273,8 @@ export class MemoryStore {
     try {
       // Check if FTS index already exists
       const indices = await table.listIndices();
-      const hasFtsIndex = indices?.some((idx: any) =>
-        idx.indexType === "FTS" || idx.columns?.includes("text")
+      const hasFtsIndex = indices?.some(
+        (idx: any) => idx.indexType === "FTS" || idx.columns?.includes("text"),
       );
 
       if (!hasFtsIndex) {
@@ -262,11 +285,15 @@ export class MemoryStore {
         });
       }
     } catch (err) {
-      throw new Error(`FTS index creation failed: ${err instanceof Error ? err.message : String(err)}`);
+      throw new Error(
+        `FTS index creation failed: ${err instanceof Error ? err.message : String(err)}`,
+      );
     }
   }
 
-  async store(entry: Omit<MemoryEntry, "id" | "timestamp">): Promise<MemoryEntry> {
+  async store(
+    entry: Omit<MemoryEntry, "id" | "timestamp">,
+  ): Promise<MemoryEntry> {
     await this.ensureInitialized();
 
     const fullEntry: MemoryEntry = {
@@ -282,7 +309,7 @@ export class MemoryStore {
       const code = err.code || "";
       const message = err.message || String(err);
       throw new Error(
-        `Failed to store memory in "${this.config.dbPath}": ${code} ${message}`
+        `Failed to store memory in "${this.config.dbPath}": ${code} ${message}`,
       );
     }
     return fullEntry;
@@ -303,7 +330,7 @@ export class MemoryStore {
     const vector = entry.vector || [];
     if (!Array.isArray(vector) || vector.length !== this.config.vectorDim) {
       throw new Error(
-        `Vector dimension mismatch: expected ${this.config.vectorDim}, got ${Array.isArray(vector) ? vector.length : 'non-array'}`
+        `Vector dimension mismatch: expected ${this.config.vectorDim}, got ${Array.isArray(vector) ? vector.length : "non-array"}`,
       );
     }
 
@@ -311,7 +338,9 @@ export class MemoryStore {
       ...entry,
       scope: entry.scope || "global",
       importance: Number.isFinite(entry.importance) ? entry.importance : 0.7,
-      timestamp: Number.isFinite(entry.timestamp) ? entry.timestamp : Date.now(),
+      timestamp: Number.isFinite(entry.timestamp)
+        ? entry.timestamp
+        : Date.now(),
       metadata: entry.metadata || "{}",
     };
 
@@ -322,11 +351,46 @@ export class MemoryStore {
   async hasId(id: string): Promise<boolean> {
     await this.ensureInitialized();
     const safeId = escapeSqlLiteral(id);
-    const res = await this.table!.query().select(["id"]).where(`id = '${safeId}'`).limit(1).toArray();
+    const res = await this.table!.query()
+      .select(["id"])
+      .where(`id = '${safeId}'`)
+      .limit(1)
+      .toArray();
     return res.length > 0;
   }
 
-  async vectorSearch(vector: number[], limit = 5, minScore = 0.3, scopeFilter?: string[]): Promise<MemorySearchResult[]> {
+  /**
+   * Read a single memory entry by exact ID without any mutation.
+   * Unlike update(id, {}), this performs a pure read (no delete+add cycle).
+   */
+  async getById(id: string): Promise<MemoryEntry | null> {
+    await this.ensureInitialized();
+    const safeId = escapeSqlLiteral(id);
+    const rows = await this.table!.query()
+      .where(`id = '${safeId}'`)
+      .limit(1)
+      .toArray();
+    if (rows.length === 0) return null;
+
+    const row = rows[0];
+    return {
+      id: row.id as string,
+      text: row.text as string,
+      vector: Array.from(row.vector as Iterable<number>),
+      category: row.category as MemoryEntry["category"],
+      scope: (row.scope as string | undefined) ?? "global",
+      importance: Number(row.importance),
+      timestamp: Number(row.timestamp),
+      metadata: (row.metadata as string) || "{}",
+    };
+  }
+
+  async vectorSearch(
+    vector: number[],
+    limit = 5,
+    minScore = 0.3,
+    scopeFilter?: string[],
+  ): Promise<MemorySearchResult[]> {
     await this.ensureInitialized();
 
     const safeLimit = clampInt(limit, 1, 20);
@@ -337,7 +401,7 @@ export class MemoryStore {
     // Apply scope filter if provided
     if (scopeFilter && scopeFilter.length > 0) {
       const scopeConditions = scopeFilter
-        .map(scope => `scope = '${escapeSqlLiteral(scope)}'`)
+        .map((scope) => `scope = '${escapeSqlLiteral(scope)}'`)
         .join(" OR ");
       query = query.where(`(${scopeConditions}) OR scope IS NULL`); // NULL for backward compatibility
     }
@@ -354,7 +418,11 @@ export class MemoryStore {
       const rowScope = (row.scope as string | undefined) ?? "global";
 
       // Double-check scope filter in application layer
-      if (scopeFilter && scopeFilter.length > 0 && !scopeFilter.includes(rowScope)) {
+      if (
+        scopeFilter &&
+        scopeFilter.length > 0 &&
+        !scopeFilter.includes(rowScope)
+      ) {
         continue;
       }
 
@@ -378,7 +446,11 @@ export class MemoryStore {
     return mapped;
   }
 
-  async bm25Search(query: string, limit = 5, scopeFilter?: string[]): Promise<MemorySearchResult[]> {
+  async bm25Search(
+    query: string,
+    limit = 5,
+    scopeFilter?: string[],
+  ): Promise<MemorySearchResult[]> {
     await this.ensureInitialized();
 
     if (!this.ftsIndexCreated) {
@@ -394,9 +466,11 @@ export class MemoryStore {
       // Apply scope filter if provided
       if (scopeFilter && scopeFilter.length > 0) {
         const scopeConditions = scopeFilter
-          .map(scope => `scope = '${escapeSqlLiteral(scope)}'`)
+          .map((scope) => `scope = '${escapeSqlLiteral(scope)}'`)
           .join(" OR ");
-        searchQuery = searchQuery.where(`(${scopeConditions}) OR scope IS NULL`);
+        searchQuery = searchQuery.where(
+          `(${scopeConditions}) OR scope IS NULL`,
+        );
       }
 
       const results = await searchQuery.toArray();
@@ -406,14 +480,19 @@ export class MemoryStore {
         const rowScope = (row.scope as string | undefined) ?? "global";
 
         // Double-check scope filter in application layer
-        if (scopeFilter && scopeFilter.length > 0 && !scopeFilter.includes(rowScope)) {
+        if (
+          scopeFilter &&
+          scopeFilter.length > 0 &&
+          !scopeFilter.includes(rowScope)
+        ) {
           continue;
         }
 
         // LanceDB FTS _score is raw BM25 (unbounded). Normalize with sigmoid.
         // LanceDB may return BigInt for numeric columns; coerce safely.
-        const rawScore = (row._score != null) ? Number(row._score) : 0;
-        const normalizedScore = rawScore > 0 ? 1 / (1 + Math.exp(-rawScore / 5)) : 0.5;
+        const rawScore = row._score != null ? Number(row._score) : 0;
+        const normalizedScore =
+          rawScore > 0 ? 1 / (1 + Math.exp(-rawScore / 5)) : 0.5;
 
         mapped.push({
           entry: {
@@ -441,7 +520,8 @@ export class MemoryStore {
     await this.ensureInitialized();
 
     // Support both full UUID and short prefix (8+ hex chars)
-    const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+    const uuidRegex =
+      /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
     const prefixRegex = /^[0-9a-f]{8,}$/i;
     const isFullId = uuidRegex.test(id);
     const isPrefix = !isFullId && prefixRegex.test(id);
@@ -452,13 +532,21 @@ export class MemoryStore {
 
     let candidates: any[];
     if (isFullId) {
-      candidates = await this.table!.query().where(`id = '${id}'`).limit(1).toArray();
+      candidates = await this.table!.query()
+        .where(`id = '${id}'`)
+        .limit(1)
+        .toArray();
     } else {
       // Prefix match: fetch candidates and filter in app layer
-      const all = await this.table!.query().select(["id", "scope"]).limit(1000).toArray();
+      const all = await this.table!.query()
+        .select(["id", "scope"])
+        .limit(1000)
+        .toArray();
       candidates = all.filter((r: any) => (r.id as string).startsWith(id));
       if (candidates.length > 1) {
-        throw new Error(`Ambiguous prefix "${id}" matches ${candidates.length} memories. Use a longer prefix or full ID.`);
+        throw new Error(
+          `Ambiguous prefix "${id}" matches ${candidates.length} memories. Use a longer prefix or full ID.`,
+        );
       }
     }
     if (candidates.length === 0) {
@@ -469,7 +557,11 @@ export class MemoryStore {
     const rowScope = (candidates[0].scope as string | undefined) ?? "global";
 
     // Check scope permissions
-    if (scopeFilter && scopeFilter.length > 0 && !scopeFilter.includes(rowScope)) {
+    if (
+      scopeFilter &&
+      scopeFilter.length > 0 &&
+      !scopeFilter.includes(rowScope)
+    ) {
       throw new Error(`Memory ${resolvedId} is outside accessible scopes`);
     }
 
@@ -477,7 +569,12 @@ export class MemoryStore {
     return true;
   }
 
-  async list(scopeFilter?: string[], category?: string, limit = 20, offset = 0): Promise<MemoryEntry[]> {
+  async list(
+    scopeFilter?: string[],
+    category?: string,
+    limit = 20,
+    offset = 0,
+  ): Promise<MemoryEntry[]> {
     await this.ensureInitialized();
 
     let query = this.table!.query();
@@ -487,7 +584,7 @@ export class MemoryStore {
 
     if (scopeFilter && scopeFilter.length > 0) {
       const scopeConditions = scopeFilter
-        .map(scope => `scope = '${escapeSqlLiteral(scope)}'`)
+        .map((scope) => `scope = '${escapeSqlLiteral(scope)}'`)
         .join(" OR ");
       conditions.push(`((${scopeConditions}) OR scope IS NULL)`);
     }
@@ -502,20 +599,30 @@ export class MemoryStore {
 
     // Fetch all matching rows (no pre-limit) so app-layer sort is correct across full dataset
     const results = await query
-      .select(["id", "text", "category", "scope", "importance", "timestamp", "metadata"])
+      .select([
+        "id",
+        "text",
+        "category",
+        "scope",
+        "importance",
+        "timestamp",
+        "metadata",
+      ])
       .toArray();
 
     return results
-      .map((row): MemoryEntry => ({
-        id: row.id as string,
-        text: row.text as string,
-        vector: [], // Don't include vectors in list results for performance
-        category: row.category as MemoryEntry["category"],
-        scope: (row.scope as string | undefined) ?? "global",
-        importance: Number(row.importance),
-        timestamp: Number(row.timestamp),
-        metadata: (row.metadata as string) || "{}",
-      }))
+      .map(
+        (row): MemoryEntry => ({
+          id: row.id as string,
+          text: row.text as string,
+          vector: [], // Don't include vectors in list results for performance
+          category: row.category as MemoryEntry["category"],
+          scope: (row.scope as string | undefined) ?? "global",
+          importance: Number(row.importance),
+          timestamp: Number(row.timestamp),
+          metadata: (row.metadata as string) || "{}",
+        }),
+      )
       .sort((a, b) => (b.timestamp || 0) - (a.timestamp || 0))
       .slice(offset, offset + limit);
   }
@@ -523,7 +630,7 @@ export class MemoryStore {
   async stats(scopeFilter?: string[]): Promise<{
     totalCount: number;
     scopeCounts: Record<string, number>;
-    categoryCounts: Record<string, number>
+    categoryCounts: Record<string, number>;
   }> {
     await this.ensureInitialized();
 
@@ -531,7 +638,7 @@ export class MemoryStore {
 
     if (scopeFilter && scopeFilter.length > 0) {
       const scopeConditions = scopeFilter
-        .map(scope => `scope = '${escapeSqlLiteral(scope)}'`)
+        .map((scope) => `scope = '${escapeSqlLiteral(scope)}'`)
         .join(" OR ");
       query = query.where(`((${scopeConditions}) OR scope IS NULL)`);
     }
@@ -558,13 +665,20 @@ export class MemoryStore {
 
   async update(
     id: string,
-    updates: { text?: string; vector?: number[]; importance?: number; category?: MemoryEntry["category"]; metadata?: string },
-    scopeFilter?: string[]
+    updates: {
+      text?: string;
+      vector?: number[];
+      importance?: number;
+      category?: MemoryEntry["category"];
+      metadata?: string;
+    },
+    scopeFilter?: string[],
   ): Promise<MemoryEntry | null> {
     await this.ensureInitialized();
 
     // Support both full UUID and short prefix (8+ hex chars), same as delete()
-    const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+    const uuidRegex =
+      /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
     const prefixRegex = /^[0-9a-f]{8,}$/i;
     const isFullId = uuidRegex.test(id);
     const isPrefix = !isFullId && prefixRegex.test(id);
@@ -576,13 +690,30 @@ export class MemoryStore {
     let rows: any[];
     if (isFullId) {
       const safeId = escapeSqlLiteral(id);
-      rows = await this.table!.query().where(`id = '${safeId}'`).limit(1).toArray();
+      rows = await this.table!.query()
+        .where(`id = '${safeId}'`)
+        .limit(1)
+        .toArray();
     } else {
       // Prefix match
-      const all = await this.table!.query().select(["id", "text", "vector", "category", "scope", "importance", "timestamp", "metadata"]).limit(1000).toArray();
+      const all = await this.table!.query()
+        .select([
+          "id",
+          "text",
+          "vector",
+          "category",
+          "scope",
+          "importance",
+          "timestamp",
+          "metadata",
+        ])
+        .limit(1000)
+        .toArray();
       rows = all.filter((r: any) => (r.id as string).startsWith(id));
       if (rows.length > 1) {
-        throw new Error(`Ambiguous prefix "${id}" matches ${rows.length} memories. Use a longer prefix or full ID.`);
+        throw new Error(
+          `Ambiguous prefix "${id}" matches ${rows.length} memories. Use a longer prefix or full ID.`,
+        );
       }
     }
 
@@ -592,7 +723,11 @@ export class MemoryStore {
     const rowScope = (row.scope as string | undefined) ?? "global";
 
     // Check scope permissions
-    if (scopeFilter && scopeFilter.length > 0 && !scopeFilter.includes(rowScope)) {
+    if (
+      scopeFilter &&
+      scopeFilter.length > 0 &&
+      !scopeFilter.includes(rowScope)
+    ) {
       throw new Error(`Memory ${id} is outside accessible scopes`);
     }
 
@@ -600,7 +735,7 @@ export class MemoryStore {
     const updated: MemoryEntry = {
       id: row.id as string,
       text: updates.text ?? (row.text as string),
-      vector: updates.vector ?? (Array.from(row.vector as Iterable<number>)),
+      vector: updates.vector ?? Array.from(row.vector as Iterable<number>),
       category: updates.category ?? (row.category as MemoryEntry["category"]),
       scope: rowScope,
       importance: updates.importance ?? Number(row.importance),
@@ -616,14 +751,17 @@ export class MemoryStore {
     return updated;
   }
 
-  async bulkDelete(scopeFilter: string[], beforeTimestamp?: number): Promise<number> {
+  async bulkDelete(
+    scopeFilter: string[],
+    beforeTimestamp?: number,
+  ): Promise<number> {
     await this.ensureInitialized();
 
     const conditions: string[] = [];
 
     if (scopeFilter.length > 0) {
       const scopeConditions = scopeFilter
-        .map(scope => `scope = '${escapeSqlLiteral(scope)}'`)
+        .map((scope) => `scope = '${escapeSqlLiteral(scope)}'`)
         .join(" OR ");
       conditions.push(`(${scopeConditions})`);
     }
@@ -633,7 +771,9 @@ export class MemoryStore {
     }
 
     if (conditions.length === 0) {
-      throw new Error("Bulk delete requires at least scope or timestamp filter for safety");
+      throw new Error(
+        "Bulk delete requires at least scope or timestamp filter for safety",
+      );
     }
 
     const whereClause = conditions.join(" AND ");
@@ -653,4 +793,4 @@ export class MemoryStore {
   get hasFtsSupport(): boolean {
     return this.ftsIndexCreated;
   }
-}
+}