recallnest 1.4.1 → 2.2.0

package/src/llm-client.ts

@@ -14,6 +14,89 @@
  */
 
 import OpenAI from "openai";
+import { logInfo } from "./stderr-log.js";
+import { isEmotionScoringEnabled } from "./memory-schema.js";
+
+// ============================================================================
+// LME-9: Circuit Breaker — LLM 降级策略
+// ============================================================================
+
+type CircuitState = "closed" | "open" | "half-open";
+
+export interface CircuitBreakerConfig {
+  /** Consecutive failures before opening the circuit (default: 3) */
+  failureThreshold: number;
+  /** Cooldown in ms before trying again (default: 30_000 = 30s) */
+  cooldownMs: number;
+}
+
+const DEFAULT_BREAKER_CONFIG: CircuitBreakerConfig = {
+  failureThreshold: 3,
+  cooldownMs: 30_000,
+};
+
+export class CircuitBreaker {
+  private state: CircuitState = "closed";
+  private consecutiveFailures = 0;
+  private openedAt = 0;
+  private readonly config: CircuitBreakerConfig;
+
+  constructor(config?: Partial<CircuitBreakerConfig>) {
+    this.config = { ...DEFAULT_BREAKER_CONFIG, ...config };
+  }
+
+  /** Check if a call should be allowed through. */
+  canAttempt(): boolean {
+    if (this.state === "closed") return true;
+    if (this.state === "open") {
+      // Check if cooldown has elapsed → transition to half-open
+      if (Date.now() - this.openedAt >= this.config.cooldownMs) {
+        this.state = "half-open";
+        logInfo("[circuit-breaker] transitioning to half-open, allowing probe");
+        return true;
+      }
+      return false;
+    }
+    // half-open: allow one probe
+    return true;
+  }
+
+  /** Record a successful call. */
+  recordSuccess(): void {
+    if (this.state !== "closed") {
+      logInfo("[circuit-breaker] probe succeeded, circuit closed");
+    }
+    this.consecutiveFailures = 0;
+    this.state = "closed";
+  }
+
+  /** Record a failed call. */
+  recordFailure(): void {
+    this.consecutiveFailures++;
+    if (this.state === "half-open") {
+      // Probe failed → reopen
+      this.state = "open";
+      this.openedAt = Date.now();
+      logInfo("[circuit-breaker] probe failed, circuit re-opened");
+      return;
+    }
+    if (this.consecutiveFailures >= this.config.failureThreshold) {
+      this.state = "open";
+      this.openedAt = Date.now();
+      logInfo(`[circuit-breaker] ${this.consecutiveFailures} consecutive failures, circuit opened`);
+    }
+  }
+
+  /** Current circuit state (for testing/diagnostics). */
+  getState(): CircuitState {
+    return this.state;
+  }
+
+  /** Current failure count (for testing/diagnostics). */
+  getFailureCount(): number {
+    return this.consecutiveFailures;
+  }
+}
 
 // ============================================================================
 // Types
@@ -53,6 +136,12 @@ export interface SmartExtraction {
   l1: string;
   /** Importance score 0-1 (LLM's estimate) */
   importance: number;
+  /** Optional emotional tone (only populated when feature flag is on) */
+  emotion?: {
+    valence: number;
+    arousal: number;
+    label?: string;
+  };
 }
 
 /** Category-specific merge strategies */
@@ -96,8 +185,10 @@ export class LLMClient {
   private model: string;
   private temperature: number;
   private timeoutMs: number;
+  /** LME-9: Circuit breaker for graceful LLM degradation */
+  readonly breaker: CircuitBreaker;
 
-  constructor(config: LLMConfig) {
+  constructor(config: LLMConfig, breakerConfig?: Partial<CircuitBreakerConfig>) {
     const apiKey = resolveEnvVars(config.apiKey);
     this.client = new OpenAI({
       apiKey,
@@ -106,6 +197,7 @@ export class LLMClient {
     this.model = config.model;
     this.temperature = config.temperature ?? 0.1;
     this.timeoutMs = config.timeoutMs ?? 15000;
+    this.breaker = new CircuitBreaker(breakerConfig);
   }
 
   /**
@@ -116,7 +208,9 @@ export class LLMClient {
     try {
       const response = await this.chat(
         "你是记忆索引助手。给以下对话片段写一句话摘要（不超过80字），" +
-        "用于快速检索。只输出摘要本身，不加任何前缀。",
+        "用于快速检索。只输出摘要本身，不加任何前缀。\n" +
+        "保真规则：端口号/IP/URL/文件路径/API名称 → 原样保留；" +
+        "函数名/事件名/配置项 → 逐项保留不概括。",
         text.slice(0, 2000), // Cap input to avoid token overflow
       );
       if (!response || response.length < 5) return null;
@@ -144,7 +238,7 @@ export class LLMClient {
       const validCategories: SmartCategory[] = ["profile", "preferences", "entities", "events", "cases", "patterns"];
       if (!validCategories.includes(parsed.category)) return null;
 
-      return {
+      const result: SmartExtraction = {
         category: parsed.category,
         l0: (parsed.l0 || "").slice(0, 150),
         l1: (parsed.l1 || "").slice(0, 500),
@@ -152,6 +246,16 @@ export class LLMClient {
           ? Math.max(0, Math.min(1, parsed.importance))
           : CATEGORY_DEFAULT_IMPORTANCE[parsed.category],
       };
+
+      if (isEmotionScoringEnabled() && parsed.emotion) {
+        result.emotion = {
+          valence: Math.max(-1, Math.min(1, parsed.emotion.valence ?? 0)),
+          arousal: Math.max(0, Math.min(1, parsed.emotion.arousal ?? 0)),
+          label: parsed.emotion.label,
+        };
+      }
+
+      return result;
     } catch {
       return null;
     }
@@ -255,6 +359,87 @@ export class LLMClient {
     return results;
   }
 
+  /**
+   * B-3: Assess the long-term importance of a memory (0–1).
+   * Called when store_memory importance is at the default value, to let LLM refine it.
+   * Returns null on failure (caller should keep the default).
+   */
+  async assessImportance(text: string, category: string): Promise<number | null> {
+    try {
+      const response = await this.chat(
+        "你是记忆重要性评估助手。评估以下记忆的长期重要性（0.0-1.0）。\n\n" +
+        "锚定标准（每级附具体示例，严格对标）：\n" +
+        "- 0.85-1.0：用户明确纠正行为（如'不要这样做'）、身份声明（职业/角色）、" +
+          "情感/行为变化、核心偏好（写作风格/沟通方式）、反复强调的规则\n" +
+        "- 0.70-0.84：关键决策（架构选型/技术路线）、项目承诺（deadline/里程碑）、" +
+          "可复用案例（踩坑→修复→教训）、持久偏好（喜欢X不喜欢Y）\n" +
+        "- 0.55-0.69：实体信息（项目名/工具名/人名）、新学到的背景知识、" +
+          "配置参数（API key位置/环境变量）\n" +
+        "- 0.40-0.54：普通事件（今天部署了X）、一次性操作步骤、" +
+          "已解决的 bug 细节（修完即过时）\n" +
+        "- 0.10-0.30：日常寒暄、重复信息（已有更完整版本）、" +
+          "临时调试输出、短期上下文（如'刚才那个文件'）\n\n" +
+        "常见误判提醒：\n" +
+        "- 用户说'记住'/'永远不要' → 至少 0.85\n" +
+        "- 看起来是小事但反复出现 → 至少 0.70（重复=重要）\n" +
+        "- 纯技术细节但没有复用价值 → 不超过 0.50\n\n" +
+        "只输出一行 JSON：{\"importance\":0.7,\"reason\":\"简短原因\"}",
+        `[类别] ${category}\n[内容] ${text.slice(0, 1000)}`,
+      );
+      if (!response) return null;
+      const parsed = parseJSON<{ importance: number; reason?: string }>(response);
+      if (parsed && typeof parsed.importance === "number") {
+        return Math.max(0, Math.min(1, parsed.importance));
+      }
+      return null;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * HP-4: Batch re-assess importance for existing memories during distill.
+   * Returns a map of id → new importance (only for entries that changed).
+   */
+  async reassessImportanceBatch(
+    entries: Array<{ id: string; text: string; category: string; currentImportance: number }>,
+  ): Promise<Map<string, number>> {
+    const results = new Map<string, number>();
+    if (entries.length === 0) return results;
+
+    const batch = entries
+      .map((e, i) => `[${i}] category=${e.category} importance=${e.currentImportance}\n${e.text.slice(0, 300)}`)
+      .join("\n---\n");
+
+    try {
+      const response = await this.chat(
+        "批量重评记忆重要性。使用同一套锚定标准（0.85+ 身份/纠正/核心偏好，" +
+        "0.70-0.84 决策/案例/偏好，0.55-0.69 实体/背景，0.40-0.54 事件/操作，" +
+        "0.10-0.30 寒暄/重复/临时）。\n" +
+        "只输出 JSON 数组，每项 {\"idx\":0,\"importance\":0.7}，" +
+        "只包含需要调整的项（与当前分数差 ≥ 0.1 才输出）。",
+        batch,
+      );
+      if (!response) return results;
+      const parsed = parseJSON<Array<{ idx: number; importance: number }>>(response);
+      if (Array.isArray(parsed)) {
+        for (const item of parsed) {
+          if (
+            typeof item.idx === "number" &&
+            typeof item.importance === "number" &&
+            item.idx >= 0 &&
+            item.idx < entries.length
+          ) {
+            results.set(entries[item.idx].id, Math.max(0, Math.min(1, item.importance)));
+          }
+        }
+      }
+    } catch {
+      // Batch re-assessment failure is non-fatal
+    }
+    return results;
+  }
+
   /**
    * Semantic dedup decision: given a new chunk and an existing similar chunk,
    * decide whether to CREATE (store new), MERGE (combine), or SKIP (discard).
@@ -363,7 +548,10 @@ export class LLMClient {
     try {
       return await this.chat(
         "你是记忆精炼助手。把以下内容提炼为一段核心摘要（不超过200字）。\n" +
-        "要求：保留关键事实、人名、数字、时间等；去除冗余修辞；直接输出摘要，不加前缀。",
+        "要求：保留关键事实、人名、数字、时间等；去除冗余修辞；直接输出摘要，不加前缀。\n" +
+        "保真规则：端口号/IP/URL/文件路径 → 原样保留；" +
+        "命名列表（函数名/事件名/配置项）→ 逐项保留不概括；" +
+        "规则表/状态转移 → 完整保留；对比/排序 → 保留顺序和理由。",
         text.slice(0, 2000),
       );
     } catch {
@@ -454,6 +642,33 @@ export class LLMClient {
     }
   }
 
+  /**
+   * HP-5: Extract cross-memory pattern from a cluster of related memories.
+   * Asks LLM whether the cluster reveals an implicit recurring theme,
+   * preference, or behavior not stated in any single memory.
+   *
+   * @returns Pattern text if found, null if no pattern or LLM failure.
+   */
+  async extractPattern(clusterTexts: string[]): Promise<string | null> {
+    if (clusterTexts.length < 3) return null;
+
+    const numbered = clusterTexts.map((t, i) => `[${i + 1}] ${t}`).join("\n");
+    const result = await this.chatJson<{ hasPattern: boolean; pattern?: string }>(
+      "你是记忆模式发现助手。分析以下一组相关记忆，判断它们是否暗示了某个跨条目的隐含模式——" +
+      "例如反复出现的偏好、行为倾向、价值观或循环主题。\n\n" +
+      "规则：\n" +
+      "- 只发现真正跨条目的模式，而非单条记忆已经明确表达的内容\n" +
+      "- 模式必须有至少 2 条记忆作为证据支撑\n" +
+      "- 如果没有发现有意义的模式，返回 hasPattern: false\n" +
+      "- 模式描述不超过 150 字，简洁且可操作\n" +
+      '- 输出 JSON：{"hasPattern": true, "pattern": "描述..."} 或 {"hasPattern": false}',
+      `记忆条目（共${clusterTexts.length}条）：\n${numbered}`,
+    );
+
+    if (!result || !result.hasPattern || !result.pattern) return null;
+    return result.pattern;
+  }
+
   /**
    * Chat + JSON parse helper for structured extraction.
    * Returns null on failure (LLM error or invalid JSON).
@@ -481,11 +696,63 @@ export class LLMClient {
     }
   }
 
+  async chatLong(system: string, user: string, maxTokens = 2000): Promise<string | null> {
+    if (!this.breaker.canAttempt()) {
+      return null;
+    }
+
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), this.timeoutMs * 2);
+
+    try {
+      const response = await this.client.chat.completions.create(
+        {
+          model: this.model,
+          messages: [
+            { role: "system", content: system },
+            { role: "user", content: user },
+          ],
+          temperature: this.temperature,
+          max_tokens: maxTokens,
+        },
+        { signal: controller.signal },
+      );
+
+      const result = response.choices[0]?.message?.content?.trim() || null;
+      this.breaker.recordSuccess();
+      return result;
+    } catch (err) {
+      this.breaker.recordFailure();
+      throw err;
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+
+  // --------------------------------------------------------------------------
+  // Constructive Retrieval — public wrappers for reconstruction pipeline
+  // --------------------------------------------------------------------------
+
+  /** Public wrapper for reconstruction pipeline */
+  async generateReconstruction(system: string, user: string): Promise<string | null> {
+    return this.chat(system, user);
+  }
+
+  /** Check if LLM circuit breaker allows requests */
+  isAvailable(): boolean {
+    return this.breaker.canAttempt();
+  }
+
   // --------------------------------------------------------------------------
   // Internals
   // --------------------------------------------------------------------------
 
   private async chat(system: string, user: string): Promise<string | null> {
+    // LME-9: Circuit breaker — short-circuit when LLM is down
+    if (!this.breaker.canAttempt()) {
+      return null;
+    }
+
     const controller = new AbortController();
     const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
 
@@ -503,7 +770,12 @@ export class LLMClient {
         { signal: controller.signal },
       );
 
-      return response.choices[0]?.message?.content?.trim() || null;
+      const result = response.choices[0]?.message?.content?.trim() || null;
+      this.breaker.recordSuccess();
+      return result;
+    } catch (err) {
+      this.breaker.recordFailure();
+      throw err;
     } finally {
       clearTimeout(timeout);
     }
@@ -538,11 +810,22 @@ const SMART_EXTRACT_SYSTEM_PROMPT = `你是 AI 记忆分类助手。把对话片
 | 报错→修复、问题→方案 | cases |
 | "每次…"、"一般…"、规律总结 | patterns |
 
+## 保真规则（l0/l1 必须遵守）
+- 端口号/IP/URL/文件路径/API endpoint → 原样保留
+- 命名列表（函数名/事件名/配置项）→ 逐项保留，不概括为"等"
+- 规则表/状态转移 → 完整保留
+- 对比/排序 → 保留顺序和理由
+
 ## 输出格式
 只输出一个 JSON 对象：
 {"category":"类别","l0":"一句话摘要(≤80字)","l1":"结构化概述(2-5行markdown)","importance":0.7}
 
-importance 评分标准：身份/模式 0.8+、偏好/案例 0.7、实体 0.65、普通事件 0.5`;
+importance 评分标准：身份/模式 0.8+、偏好/案例 0.7、实体 0.65、普通事件 0.5
+
+Also rate emotional tone:
+- emotion.valence: [-1, 1] (negative to positive)
+- emotion.arousal: [0, 1] (calm to excited)
+- emotion.label: one word (e.g., "frustration", "neutral")`;
 
 const SMART_EXTRACT_BATCH_PROMPT = `你是 AI 记忆分类助手。把每段对话分类到 6 种记忆类型之一。