@mnemoai/core 1.1.0 → 1.1.2

package/dist/src/memory-upgrader.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Memory Upgrader — Convert legacy memories to new smart memory format
+ *
+ * Legacy memories lack L0/L1/L2 metadata, memory_category (6-category),
+ * tier, access_count, and confidence fields. This module enriches them
+ * to enable unified memory lifecycle management (decay, tier promotion,
+ * smart dedup).
+ *
+ * Pipeline per memory:
+ *   1. Detect legacy format (missing `memory_category` in metadata)
+ *   2. Reverse-map 5-category → 6-category
+ *   3. Generate L0/L1/L2 via LLM (or fallback to simple rules)
+ *   4. Write enriched metadata back via store.update()
+ */
+import type { MemoryStore, MemoryEntry } from "./store.js";
+import type { LlmClient } from "./llm-client.js";
+export interface UpgradeOptions {
+    /** Only report counts without modifying data (default: false) */
+    dryRun?: boolean;
+    /** Number of memories to process per batch (default: 10) */
+    batchSize?: number;
+    /** Skip LLM calls; use simple text truncation for L0/L1 (default: false) */
+    noLlm?: boolean;
+    /** Maximum number of memories to upgrade (default: unlimited) */
+    limit?: number;
+    /** Scope filter — only upgrade memories in these scopes */
+    scopeFilter?: string[];
+    /** Logger function */
+    log?: (msg: string) => void;
+}
+export interface UpgradeResult {
+    /** Total legacy memories found */
+    totalLegacy: number;
+    /** Successfully upgraded count */
+    upgraded: number;
+    /** Skipped (already new format) */
+    skipped: number;
+    /** Errors encountered */
+    errors: string[];
+}
+export declare class MemoryUpgrader {
+    private store;
+    private llm;
+    private options;
+    private log;
+    constructor(store: MemoryStore, llm: LlmClient | null, options?: UpgradeOptions);
+    /**
+     * Check if a memory entry is in legacy format (needs upgrade).
+     * Legacy = no metadata, or metadata lacks `memory_category`.
+     */
+    isLegacyMemory(entry: MemoryEntry): boolean;
+    /**
+     * Scan and count legacy memories without modifying them.
+     */
+    countLegacy(scopeFilter?: string[]): Promise<{
+        total: number;
+        legacy: number;
+        byCategory: Record<string, number>;
+    }>;
+    /**
+     * Main upgrade entry point.
+     * Scans all memories, filters legacy ones, and enriches them.
+     */
+    upgrade(options?: UpgradeOptions): Promise<UpgradeResult>;
+    /**
+     * Upgrade a single legacy memory entry.
+     */
+    private upgradeEntry;
+}
+export declare function createMemoryUpgrader(store: MemoryStore, llm: LlmClient | null, options?: UpgradeOptions): MemoryUpgrader;
+//# sourceMappingURL=memory-upgrader.d.ts.map

package/dist/src/memory-upgrader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-upgrader.d.ts","sourceRoot":"","sources":["../../src/memory-upgrader.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC3D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAUjD,MAAM,WAAW,cAAc;IAC7B,iEAAiE;IACjE,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,4DAA4D;IAC5D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4EAA4E;IAC5E,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,iEAAiE;IACjE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2DAA2D;IAC3D,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,sBAAsB;IACtB,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAC7B;AAED,MAAM,WAAW,aAAa;IAC5B,kCAAkC;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,kCAAkC;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,mCAAmC;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,yBAAyB;IACzB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AA8GD,qBAAa,cAAc;IAIvB,OAAO,CAAC,KAAK;IACb,OAAO,CAAC,GAAG;IACX,OAAO,CAAC,OAAO;IALjB,OAAO,CAAC,GAAG,CAAwB;gBAGzB,KAAK,EAAE,WAAW,EAClB,GAAG,EAAE,SAAS,GAAG,IAAI,EACrB,OAAO,GAAE,cAAmB;IAKtC;;;OAGG;IACH,cAAc,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO;IAW3C;;OAEG;IACG,WAAW,CAAC,WAAW,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;QACjD,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;QACf,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KACpC,CAAC;IAeF;;;OAGG;IACG,OAAO,CAAC,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,aAAa,CAAC;IAkFnE;;OAEG;YACW,YAAY;CA8E3B;AAMD,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,WAAW,EAClB,GAAG,EAAE,SAAS,GAAG,IAAI,EACrB,OAAO,GAAE,cAAmB,GAC3B,cAAc,CAEhB"}

package/dist/src/memory-upgrader.js

@@ -0,0 +1,238 @@
+import { buildSmartMetadata, stringifySmartMetadata } from "./smart-metadata.js";
+import { log } from "./logger.js";
+function reverseMapCategory(oldCategory, text) {
+  switch (oldCategory) {
+    case "preference":
+      return "preferences";
+    case "entity":
+      return "entities";
+    case "decision":
+      return "events";
+    case "other":
+      return "patterns";
+    case "fact":
+      if (/\b(my |i am |i'm |name is |叫我|我的|我是)\b/i.test(text) && text.length < 200) {
+        return "profile";
+      }
+      return "cases";
+    default:
+      return "patterns";
+  }
+}
+function buildUpgradePrompt(text, category) {
+  return `You are a memory librarian. Given a raw memory text and its category, produce a structured 3-layer summary.
+
+**Category**: ${category}
+
+**Raw memory text**:
+"""
+${text.slice(0, 2e3)}
+"""
+
+Return ONLY valid JSON (no markdown fences):
+{
+  "l0_abstract": "One sentence (\u226430 words) summarizing the core fact/preference/event",
+  "l1_overview": "A structured markdown summary (2-5 bullet points)",
+  "l2_content": "The full original text, cleaned up if needed",
+  "resolved_category": "${category}"
+}
+
+Rules:
+- l0_abstract must be a single concise sentence, suitable as a search index key
+- l1_overview should use markdown bullet points to structure the information
+- l2_content should preserve the original meaning; may clean up formatting
+- resolved_category: if the text is clearly about personal identity/profile info (name, age, role, etc.), set to "profile"; if it's a reusable problem-solution pair, set to "cases"; otherwise keep "${category}"
+- Respond in the SAME language as the raw memory text`;
+}
+function simpleEnrich(text, category) {
+  const firstSentence = text.match(/^[^.!?。！？\n]+[.!?。！？]?/)?.[0] || text;
+  const l0 = firstSentence.slice(0, 100).trim();
+  const l1 = `- ${l0}`;
+  return {
+    l0_abstract: l0,
+    l1_overview: l1,
+    l2_content: text
+  };
+}
+class MemoryUpgrader {
+  constructor(store, llm, options = {}) {
+    this.store = store;
+    this.llm = llm;
+    this.options = options;
+    this.log = options.log ?? ((msg) => log.info(msg));
+  }
+  log;
+  /**
+   * Check if a memory entry is in legacy format (needs upgrade).
+   * Legacy = no metadata, or metadata lacks `memory_category`.
+   */
+  isLegacyMemory(entry) {
+    if (!entry.metadata) return true;
+    try {
+      const meta = JSON.parse(entry.metadata);
+      return !meta.memory_category;
+    } catch {
+      return true;
+    }
+  }
+  /**
+   * Scan and count legacy memories without modifying them.
+   */
+  async countLegacy(scopeFilter) {
+    const allMemories = await this.store.list(scopeFilter, void 0, 1e4, 0);
+    let legacy = 0;
+    const byCategory = {};
+    for (const entry of allMemories) {
+      if (this.isLegacyMemory(entry)) {
+        legacy++;
+        byCategory[entry.category] = (byCategory[entry.category] || 0) + 1;
+      }
+    }
+    return { total: allMemories.length, legacy, byCategory };
+  }
+  /**
+   * Main upgrade entry point.
+   * Scans all memories, filters legacy ones, and enriches them.
+   */
+  async upgrade(options = {}) {
+    const batchSize = options.batchSize ?? this.options.batchSize ?? 10;
+    const noLlm = options.noLlm ?? this.options.noLlm ?? false;
+    const dryRun = options.dryRun ?? this.options.dryRun ?? false;
+    const limit = options.limit ?? this.options.limit;
+    const result = {
+      totalLegacy: 0,
+      upgraded: 0,
+      skipped: 0,
+      errors: []
+    };
+    this.log("memory-upgrader: scanning memories...");
+    const allMemories = await this.store.list(
+      options.scopeFilter ?? this.options.scopeFilter,
+      void 0,
+      1e4,
+      0
+    );
+    const legacyMemories = allMemories.filter((m) => this.isLegacyMemory(m));
+    result.totalLegacy = legacyMemories.length;
+    result.skipped = allMemories.length - legacyMemories.length;
+    if (legacyMemories.length === 0) {
+      this.log("memory-upgrader: no legacy memories found \u2014 all memories are already in new format");
+      return result;
+    }
+    this.log(
+      `memory-upgrader: found ${legacyMemories.length} legacy memories out of ${allMemories.length} total`
+    );
+    if (dryRun) {
+      const byCategory = {};
+      for (const m of legacyMemories) {
+        byCategory[m.category] = (byCategory[m.category] || 0) + 1;
+      }
+      this.log(
+        `memory-upgrader: [DRY-RUN] would upgrade ${legacyMemories.length} memories`
+      );
+      this.log(`memory-upgrader: [DRY-RUN] breakdown: ${JSON.stringify(byCategory)}`);
+      return result;
+    }
+    const toProcess = limit ? legacyMemories.slice(0, limit) : legacyMemories;
+    for (let i = 0; i < toProcess.length; i += batchSize) {
+      const batch = toProcess.slice(i, i + batchSize);
+      this.log(
+        `memory-upgrader: processing batch ${Math.floor(i / batchSize) + 1}/${Math.ceil(toProcess.length / batchSize)} (${batch.length} memories)`
+      );
+      for (const entry of batch) {
+        try {
+          await this.upgradeEntry(entry, noLlm);
+          result.upgraded++;
+        } catch (err) {
+          const errMsg = `Failed to upgrade ${entry.id}: ${String(err)}`;
+          result.errors.push(errMsg);
+          this.log(`memory-upgrader: ERROR \u2014 ${errMsg}`);
+        }
+      }
+      this.log(
+        `memory-upgrader: progress \u2014 ${result.upgraded} upgraded, ${result.errors.length} errors`
+      );
+    }
+    this.log(
+      `memory-upgrader: upgrade complete \u2014 ${result.upgraded} upgraded, ${result.skipped} already new, ${result.errors.length} errors`
+    );
+    return result;
+  }
+  /**
+   * Upgrade a single legacy memory entry.
+   */
+  async upgradeEntry(entry, noLlm) {
+    let newCategory = reverseMapCategory(entry.category, entry.text);
+    let enriched;
+    if (!noLlm && this.llm) {
+      try {
+        const prompt = buildUpgradePrompt(entry.text, newCategory);
+        const llmResult = await this.llm.completeJson(prompt);
+        if (!llmResult) {
+          throw new Error("LLM returned null");
+        }
+        enriched = {
+          l0_abstract: llmResult.l0_abstract || simpleEnrich(entry.text, newCategory).l0_abstract,
+          l1_overview: llmResult.l1_overview || simpleEnrich(entry.text, newCategory).l1_overview,
+          l2_content: llmResult.l2_content || entry.text
+        };
+        if (llmResult.resolved_category) {
+          const validCategories = /* @__PURE__ */ new Set([
+            "profile",
+            "preferences",
+            "entities",
+            "events",
+            "cases",
+            "patterns"
+          ]);
+          if (validCategories.has(llmResult.resolved_category)) {
+            newCategory = llmResult.resolved_category;
+          }
+        }
+      } catch (err) {
+        this.log(
+          `memory-upgrader: LLM enrichment failed for ${entry.id}, falling back to simple \u2014 ${String(err)}`
+        );
+        enriched = simpleEnrich(entry.text, newCategory);
+      }
+    } else {
+      enriched = simpleEnrich(entry.text, newCategory);
+    }
+    const existingMeta = entry.metadata ? (() => {
+      try {
+        return JSON.parse(entry.metadata);
+      } catch {
+        return {};
+      }
+    })() : {};
+    const newMetadata = {
+      ...buildSmartMetadata(
+        { ...entry, metadata: JSON.stringify(existingMeta) },
+        {
+          l0_abstract: enriched.l0_abstract,
+          l1_overview: enriched.l1_overview,
+          l2_content: enriched.l2_content,
+          memory_category: newCategory,
+          tier: "working",
+          access_count: 0,
+          confidence: 0.7
+        }
+      ),
+      upgraded_from: entry.category,
+      upgraded_at: Date.now()
+    };
+    await this.store.update(entry.id, {
+      // Update text to L0 abstract for better search indexing
+      text: enriched.l0_abstract,
+      metadata: stringifySmartMetadata(newMetadata)
+    });
+  }
+}
+function createMemoryUpgrader(store, llm, options = {}) {
+  return new MemoryUpgrader(store, llm, options);
+}
+export {
+  MemoryUpgrader,
+  createMemoryUpgrader
+};
+//# sourceMappingURL=memory-upgrader.js.map

package/dist/src/memory-upgrader.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/memory-upgrader.ts"],
+  "sourcesContent": ["// SPDX-License-Identifier: LicenseRef-Mnemo-Pro\n/**\n * Memory Upgrader \u2014 Convert legacy memories to new smart memory format\n *\n * Legacy memories lack L0/L1/L2 metadata, memory_category (6-category),\n * tier, access_count, and confidence fields. This module enriches them\n * to enable unified memory lifecycle management (decay, tier promotion,\n * smart dedup).\n *\n * Pipeline per memory:\n *   1. Detect legacy format (missing `memory_category` in metadata)\n *   2. Reverse-map 5-category \u2192 6-category\n *   3. Generate L0/L1/L2 via LLM (or fallback to simple rules)\n *   4. Write enriched metadata back via store.update()\n */\n\nimport type { MemoryStore, MemoryEntry } from \"./store.js\";\nimport type { LlmClient } from \"./llm-client.js\";\nimport type { MemoryCategory } from \"./memory-categories.js\";\nimport type { MemoryTier } from \"./memory-categories.js\";\nimport { buildSmartMetadata, stringifySmartMetadata } from \"./smart-metadata.js\";\nimport { log } from \"./logger.js\";\n\n// ============================================================================\n// Types\n// ============================================================================\n\nexport interface UpgradeOptions {\n  /** Only report counts without modifying data (default: false) */\n  dryRun?: boolean;\n  /** Number of memories to process per batch (default: 10) */\n  batchSize?: number;\n  /** Skip LLM calls; use simple text truncation for L0/L1 (default: false) */\n  noLlm?: boolean;\n  /** Maximum number of memories to upgrade (default: unlimited) */\n  limit?: number;\n  /** Scope filter \u2014 only upgrade memories in these scopes */\n  scopeFilter?: string[];\n  /** Logger function */\n  log?: (msg: string) => void;\n}\n\nexport interface UpgradeResult {\n  /** Total legacy memories found */\n  totalLegacy: number;\n  /** Successfully upgraded count */\n  upgraded: number;\n  /** Skipped (already new format) */\n  skipped: number;\n  /** Errors encountered */\n  errors: string[];\n}\n\ninterface EnrichedMetadata {\n  l0_abstract: string;\n  l1_overview: string;\n  l2_content: string;\n  memory_category: MemoryCategory;\n  tier: MemoryTier;\n  access_count: number;\n  confidence: number;\n  last_accessed_at: number;\n  upgraded_from: string; // original 5-category\n  upgraded_at: number;   // timestamp of upgrade\n}\n\n// ============================================================================\n// Reverse Category Mapping\n// ============================================================================\n\n/**\n * Reverse-map old 5-category \u2192 new 6-category.\n *\n * Ambiguous case: `fact` maps to both `profile` and `cases`.\n * Without LLM, defaults to `cases` (conservative).\n * With LLM, the enrichment prompt will determine the correct category.\n */\nfunction reverseMapCategory(\n  oldCategory: MemoryEntry[\"category\"],\n  text: string,\n): MemoryCategory {\n  switch (oldCategory) {\n    case \"preference\":\n      return \"preferences\";\n    case \"entity\":\n      return \"entities\";\n    case \"decision\":\n      return \"events\";\n    case \"other\":\n      return \"patterns\";\n    case \"fact\":\n      // Heuristic: if text looks like personal identity info, map to profile\n      if (\n        /\\b(my |i am |i'm |name is |\u53EB\u6211|\u6211\u7684|\u6211\u662F)\\b/i.test(text) &&\n        text.length < 200\n      ) {\n        return \"profile\";\n      }\n      return \"cases\";\n    default:\n      return \"patterns\";\n  }\n}\n\n// ============================================================================\n// LLM Upgrade Prompt\n// ============================================================================\n\nfunction buildUpgradePrompt(text: string, category: MemoryCategory): string {\n  return `You are a memory librarian. Given a raw memory text and its category, produce a structured 3-layer summary.\n\n**Category**: ${category}\n\n**Raw memory text**:\n\"\"\"\n${text.slice(0, 2000)}\n\"\"\"\n\nReturn ONLY valid JSON (no markdown fences):\n{\n  \"l0_abstract\": \"One sentence (\u226430 words) summarizing the core fact/preference/event\",\n  \"l1_overview\": \"A structured markdown summary (2-5 bullet points)\",\n  \"l2_content\": \"The full original text, cleaned up if needed\",\n  \"resolved_category\": \"${category}\"\n}\n\nRules:\n- l0_abstract must be a single concise sentence, suitable as a search index key\n- l1_overview should use markdown bullet points to structure the information\n- l2_content should preserve the original meaning; may clean up formatting\n- resolved_category: if the text is clearly about personal identity/profile info (name, age, role, etc.), set to \"profile\"; if it's a reusable problem-solution pair, set to \"cases\"; otherwise keep \"${category}\"\n- Respond in the SAME language as the raw memory text`;\n}\n\n// ============================================================================\n// Simple (No-LLM) Enrichment\n// ============================================================================\n\nfunction simpleEnrich(\n  text: string,\n  category: MemoryCategory,\n): Pick<EnrichedMetadata, \"l0_abstract\" | \"l1_overview\" | \"l2_content\"> {\n  // L0: first sentence or first 80 chars\n  const firstSentence = text.match(/^[^.!?\u3002\uFF01\uFF1F\\n]+[.!?\u3002\uFF01\uFF1F]?/)?.[0] || text;\n  const l0 = firstSentence.slice(0, 100).trim();\n\n  // L1: structured as a single bullet\n  const l1 = `- ${l0}`;\n\n  // L2: full text\n  return {\n    l0_abstract: l0,\n    l1_overview: l1,\n    l2_content: text,\n  };\n}\n\n// ============================================================================\n// Memory Upgrader\n// ============================================================================\n\nexport class MemoryUpgrader {\n  private log: (msg: string) => void;\n\n  constructor(\n    private store: MemoryStore,\n    private llm: LlmClient | null,\n    private options: UpgradeOptions = {},\n  ) {\n    this.log = options.log ?? ((msg: string) => log.info(msg));\n  }\n\n  /**\n   * Check if a memory entry is in legacy format (needs upgrade).\n   * Legacy = no metadata, or metadata lacks `memory_category`.\n   */\n  isLegacyMemory(entry: MemoryEntry): boolean {\n    if (!entry.metadata) return true;\n    try {\n      const meta = JSON.parse(entry.metadata);\n      // If it has memory_category, it was created by SmartExtractor \u2192 new format\n      return !meta.memory_category;\n    } catch {\n      return true;\n    }\n  }\n\n  /**\n   * Scan and count legacy memories without modifying them.\n   */\n  async countLegacy(scopeFilter?: string[]): Promise<{\n    total: number;\n    legacy: number;\n    byCategory: Record<string, number>;\n  }> {\n    const allMemories = await this.store.list(scopeFilter, undefined, 10000, 0);\n    let legacy = 0;\n    const byCategory: Record<string, number> = {};\n\n    for (const entry of allMemories) {\n      if (this.isLegacyMemory(entry)) {\n        legacy++;\n        byCategory[entry.category] = (byCategory[entry.category] || 0) + 1;\n      }\n    }\n\n    return { total: allMemories.length, legacy, byCategory };\n  }\n\n  /**\n   * Main upgrade entry point.\n   * Scans all memories, filters legacy ones, and enriches them.\n   */\n  async upgrade(options: UpgradeOptions = {}): Promise<UpgradeResult> {\n    const batchSize = options.batchSize ?? this.options.batchSize ?? 10;\n    const noLlm = options.noLlm ?? this.options.noLlm ?? false;\n    const dryRun = options.dryRun ?? this.options.dryRun ?? false;\n    const limit = options.limit ?? this.options.limit;\n\n    const result: UpgradeResult = {\n      totalLegacy: 0,\n      upgraded: 0,\n      skipped: 0,\n      errors: [],\n    };\n\n    // Load all memories\n    this.log(\"memory-upgrader: scanning memories...\");\n    const allMemories = await this.store.list(\n      options.scopeFilter ?? this.options.scopeFilter,\n      undefined,\n      10000,\n      0,\n    );\n\n    // Filter legacy memories\n    const legacyMemories = allMemories.filter((m) => this.isLegacyMemory(m));\n    result.totalLegacy = legacyMemories.length;\n    result.skipped = allMemories.length - legacyMemories.length;\n\n    if (legacyMemories.length === 0) {\n      this.log(\"memory-upgrader: no legacy memories found \u2014 all memories are already in new format\");\n      return result;\n    }\n\n    this.log(\n      `memory-upgrader: found ${legacyMemories.length} legacy memories out of ${allMemories.length} total`,\n    );\n\n    if (dryRun) {\n      const byCategory: Record<string, number> = {};\n      for (const m of legacyMemories) {\n        byCategory[m.category] = (byCategory[m.category] || 0) + 1;\n      }\n      this.log(\n        `memory-upgrader: [DRY-RUN] would upgrade ${legacyMemories.length} memories`,\n      );\n      this.log(`memory-upgrader: [DRY-RUN] breakdown: ${JSON.stringify(byCategory)}`);\n      return result;\n    }\n\n    // Process in batches\n    const toProcess = limit\n      ? legacyMemories.slice(0, limit)\n      : legacyMemories;\n\n    for (let i = 0; i < toProcess.length; i += batchSize) {\n      const batch = toProcess.slice(i, i + batchSize);\n      this.log(\n        `memory-upgrader: processing batch ${Math.floor(i / batchSize) + 1}/${Math.ceil(toProcess.length / batchSize)} (${batch.length} memories)`,\n      );\n\n      for (const entry of batch) {\n        try {\n          await this.upgradeEntry(entry, noLlm);\n          result.upgraded++;\n        } catch (err) {\n          const errMsg = `Failed to upgrade ${entry.id}: ${String(err)}`;\n          result.errors.push(errMsg);\n          this.log(`memory-upgrader: ERROR \u2014 ${errMsg}`);\n        }\n      }\n\n      // Progress report\n      this.log(\n        `memory-upgrader: progress \u2014 ${result.upgraded} upgraded, ${result.errors.length} errors`,\n      );\n    }\n\n    this.log(\n      `memory-upgrader: upgrade complete \u2014 ${result.upgraded} upgraded, ${result.skipped} already new, ${result.errors.length} errors`,\n    );\n    return result;\n  }\n\n  /**\n   * Upgrade a single legacy memory entry.\n   */\n  private async upgradeEntry(\n    entry: MemoryEntry,\n    noLlm: boolean,\n  ): Promise<void> {\n    // Step 1: Reverse-map category\n    let newCategory = reverseMapCategory(entry.category, entry.text);\n\n    // Step 2: Generate L0/L1/L2\n    let enriched: Pick<EnrichedMetadata, \"l0_abstract\" | \"l1_overview\" | \"l2_content\">;\n\n    if (!noLlm && this.llm) {\n      try {\n        const prompt = buildUpgradePrompt(entry.text, newCategory);\n        const llmResult = await this.llm.completeJson<{\n          l0_abstract: string;\n          l1_overview: string;\n          l2_content: string;\n          resolved_category?: string;\n        }>(prompt);\n\n        if (!llmResult) {\n          throw new Error(\"LLM returned null\");\n        }\n\n        enriched = {\n          l0_abstract: llmResult.l0_abstract || simpleEnrich(entry.text, newCategory).l0_abstract,\n          l1_overview: llmResult.l1_overview || simpleEnrich(entry.text, newCategory).l1_overview,\n          l2_content: llmResult.l2_content || entry.text,\n        };\n\n        // LLM may have resolved the ambiguous fact\u2192profile/cases\n        if (llmResult.resolved_category) {\n          const validCategories = new Set([\n            \"profile\", \"preferences\", \"entities\", \"events\", \"cases\", \"patterns\",\n          ]);\n          if (validCategories.has(llmResult.resolved_category)) {\n            newCategory = llmResult.resolved_category as MemoryCategory;\n          }\n        }\n      } catch (err) {\n        this.log(\n          `memory-upgrader: LLM enrichment failed for ${entry.id}, falling back to simple \u2014 ${String(err)}`,\n        );\n        enriched = simpleEnrich(entry.text, newCategory);\n      }\n    } else {\n      enriched = simpleEnrich(entry.text, newCategory);\n    }\n\n    // Step 3: Build enriched metadata\n    const existingMeta = entry.metadata ? (() => {\n      try { return JSON.parse(entry.metadata!); } catch { return {}; }\n    })() : {};\n\n    const newMetadata: EnrichedMetadata = {\n      ...buildSmartMetadata(\n        { ...entry, metadata: JSON.stringify(existingMeta) },\n        {\n          l0_abstract: enriched.l0_abstract,\n          l1_overview: enriched.l1_overview,\n          l2_content: enriched.l2_content,\n          memory_category: newCategory,\n          tier: \"working\" as MemoryTier,\n          access_count: 0,\n          confidence: 0.7,\n        },\n      ),\n      upgraded_from: entry.category,\n      upgraded_at: Date.now(),\n    };\n\n    // Step 4: Update the memory entry\n    await this.store.update(entry.id, {\n      // Update text to L0 abstract for better search indexing\n      text: enriched.l0_abstract,\n      metadata: stringifySmartMetadata(newMetadata),\n    });\n  }\n}\n\n// ============================================================================\n// Factory\n// ============================================================================\n\nexport function createMemoryUpgrader(\n  store: MemoryStore,\n  llm: LlmClient | null,\n  options: UpgradeOptions = {},\n): MemoryUpgrader {\n  return new MemoryUpgrader(store, llm, options);\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/src/migrate.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Migration Utilities
+ * Migrates data from old memory-lancedb plugin to memory-lancedb-pro
+ */
+import type { MemoryStore } from "./store.js";
+interface MigrationResult {
+    success: boolean;
+    migratedCount: number;
+    skippedCount: number;
+    errors: string[];
+    summary: string;
+}
+interface MigrationOptions {
+    sourceDbPath?: string;
+    dryRun?: boolean;
+    defaultScope?: string;
+    skipExisting?: boolean;
+}
+export declare class MemoryMigrator {
+    private targetStore;
+    constructor(targetStore: MemoryStore);
+    migrate(options?: MigrationOptions): Promise<MigrationResult>;
+    private findSourceDatabase;
+    private loadLegacyData;
+    private migrateEntries;
+    checkMigrationNeeded(sourceDbPath?: string): Promise<{
+        needed: boolean;
+        sourceFound: boolean;
+        sourceDbPath?: string;
+        entryCount?: number;
+    }>;
+    verifyMigration(sourceDbPath?: string): Promise<{
+        valid: boolean;
+        sourceCount: number;
+        targetCount: number;
+        issues: string[];
+    }>;
+}
+export declare function createMigrator(targetStore: MemoryStore): MemoryMigrator;
+export declare function migrateFromLegacy(targetStore: MemoryStore, options?: MigrationOptions): Promise<MigrationResult>;
+export declare function checkForLegacyData(): Promise<{
+    found: boolean;
+    paths: string[];
+    totalEntries: number;
+}>;
+export {};
+//# sourceMappingURL=migrate.d.ts.map

package/dist/src/migrate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate.d.ts","sourceRoot":"","sources":["../../src/migrate.ts"],"names":[],"mappings":"AACA;;;GAGG;AAKH,OAAO,KAAK,EAAE,WAAW,EAAe,MAAM,YAAY,CAAC;AAkB3D,UAAU,eAAe;IACvB,OAAO,EAAE,OAAO,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,UAAU,gBAAgB;IACxB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAmCD,qBAAa,cAAc;IACb,OAAO,CAAC,WAAW;gBAAX,WAAW,EAAE,WAAW;IAEtC,OAAO,CAAC,OAAO,GAAE,gBAAqB,GAAG,OAAO,CAAC,eAAe,CAAC;YAsDzD,kBAAkB;YA2BlB,cAAc;YAyBd,cAAc;IA4DtB,oBAAoB,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;QACzD,MAAM,EAAE,OAAO,CAAC;QAChB,WAAW,EAAE,OAAO,CAAC;QACrB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC;IA2BI,eAAe,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;QACpD,KAAK,EAAE,OAAO,CAAC;QACf,WAAW,EAAE,MAAM,CAAC;QACpB,WAAW,EAAE,MAAM,CAAC;QACpB,MAAM,EAAE,MAAM,EAAE,CAAC;KAClB,CAAC;CAwCH;AAED,wBAAgB,cAAc,CAAC,WAAW,EAAE,WAAW,GAAG,cAAc,CAEvE;AAED,wBAAsB,iBAAiB,CACrC,WAAW,EAAE,WAAW,EACxB,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,eAAe,CAAC,CAG1B;AAED,wBAAsB,kBAAkB,IAAI,OAAO,CAAC;IAClD,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;CACtB,CAAC,CAyBD"}