@mnemoai/core 1.1.0 → 1.1.1

package/dist/src/chunker.js

@@ -0,0 +1,157 @@
+const EMBEDDING_CONTEXT_LIMITS = {
+  // Jina v5
+  "jina-embeddings-v5-text-small": 8192,
+  "jina-embeddings-v5-text-nano": 8192,
+  // OpenAI
+  "text-embedding-3-small": 8192,
+  "text-embedding-3-large": 8192,
+  // Google
+  "text-embedding-004": 8192,
+  "gemini-embedding-001": 2048,
+  // Local/common
+  "nomic-embed-text": 8192,
+  "all-MiniLM-L6-v2": 512,
+  "all-mpnet-base-v2": 512
+};
+const DEFAULT_CHUNKER_CONFIG = {
+  maxChunkSize: 4e3,
+  overlapSize: 200,
+  minChunkSize: 200,
+  semanticSplit: true,
+  maxLinesPerChunk: 50
+};
+const SENTENCE_ENDING = /[.!?。！？]/;
+function clamp(n, lo, hi) {
+  return Math.max(lo, Math.min(hi, n));
+}
+function countLines(s) {
+  return s.split(/\r\n|\n|\r/).length;
+}
+function findLastIndexWithin(text, re, start, end) {
+  let last = -1;
+  for (let i = end - 1; i >= start; i--) {
+    if (re.test(text[i])) return i;
+  }
+  return last;
+}
+function findSplitEnd(text, start, maxEnd, minEnd, config) {
+  const safeMinEnd = clamp(minEnd, start + 1, maxEnd);
+  const safeMaxEnd = clamp(maxEnd, safeMinEnd, text.length);
+  if (config.maxLinesPerChunk > 0) {
+    const candidate = text.slice(start, safeMaxEnd);
+    if (countLines(candidate) > config.maxLinesPerChunk) {
+      let breaks = 0;
+      for (let i = start; i < safeMaxEnd; i++) {
+        const ch = text[i];
+        if (ch === "\n") {
+          breaks++;
+          if (breaks >= config.maxLinesPerChunk) {
+            return Math.max(i + 1, safeMinEnd);
+          }
+        }
+      }
+    }
+  }
+  if (config.semanticSplit) {
+    for (let i = safeMaxEnd - 1; i >= safeMinEnd; i--) {
+      if (SENTENCE_ENDING.test(text[i])) {
+        let j = i + 1;
+        while (j < safeMaxEnd && /\s/.test(text[j])) j++;
+        return j;
+      }
+    }
+    for (let i = safeMaxEnd - 1; i >= safeMinEnd; i--) {
+      if (text[i] === "\n") return i + 1;
+    }
+  }
+  for (let i = safeMaxEnd - 1; i >= safeMinEnd; i--) {
+    if (/\s/.test(text[i])) return i;
+  }
+  return safeMaxEnd;
+}
+function sliceTrimWithIndices(text, start, end) {
+  const raw = text.slice(start, end);
+  const leading = raw.match(/^\s*/)?.[0]?.length ?? 0;
+  const trailing = raw.match(/\s*$/)?.[0]?.length ?? 0;
+  const chunk = raw.trim();
+  const trimmedStart = start + leading;
+  const trimmedEnd = end - trailing;
+  return {
+    chunk,
+    meta: {
+      startIndex: trimmedStart,
+      endIndex: Math.max(trimmedStart, trimmedEnd),
+      length: chunk.length
+    }
+  };
+}
+function chunkDocument(text, config = DEFAULT_CHUNKER_CONFIG) {
+  if (!text || text.trim().length === 0) {
+    return { chunks: [], metadatas: [], totalOriginalLength: 0, chunkCount: 0 };
+  }
+  const totalOriginalLength = text.length;
+  const chunks = [];
+  const metadatas = [];
+  let pos = 0;
+  const maxGuard = Math.max(4, Math.ceil(text.length / Math.max(1, config.maxChunkSize - config.overlapSize)) + 5);
+  let guard = 0;
+  while (pos < text.length && guard < maxGuard) {
+    guard++;
+    const remaining = text.length - pos;
+    if (remaining <= config.maxChunkSize) {
+      const { chunk: chunk2, meta: meta2 } = sliceTrimWithIndices(text, pos, text.length);
+      if (chunk2.length > 0) {
+        chunks.push(chunk2);
+        metadatas.push(meta2);
+      }
+      break;
+    }
+    const maxEnd = Math.min(pos + config.maxChunkSize, text.length);
+    const minEnd = Math.min(pos + config.minChunkSize, maxEnd);
+    const end = findSplitEnd(text, pos, maxEnd, minEnd, config);
+    const { chunk, meta } = sliceTrimWithIndices(text, pos, end);
+    if (chunk.length < config.minChunkSize) {
+      const hardEnd = Math.min(pos + config.maxChunkSize, text.length);
+      const hard = sliceTrimWithIndices(text, pos, hardEnd);
+      if (hard.chunk.length > 0) {
+        chunks.push(hard.chunk);
+        metadatas.push(hard.meta);
+      }
+      if (hardEnd >= text.length) break;
+      pos = Math.max(hardEnd - config.overlapSize, pos + 1);
+      continue;
+    }
+    chunks.push(chunk);
+    metadatas.push(meta);
+    if (end >= text.length) break;
+    const nextPos = Math.max(end - config.overlapSize, pos + 1);
+    pos = nextPos;
+  }
+  return {
+    chunks,
+    metadatas,
+    totalOriginalLength,
+    chunkCount: chunks.length
+  };
+}
+function smartChunk(text, embedderModel) {
+  const limit = embedderModel ? EMBEDDING_CONTEXT_LIMITS[embedderModel] : void 0;
+  const base = limit ?? 8192;
+  const config = {
+    maxChunkSize: Math.max(1e3, Math.floor(base * 0.7)),
+    overlapSize: Math.max(0, Math.floor(base * 0.05)),
+    minChunkSize: Math.max(100, Math.floor(base * 0.1)),
+    semanticSplit: true,
+    maxLinesPerChunk: 50
+  };
+  return chunkDocument(text, config);
+}
+var chunker_default = chunkDocument;
+export {
+  DEFAULT_CHUNKER_CONFIG,
+  EMBEDDING_CONTEXT_LIMITS,
+  chunkDocument,
+  chunker_default as default,
+  smartChunk
+};
+//# sourceMappingURL=chunker.js.map

package/dist/src/chunker.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/chunker.ts"],
+  "sourcesContent": ["// SPDX-License-Identifier: MIT\n/**\n * Long Context Chunking System\n *\n * Goal: split documents that exceed embedding model context limits into smaller,\n * semantically coherent chunks with overlap.\n *\n * Notes:\n * - We use *character counts* as a conservative proxy for tokens.\n * - The embedder triggers this only after a provider throws a context-length error.\n */\n\n// ============================================================================\n// Types & Constants\n// ============================================================================\n\nexport interface ChunkMetadata {\n  startIndex: number;\n  endIndex: number;\n  length: number;\n}\n\nexport interface ChunkResult {\n  chunks: string[];\n  metadatas: ChunkMetadata[];\n  totalOriginalLength: number;\n  chunkCount: number;\n}\n\nexport interface ChunkerConfig {\n  /** Maximum characters per chunk. */\n  maxChunkSize: number;\n  /** Overlap between chunks in characters. */\n  overlapSize: number;\n  /** Minimum chunk size (except the final chunk). */\n  minChunkSize: number;\n  /** Attempt to split on sentence boundaries for better semantic coherence. */\n  semanticSplit: boolean;\n  /** Max lines per chunk before we try to split earlier on a line boundary. */\n  maxLinesPerChunk: number;\n}\n\n// Common embedding context limits (provider/model specific). These are typically\n// token limits, but we treat them as inputs to a conservative char-based heuristic.\nexport const EMBEDDING_CONTEXT_LIMITS: Record<string, number> = {\n  // Jina v5\n  \"jina-embeddings-v5-text-small\": 8192,\n  \"jina-embeddings-v5-text-nano\": 8192,\n\n  // OpenAI\n  \"text-embedding-3-small\": 8192,\n  \"text-embedding-3-large\": 8192,\n\n  // Google\n  \"text-embedding-004\": 8192,\n  \"gemini-embedding-001\": 2048,\n\n  // Local/common\n  \"nomic-embed-text\": 8192,\n  \"all-MiniLM-L6-v2\": 512,\n  \"all-mpnet-base-v2\": 512,\n};\n\nexport const DEFAULT_CHUNKER_CONFIG: ChunkerConfig = {\n  maxChunkSize: 4000,\n  overlapSize: 200,\n  minChunkSize: 200,\n  semanticSplit: true,\n  maxLinesPerChunk: 50,\n};\n\n// Sentence ending patterns (English + CJK-ish punctuation)\nconst SENTENCE_ENDING = /[.!?\u3002\uFF01\uFF1F]/;\n\n// ============================================================================\n// Helpers\n// ============================================================================\n\nfunction clamp(n: number, lo: number, hi: number): number {\n  return Math.max(lo, Math.min(hi, n));\n}\n\nfunction countLines(s: string): number {\n  // Count \\n (treat CRLF as one line break)\n  return s.split(/\\r\\n|\\n|\\r/).length;\n}\n\nfunction findLastIndexWithin(text: string, re: RegExp, start: number, end: number): number {\n  // Find last match start index for regex within [start, end).\n  // NOTE: `re` must NOT be global; we will scan manually.\n  let last = -1;\n  for (let i = end - 1; i >= start; i--) {\n    if (re.test(text[i])) return i;\n  }\n  return last;\n}\n\nfunction findSplitEnd(text: string, start: number, maxEnd: number, minEnd: number, config: ChunkerConfig): number {\n  const safeMinEnd = clamp(minEnd, start + 1, maxEnd);\n  const safeMaxEnd = clamp(maxEnd, safeMinEnd, text.length);\n\n  // Respect line limit: if we exceed maxLinesPerChunk, force earlier split at a line break.\n  if (config.maxLinesPerChunk > 0) {\n    const candidate = text.slice(start, safeMaxEnd);\n    if (countLines(candidate) > config.maxLinesPerChunk) {\n      // Find the position of the Nth line break.\n      let breaks = 0;\n      for (let i = start; i < safeMaxEnd; i++) {\n        const ch = text[i];\n        if (ch === \"\\n\") {\n          breaks++;\n          if (breaks >= config.maxLinesPerChunk) {\n            // Split right after this newline.\n            return Math.max(i + 1, safeMinEnd);\n          }\n        }\n      }\n    }\n  }\n\n  if (config.semanticSplit) {\n    // Prefer a sentence boundary near the end.\n    // Scan backward from safeMaxEnd to safeMinEnd.\n    for (let i = safeMaxEnd - 1; i >= safeMinEnd; i--) {\n      if (SENTENCE_ENDING.test(text[i])) {\n        // Include trailing whitespace after punctuation.\n        let j = i + 1;\n        while (j < safeMaxEnd && /\\s/.test(text[j])) j++;\n        return j;\n      }\n    }\n\n    // Next best: newline boundary.\n    for (let i = safeMaxEnd - 1; i >= safeMinEnd; i--) {\n      if (text[i] === \"\\n\") return i + 1;\n    }\n  }\n\n  // Fallback: last whitespace boundary.\n  for (let i = safeMaxEnd - 1; i >= safeMinEnd; i--) {\n    if (/\\s/.test(text[i])) return i;\n  }\n\n  return safeMaxEnd;\n}\n\nfunction sliceTrimWithIndices(text: string, start: number, end: number): { chunk: string; meta: ChunkMetadata } {\n  const raw = text.slice(start, end);\n  const leading = raw.match(/^\\s*/)?.[0]?.length ?? 0;\n  const trailing = raw.match(/\\s*$/)?.[0]?.length ?? 0;\n  const chunk = raw.trim();\n\n  const trimmedStart = start + leading;\n  const trimmedEnd = end - trailing;\n\n  return {\n    chunk,\n    meta: {\n      startIndex: trimmedStart,\n      endIndex: Math.max(trimmedStart, trimmedEnd),\n      length: chunk.length,\n    },\n  };\n}\n\n// ============================================================================\n// Chunking Core\n// ============================================================================\n\nexport function chunkDocument(text: string, config: ChunkerConfig = DEFAULT_CHUNKER_CONFIG): ChunkResult {\n  if (!text || text.trim().length === 0) {\n    return { chunks: [], metadatas: [], totalOriginalLength: 0, chunkCount: 0 };\n  }\n\n  const totalOriginalLength = text.length;\n  const chunks: string[] = [];\n  const metadatas: ChunkMetadata[] = [];\n\n  let pos = 0;\n  const maxGuard = Math.max(4, Math.ceil(text.length / Math.max(1, config.maxChunkSize - config.overlapSize)) + 5);\n  let guard = 0;\n\n  while (pos < text.length && guard < maxGuard) {\n    guard++;\n\n    const remaining = text.length - pos;\n    if (remaining <= config.maxChunkSize) {\n      const { chunk, meta } = sliceTrimWithIndices(text, pos, text.length);\n      if (chunk.length > 0) {\n        chunks.push(chunk);\n        metadatas.push(meta);\n      }\n      break;\n    }\n\n    const maxEnd = Math.min(pos + config.maxChunkSize, text.length);\n    const minEnd = Math.min(pos + config.minChunkSize, maxEnd);\n\n    const end = findSplitEnd(text, pos, maxEnd, minEnd, config);\n    const { chunk, meta } = sliceTrimWithIndices(text, pos, end);\n\n    // If trimming made it too small, fall back to a hard split.\n    if (chunk.length < config.minChunkSize) {\n      const hardEnd = Math.min(pos + config.maxChunkSize, text.length);\n      const hard = sliceTrimWithIndices(text, pos, hardEnd);\n      if (hard.chunk.length > 0) {\n        chunks.push(hard.chunk);\n        metadatas.push(hard.meta);\n      }\n      if (hardEnd >= text.length) break;\n      pos = Math.max(hardEnd - config.overlapSize, pos + 1);\n      continue;\n    }\n\n    chunks.push(chunk);\n    metadatas.push(meta);\n\n    if (end >= text.length) break;\n\n    // Move forward with overlap.\n    const nextPos = Math.max(end - config.overlapSize, pos + 1);\n    pos = nextPos;\n  }\n\n  return {\n    chunks,\n    metadatas,\n    totalOriginalLength,\n    chunkCount: chunks.length,\n  };\n}\n\n/**\n * Smart chunker that adapts to model context limits.\n *\n * We intentionally pick conservative char limits (70% of the reported limit)\n * since token/char ratios vary.\n */\nexport function smartChunk(text: string, embedderModel?: string): ChunkResult {\n  const limit = embedderModel ? EMBEDDING_CONTEXT_LIMITS[embedderModel] : undefined;\n  const base = limit ?? 8192;\n\n  const config: ChunkerConfig = {\n    maxChunkSize: Math.max(1000, Math.floor(base * 0.7)),\n    overlapSize: Math.max(0, Math.floor(base * 0.05)),\n    minChunkSize: Math.max(100, Math.floor(base * 0.1)),\n    semanticSplit: true,\n    maxLinesPerChunk: 50,\n  };\n\n  return chunkDocument(text, config);\n}\n\nexport default chunkDocument;\n"],
+  "mappings": "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",
+  "names": ["chunk", "meta"]
+}

package/dist/src/config.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Shared Configuration Helpers
+ * Extracted from index.ts for reuse by MCP server and gateway plugin.
+ */
+export interface PluginConfig {
+    embedding: {
+        provider: "openai-compatible";
+        apiKey: string | string[];
+        model?: string;
+        baseURL?: string;
+        dimensions?: number;
+        taskQuery?: string;
+        taskPassage?: string;
+        normalized?: boolean;
+    };
+    dbPath?: string;
+    autoCapture?: boolean;
+    autoRecall?: boolean;
+    autoRecallMinLength?: number;
+    autoRecallMinRepeated?: number;
+    captureAssistant?: boolean;
+    retrieval?: {
+        mode?: "hybrid" | "vector";
+        vectorWeight?: number;
+        bm25Weight?: number;
+        minScore?: number;
+        rerank?: "cross-encoder" | "lightweight" | "none";
+        candidatePoolSize?: number;
+        rerankApiKey?: string;
+        rerankModel?: string;
+        rerankEndpoint?: string;
+        rerankProvider?: "jina" | "siliconflow" | "voyage" | "pinecone";
+        recencyHalfLifeDays?: number;
+        recencyWeight?: number;
+        filterNoise?: boolean;
+        lengthNormAnchor?: number;
+        hardMinScore?: number;
+        timeDecayHalfLifeDays?: number;
+        reinforcementFactor?: number;
+        maxHalfLifeMultiplier?: number;
+    };
+    scopes?: {
+        default?: string;
+        definitions?: Record<string, {
+            description: string;
+        }>;
+        agentAccess?: Record<string, string[]>;
+    };
+    enableManagementTools?: boolean;
+    sessionMemory?: {
+        enabled?: boolean;
+        messageCount?: number;
+    };
+    mdMirror?: {
+        enabled?: boolean;
+        dir?: string;
+    };
+    autoCaptureLLM?: {
+        enabled?: boolean;
+        endpoint?: string;
+        model?: string;
+        timeoutMs?: number;
+    };
+}
+export declare function getDefaultDbPath(): string;
+export declare function resolveEnvVars(value: string): string;
+export declare function parsePositiveInt(value: unknown): number | undefined;
+export declare function parsePluginConfig(value: unknown): PluginConfig;
+export declare function loadConfigFromOpenClaw(): PluginConfig;
+//# sourceMappingURL=config.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/config.ts"],"names":[],"mappings":"AACA;;;GAGG;AAUH,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE;QACT,QAAQ,EAAE,mBAAmB,CAAC;QAC9B,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;QAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,UAAU,CAAC,EAAE,OAAO,CAAC;KACtB,CAAC;IACF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,SAAS,CAAC,EAAE;QACV,IAAI,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAC;QAC3B,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,MAAM,CAAC,EAAE,eAAe,GAAG,aAAa,GAAG,MAAM,CAAC;QAClD,iBAAiB,CAAC,EAAE,MAAM,CAAC;QAC3B,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,cAAc,CAAC,EAAE,MAAM,GAAG,aAAa,GAAG,QAAQ,GAAG,UAAU,CAAC;QAChE,mBAAmB,CAAC,EAAE,MAAM,CAAC;QAC7B,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,WAAW,CAAC,EAAE,OAAO,CAAC;QACtB,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,qBAAqB,CAAC,EAAE,MAAM,CAAC;QAC/B,mBAAmB,CAAC,EAAE,MAAM,CAAC;QAC7B,qBAAqB,CAAC,EAAE,MAAM,CAAC;KAChC,CAAC;IACF,MAAM,CAAC,EAAE;QACP,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;YAAE,WAAW,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QACtD,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;KACxC,CAAC;IACF,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,aAAa,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC7D,QAAQ,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/C,cAAc,CAAC,EAAE;QACf,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,CAAC;CACH;AAMD,wBAAgB,gBAAgB,IAAI,MAAM,CAWzC;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAQpD;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAYnE;AAMD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,YAAY,CAuH9D;AAOD,wBAAgB,sBAAsB,IAAI,YAAY,CAgCrD"}

package/dist/src/config.js

@@ -0,0 +1,142 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { readFileSync } from "node:fs";
+function getDefaultDbPath() {
+  if (process.env.MNEMO_DB_PATH) return process.env.MNEMO_DB_PATH;
+  const mnemoPath = join(homedir(), ".mnemo", "memory-db");
+  const openclawPath = join(homedir(), ".openclaw", "memory", "lancedb-pro");
+  try {
+    const { existsSync } = require("fs");
+    if (existsSync(openclawPath)) return openclawPath;
+  } catch {
+  }
+  return mnemoPath;
+}
+function resolveEnvVars(value) {
+  return value.replace(/\$\{([^}]+)\}/g, (_, envVar) => {
+    const envValue = process.env[envVar];
+    if (!envValue) {
+      throw new Error(`Environment variable ${envVar} is not set`);
+    }
+    return envValue;
+  });
+}
+function parsePositiveInt(value) {
+  if (typeof value === "number" && Number.isFinite(value) && value > 0) {
+    return Math.floor(value);
+  }
+  if (typeof value === "string") {
+    const s = value.trim();
+    if (!s) return void 0;
+    const resolved = resolveEnvVars(s);
+    const n = Number(resolved);
+    if (Number.isFinite(n) && n > 0) return Math.floor(n);
+  }
+  return void 0;
+}
+function parsePluginConfig(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("mnemo config required");
+  }
+  const cfg = value;
+  const embedding = cfg.embedding;
+  if (!embedding) {
+    throw new Error("embedding config is required");
+  }
+  let apiKey;
+  if (typeof embedding.apiKey === "string") {
+    apiKey = embedding.apiKey;
+  } else if (Array.isArray(embedding.apiKey) && embedding.apiKey.length > 0) {
+    const invalid = embedding.apiKey.findIndex(
+      (k) => typeof k !== "string" || k.trim().length === 0
+    );
+    if (invalid !== -1) {
+      throw new Error(
+        `embedding.apiKey[${invalid}] is invalid: expected non-empty string`
+      );
+    }
+    apiKey = embedding.apiKey;
+  } else if (embedding.apiKey !== void 0) {
+    throw new Error("embedding.apiKey must be a string or non-empty array of strings");
+  } else {
+    apiKey = process.env.OPENAI_API_KEY || "";
+  }
+  if (!apiKey || Array.isArray(apiKey) && apiKey.length === 0) {
+    throw new Error("embedding.apiKey is required (set directly or via OPENAI_API_KEY env var)");
+  }
+  return {
+    embedding: {
+      provider: "openai-compatible",
+      apiKey,
+      model: typeof embedding.model === "string" ? embedding.model : "text-embedding-3-small",
+      baseURL: typeof embedding.baseURL === "string" ? resolveEnvVars(embedding.baseURL) : void 0,
+      dimensions: parsePositiveInt(embedding.dimensions ?? cfg.dimensions),
+      taskQuery: typeof embedding.taskQuery === "string" ? embedding.taskQuery : void 0,
+      taskPassage: typeof embedding.taskPassage === "string" ? embedding.taskPassage : void 0,
+      normalized: typeof embedding.normalized === "boolean" ? embedding.normalized : void 0
+    },
+    dbPath: typeof cfg.dbPath === "string" ? cfg.dbPath : void 0,
+    autoCapture: cfg.autoCapture !== false,
+    autoRecall: cfg.autoRecall === true,
+    autoRecallMinLength: parsePositiveInt(cfg.autoRecallMinLength),
+    autoRecallMinRepeated: parsePositiveInt(cfg.autoRecallMinRepeated),
+    captureAssistant: cfg.captureAssistant === true,
+    retrieval: typeof cfg.retrieval === "object" && cfg.retrieval !== null ? cfg.retrieval : void 0,
+    scopes: typeof cfg.scopes === "object" && cfg.scopes !== null ? cfg.scopes : void 0,
+    enableManagementTools: cfg.enableManagementTools === true,
+    sessionMemory: typeof cfg.sessionMemory === "object" && cfg.sessionMemory !== null ? {
+      enabled: cfg.sessionMemory.enabled !== false,
+      messageCount: typeof cfg.sessionMemory.messageCount === "number" ? cfg.sessionMemory.messageCount : void 0
+    } : void 0,
+    mdMirror: typeof cfg.mdMirror === "object" && cfg.mdMirror !== null ? {
+      enabled: cfg.mdMirror.enabled === true,
+      dir: typeof cfg.mdMirror.dir === "string" ? cfg.mdMirror.dir : void 0
+    } : void 0,
+    autoCaptureLLM: typeof cfg.autoCaptureLLM === "object" && cfg.autoCaptureLLM !== null ? {
+      enabled: cfg.autoCaptureLLM.enabled === true,
+      endpoint: typeof cfg.autoCaptureLLM.endpoint === "string" ? cfg.autoCaptureLLM.endpoint : void 0,
+      model: typeof cfg.autoCaptureLLM.model === "string" ? cfg.autoCaptureLLM.model : void 0,
+      timeoutMs: parsePositiveInt(
+        cfg.autoCaptureLLM.timeoutMs
+      )
+    } : void 0
+  };
+}
+function loadConfigFromOpenClaw() {
+  const { existsSync } = require("fs");
+  const envPath = process.env.MNEMO_CONFIG;
+  const mnemoPath = join(homedir(), ".mnemo", "mnemo.json");
+  const openclawPath = join(homedir(), ".openclaw", "openclaw.json");
+  const configPath = envPath || (existsSync(mnemoPath) ? mnemoPath : openclawPath);
+  let raw;
+  try {
+    raw = readFileSync(configPath, "utf8");
+  } catch (err) {
+    throw new Error(
+      `Failed to read ${configPath}: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+  let json;
+  try {
+    json = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(
+      `Failed to parse ${configPath}: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+  const pluginConfig = json?.plugins?.entries?.["memory-lancedb-pro"]?.config;
+  if (!pluginConfig) {
+    throw new Error(
+      `No config found at plugins.entries["memory-lancedb-pro"].config in ${configPath}`
+    );
+  }
+  return parsePluginConfig(pluginConfig);
+}
+export {
+  getDefaultDbPath,
+  loadConfigFromOpenClaw,
+  parsePluginConfig,
+  parsePositiveInt,
+  resolveEnvVars
+};
+//# sourceMappingURL=config.js.map

package/dist/src/config.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/config.ts"],
+  "sourcesContent": ["// SPDX-License-Identifier: MIT\n/**\n * Shared Configuration Helpers\n * Extracted from index.ts for reuse by MCP server and gateway plugin.\n */\n\nimport { homedir } from \"node:os\";\nimport { join } from \"node:path\";\nimport { readFileSync } from \"node:fs\";\n\n// ============================================================================\n// Configuration Types\n// ============================================================================\n\nexport interface PluginConfig {\n  embedding: {\n    provider: \"openai-compatible\";\n    apiKey: string | string[];\n    model?: string;\n    baseURL?: string;\n    dimensions?: number;\n    taskQuery?: string;\n    taskPassage?: string;\n    normalized?: boolean;\n  };\n  dbPath?: string;\n  autoCapture?: boolean;\n  autoRecall?: boolean;\n  autoRecallMinLength?: number;\n  autoRecallMinRepeated?: number;\n  captureAssistant?: boolean;\n  retrieval?: {\n    mode?: \"hybrid\" | \"vector\";\n    vectorWeight?: number;\n    bm25Weight?: number;\n    minScore?: number;\n    rerank?: \"cross-encoder\" | \"lightweight\" | \"none\";\n    candidatePoolSize?: number;\n    rerankApiKey?: string;\n    rerankModel?: string;\n    rerankEndpoint?: string;\n    rerankProvider?: \"jina\" | \"siliconflow\" | \"voyage\" | \"pinecone\";\n    recencyHalfLifeDays?: number;\n    recencyWeight?: number;\n    filterNoise?: boolean;\n    lengthNormAnchor?: number;\n    hardMinScore?: number;\n    timeDecayHalfLifeDays?: number;\n    reinforcementFactor?: number;\n    maxHalfLifeMultiplier?: number;\n  };\n  scopes?: {\n    default?: string;\n    definitions?: Record<string, { description: string }>;\n    agentAccess?: Record<string, string[]>;\n  };\n  enableManagementTools?: boolean;\n  sessionMemory?: { enabled?: boolean; messageCount?: number };\n  mdMirror?: { enabled?: boolean; dir?: string };\n  autoCaptureLLM?: {\n    enabled?: boolean;\n    endpoint?: string;\n    model?: string;\n    timeoutMs?: number;\n  };\n}\n\n// ============================================================================\n// Helpers\n// ============================================================================\n\nexport function getDefaultDbPath(): string {\n  // Prefer MNEMO_DB_PATH env, then ~/.mnemo/memory-db (open source default),\n  // then ~/.openclaw/memory/lancedb-pro (OpenClaw integration fallback)\n  if (process.env.MNEMO_DB_PATH) return process.env.MNEMO_DB_PATH;\n  const mnemoPath = join(homedir(), \".mnemo\", \"memory-db\");\n  const openclawPath = join(homedir(), \".openclaw\", \"memory\", \"lancedb-pro\");\n  try {\n    const { existsSync } = require(\"fs\");\n    if (existsSync(openclawPath)) return openclawPath;\n  } catch {}\n  return mnemoPath;\n}\n\nexport function resolveEnvVars(value: string): string {\n  return value.replace(/\\$\\{([^}]+)\\}/g, (_, envVar) => {\n    const envValue = process.env[envVar];\n    if (!envValue) {\n      throw new Error(`Environment variable ${envVar} is not set`);\n    }\n    return envValue;\n  });\n}\n\nexport function parsePositiveInt(value: unknown): number | undefined {\n  if (typeof value === \"number\" && Number.isFinite(value) && value > 0) {\n    return Math.floor(value);\n  }\n  if (typeof value === \"string\") {\n    const s = value.trim();\n    if (!s) return undefined;\n    const resolved = resolveEnvVars(s);\n    const n = Number(resolved);\n    if (Number.isFinite(n) && n > 0) return Math.floor(n);\n  }\n  return undefined;\n}\n\n// ============================================================================\n// Config Parser\n// ============================================================================\n\nexport function parsePluginConfig(value: unknown): PluginConfig {\n  if (!value || typeof value !== \"object\" || Array.isArray(value)) {\n    throw new Error(\"mnemo config required\");\n  }\n  const cfg = value as Record<string, unknown>;\n\n  const embedding = cfg.embedding as Record<string, unknown> | undefined;\n  if (!embedding) {\n    throw new Error(\"embedding config is required\");\n  }\n\n  // Accept single key (string) or array of keys for round-robin rotation\n  let apiKey: string | string[];\n  if (typeof embedding.apiKey === \"string\") {\n    apiKey = embedding.apiKey;\n  } else if (Array.isArray(embedding.apiKey) && embedding.apiKey.length > 0) {\n    const invalid = embedding.apiKey.findIndex(\n      (k: unknown) => typeof k !== \"string\" || (k as string).trim().length === 0,\n    );\n    if (invalid !== -1) {\n      throw new Error(\n        `embedding.apiKey[${invalid}] is invalid: expected non-empty string`,\n      );\n    }\n    apiKey = embedding.apiKey as string[];\n  } else if (embedding.apiKey !== undefined) {\n    throw new Error(\"embedding.apiKey must be a string or non-empty array of strings\");\n  } else {\n    apiKey = process.env.OPENAI_API_KEY || \"\";\n  }\n\n  if (!apiKey || (Array.isArray(apiKey) && apiKey.length === 0)) {\n    throw new Error(\"embedding.apiKey is required (set directly or via OPENAI_API_KEY env var)\");\n  }\n\n  return {\n    embedding: {\n      provider: \"openai-compatible\",\n      apiKey,\n      model:\n        typeof embedding.model === \"string\"\n          ? embedding.model\n          : \"text-embedding-3-small\",\n      baseURL:\n        typeof embedding.baseURL === \"string\"\n          ? resolveEnvVars(embedding.baseURL)\n          : undefined,\n      dimensions: parsePositiveInt(embedding.dimensions ?? cfg.dimensions),\n      taskQuery:\n        typeof embedding.taskQuery === \"string\"\n          ? embedding.taskQuery\n          : undefined,\n      taskPassage:\n        typeof embedding.taskPassage === \"string\"\n          ? embedding.taskPassage\n          : undefined,\n      normalized:\n        typeof embedding.normalized === \"boolean\"\n          ? embedding.normalized\n          : undefined,\n    },\n    dbPath: typeof cfg.dbPath === \"string\" ? cfg.dbPath : undefined,\n    autoCapture: cfg.autoCapture !== false,\n    autoRecall: cfg.autoRecall === true,\n    autoRecallMinLength: parsePositiveInt(cfg.autoRecallMinLength),\n    autoRecallMinRepeated: parsePositiveInt(cfg.autoRecallMinRepeated),\n    captureAssistant: cfg.captureAssistant === true,\n    retrieval:\n      typeof cfg.retrieval === \"object\" && cfg.retrieval !== null\n        ? (cfg.retrieval as any)\n        : undefined,\n    scopes:\n      typeof cfg.scopes === \"object\" && cfg.scopes !== null\n        ? (cfg.scopes as any)\n        : undefined,\n    enableManagementTools: cfg.enableManagementTools === true,\n    sessionMemory:\n      typeof cfg.sessionMemory === \"object\" && cfg.sessionMemory !== null\n        ? {\n            enabled:\n              (cfg.sessionMemory as Record<string, unknown>).enabled !== false,\n            messageCount:\n              typeof (cfg.sessionMemory as Record<string, unknown>)\n                .messageCount === \"number\"\n                ? ((cfg.sessionMemory as Record<string, unknown>)\n                    .messageCount as number)\n                : undefined,\n          }\n        : undefined,\n    mdMirror:\n      typeof cfg.mdMirror === \"object\" && cfg.mdMirror !== null\n        ? {\n            enabled:\n              (cfg.mdMirror as Record<string, unknown>).enabled === true,\n            dir:\n              typeof (cfg.mdMirror as Record<string, unknown>).dir === \"string\"\n                ? ((cfg.mdMirror as Record<string, unknown>).dir as string)\n                : undefined,\n          }\n        : undefined,\n    autoCaptureLLM:\n      typeof cfg.autoCaptureLLM === \"object\" && cfg.autoCaptureLLM !== null\n        ? {\n            enabled:\n              (cfg.autoCaptureLLM as Record<string, unknown>).enabled === true,\n            endpoint:\n              typeof (cfg.autoCaptureLLM as Record<string, unknown>).endpoint === \"string\"\n                ? ((cfg.autoCaptureLLM as Record<string, unknown>).endpoint as string)\n                : undefined,\n            model:\n              typeof (cfg.autoCaptureLLM as Record<string, unknown>).model === \"string\"\n                ? ((cfg.autoCaptureLLM as Record<string, unknown>).model as string)\n                : undefined,\n            timeoutMs: parsePositiveInt(\n              (cfg.autoCaptureLLM as Record<string, unknown>).timeoutMs,\n            ),\n          }\n        : undefined,\n  };\n}\n\n// ============================================================================\n// Load config from config file\n// Checks: MNEMO_CONFIG env \u2192 ~/.mnemo/mnemo.json \u2192 ~/.openclaw/openclaw.json\n// ============================================================================\n\nexport function loadConfigFromOpenClaw(): PluginConfig {\n  const { existsSync } = require(\"fs\");\n  const envPath = process.env.MNEMO_CONFIG;\n  const mnemoPath = join(homedir(), \".mnemo\", \"mnemo.json\");\n  const openclawPath = join(homedir(), \".openclaw\", \"openclaw.json\");\n  const configPath = envPath || (existsSync(mnemoPath) ? mnemoPath : openclawPath);\n  let raw: string;\n  try {\n    raw = readFileSync(configPath, \"utf8\");\n  } catch (err) {\n    throw new Error(\n      `Failed to read ${configPath}: ${err instanceof Error ? err.message : String(err)}`,\n    );\n  }\n\n  let json: any;\n  try {\n    json = JSON.parse(raw);\n  } catch (err) {\n    throw new Error(\n      `Failed to parse ${configPath}: ${err instanceof Error ? err.message : String(err)}`,\n    );\n  }\n\n  const pluginConfig = json?.plugins?.entries?.[\"memory-lancedb-pro\"]?.config;\n  if (!pluginConfig) {\n    throw new Error(\n      `No config found at plugins.entries[\"memory-lancedb-pro\"].config in ${configPath}`,\n    );\n  }\n\n  return parsePluginConfig(pluginConfig);\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/src/decay-engine.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Decay Engine — Weibull stretched-exponential decay model
+ *
+ * Composite score = recencyWeight * recency + frequencyWeight * frequency + intrinsicWeight * intrinsic
+ *
+ * - Recency: Weibull decay with importance-modulated half-life and tier-specific beta
+ * - Frequency: Logarithmic saturation with time-weighted access pattern bonus
+ * - Intrinsic: importance × confidence
+ */
+import type { MemoryTier } from "./memory-categories.js";
+export interface DecayConfig {
+    /** Days until recency score halves (default: 30) */
+    recencyHalfLifeDays: number;
+    /** Weight of recency in composite (default: 0.4) */
+    recencyWeight: number;
+    /** Weight of access frequency (default: 0.3) */
+    frequencyWeight: number;
+    /** Weight of importance × confidence (default: 0.3) */
+    intrinsicWeight: number;
+    /** Below this composite = stale (default: 0.3) */
+    staleThreshold: number;
+    /** Minimum search boost (default: 0.3) */
+    searchBoostMin: number;
+    /** Importance modulation coefficient for half-life (default: 1.5) */
+    importanceModulation: number;
+    /** Weibull beta for Core tier — sub-exponential (default: 0.8) */
+    betaCore: number;
+    /** Weibull beta for Working tier — standard exponential (default: 1.0) */
+    betaWorking: number;
+    /** Weibull beta for Peripheral tier — super-exponential (default: 1.3) */
+    betaPeripheral: number;
+    /** Decay floor for Core memories (default: 0.9) */
+    coreDecayFloor: number;
+    /** Decay floor for Working memories (default: 0.7) */
+    workingDecayFloor: number;
+    /** Decay floor for Peripheral memories (default: 0.5) */
+    peripheralDecayFloor: number;
+}
+export declare const DEFAULT_DECAY_CONFIG: DecayConfig;
+export interface DecayScore {
+    memoryId: string;
+    recency: number;
+    frequency: number;
+    intrinsic: number;
+    composite: number;
+}
+/** Minimal memory fields needed for decay calculation. */
+export interface DecayableMemory {
+    id: string;
+    importance: number;
+    confidence: number;
+    tier: MemoryTier;
+    accessCount: number;
+    createdAt: number;
+    lastAccessedAt: number;
+    /** Emotional salience (0-1). Modulates decay: high salience = slower decay. */
+    emotionalSalience: number;
+}
+export interface DecayEngine {
+    /** Calculate decay score for a single memory */
+    score(memory: DecayableMemory, now?: number): DecayScore;
+    /** Calculate decay scores for multiple memories */
+    scoreAll(memories: DecayableMemory[], now?: number): DecayScore[];
+    /** Apply decay boost to search results (multiplies each score by boost) */
+    applySearchBoost(results: Array<{
+        memory: DecayableMemory;
+        score: number;
+    }>, now?: number): void;
+    /** Find stale memories (composite below threshold) */
+    getStaleMemories(memories: DecayableMemory[], now?: number): DecayScore[];
+}
+export declare function createDecayEngine(config?: DecayConfig): DecayEngine;
+//# sourceMappingURL=decay-engine.d.ts.map

package/dist/src/decay-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decay-engine.d.ts","sourceRoot":"","sources":["../../src/decay-engine.ts"],"names":[],"mappings":"AACA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAQzD,MAAM,WAAW,WAAW;IAC1B,oDAAoD;IACpD,mBAAmB,EAAE,MAAM,CAAC;IAC5B,oDAAoD;IACpD,aAAa,EAAE,MAAM,CAAC;IACtB,gDAAgD;IAChD,eAAe,EAAE,MAAM,CAAC;IACxB,uDAAuD;IACvD,eAAe,EAAE,MAAM,CAAC;IACxB,kDAAkD;IAClD,cAAc,EAAE,MAAM,CAAC;IACvB,0CAA0C;IAC1C,cAAc,EAAE,MAAM,CAAC;IACvB,qEAAqE;IACrE,oBAAoB,EAAE,MAAM,CAAC;IAC7B,kEAAkE;IAClE,QAAQ,EAAE,MAAM,CAAC;IACjB,0EAA0E;IAC1E,WAAW,EAAE,MAAM,CAAC;IACpB,0EAA0E;IAC1E,cAAc,EAAE,MAAM,CAAC;IACvB,mDAAmD;IACnD,cAAc,EAAE,MAAM,CAAC;IACvB,sDAAsD;IACtD,iBAAiB,EAAE,MAAM,CAAC;IAC1B,yDAAyD;IACzD,oBAAoB,EAAE,MAAM,CAAC;CAC9B;AAGD,eAAO,MAAM,oBAAoB,EAAE,WAclC,CAAC;AAEF,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,0DAA0D;AAC1D,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,UAAU,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,+EAA+E;IAC/E,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,WAAW;IAC1B,gDAAgD;IAChD,KAAK,CAAC,MAAM,EAAE,eAAe,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,UAAU,CAAC;IACzD,mDAAmD;IACnD,QAAQ,CAAC,QAAQ,EAAE,eAAe,EAAE,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,UAAU,EAAE,CAAC;IAClE,2EAA2E;IAC3E,gBAAgB,CACd,OAAO,EAAE,KAAK,CAAC;QAAE,MAAM,EAAE,eAAe,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,EAC1D,GAAG,CAAC,EAAE,MAAM,GACX,IAAI,CAAC;IACR,sDAAsD;IACtD,gBAAgB,CACd,QAAQ,EAAE,eAAe,EAAE,EAC3B,GAAG,CAAC,EAAE,MAAM,GACX,UAAU,EAAE,CAAC;CACjB;AAMD,wBAAgB,iBAAiB,CAC/B,MAAM,GAAE,WAAkC,GACzC,WAAW,CAgIb"}

package/dist/src/decay-engine.js

@@ -0,0 +1,119 @@
+const MS_PER_DAY = 864e5;
+const DEFAULT_DECAY_CONFIG = {
+  recencyHalfLifeDays: 30,
+  recencyWeight: 0.4,
+  // initial — pending optimization
+  frequencyWeight: 0.3,
+  // initial — pending optimization
+  intrinsicWeight: 0.3,
+  // initial — pending optimization
+  staleThreshold: 0.3,
+  searchBoostMin: 0.3,
+  importanceModulation: 1.5,
+  betaCore: 0.8,
+  betaWorking: 1,
+  betaPeripheral: 1.3,
+  coreDecayFloor: 0.9,
+  workingDecayFloor: 0.7,
+  peripheralDecayFloor: 0.5
+};
+function createDecayEngine(config = DEFAULT_DECAY_CONFIG) {
+  const {
+    recencyHalfLifeDays: halfLife,
+    recencyWeight: rw,
+    frequencyWeight: fw,
+    intrinsicWeight: iw,
+    staleThreshold,
+    searchBoostMin: boostMin,
+    importanceModulation: mu,
+    betaCore,
+    betaWorking,
+    betaPeripheral,
+    coreDecayFloor,
+    workingDecayFloor,
+    peripheralDecayFloor
+  } = config;
+  function getTierBeta(tier) {
+    switch (tier) {
+      case "core":
+        return betaCore;
+      case "working":
+        return betaWorking;
+      case "peripheral":
+        return betaPeripheral;
+    }
+  }
+  function getTierFloor(tier) {
+    switch (tier) {
+      case "core":
+        return coreDecayFloor;
+      case "working":
+        return workingDecayFloor;
+      case "peripheral":
+        return peripheralDecayFloor;
+    }
+  }
+  function recency(memory, now) {
+    const lastActive = memory.accessCount > 0 ? memory.lastAccessedAt : memory.createdAt;
+    const daysSince = Math.max(0, (now - lastActive) / MS_PER_DAY);
+    const salience = memory.emotionalSalience ?? 0.3;
+    const effectiveHL = halfLife * Math.exp(mu * memory.importance) * (1 + salience * 0.5);
+    const lambda = Math.LN2 / effectiveHL;
+    const beta = getTierBeta(memory.tier);
+    return Math.exp(-lambda * Math.pow(daysSince, beta));
+  }
+  function frequency(memory) {
+    const base = 1 - Math.exp(-memory.accessCount / 5);
+    if (memory.accessCount <= 1) return base;
+    const lastActive = memory.accessCount > 0 ? memory.lastAccessedAt : memory.createdAt;
+    const accessSpanDays = Math.max(
+      1,
+      (lastActive - memory.createdAt) / MS_PER_DAY
+    );
+    const avgGapDays = accessSpanDays / Math.max(memory.accessCount - 1, 1);
+    const recentnessBonus = Math.exp(-avgGapDays / 30);
+    return base * (0.5 + 0.5 * recentnessBonus);
+  }
+  function intrinsic(memory) {
+    const salience = memory.emotionalSalience ?? 0.3;
+    return memory.importance * memory.confidence * (1 + salience * 0.3);
+  }
+  function scoreOne(memory, now) {
+    const r = recency(memory, now);
+    const f = frequency(memory);
+    const i = intrinsic(memory);
+    const composite = rw * r + fw * f + iw * i;
+    return {
+      memoryId: memory.id,
+      recency: r,
+      frequency: f,
+      intrinsic: i,
+      composite
+    };
+  }
+  return {
+    score(memory, now = Date.now()) {
+      return scoreOne(memory, now);
+    },
+    scoreAll(memories, now = Date.now()) {
+      return memories.map((m) => scoreOne(m, now));
+    },
+    applySearchBoost(results, now = Date.now()) {
+      for (const r of results) {
+        const ds = scoreOne(r.memory, now);
+        const tierFloor = Math.max(getTierFloor(r.memory.tier), ds.composite);
+        const multiplier = boostMin + (1 - boostMin) * tierFloor;
+        r.score *= Math.min(1, Math.max(boostMin, multiplier));
+      }
+    },
+    getStaleMemories(memories, now = Date.now()) {
+      const scores = memories.map((m) => scoreOne(m, now));
+      return scores.filter((s) => s.composite < staleThreshold).sort((a, b) => a.composite - b.composite);
+    }
+  };
+}
+export {
+  DEFAULT_DECAY_CONFIG,
+  createDecayEngine
+};
+//# sourceMappingURL=decay-engine.js.map