@mnemoai/core 1.1.0 → 1.1.2

package/dist/src/smart-metadata.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/smart-metadata.ts"],
+  "sourcesContent": ["// SPDX-License-Identifier: MIT\nimport type { MemoryCategory, MemoryTier } from \"./memory-categories.js\";\nimport type { DecayableMemory } from \"./decay-engine.js\";\n\ntype LegacyStoreCategory =\n  | \"preference\"\n  | \"fact\"\n  | \"decision\"\n  | \"entity\"\n  | \"other\"\n  | \"reflection\";\n\ntype EntryLike = {\n  text?: string;\n  category?: LegacyStoreCategory;\n  importance?: number;\n  timestamp?: number;\n  metadata?: string;\n};\n\nexport interface SmartMemoryMetadata {\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  source_session?: string;\n  /** Emotional salience score (0-1). Higher = more emotionally significant = decays slower.\n   *  Computed at store time via heuristic rules (zero LLM cost). */\n  emotional_salience: number;\n  [key: string]: unknown;\n}\n\nexport interface LifecycleMemory {\n  id: string;\n  importance: number;\n  confidence: number;\n  tier: MemoryTier;\n  accessCount: number;\n  createdAt: number;\n  lastAccessedAt: number;\n  emotionalSalience: number;\n}\n\nfunction clamp01(value: unknown, fallback: number): number {\n  const n = typeof value === \"number\" ? value : Number(value);\n  if (!Number.isFinite(n)) return fallback;\n  return Math.min(1, Math.max(0, n));\n}\n\nfunction clampCount(value: unknown, fallback = 0): number {\n  const n = typeof value === \"number\" ? value : Number(value);\n  if (!Number.isFinite(n) || n < 0) return fallback;\n  return Math.floor(n);\n}\n\n// ============================================================================\n// Emotional Salience \u2014 heuristic scoring (zero LLM cost)\n// ============================================================================\n\n/** High-salience signal patterns (decisions, strong emotions, firsts, money, people) */\nconst SALIENCE_BOOSTERS: Array<{ pattern: RegExp; boost: number }> = [\n  // Decisions and commitments\n  { pattern: /\\b(\u51B3\u5B9A|\u51B3\u7B56|confirmed|decided|commit|approved|\u6279\u4E86|\u62CD\u677F|\u5B9A\u4E86)\\b/i, boost: 0.3 },\n  // Strong emotions\n  { pattern: /\\b(\u9707\u60CA|\u60CA\u559C|\u6124\u6012|\u5931\u671B|\u5174\u594B|amazing|shocked|frustrated|excited|worried|\u62C5\u5FC3)\\b/i, boost: 0.25 },\n  // First-time events\n  { pattern: /\\b(\u7B2C\u4E00\u6B21|\u9996\u6B21|first time|first ever|\u4ECE\u672A|never before)\\b/i, boost: 0.25 },\n  // Financial significance\n  { pattern: /\\b(\\d+\u4E07|\\d+\u4EBF|\\$[\\d,.]+[MBK]|\u4F30\u503C|valuation|\u6295\u8D44|\u6301\u4ED3)\\b/i, boost: 0.2 },\n  // People and relationships (user-configurable entity names)\n  { pattern: /\\b(colleague|partner|mentor|friend|manager|teammate)\\b/i, boost: 0.15 },\n  // Lessons learned / mistakes\n  { pattern: /\\b(\u6559\u8BAD|\u8E29\u5751|pitfall|lesson|mistake|bug|\u6545\u969C|\u6302\u4E86|\u5D29\u4E86)\\b/i, boost: 0.2 },\n  // Preferences and identity\n  { pattern: /\\b(\u559C\u6B22|\u8BA8\u538C|\u504F\u597D|prefer|hate|love|always|never)\\b/i, boost: 0.15 },\n  // Exclamation / emphasis (emotional weight)\n  { pattern: /[!\uFF01]{2,}|\u203C\uFE0F|\u26A0\uFE0F|\uD83D\uDD34|\uD83D\uDC80/, boost: 0.1 },\n];\n\n/** Low-salience patterns (routine, technical noise) */\nconst SALIENCE_DAMPENERS: Array<{ pattern: RegExp; dampen: number }> = [\n  { pattern: /\\b(heartbeat|HEARTBEAT_OK)\\b/i, dampen: 0.2 },\n  { pattern: /\\b(cron|restart|gateway|status)\\b/i, dampen: 0.1 },\n  { pattern: /\\b(debug|stack trace|npm|node_modules|\\.tsx?|\\.jsx?)\\b/i, dampen: 0.1 },\n  { pattern: /^\\[?(Updated|Added|Removed|Fixed|Set)\\]?\\s.{0,30}$/i, dampen: 0.15 }, // short auto-generated entries only\n];\n\n/**\n * Compute emotional salience from text + category.\n * Returns 0-1. Higher = more emotionally charged / personally significant.\n * Pure heuristic, no LLM call.\n */\nexport function computeEmotionalSalience(\n  text: string,\n  category?: string,\n  importance?: number,\n): number {\n  let score = 0.35; // baseline \u2014 neutral memory\n\n  // Category boost\n  if (category === \"decision\") score += 0.15;\n  if (category === \"preference\") score += 0.1;\n  if (category === \"reflection\") score += 0.1;\n\n  // Importance as a weak signal\n  if (typeof importance === \"number\" && importance > 0.8) score += 0.1;\n  if (typeof importance === \"number\" && importance > 0.9) score += 0.05;\n\n  // Pattern matching\n  for (const { pattern, boost } of SALIENCE_BOOSTERS) {\n    if (pattern.test(text)) score += boost;\n  }\n  for (const { pattern, dampen } of SALIENCE_DAMPENERS) {\n    if (pattern.test(text)) score -= dampen;\n  }\n\n  return Math.min(1, Math.max(0, score));\n}\n\n// ============================================================================\n// Emotion Calibration \u2014 rule-based post-processing for LLM valence\n// ============================================================================\n\n/** Strong emotion signal words (positive or negative) */\nconst STRONG_EMOTION_PATTERNS = [\n  /\u592A\u597D\u4E86|\u592A\u68D2\u4E86|amazing|incredible|wonderful|fantastic|excellent/i,\n  /terrible|horrible|awful|disgusting|devastating/i,\n  /fuck|shit|damn|\u9760|\u5367\u69FD|\u6211\u53BB|\u5988\u7684/i,\n  /\u54C8\u54C8\u54C8|lol|lmao|rofl|\uD83D\uDE02|\uD83E\uDD23/i,\n  /[!\uFF01]{3,}/,\n  /heartbroken|ecstatic|furious|thrilled|terrified/i,\n  /\u5D29\u6E83|\u66B4\u6012|\u72C2\u559C|\u7EDD\u671B|\u9707\u60CA|\u5174\u594B\u6B7B\u4E86/i,\n];\n\n/** Factual / data-heavy text indicators */\nconst FACTUAL_PATTERNS = [\n  /\u4F30\u503C|revenue|valuation|profit|loss|margin/i,\n  /[$\uFFE5\u20AC\u00A3]/,\n  /%/,\n];\n\n/**\n * Calibrate LLM-returned emotion valence with rule-based post-processing.\n *\n * Fixes two common LLM failure modes:\n * 1. Strong emotional text scored as neutral (0.4-0.6) \u2192 push toward extremes\n * 2. Pure factual/data text scored as emotional \u2192 compress toward neutral\n *\n * @param text - The memory text\n * @param rawValence - LLM-returned valence (0-1, 0.5 = neutral)\n * @returns Calibrated valence (0-1)\n */\nexport function calibrateEmotion(text: string, rawValence: number): number {\n  if (!Number.isFinite(rawValence)) return 0.5;\n\n  // Check for strong emotion signals\n  const hasStrongEmotion = STRONG_EMOTION_PATTERNS.some(p => p.test(text));\n\n  // Check if text is factual/data-heavy\n  const digitChars = (text.match(/\\d/g) || []).length;\n  const digitRatio = text.length > 0 ? digitChars / text.length : 0;\n  const hasFactualSignals = digitRatio > 0.3 || FACTUAL_PATTERNS.some(p => p.test(text));\n\n  let calibrated = rawValence;\n\n  // Fix 1: Strong emotion + neutral valence \u2192 push to 0.3 or 0.7\n  if (hasStrongEmotion && rawValence >= 0.4 && rawValence <= 0.6) {\n    // Determine direction: below 0.5 \u2192 negative, above \u2192 positive\n    calibrated = rawValence <= 0.5 ? 0.3 : 0.7;\n  }\n\n  // Fix 2: Factual text \u2192 compress to 0.45-0.55\n  if (hasFactualSignals && !hasStrongEmotion) {\n    if (calibrated < 0.45) calibrated = 0.45;\n    if (calibrated > 0.55) calibrated = 0.55;\n  }\n\n  return Math.min(1, Math.max(0, calibrated));\n}\n\nfunction normalizeTier(value: unknown): MemoryTier {\n  switch (value) {\n    case \"core\":\n    case \"working\":\n    case \"peripheral\":\n      return value;\n    default:\n      return \"working\";\n  }\n}\n\nexport function reverseMapLegacyCategory(\n  oldCategory: LegacyStoreCategory | undefined,\n  text = \"\",\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      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\nfunction defaultOverview(text: string): string {\n  return `- ${text}`;\n}\n\nfunction normalizeText(value: unknown, fallback: string): string {\n  return typeof value === \"string\" && value.trim() ? value.trim() : fallback;\n}\n\nexport function parseSmartMetadata(\n  rawMetadata: string | undefined,\n  entry: EntryLike = {},\n): SmartMemoryMetadata {\n  let parsed: Record<string, unknown> = {};\n  if (rawMetadata) {\n    try {\n      const obj = JSON.parse(rawMetadata);\n      if (obj && typeof obj === \"object\") {\n        parsed = obj as Record<string, unknown>;\n      }\n    } catch {\n      parsed = {};\n    }\n  }\n\n  const text = entry.text ?? \"\";\n  const timestamp =\n    typeof entry.timestamp === \"number\" && Number.isFinite(entry.timestamp)\n      ? entry.timestamp\n      : Date.now();\n\n  const memoryCategory = reverseMapLegacyCategory(entry.category, text);\n  const l0 = normalizeText(parsed.l0_abstract, text);\n  const l2 = normalizeText(parsed.l2_content, text);\n  const normalized: SmartMemoryMetadata = {\n    ...parsed,\n    l0_abstract: l0,\n    l1_overview: normalizeText(parsed.l1_overview, defaultOverview(l0)),\n    l2_content: l2,\n    memory_category:\n      typeof parsed.memory_category === \"string\"\n        ? (parsed.memory_category as MemoryCategory)\n        : memoryCategory,\n    tier: normalizeTier(parsed.tier),\n    access_count: clampCount(parsed.access_count, 0),\n    confidence: clamp01(parsed.confidence, 0.7),\n    last_accessed_at: clampCount(parsed.last_accessed_at, timestamp),\n    source_session:\n      typeof parsed.source_session === \"string\" ? parsed.source_session : undefined,\n    emotional_salience: clamp01(\n      parsed.emotional_salience,\n      computeEmotionalSalience(text, entry.category, entry.importance),\n    ),\n  };\n\n  return normalized;\n}\n\nexport function buildSmartMetadata(\n  entry: EntryLike,\n  patch: Partial<SmartMemoryMetadata> = {},\n): SmartMemoryMetadata {\n  const base = parseSmartMetadata(entry.metadata, entry);\n  const text = entry.text ?? \"\";\n\n  // Calibrate emotional salience: fix LLM mis-scoring of strong emotions / factual text\n  const rawSalience = clamp01(\n    patch.emotional_salience ?? base.emotional_salience,\n    base.emotional_salience,\n  );\n  const calibratedSalience = calibrateEmotion(text, rawSalience);\n\n  return {\n    ...base,\n    ...patch,\n    l0_abstract: normalizeText(patch.l0_abstract, base.l0_abstract),\n    l1_overview: normalizeText(patch.l1_overview, base.l1_overview),\n    l2_content: normalizeText(patch.l2_content, base.l2_content),\n    memory_category:\n      typeof patch.memory_category === \"string\"\n        ? patch.memory_category\n        : base.memory_category,\n    tier: normalizeTier(patch.tier ?? base.tier),\n    access_count: clampCount(patch.access_count, base.access_count),\n    confidence: clamp01(patch.confidence, base.confidence),\n    last_accessed_at: clampCount(\n      patch.last_accessed_at,\n      base.last_accessed_at || entry.timestamp || Date.now(),\n    ),\n    source_session:\n      typeof patch.source_session === \"string\"\n        ? patch.source_session\n        : base.source_session,\n    emotional_salience: calibratedSalience,\n  };\n}\n\n// Metadata array size caps \u2014 prevent unbounded JSON growth\nconst MAX_SOURCES = 20;\nconst MAX_HISTORY = 50;\nconst MAX_RELATIONS = 16;\n\nexport function stringifySmartMetadata(\n  metadata: SmartMemoryMetadata | Record<string, unknown>,\n): string {\n  const capped = { ...metadata } as Record<string, unknown>;\n\n  // Cap array fields to prevent metadata bloat\n  if (Array.isArray(capped.sources) && capped.sources.length > MAX_SOURCES) {\n    capped.sources = capped.sources.slice(-MAX_SOURCES); // keep most recent\n  }\n  if (Array.isArray(capped.history) && capped.history.length > MAX_HISTORY) {\n    capped.history = capped.history.slice(-MAX_HISTORY);\n  }\n  if (Array.isArray(capped.relations) && capped.relations.length > MAX_RELATIONS) {\n    capped.relations = capped.relations.slice(0, MAX_RELATIONS);\n  }\n\n  return JSON.stringify(capped);\n}\n\nexport function toLifecycleMemory(\n  id: string,\n  entry: EntryLike,\n): LifecycleMemory {\n  const metadata = parseSmartMetadata(entry.metadata, entry);\n  const createdAt =\n    typeof entry.timestamp === \"number\" && Number.isFinite(entry.timestamp)\n      ? entry.timestamp\n      : Date.now();\n\n  return {\n    id,\n    importance:\n      typeof entry.importance === \"number\" && Number.isFinite(entry.importance)\n        ? entry.importance\n        : 0.7,\n    confidence: metadata.confidence,\n    tier: metadata.tier,\n    accessCount: metadata.access_count,\n    createdAt,\n    lastAccessedAt: metadata.last_accessed_at || createdAt,\n    emotionalSalience: metadata.emotional_salience,\n  };\n}\n\n/**\n * Parse a memory entry into both a DecayableMemory (for the decay engine)\n * and the raw SmartMemoryMetadata (for in-place mutation before write-back).\n */\nexport function getDecayableFromEntry(\n  entry: EntryLike & { id?: string },\n): { memory: DecayableMemory; meta: SmartMemoryMetadata } {\n  const meta = parseSmartMetadata(entry.metadata, entry);\n  const createdAt =\n    typeof entry.timestamp === \"number\" && Number.isFinite(entry.timestamp)\n      ? entry.timestamp\n      : Date.now();\n\n  const memory: DecayableMemory = {\n    id: (entry as { id?: string }).id ?? \"\",\n    importance:\n      typeof entry.importance === \"number\" && Number.isFinite(entry.importance)\n        ? entry.importance\n        : 0.7,\n    confidence: meta.confidence,\n    tier: meta.tier,\n    accessCount: meta.access_count,\n    createdAt,\n    lastAccessedAt: meta.last_accessed_at || createdAt,\n    emotionalSalience: meta.emotional_salience,\n  };\n\n  return { memory, meta };\n}\n\n// ============================================================================\n// Contextual Support \u2014 optional extension to SmartMemoryMetadata\n// ============================================================================\n\n/** Predefined context vocabulary for support slices */\nexport const SUPPORT_CONTEXT_VOCABULARY = [\n  \"general\", \"morning\", \"afternoon\", \"evening\", \"night\",\n  \"weekday\", \"weekend\", \"work\", \"leisure\",\n  \"summer\", \"winter\", \"travel\",\n] as const;\n\nexport type SupportContext = (typeof SUPPORT_CONTEXT_VOCABULARY)[number] | string;\n\n/** Max number of context slices per memory to prevent metadata bloat */\nexport const MAX_SUPPORT_SLICES = 8;\n\n/** A single context-specific support slice */\nexport interface ContextualSupport {\n  context: SupportContext;\n  confirmations: number;\n  contradictions: number;\n  strength: number;       // confirmations / (confirmations + contradictions)\n  last_observed_at: number;\n}\n\n/** V2 support info with per-context slices */\nexport interface SupportInfoV2 {\n  global_strength: number;      // weighted average across all slices\n  total_observations: number;   // sum of all confirmations + contradictions\n  slices: ContextualSupport[];\n}\n\n/**\n * Normalize a raw context label to a canonical context.\n * Maps common variants and falls back to \"general\".\n */\nexport function normalizeContext(raw: string | undefined): SupportContext {\n  if (!raw || !raw.trim()) return \"general\";\n  const lower = raw.trim().toLowerCase();\n\n  // Direct vocabulary match\n  if ((SUPPORT_CONTEXT_VOCABULARY as readonly string[]).includes(lower)) {\n    return lower as SupportContext;\n  }\n\n  // Common Chinese/English mappings\n  const aliases: Record<string, SupportContext> = {\n    \"\u65E9\u4E0A\": \"morning\", \"\u4E0A\u5348\": \"morning\", \"\u65E9\u6668\": \"morning\",\n    \"\u4E0B\u5348\": \"afternoon\", \"\u508D\u665A\": \"evening\", \"\u665A\u4E0A\": \"evening\",\n    \"\u6DF1\u591C\": \"night\", \"\u591C\u665A\": \"night\", \"\u51CC\u6668\": \"night\",\n    \"\u5DE5\u4F5C\u65E5\": \"weekday\", \"\u5E73\u65F6\": \"weekday\",\n    \"\u5468\u672B\": \"weekend\", \"\u5047\u65E5\": \"weekend\", \"\u4F11\u606F\u65E5\": \"weekend\",\n    \"\u5DE5\u4F5C\": \"work\", \"\u4E0A\u73ED\": \"work\", \"\u529E\u516C\": \"work\",\n    \"\u4F11\u95F2\": \"leisure\", \"\u653E\u677E\": \"leisure\", \"\u4F11\u606F\": \"leisure\",\n    \"\u590F\u5929\": \"summer\", \"\u590F\u5B63\": \"summer\",\n    \"\u51AC\u5929\": \"winter\", \"\u51AC\u5B63\": \"winter\",\n    \"\u65C5\u884C\": \"travel\", \"\u51FA\u5DEE\": \"travel\", \"\u65C5\u6E38\": \"travel\",\n  };\n\n  return aliases[lower] || lower; // keep as custom context if not mapped\n}\n\n/**\n * Parse support_info from metadata JSON. Handles V1 (flat) \u2192 V2 (sliced) migration.\n */\nexport function parseSupportInfo(raw: unknown): SupportInfoV2 {\n  const defaultV2: SupportInfoV2 = {\n    global_strength: 0.5,\n    total_observations: 0,\n    slices: [],\n  };\n\n  if (!raw || typeof raw !== \"object\") return defaultV2;\n  const obj = raw as Record<string, unknown>;\n\n  // V2 format: has slices array\n  if (Array.isArray(obj.slices)) {\n    return {\n      global_strength: typeof obj.global_strength === \"number\" ? obj.global_strength : 0.5,\n      total_observations: typeof obj.total_observations === \"number\" ? obj.total_observations : 0,\n      slices: (obj.slices as Record<string, unknown>[]).filter(\n        s => s && typeof s.context === \"string\",\n      ).map(s => ({\n        context: String(s.context),\n        confirmations: typeof s.confirmations === \"number\" && s.confirmations >= 0 ? s.confirmations : 0,\n        contradictions: typeof s.contradictions === \"number\" && s.contradictions >= 0 ? s.contradictions : 0,\n        strength: typeof s.strength === \"number\" && s.strength >= 0 && s.strength <= 1 ? s.strength : 0.5,\n        last_observed_at: typeof s.last_observed_at === \"number\" ? s.last_observed_at : Date.now(),\n      })),\n    };\n  }\n\n  // V1 format: flat { confirmations, contradictions, strength }\n  const conf = typeof obj.confirmations === \"number\" ? obj.confirmations : 0;\n  const contra = typeof obj.contradictions === \"number\" ? obj.contradictions : 0;\n  const total = conf + contra;\n  if (total === 0) return defaultV2;\n\n  return {\n    global_strength: total > 0 ? conf / total : 0.5,\n    total_observations: total,\n    slices: [{\n      context: \"general\",\n      confirmations: conf,\n      contradictions: contra,\n      strength: total > 0 ? conf / total : 0.5,\n      last_observed_at: Date.now(),\n    }],\n  };\n}\n\n/**\n * Update support stats for a specific context.\n * Returns a new SupportInfoV2 with the updated slice.\n */\nexport function updateSupportStats(\n  existing: SupportInfoV2,\n  contextLabel: string | undefined,\n  event: \"support\" | \"contradict\",\n): SupportInfoV2 {\n  const ctx = normalizeContext(contextLabel);\n  const base = { ...existing, slices: [...existing.slices.map(s => ({ ...s }))] };\n\n  // Find or create the context slice\n  let slice = base.slices.find(s => s.context === ctx);\n  if (!slice) {\n    slice = { context: ctx, confirmations: 0, contradictions: 0, strength: 0.5, last_observed_at: Date.now() };\n    base.slices.push(slice);\n  }\n\n  // Update slice\n  if (event === \"support\") slice.confirmations++;\n  else slice.contradictions++;\n  const sliceTotal = slice.confirmations + slice.contradictions;\n  slice.strength = sliceTotal > 0 ? slice.confirmations / sliceTotal : 0.5;\n  slice.last_observed_at = Date.now();\n\n  // Cap slices (keep most recently observed, but preserve dropped evidence).\n  // NOTE: Evidence from slices dropped in *previous* updates is already baked\n  // into total_observations/global_strength, so those values may drift slightly\n  // over many truncation cycles. This is an accepted trade-off for bounded JSON size.\n  let slices = base.slices;\n  let droppedConf = 0, droppedContra = 0;\n  if (slices.length > MAX_SUPPORT_SLICES) {\n    slices = slices\n      .sort((a, b) => b.last_observed_at - a.last_observed_at);\n    const dropped = slices.slice(MAX_SUPPORT_SLICES);\n    for (const d of dropped) {\n      droppedConf += d.confirmations;\n      droppedContra += d.contradictions;\n    }\n    slices = slices.slice(0, MAX_SUPPORT_SLICES);\n  }\n\n  // Recompute global strength including evidence from dropped slices\n  let totalConf = droppedConf, totalContra = droppedContra;\n  for (const s of slices) {\n    totalConf += s.confirmations;\n    totalContra += s.contradictions;\n  }\n  const totalObs = totalConf + totalContra;\n  const global_strength = totalObs > 0 ? totalConf / totalObs : 0.5;\n\n  return { global_strength, total_observations: totalObs, slices };\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/src/storage-adapter.d.ts

@@ -0,0 +1,102 @@
+/**
+ * StorageAdapter — Abstract interface for vector storage backends.
+ *
+ * Mnemo ships with LanceDB as the default adapter.
+ * Implement this interface to add support for other backends
+ * (Qdrant, Chroma, Milvus, Pinecone, PGVector, etc.)
+ */
+export interface MemoryRecord {
+    id: string;
+    text: string;
+    vector: number[];
+    timestamp: number;
+    scope: string;
+    importance: number;
+    category: string;
+    metadata: string;
+    [key: string]: unknown;
+}
+export interface SearchResult {
+    record: MemoryRecord;
+    score: number;
+}
+export interface QueryOptions {
+    where?: string;
+    select?: string[];
+    limit?: number;
+    offset?: number;
+}
+export interface StorageAdapter {
+    /** Adapter name for logging and diagnostics */
+    readonly name: string;
+    /**
+     * Connect to the storage backend.
+     * @param dbPath - path or connection string
+     */
+    connect(dbPath: string): Promise<void>;
+    /**
+     * Ensure the memories table exists with proper schema.
+     * Creates the table if it doesn't exist, opens it if it does.
+     * @param vectorDimensions - embedding vector dimensions (e.g. 1024)
+     */
+    ensureTable(vectorDimensions: number): Promise<void>;
+    /**
+     * Insert one or more records.
+     */
+    add(records: MemoryRecord[]): Promise<void>;
+    /**
+     * Update a record by ID. Typically delete + re-insert.
+     */
+    update(id: string, record: MemoryRecord): Promise<void>;
+    /**
+     * Delete records matching a filter expression.
+     * @param filter - SQL-like filter string, e.g. "id = 'abc'"
+     */
+    delete(filter: string): Promise<void>;
+    /**
+     * Vector similarity search.
+     * @returns results sorted by descending similarity score (0-1)
+     */
+    vectorSearch(vector: number[], limit: number, minScore?: number, scopeFilter?: string[]): Promise<SearchResult[]>;
+    /**
+     * Full-text (BM25) search.
+     * @returns results sorted by descending relevance score
+     */
+    fullTextSearch(query: string, limit: number, scopeFilter?: string[]): Promise<SearchResult[]>;
+    /**
+     * General-purpose query with optional filter, select, limit.
+     */
+    query(options: QueryOptions): Promise<MemoryRecord[]>;
+    /**
+     * Count records matching an optional filter.
+     */
+    count(filter?: string): Promise<number>;
+    /**
+     * Ensure full-text search index exists on the text field.
+     */
+    ensureFullTextIndex(): Promise<void>;
+    /**
+     * Check if full-text search is supported and initialized.
+     */
+    hasFullTextSearch(): boolean;
+    /**
+     * Close the connection / cleanup resources.
+     */
+    close(): Promise<void>;
+}
+export type AdapterFactory = (config?: Record<string, unknown>) => StorageAdapter;
+/**
+ * Register a storage adapter backend.
+ * @example registerAdapter("qdrant", (config) => new QdrantAdapter(config))
+ */
+export declare function registerAdapter(name: string, factory: AdapterFactory): void;
+/**
+ * Create a storage adapter by name.
+ * Falls back to LanceDB if name is not registered.
+ */
+export declare function createAdapter(name: string, config?: Record<string, unknown>): StorageAdapter;
+/**
+ * List all registered adapter names.
+ */
+export declare function listAdapters(): string[];
+//# sourceMappingURL=storage-adapter.d.ts.map

package/dist/src/storage-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage-adapter.d.ts","sourceRoot":"","sources":["../../src/storage-adapter.ts"],"names":[],"mappings":"AACA;;;;;;GAMG;AAIH,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,YAAY,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAID,MAAM,WAAW,cAAc;IAC7B,+CAA+C;IAC/C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;;OAGG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvC;;;;OAIG;IACH,WAAW,CAAC,gBAAgB,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAErD;;OAEG;IACH,GAAG,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE5C;;OAEG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAExD;;;OAGG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEtC;;;OAGG;IACH,YAAY,CACV,MAAM,EAAE,MAAM,EAAE,EAChB,KAAK,EAAE,MAAM,EACb,QAAQ,CAAC,EAAE,MAAM,EACjB,WAAW,CAAC,EAAE,MAAM,EAAE,GACrB,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;IAE3B;;;OAGG;IACH,cAAc,CACZ,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,WAAW,CAAC,EAAE,MAAM,EAAE,GACrB,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;IAE3B;;OAEG;IACH,KAAK,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;IAEtD;;OAEG;IACH,KAAK,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAExC;;OAEG;IACH,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAErC;;OAEG;IACH,iBAAiB,IAAI,OAAO,CAAC;IAE7B;;OAEG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAID,MAAM,MAAM,cAAc,GAAG,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,cAAc,CAAC;AAIlF;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,IAAI,CAE3E;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,cAAc,CAU5F;AAED;;GAEG;AACH,wBAAgB,YAAY,IAAI,MAAM,EAAE,CAEvC"}

package/dist/src/storage-adapter.js

@@ -0,0 +1,22 @@
+const _registry = /* @__PURE__ */ new Map();
+function registerAdapter(name, factory) {
+  _registry.set(name, factory);
+}
+function createAdapter(name, config) {
+  const factory = _registry.get(name);
+  if (!factory) {
+    throw new Error(
+      `Storage adapter "${name}" not found. Available: ${[..._registry.keys()].join(", ") || "(none)"}. Did you forget to call registerAdapter()?`
+    );
+  }
+  return factory(config);
+}
+function listAdapters() {
+  return [..._registry.keys()];
+}
+export {
+  createAdapter,
+  listAdapters,
+  registerAdapter
+};
+//# sourceMappingURL=storage-adapter.js.map

package/dist/src/storage-adapter.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/storage-adapter.ts"],
+  "sourcesContent": ["// SPDX-License-Identifier: MIT\n/**\n * StorageAdapter \u2014 Abstract interface for vector storage backends.\n *\n * Mnemo ships with LanceDB as the default adapter.\n * Implement this interface to add support for other backends\n * (Qdrant, Chroma, Milvus, Pinecone, PGVector, etc.)\n */\n\n// \u2500\u2500 Types \u2500\u2500\n\nexport interface MemoryRecord {\n  id: string;\n  text: string;\n  vector: number[];\n  timestamp: number;\n  scope: string;\n  importance: number;\n  category: string;\n  metadata: string;\n  [key: string]: unknown;\n}\n\nexport interface SearchResult {\n  record: MemoryRecord;\n  score: number;\n}\n\nexport interface QueryOptions {\n  where?: string;\n  select?: string[];\n  limit?: number;\n  offset?: number;\n}\n\n// \u2500\u2500 Interface \u2500\u2500\n\nexport interface StorageAdapter {\n  /** Adapter name for logging and diagnostics */\n  readonly name: string;\n\n  /**\n   * Connect to the storage backend.\n   * @param dbPath - path or connection string\n   */\n  connect(dbPath: string): Promise<void>;\n\n  /**\n   * Ensure the memories table exists with proper schema.\n   * Creates the table if it doesn't exist, opens it if it does.\n   * @param vectorDimensions - embedding vector dimensions (e.g. 1024)\n   */\n  ensureTable(vectorDimensions: number): Promise<void>;\n\n  /**\n   * Insert one or more records.\n   */\n  add(records: MemoryRecord[]): Promise<void>;\n\n  /**\n   * Update a record by ID. Typically delete + re-insert.\n   */\n  update(id: string, record: MemoryRecord): Promise<void>;\n\n  /**\n   * Delete records matching a filter expression.\n   * @param filter - SQL-like filter string, e.g. \"id = 'abc'\"\n   */\n  delete(filter: string): Promise<void>;\n\n  /**\n   * Vector similarity search.\n   * @returns results sorted by descending similarity score (0-1)\n   */\n  vectorSearch(\n    vector: number[],\n    limit: number,\n    minScore?: number,\n    scopeFilter?: string[],\n  ): Promise<SearchResult[]>;\n\n  /**\n   * Full-text (BM25) search.\n   * @returns results sorted by descending relevance score\n   */\n  fullTextSearch(\n    query: string,\n    limit: number,\n    scopeFilter?: string[],\n  ): Promise<SearchResult[]>;\n\n  /**\n   * General-purpose query with optional filter, select, limit.\n   */\n  query(options: QueryOptions): Promise<MemoryRecord[]>;\n\n  /**\n   * Count records matching an optional filter.\n   */\n  count(filter?: string): Promise<number>;\n\n  /**\n   * Ensure full-text search index exists on the text field.\n   */\n  ensureFullTextIndex(): Promise<void>;\n\n  /**\n   * Check if full-text search is supported and initialized.\n   */\n  hasFullTextSearch(): boolean;\n\n  /**\n   * Close the connection / cleanup resources.\n   */\n  close(): Promise<void>;\n}\n\n// \u2500\u2500 Factory \u2500\u2500\n\nexport type AdapterFactory = (config?: Record<string, unknown>) => StorageAdapter;\n\nconst _registry = new Map<string, AdapterFactory>();\n\n/**\n * Register a storage adapter backend.\n * @example registerAdapter(\"qdrant\", (config) => new QdrantAdapter(config))\n */\nexport function registerAdapter(name: string, factory: AdapterFactory): void {\n  _registry.set(name, factory);\n}\n\n/**\n * Create a storage adapter by name.\n * Falls back to LanceDB if name is not registered.\n */\nexport function createAdapter(name: string, config?: Record<string, unknown>): StorageAdapter {\n  const factory = _registry.get(name);\n  if (!factory) {\n    throw new Error(\n      `Storage adapter \"${name}\" not found. ` +\n      `Available: ${[..._registry.keys()].join(\", \") || \"(none)\"}. ` +\n      `Did you forget to call registerAdapter()?`\n    );\n  }\n  return factory(config);\n}\n\n/**\n * List all registered adapter names.\n */\nexport function listAdapters(): string[] {\n  return [..._registry.keys()];\n}\n"],
+  "mappings": "AAyHA,MAAM,YAAY,oBAAI,IAA4B;AAM3C,SAAS,gBAAgB,MAAc,SAA+B;AAC3E,YAAU,IAAI,MAAM,OAAO;AAC7B;AAMO,SAAS,cAAc,MAAc,QAAkD;AAC5F,QAAM,UAAU,UAAU,IAAI,IAAI;AAClC,MAAI,CAAC,SAAS;AACZ,UAAM,IAAI;AAAA,MACR,oBAAoB,IAAI,2BACV,CAAC,GAAG,UAAU,KAAK,CAAC,EAAE,KAAK,IAAI,KAAK,QAAQ;AAAA,IAE5D;AAAA,EACF;AACA,SAAO,QAAQ,MAAM;AACvB;AAKO,SAAS,eAAyB;AACvC,SAAO,CAAC,GAAG,UAAU,KAAK,CAAC;AAC7B;",
+  "names": []
+}

package/dist/src/store.d.ts

@@ -0,0 +1,108 @@
+/**
+ * LanceDB Storage Layer with Multi-Scope Support
+ */
+import type { SemanticGate } from "./semantic-gate.js";
+export interface MemoryEntry {
+    id: string;
+    text: string;
+    vector: number[];
+    category: "preference" | "fact" | "decision" | "entity" | "other" | "reflection";
+    scope: string;
+    importance: number;
+    timestamp: number;
+    metadata?: string;
+}
+export interface MemorySearchResult {
+    entry: MemoryEntry;
+    score: number;
+}
+export interface StoreConfig {
+    dbPath: string;
+    vectorDim: number;
+    /** Enable near-duplicate detection before writing (default: true) */
+    deduplication?: boolean;
+    /** Enable semantic noise gate to filter fragments (default: true) */
+    semanticGate?: boolean;
+    /** Storage backend: "lancedb" (default), "qdrant", "chroma", "pgvector" */
+    storageBackend?: string;
+    /** Backend-specific config (url, connectionString, etc.) */
+    storageConfig?: Record<string, unknown>;
+}
+export interface MetadataPatch {
+    [key: string]: unknown;
+}
+import type { StorageAdapter } from "./storage-adapter.js";
+export declare const loadLanceDB: () => Promise<typeof import("@lancedb/lancedb")>;
+/**
+ * Validate and prepare the storage directory before LanceDB connection.
+ * Resolves symlinks, creates missing directories, and checks write permissions.
+ * Returns the resolved absolute path on success, or throws a descriptive error.
+ */
+export declare function validateStoragePath(dbPath: string): string;
+export declare class MemoryStore {
+    private readonly config;
+    private db;
+    private table;
+    private initPromise;
+    private ftsIndexCreated;
+    private updateQueue;
+    private semanticGateInstance;
+    /** When using a non-LanceDB adapter, this holds the active adapter instance */
+    private _adapter;
+    /** True when using the adapter path (non-LanceDB backends) */
+    get usingAdapter(): boolean;
+    constructor(config: StoreConfig);
+    /** Inject a SemanticGate instance (created externally with an Embedder). */
+    setSemanticGate(gate: SemanticGate): void;
+    get dbPath(): string;
+    /** Get the active adapter (null if using legacy LanceDB path) */
+    get adapter(): StorageAdapter | null;
+    /** Whether BM25 full-text search is available */
+    get hasFtsSupport(): boolean;
+    private ensureInitialized;
+    private doInitialize;
+    private createFtsIndex;
+    store(entry: Omit<MemoryEntry, "id" | "timestamp">): Promise<MemoryEntry>;
+    /**
+     * Import a pre-built entry while preserving its id/timestamp.
+     * Used for re-embedding / migration / A/B testing across embedding models.
+     * Intentionally separate from `store()` to keep normal writes simple.
+     */
+    importEntry(entry: MemoryEntry): Promise<MemoryEntry>;
+    hasId(id: string): Promise<boolean>;
+    getById(id: string, scopeFilter?: string[]): Promise<MemoryEntry | null>;
+    vectorSearch(vector: number[], limit?: number, minScore?: number, scopeFilter?: string[]): Promise<MemorySearchResult[]>;
+    bm25Search(query: string, limit?: number, scopeFilter?: string[]): Promise<MemorySearchResult[]>;
+    private lexicalFallbackSearch;
+    delete(id: string, scopeFilter?: string[]): Promise<boolean>;
+    list(scopeFilter?: string[], category?: string, limit?: number, offset?: number): Promise<MemoryEntry[]>;
+    stats(scopeFilter?: string[]): Promise<{
+        totalCount: number;
+        scopeCounts: Record<string, number>;
+        categoryCounts: Record<string, number>;
+    }>;
+    update(id: string, updates: {
+        text?: string;
+        vector?: number[];
+        importance?: number;
+        category?: MemoryEntry["category"];
+        metadata?: string;
+    }, scopeFilter?: string[]): Promise<MemoryEntry | null>;
+    private runSerializedUpdate;
+    patchMetadata(id: string, patch: MetadataPatch, scopeFilter?: string[]): Promise<MemoryEntry | null>;
+    bulkDelete(scopeFilter: string[], beforeTimestamp?: number): Promise<number>;
+    /** Last FTS error for diagnostics */
+    private _lastFtsError;
+    get lastFtsError(): string | null;
+    /** Get FTS index health status */
+    getFtsStatus(): {
+        available: boolean;
+        lastError: string | null;
+    };
+    /** Rebuild FTS index (drops and recreates). Useful for recovery after corruption. */
+    rebuildFtsIndex(): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+}
+//# sourceMappingURL=store.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/store.ts"],"names":[],"mappings":"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"}