@mnemoai/core 1.1.0 → 1.1.1

package/dist/src/decay-engine.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/decay-engine.ts"],
+  "sourcesContent": ["// SPDX-License-Identifier: MIT\n/**\n * Decay Engine \u2014 Weibull stretched-exponential decay model\n *\n * Composite score = recencyWeight * recency + frequencyWeight * frequency + intrinsicWeight * intrinsic\n *\n * - Recency: Weibull decay with importance-modulated half-life and tier-specific beta\n * - Frequency: Logarithmic saturation with time-weighted access pattern bonus\n * - Intrinsic: importance \u00D7 confidence\n */\n\nimport type { MemoryTier } from \"./memory-categories.js\";\n\n// ============================================================================\n// Types\n// ============================================================================\n\nconst MS_PER_DAY = 86_400_000;\n\nexport interface DecayConfig {\n  /** Days until recency score halves (default: 30) */\n  recencyHalfLifeDays: number;\n  /** Weight of recency in composite (default: 0.4) */\n  recencyWeight: number;\n  /** Weight of access frequency (default: 0.3) */\n  frequencyWeight: number;\n  /** Weight of importance \u00D7 confidence (default: 0.3) */\n  intrinsicWeight: number;\n  /** Below this composite = stale (default: 0.3) */\n  staleThreshold: number;\n  /** Minimum search boost (default: 0.3) */\n  searchBoostMin: number;\n  /** Importance modulation coefficient for half-life (default: 1.5) */\n  importanceModulation: number;\n  /** Weibull beta for Core tier \u2014 sub-exponential (default: 0.8) */\n  betaCore: number;\n  /** Weibull beta for Working tier \u2014 standard exponential (default: 1.0) */\n  betaWorking: number;\n  /** Weibull beta for Peripheral tier \u2014 super-exponential (default: 1.3) */\n  betaPeripheral: number;\n  /** Decay floor for Core memories (default: 0.9) */\n  coreDecayFloor: number;\n  /** Decay floor for Working memories (default: 0.7) */\n  workingDecayFloor: number;\n  /** Decay floor for Peripheral memories (default: 0.5) */\n  peripheralDecayFloor: number;\n}\n\n// NOTE: These weights are initial values pending grid-search optimization.\nexport const DEFAULT_DECAY_CONFIG: DecayConfig = {\n  recencyHalfLifeDays: 30,\n  recencyWeight: 0.4,       // initial \u2014 pending optimization\n  frequencyWeight: 0.3,     // initial \u2014 pending optimization\n  intrinsicWeight: 0.3,     // initial \u2014 pending optimization\n  staleThreshold: 0.3,\n  searchBoostMin: 0.3,\n  importanceModulation: 1.5,\n  betaCore: 0.8,\n  betaWorking: 1.0,\n  betaPeripheral: 1.3,\n  coreDecayFloor: 0.9,\n  workingDecayFloor: 0.7,\n  peripheralDecayFloor: 0.5,\n};\n\nexport interface DecayScore {\n  memoryId: string;\n  recency: number;\n  frequency: number;\n  intrinsic: number;\n  composite: number;\n}\n\n/** Minimal memory fields needed for decay calculation. */\nexport interface DecayableMemory {\n  id: string;\n  importance: number;\n  confidence: number;\n  tier: MemoryTier;\n  accessCount: number;\n  createdAt: number;\n  lastAccessedAt: number;\n  /** Emotional salience (0-1). Modulates decay: high salience = slower decay. */\n  emotionalSalience: number;\n}\n\nexport interface DecayEngine {\n  /** Calculate decay score for a single memory */\n  score(memory: DecayableMemory, now?: number): DecayScore;\n  /** Calculate decay scores for multiple memories */\n  scoreAll(memories: DecayableMemory[], now?: number): DecayScore[];\n  /** Apply decay boost to search results (multiplies each score by boost) */\n  applySearchBoost(\n    results: Array<{ memory: DecayableMemory; score: number }>,\n    now?: number,\n  ): void;\n  /** Find stale memories (composite below threshold) */\n  getStaleMemories(\n    memories: DecayableMemory[],\n    now?: number,\n  ): DecayScore[];\n}\n\n// ============================================================================\n// Factory\n// ============================================================================\n\nexport function createDecayEngine(\n  config: DecayConfig = DEFAULT_DECAY_CONFIG,\n): DecayEngine {\n  const {\n    recencyHalfLifeDays: halfLife,\n    recencyWeight: rw,\n    frequencyWeight: fw,\n    intrinsicWeight: iw,\n    staleThreshold,\n    searchBoostMin: boostMin,\n    importanceModulation: mu,\n    betaCore,\n    betaWorking,\n    betaPeripheral,\n    coreDecayFloor,\n    workingDecayFloor,\n    peripheralDecayFloor,\n  } = config;\n\n  function getTierBeta(tier: MemoryTier): number {\n    switch (tier) {\n      case \"core\":\n        return betaCore;\n      case \"working\":\n        return betaWorking;\n      case \"peripheral\":\n        return betaPeripheral;\n    }\n  }\n\n  function getTierFloor(tier: MemoryTier): number {\n    switch (tier) {\n      case \"core\":\n        return coreDecayFloor;\n      case \"working\":\n        return workingDecayFloor;\n      case \"peripheral\":\n        return peripheralDecayFloor;\n    }\n  }\n\n  /**\n   * Recency: Weibull stretched-exponential decay with importance + salience modulated half-life.\n   * effectiveHL = halfLife * exp(mu * importance) * (1 + salience * 0.5)\n   *\n   * Salience effect: a memory with salience=1.0 gets 1.5x the half-life.\n   * This models the human brain's amygdala tagging: emotionally charged\n   * memories decay slower regardless of their \"importance\" category.\n   */\n  function recency(memory: DecayableMemory, now: number): number {\n    const lastActive =\n      memory.accessCount > 0 ? memory.lastAccessedAt : memory.createdAt;\n    const daysSince = Math.max(0, (now - lastActive) / MS_PER_DAY);\n    const salience = memory.emotionalSalience ?? 0.3;\n    const effectiveHL = halfLife * Math.exp(mu * memory.importance) * (1 + salience * 0.5);\n    const lambda = Math.LN2 / effectiveHL;\n    const beta = getTierBeta(memory.tier);\n    return Math.exp(-lambda * Math.pow(daysSince, beta));\n  }\n\n  /**\n   * Frequency: logarithmic saturation curve with time-weighted access pattern bonus.\n   * base = 1 - exp(-accessCount / 5)\n   * For memories with >1 access, a recentness bonus is applied.\n   */\n  function frequency(memory: DecayableMemory): number {\n    const base = 1 - Math.exp(-memory.accessCount / 5);\n    if (memory.accessCount <= 1) return base;\n\n    const lastActive =\n      memory.accessCount > 0 ? memory.lastAccessedAt : memory.createdAt;\n    const accessSpanDays = Math.max(\n      1,\n      (lastActive - memory.createdAt) / MS_PER_DAY,\n    );\n    const avgGapDays = accessSpanDays / Math.max(memory.accessCount - 1, 1);\n    const recentnessBonus = Math.exp(-avgGapDays / 30);\n    return base * (0.5 + 0.5 * recentnessBonus);\n  }\n\n  /**\n   * Intrinsic value: importance \u00D7 confidence \u00D7 (1 + salience * 0.3).\n   * Salience gives a mild intrinsic boost \u2014 emotionally significant memories\n   * are inherently more valuable even if importance score is moderate.\n   */\n  function intrinsic(memory: DecayableMemory): number {\n    const salience = memory.emotionalSalience ?? 0.3;\n    return memory.importance * memory.confidence * (1 + salience * 0.3);\n  }\n\n  function scoreOne(memory: DecayableMemory, now: number): DecayScore {\n    const r = recency(memory, now);\n    const f = frequency(memory);\n    const i = intrinsic(memory);\n    const composite = rw * r + fw * f + iw * i;\n\n    return {\n      memoryId: memory.id,\n      recency: r,\n      frequency: f,\n      intrinsic: i,\n      composite,\n    };\n  }\n\n  return {\n    score(memory, now = Date.now()) {\n      return scoreOne(memory, now);\n    },\n\n    scoreAll(memories, now = Date.now()) {\n      return memories.map((m) => scoreOne(m, now));\n    },\n\n    applySearchBoost(results, now = Date.now()) {\n      for (const r of results) {\n        const ds = scoreOne(r.memory, now);\n        const tierFloor = Math.max(getTierFloor(r.memory.tier), ds.composite);\n        const multiplier = boostMin + ((1 - boostMin) * tierFloor);\n        r.score *= Math.min(1, Math.max(boostMin, multiplier));\n      }\n    },\n\n    getStaleMemories(memories, now = Date.now()) {\n      const scores = memories.map((m) => scoreOne(m, now));\n      return scores\n        .filter((s) => s.composite < staleThreshold)\n        .sort((a, b) => a.composite - b.composite);\n    },\n  };\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/src/embedder.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Embedding Abstraction Layer
+ * OpenAI-compatible API for various embedding providers.
+ * Supports automatic chunking for documents exceeding embedding context limits.
+ *
+ * Note: Some providers (e.g. Jina) support extra parameters like `task` and
+ * `normalized` on the embeddings endpoint. The OpenAI SDK types do not include
+ * these fields, so we pass them via a narrow `any` cast.
+ */
+export interface EmbeddingConfig {
+    provider: "openai-compatible";
+    /** Single API key or array of keys for round-robin rotation with failover. */
+    apiKey: string | string[];
+    model: string;
+    baseURL?: string;
+    dimensions?: number;
+    /** Optional task type for query embeddings (e.g. "retrieval.query") */
+    taskQuery?: string;
+    /** Optional task type for passage/document embeddings (e.g. "retrieval.passage") */
+    taskPassage?: string;
+    /** Optional flag to request normalized embeddings (provider-dependent, e.g. Jina v5) */
+    normalized?: boolean;
+    /** Enable automatic chunking for documents exceeding context limits (default: true) */
+    chunking?: boolean;
+}
+export declare function formatEmbeddingProviderError(error: unknown, opts: {
+    baseURL?: string;
+    model: string;
+    mode?: "single" | "batch";
+}): string;
+export declare function getVectorDimensions(model: string, overrideDims?: number): number;
+export declare class Embedder {
+    /** Pool of OpenAI clients — one per API key for round-robin rotation. */
+    private clients;
+    /** Round-robin index for client rotation. */
+    private _clientIndex;
+    readonly dimensions: number;
+    private readonly _cache;
+    private readonly _model;
+    private readonly _baseURL?;
+    private readonly _taskQuery?;
+    private readonly _taskPassage?;
+    private readonly _normalized?;
+    /** Optional requested dimensions to pass through to the embedding provider (OpenAI-compatible). */
+    private readonly _requestDimensions?;
+    /** Enable automatic chunking for long documents (default: true) */
+    private readonly _autoChunk;
+    constructor(config: EmbeddingConfig & {
+        chunking?: boolean;
+    });
+    /** Return the next client in round-robin order. */
+    private nextClient;
+    /** Check whether an error is a rate-limit / quota-exceeded / overload error. */
+    private isRateLimitError;
+    /**
+     * Call embeddings.create with automatic key rotation on rate-limit errors.
+     * Tries each key in the pool at most once before giving up.
+     */
+    private embedWithRetry;
+    /** Number of API keys in the rotation pool. */
+    get keyCount(): number;
+    /**
+     * Backward-compatible embedding API.
+     *
+     * Historically the plugin used a single `embed()` method for both query and
+     * passage embeddings. With task-aware providers we treat this as passage.
+     */
+    embed(text: string): Promise<number[]>;
+    /** Backward-compatible batch embedding API (treated as passage). */
+    embedBatch(texts: string[]): Promise<number[][]>;
+    embedQuery(text: string): Promise<number[]>;
+    embedPassage(text: string): Promise<number[]>;
+    embedBatchQuery(texts: string[]): Promise<number[][]>;
+    embedBatchPassage(texts: string[]): Promise<number[][]>;
+    private validateEmbedding;
+    private buildPayload;
+    private embedSingle;
+    private embedMany;
+    get model(): string;
+    test(): Promise<{
+        success: boolean;
+        error?: string;
+        dimensions?: number;
+    }>;
+    get cacheStats(): {
+        keyCount: number;
+        size: number;
+        hits: number;
+        misses: number;
+        hitRate: string;
+    };
+}
+export declare function createEmbedder(config: EmbeddingConfig): Embedder;
+//# sourceMappingURL=embedder.d.ts.map

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

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