@mnemoai/core 1.1.0 → 1.1.1

package/src/config.ts

@@ -1,271 +0,0 @@
-// SPDX-License-Identifier: MIT
-/**
- * Shared Configuration Helpers
- * Extracted from index.ts for reuse by MCP server and gateway plugin.
- */
-
-import { homedir } from "node:os";
-import { join } from "node:path";
-import { readFileSync } from "node:fs";
-
-// ============================================================================
-// Configuration Types
-// ============================================================================
-
-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;
-  };
-}
-
-// ============================================================================
-// Helpers
-// ============================================================================
-
-export function getDefaultDbPath(): string {
-  // Prefer MNEMO_DB_PATH env, then ~/.mnemo/memory-db (open source default),
-  // then ~/.openclaw/memory/lancedb-pro (OpenClaw integration fallback)
-  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;
-}
-
-export function resolveEnvVars(value: string): string {
-  return value.replace(/\$\{([^}]+)\}/g, (_, envVar) => {
-    const envValue = process.env[envVar];
-    if (!envValue) {
-      throw new Error(`Environment variable ${envVar} is not set`);
-    }
-    return envValue;
-  });
-}
-
-export function parsePositiveInt(value: unknown): number | undefined {
-  if (typeof value === "number" && Number.isFinite(value) && value > 0) {
-    return Math.floor(value);
-  }
-  if (typeof value === "string") {
-    const s = value.trim();
-    if (!s) return undefined;
-    const resolved = resolveEnvVars(s);
-    const n = Number(resolved);
-    if (Number.isFinite(n) && n > 0) return Math.floor(n);
-  }
-  return undefined;
-}
-
-// ============================================================================
-// Config Parser
-// ============================================================================
-
-export function parsePluginConfig(value: unknown): PluginConfig {
-  if (!value || typeof value !== "object" || Array.isArray(value)) {
-    throw new Error("mnemo config required");
-  }
-  const cfg = value as Record<string, unknown>;
-
-  const embedding = cfg.embedding as Record<string, unknown> | undefined;
-  if (!embedding) {
-    throw new Error("embedding config is required");
-  }
-
-  // Accept single key (string) or array of keys for round-robin rotation
-  let apiKey: string | string[];
-  if (typeof embedding.apiKey === "string") {
-    apiKey = embedding.apiKey;
-  } else if (Array.isArray(embedding.apiKey) && embedding.apiKey.length > 0) {
-    const invalid = embedding.apiKey.findIndex(
-      (k: unknown) => typeof k !== "string" || (k as string).trim().length === 0,
-    );
-    if (invalid !== -1) {
-      throw new Error(
-        `embedding.apiKey[${invalid}] is invalid: expected non-empty string`,
-      );
-    }
-    apiKey = embedding.apiKey as string[];
-  } else if (embedding.apiKey !== undefined) {
-    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)
-          : undefined,
-      dimensions: parsePositiveInt(embedding.dimensions ?? cfg.dimensions),
-      taskQuery:
-        typeof embedding.taskQuery === "string"
-          ? embedding.taskQuery
-          : undefined,
-      taskPassage:
-        typeof embedding.taskPassage === "string"
-          ? embedding.taskPassage
-          : undefined,
-      normalized:
-        typeof embedding.normalized === "boolean"
-          ? embedding.normalized
-          : undefined,
-    },
-    dbPath: typeof cfg.dbPath === "string" ? cfg.dbPath : undefined,
-    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 as any)
-        : undefined,
-    scopes:
-      typeof cfg.scopes === "object" && cfg.scopes !== null
-        ? (cfg.scopes as any)
-        : undefined,
-    enableManagementTools: cfg.enableManagementTools === true,
-    sessionMemory:
-      typeof cfg.sessionMemory === "object" && cfg.sessionMemory !== null
-        ? {
-            enabled:
-              (cfg.sessionMemory as Record<string, unknown>).enabled !== false,
-            messageCount:
-              typeof (cfg.sessionMemory as Record<string, unknown>)
-                .messageCount === "number"
-                ? ((cfg.sessionMemory as Record<string, unknown>)
-                    .messageCount as number)
-                : undefined,
-          }
-        : undefined,
-    mdMirror:
-      typeof cfg.mdMirror === "object" && cfg.mdMirror !== null
-        ? {
-            enabled:
-              (cfg.mdMirror as Record<string, unknown>).enabled === true,
-            dir:
-              typeof (cfg.mdMirror as Record<string, unknown>).dir === "string"
-                ? ((cfg.mdMirror as Record<string, unknown>).dir as string)
-                : undefined,
-          }
-        : undefined,
-    autoCaptureLLM:
-      typeof cfg.autoCaptureLLM === "object" && cfg.autoCaptureLLM !== null
-        ? {
-            enabled:
-              (cfg.autoCaptureLLM as Record<string, unknown>).enabled === true,
-            endpoint:
-              typeof (cfg.autoCaptureLLM as Record<string, unknown>).endpoint === "string"
-                ? ((cfg.autoCaptureLLM as Record<string, unknown>).endpoint as string)
-                : undefined,
-            model:
-              typeof (cfg.autoCaptureLLM as Record<string, unknown>).model === "string"
-                ? ((cfg.autoCaptureLLM as Record<string, unknown>).model as string)
-                : undefined,
-            timeoutMs: parsePositiveInt(
-              (cfg.autoCaptureLLM as Record<string, unknown>).timeoutMs,
-            ),
-          }
-        : undefined,
-  };
-}
-
-// ============================================================================
-// Load config from config file
-// Checks: MNEMO_CONFIG env → ~/.mnemo/mnemo.json → ~/.openclaw/openclaw.json
-// ============================================================================
-
-export function loadConfigFromOpenClaw(): PluginConfig {
-  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: string;
-  try {
-    raw = readFileSync(configPath, "utf8");
-  } catch (err) {
-    throw new Error(
-      `Failed to read ${configPath}: ${err instanceof Error ? err.message : String(err)}`,
-    );
-  }
-
-  let json: any;
-  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);
-}

package/src/decay-engine.ts

@@ -1,238 +0,0 @@
-// SPDX-License-Identifier: MIT
-/**
- * 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";
-
-// ============================================================================
-// Types
-// ============================================================================
-
-const MS_PER_DAY = 86_400_000;
-
-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;
-}
-
-// NOTE: These weights are initial values pending grid-search optimization.
-export const DEFAULT_DECAY_CONFIG: DecayConfig = {
-  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.0,
-  betaPeripheral: 1.3,
-  coreDecayFloor: 0.9,
-  workingDecayFloor: 0.7,
-  peripheralDecayFloor: 0.5,
-};
-
-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[];
-}
-
-// ============================================================================
-// Factory
-// ============================================================================
-
-export function createDecayEngine(
-  config: DecayConfig = DEFAULT_DECAY_CONFIG,
-): DecayEngine {
-  const {
-    recencyHalfLifeDays: halfLife,
-    recencyWeight: rw,
-    frequencyWeight: fw,
-    intrinsicWeight: iw,
-    staleThreshold,
-    searchBoostMin: boostMin,
-    importanceModulation: mu,
-    betaCore,
-    betaWorking,
-    betaPeripheral,
-    coreDecayFloor,
-    workingDecayFloor,
-    peripheralDecayFloor,
-  } = config;
-
-  function getTierBeta(tier: MemoryTier): number {
-    switch (tier) {
-      case "core":
-        return betaCore;
-      case "working":
-        return betaWorking;
-      case "peripheral":
-        return betaPeripheral;
-    }
-  }
-
-  function getTierFloor(tier: MemoryTier): number {
-    switch (tier) {
-      case "core":
-        return coreDecayFloor;
-      case "working":
-        return workingDecayFloor;
-      case "peripheral":
-        return peripheralDecayFloor;
-    }
-  }
-
-  /**
-   * Recency: Weibull stretched-exponential decay with importance + salience modulated half-life.
-   * effectiveHL = halfLife * exp(mu * importance) * (1 + salience * 0.5)
-   *
-   * Salience effect: a memory with salience=1.0 gets 1.5x the half-life.
-   * This models the human brain's amygdala tagging: emotionally charged
-   * memories decay slower regardless of their "importance" category.
-   */
-  function recency(memory: DecayableMemory, now: number): number {
-    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));
-  }
-
-  /**
-   * Frequency: logarithmic saturation curve with time-weighted access pattern bonus.
-   * base = 1 - exp(-accessCount / 5)
-   * For memories with >1 access, a recentness bonus is applied.
-   */
-  function frequency(memory: DecayableMemory): number {
-    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);
-  }
-
-  /**
-   * Intrinsic value: importance × confidence × (1 + salience * 0.3).
-   * Salience gives a mild intrinsic boost — emotionally significant memories
-   * are inherently more valuable even if importance score is moderate.
-   */
-  function intrinsic(memory: DecayableMemory): number {
-    const salience = memory.emotionalSalience ?? 0.3;
-    return memory.importance * memory.confidence * (1 + salience * 0.3);
-  }
-
-  function scoreOne(memory: DecayableMemory, now: number): DecayScore {
-    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);
-    },
-  };
-}