recallnest 2.6.1 → 3.0.1

package/src/ingest.ts

@@ -60,6 +60,29 @@ interface ConversationTurn {
   text: string;
   timestamp: string;
   sessionId: string;
+  /**
+   * 本条记忆所在 session 里用户亲手贴的图片总数——注意是整个 session 的，
+   * 不是本轮的张数。工具产的图（截图 / 读图，实测占全部图片九成）不计。
+   *
+   * 粒度取 session 而不是轮次，是有意的（2026-08-27 定）：图所在的那一轮
+   * 常常因为正文太短根本没进库，精确坐标挂不上去；而同 session 的别的轮次
+   * 进了库。打成 session 级的标，搜到那些轮次时才能顺藤摸到图。
+   *
+   * 代价是精度低：一个 session 里几十条记忆会带同一个标，图未必跟搜到的
+   * 这一条有关。这是粒度换覆盖，明知而为——判断值不值得看，回 Deja 按
+   * session 读原文，图本体不进库。
+   */
+  sessionImages?: number;
+  /**
+   * 本 session 里 AI 自己产的图片总数：工具截图、读进来的图片文件、模型生成的图。
+   * 实测它是用户贴图的三倍多（5812 vs 1629）。
+   *
+   * 跟 sessionImages 分开计，因为两者服务的检索意图不是一回事——人找「我发过的
+   * 那张截图」要的是前者；agent 回溯「我当时生成的示意图长什么样」「那个页面当时
+   * 渲染成什么样」要的是后者。混成一个数，两种意图都答不好；只留前者，则 agent
+   * 自己回溯时看不见任何线索。
+   */
+  sessionToolImages?: number;
 }
 
 // ============================================================================
@@ -649,13 +672,20 @@ export async function drainPendingQueue(
         const entryText = extractions[j].l1 || extractions[j].l0;
         const language = detectLang(entryText);
         const fts_text = tokenizeFts(entryText, language);
-        await store.store({
+        // 2026-08-24 修：回填路径此前直接 store.store()，绕过 buildIngestedEntry，
+        // 导致条目缺 boundary/layer/tier（transcript 碎片不降权）。改走同一构造器；
+        // 入队时未保留原文件路径，file 用 "pending-queue" 诚实标记回填来源。
+        const entry = buildIngestedEntry({
+          source: batch[j].scope.split(":")[0],
+          scope: batch[j].scope,
           text: entryText,
           vector: vectors[j],
-          category: extractions[j].category as any,
-          scope: batch[j].scope,
-          importance: extractions[j].importance,
-          metadata: JSON.stringify({ source: batch[j].scope.split(":")[0], l0_abstract: extractions[j].l0, l1_overview: extractions[j].l1, l2_content: extractions[j].l1 || extractions[j].l0 }),
+          extraction: extractions[j],
+          file: "pending-queue",
+        });
+        await store.store({
+          ...entry,
+          category: entry.category as any,
           language,
           fts_text,
         });
@@ -696,6 +726,10 @@ function buildIngestedEntry(params: {
   heading?: string;
   /** Tier 3.1: optional core summary (≤200 chars) for token-efficient context output */
   coreSummary?: string | null;
+  /** 本条记忆所在 session 里用户亲手贴的图片总数；无图时不传 */
+  sessionImages?: number;
+  /** 本条记忆所在 session 里 AI 自己产的图片总数（截图 / 读图 / 生图）；无则不传 */
+  sessionToolImages?: number;
 }): {
   text: string;
   vector: number[];
@@ -739,6 +773,8 @@ function buildIngestedEntry(params: {
       l1_overview: params.extraction.l1,
       l2_content: params.text,
       ...(params.coreSummary ? { core_summary: params.coreSummary } : {}),
+      ...(params.sessionImages ? { sessionImages: params.sessionImages } : {}),
+      ...(params.sessionToolImages ? { sessionToolImages: params.sessionToolImages } : {}),
       tier,
       boundary: resolution.boundary,
       ...(narrative ? { narrative } : {}),
@@ -786,16 +822,72 @@ const MARKDOWN_CHUNK_CONFIG: ChunkerConfig = {
 // CC Transcript Parser
 // ============================================================================
 
-function parseCCTranscript(filePath: string): ConversationTurn[] {
+/**
+ * 数一条 transcript 记录里所有的图片信号，**不预设它们是什么用途、在什么位置**。
+ *
+ * 这是有意的宽口径：AI 产图的形态一直在长（工具截图、读进来的图片文件、模型生图、
+ * 写公众号时让它配的插图……），任何"列举有哪几类"的写法都注定漏掉下一类。所以这里
+ * 只回答一个问题——「这是不是一张图」，然后由调用方用**补集**去定义 AI 产图：
+ * 整条记录里的图 减去 用户在消息里亲手贴的，剩下的全算，不问出身。
+ *
+ * 判据是「携带图片的块」的三种通用形态，跨 Anthropic / OpenAI / Kimi 都成立：
+ *   - type 里含 image（image / input_image / image_url / image_generation_* …）
+ *   - 有 image_url / imageUrl 字段
+ *   - 有 media_type / mimeType 且以 image/ 开头
+ *
+ * ⚠️ 这是**信号计数不是精确张数**：一次生图可能同时留下 call 与 end 两条记录，
+ * 会被数成 2。这是刻意选的方向——宁可多算，不可漏报，因为它服务的问题是
+ * 「这附近有没有图」而不是「精确几张」。
+ */
+function countImageSignals(node: unknown, depth = 0): number {
+  if (depth > 10 || node === null || typeof node !== "object") return 0;
+  if (Array.isArray(node)) {
+    let sum = 0;
+    for (const item of node) sum += countImageSignals(item, depth + 1);
+    return sum;
+  }
+
+  const obj = node as Record<string, unknown>;
+  const type = obj.type;
+  const mediaType = obj.media_type ?? obj.mimeType;
+  const isImageBlock =
+    (typeof type === "string" && type.includes("image")) ||
+    typeof obj.image_url === "string" ||
+    (obj.imageUrl !== null && typeof obj.imageUrl === "object") ||
+    (typeof mediaType === "string" && mediaType.startsWith("image/"));
+
+  // 命中即计一次并停止下钻：一个图片块内部不会再嵌另一张独立的图，继续递归
+  // 只会把 {type:"image", source:{media_type:"image/png"}} 这种数成两张。
+  if (isImageBlock) return 1;
+
+  let count = 0;
+  for (const value of Object.values(obj)) {
+    if (value !== null && typeof value === "object") {
+      count += countImageSignals(value, depth + 1);
+    }
+  }
+  return count;
+}
+
+export function parseCCTranscript(filePath: string): ConversationTurn[] {
   const turns: ConversationTurn[] = [];
   const content = readFileSync(filePath, "utf-8");
   const lines = content.split("\n").filter((l) => l.trim());
 
   let sessionId = "";
+  // 整个 session 里的图片计数，扫完全文后统一盖到每个 turn 上。两类分开数：
+  // 用户亲手贴的 vs AI 自己产的（工具截图 / 读图 / 生图）。
+  // 数得到是因为本函数本来就逐行读完整个文件，顺带累加不额外花钱。
+  let sessionImages = 0;
+  let sessionToolImages = 0;
 
   for (const line of lines) {
     try {
       const obj = JSON.parse(line);
+      // 这一行里所有的图片信号。用户亲手贴的那部分在下面单独精确认，
+      // 其余的一律按补集归入 AI 产图——不枚举它是截图、读图、生图还是配图。
+      const lineImageSignals = countImageSignals(obj);
+      let lineUserImages = 0;
 
       if (!sessionId && obj.sessionId) {
         sessionId = obj.sessionId;
@@ -804,20 +896,39 @@ function parseCCTranscript(filePath: string): ConversationTurn[] {
       if (obj.type === "user" && obj.message) {
         const msg = obj.message;
         let text = "";
+        let turnImages = 0;
         if (typeof msg.content === "string") {
           text = msg.content;
         } else if (Array.isArray(msg.content)) {
-          // Extract text blocks, skip tool_use/tool_result/images
+          // 文本块照旧提取，tool_use / tool_result 仍然整块丢弃（架构决定，见 memory-boundaries）。
+          // 图片本体也不进库，只数一下：这里只认顶层的 image block，
+          // tool_result 里内嵌的不算——那是工具截图/读图，实测占全部图片九成。
           text = msg.content
             .filter((c: any) => c.type === "text")
             .map((c: any) => c.text || "")
             .join("\n");
+          turnImages = msg.content.filter((c: any) => c?.type === "image").length;
         }
-
-        if (text.trim().length > 10) {
+        sessionImages += turnImages;
+        lineUserImages = turnImages;
+
+        // 只贴图不配字的那一轮，此前会被长度闸整条丢掉——实测占含图轮次的 12.5%，
+        // 且丢掉的常是「操作步骤在这里」+ 截图这类正文全在图里的高价值轮次
+        // （最极端的样本是 0 字配 7 张图）。给它一个占位正文，让它能跟下一条
+        // 助手回复合成 chunk——助手的回复通常描述了图里是什么，那就是定位这些图的文字。
+        //
+        // 有配文时正文一个字都不改：文字本身已是检索入口，往里塞标记只会稀释 embedding。
+        const trimmed = text.trim();
+        const body = trimmed.length > 0
+          ? trimmed
+          : turnImages > 0
+            ? `[图片×${turnImages}]`
+            : "";
+
+        if (body.length > 10 || turnImages > 0) {
           turns.push({
             role: "user",
-            text: text.trim(),
+            text: body,
             timestamp: obj.timestamp || "",
             sessionId,
           });
@@ -846,11 +957,26 @@ function parseCCTranscript(filePath: string): ConversationTurn[] {
           });
         }
       }
+
+      // 补集：这一行里除用户亲手贴的之外的图，全算 AI 产的，不问出身。
+      // 用补集而不是列举，是因为 AI 产图的形态会一直长（生图、截图、读图、
+      // 写文章时的配图……），任何枚举都注定漏掉下一类。
+      sessionToolImages += Math.max(0, lineImageSignals - lineUserImages);
     } catch {
       // Skip malformed lines
     }
   }
 
+  // 整份 transcript 扫完才知道总数，统一盖到每个 turn 上——这条标记回答的是
+  // 「这条记忆所在的 session 里有没有图」，不是「这一轮有没有图」。图所在的那轮
+  // 常因正文太短进不了库，只有盖到同 session 的其他轮次上，才可能被搜到。
+  if (sessionImages > 0 || sessionToolImages > 0) {
+    for (const turn of turns) {
+      if (sessionImages > 0) turn.sessionImages = sessionImages;
+      if (sessionToolImages > 0) turn.sessionToolImages = sessionToolImages;
+    }
+  }
+
   return turns;
 }
 
@@ -872,12 +998,26 @@ export function groupTurnsIntoChunks(turns: ConversationTurn[]): Array<{
   text: string;
   timestamp: string;
   sessionId: string;
+  sessionImages?: number;
+  sessionToolImages?: number;
 }> {
   const filtered = filterNoiseTurns(turns);
-  const chunks: Array<{ text: string; timestamp: string; sessionId: string }> = [];
+  const chunks: Array<{
+    text: string;
+    timestamp: string;
+    sessionId: string;
+    sessionImages?: number;
+    sessionToolImages?: number;
+  }> = [];
 
   for (let i = 0; i < filtered.length; i++) {
     const turn = filtered[i];
+    // 同一 session 切出来的每个 chunk 都带同一个标——它说的是「这个 session 有图」，
+    // 跟这一片本身有没有图无关，这正是 session 粒度要的效果。
+    const imgMark = {
+      ...(turn.sessionImages ? { sessionImages: turn.sessionImages } : {}),
+      ...(turn.sessionToolImages ? { sessionToolImages: turn.sessionToolImages } : {}),
+    };
 
     // If this is a user turn followed by an assistant turn, merge them
     if (turn.role === "user" && i + 1 < filtered.length && filtered[i + 1].role === "assistant") {
@@ -896,10 +1036,10 @@ export function groupTurnsIntoChunks(turns: ConversationTurn[]): Array<{
           if (seg.text.length > CONVERSATION_CHUNK_CONFIG.maxChunkSize) {
             const chunkResult = chunkDocument(seg.text, CONVERSATION_CHUNK_CONFIG);
             for (const chunk of chunkResult.chunks) {
-              chunks.push({ text: chunk, timestamp: turn.timestamp, sessionId: turn.sessionId });
+              chunks.push({ text: chunk, timestamp: turn.timestamp, sessionId: turn.sessionId, ...imgMark });
             }
           } else {
-            chunks.push({ text: seg.text, timestamp: turn.timestamp, sessionId: turn.sessionId });
+            chunks.push({ text: seg.text, timestamp: turn.timestamp, sessionId: turn.sessionId, ...imgMark });
           }
         }
       } else {
@@ -907,6 +1047,7 @@ export function groupTurnsIntoChunks(turns: ConversationTurn[]): Array<{
           text: merged,
           timestamp: turn.timestamp,
           sessionId: turn.sessionId,
+          ...imgMark,
         });
       }
 
@@ -925,10 +1066,10 @@ export function groupTurnsIntoChunks(turns: ConversationTurn[]): Array<{
           if (seg.text.length > CONVERSATION_CHUNK_CONFIG.maxChunkSize) {
             const chunkResult = chunkDocument(seg.text, CONVERSATION_CHUNK_CONFIG);
             for (const chunk of chunkResult.chunks) {
-              chunks.push({ text: chunk, timestamp: turn.timestamp, sessionId: turn.sessionId });
+              chunks.push({ text: chunk, timestamp: turn.timestamp, sessionId: turn.sessionId, ...imgMark });
             }
           } else {
-            chunks.push({ text: seg.text, timestamp: turn.timestamp, sessionId: turn.sessionId });
+            chunks.push({ text: seg.text, timestamp: turn.timestamp, sessionId: turn.sessionId, ...imgMark });
           }
         }
       } else {
@@ -936,6 +1077,7 @@ export function groupTurnsIntoChunks(turns: ConversationTurn[]): Array<{
           text,
           timestamp: turn.timestamp,
           sessionId: turn.sessionId,
+          ...imgMark,
         });
       }
     }
@@ -959,18 +1101,26 @@ export function groupTurnsIntoChunks(turns: ConversationTurn[]): Array<{
 // Codex Session Parser
 // ============================================================================
 
-function parseCodexSession(filePath: string): ConversationTurn[] {
+export function parseCodexSession(filePath: string): ConversationTurn[] {
   const turns: ConversationTurn[] = [];
   const content = readFileSync(filePath, "utf-8");
   const lines = content.split("\n").filter((l) => l.trim());
 
   let sessionId = "";
+  // 同 parseCCTranscript：两类图片分开计数。
+  // Codex 的图片字段是 input_image（OpenAI 格式），不是 Anthropic 的 image；
+  // 用户贴的在 payload.content 里可以精确认；其余一律按补集归 AI 产图。
+  let sessionImages = 0;
+  let sessionToolImages = 0;
 
   for (const line of lines) {
     try {
       const obj = JSON.parse(line);
       const payload = obj.payload;
       const timestamp = obj.timestamp || "";
+      // 同 parseCCTranscript：整行图片信号，减去用户贴的，剩下全归 AI 产
+      const lineImageSignals = countImageSignals(obj);
+      let lineUserImages = 0;
 
       if (obj.type === "session_meta" && payload?.id) {
         sessionId = payload.id;
@@ -982,6 +1132,13 @@ function parseCodexSession(filePath: string): ConversationTurn[] {
         const content = payload.content;
 
         if (Array.isArray(content)) {
+          // 只精确认用户消息里的 input_image；Codex 自己生的图 / 读的图挂在
+          // payload.output 等别处，由下面的补集统一接住，这里不去枚举它们。
+          if (role === "user") {
+            const own = content.filter((c: any) => c?.type === "input_image").length;
+            sessionImages += own;
+            lineUserImages += own;
+          }
           for (const c of content) {
             if (c.type === "input_text" && c.text && c.text.length > 10) {
               // Skip system/developer prompts (usually very long instructions)
@@ -1023,11 +1180,21 @@ function parseCodexSession(filePath: string): ConversationTurn[] {
           }
         }
       }
+
+      // 补集：除用户亲手贴的之外，这一行里的图全算 AI 产的，不问出身。
+      sessionToolImages += Math.max(0, lineImageSignals - lineUserImages);
     } catch {
       // Skip malformed lines
     }
   }
 
+  if (sessionImages > 0 || sessionToolImages > 0) {
+    for (const turn of turns) {
+      if (sessionImages > 0) turn.sessionImages = sessionImages;
+      if (sessionToolImages > 0) turn.sessionToolImages = sessionToolImages;
+    }
+  }
+
   return turns;
 }
 
@@ -1164,6 +1331,8 @@ export async function ingestCodexSessions(
                   sessionId: chunk.sessionId,
                   file: basename(filePath),
                   coreSummary: coreSummaries[j],
+                  sessionImages: chunk.sessionImages,
+                  sessionToolImages: chunk.sessionToolImages,
                 }));
               }
             }
@@ -1205,7 +1374,7 @@ export async function ingestCodexSessions(
 //   context.append_loop_event content.part    → 助手文本（part.type==="text"；think 跳过）
 // 其余类型（llm.tools_snapshot / mcp.tools_discovered / config.update / llm.request /
 // usage.record / permission.* 等，约占 86% 体积）是运行事件，一律跳过。
-function parseKimiSession(filePath: string): ConversationTurn[] {
+export function parseKimiSession(filePath: string): ConversationTurn[] {
   const turns: ConversationTurn[] = [];
   const content = readFileSync(filePath, "utf-8");
   const lines = content.split("\n").filter((l) => l.trim());
@@ -1215,6 +1384,11 @@ function parseKimiSession(filePath: string): ConversationTurn[] {
   const pathParts = filePath.split("/");
   const rawId = pathParts.length >= 4 ? pathParts[pathParts.length - 4] : basename(filePath, ".jsonl");
   const sessionId = rawId.replace(/^session_/, "");
+  // 同 parseCCTranscript：两类图片分开计数。
+  // Kimi 的图片字段是 image_url；用户贴的在 turn.prompt / context.append_message，
+  // AI 产的在 context.append_loop_event 的 tool.result 里。
+  let sessionImages = 0;
+  let sessionToolImages = 0;
 
   const pushTurn = (role: "user" | "assistant", text: string, timestamp: string) => {
     const trimmed = text.trim();
@@ -1231,6 +1405,23 @@ function parseKimiSession(filePath: string): ConversationTurn[] {
       const obj = JSON.parse(line);
       const timestamp = typeof obj.time === "number" ? new Date(obj.time).toISOString() : "";
 
+      // 图片统计在这里一次算完，不放进下面的分支——那些分支各自 continue，
+      // 放进去会被跳过。用户贴的精确认，其余按补集归 AI 产，不枚举出身。
+      {
+        const lineImageSignals = countImageSignals(obj);
+        let lineUserImages = 0;
+        if (obj.type === "turn.prompt" && obj.origin?.kind === "user" && Array.isArray(obj.input)) {
+          lineUserImages = obj.input.filter((c: any) => c?.type === "image_url").length;
+        } else if (obj.type === "context.append_message") {
+          const m = obj.message;
+          if (m?.role === "user" && m?.origin?.kind === "user" && Array.isArray(m.content)) {
+            lineUserImages = m.content.filter((c: any) => c?.type === "image_url").length;
+          }
+        }
+        sessionImages += lineUserImages;
+        sessionToolImages += Math.max(0, lineImageSignals - lineUserImages);
+      }
+
       if (obj.type === "turn.prompt") {
         if (obj.origin?.kind !== "user") continue;
         const parts = Array.isArray(obj.input) ? obj.input : [];
@@ -1271,6 +1462,13 @@ function parseKimiSession(filePath: string): ConversationTurn[] {
     }
   }
 
+  if (sessionImages > 0 || sessionToolImages > 0) {
+    for (const turn of turns) {
+      if (sessionImages > 0) turn.sessionImages = sessionImages;
+      if (sessionToolImages > 0) turn.sessionToolImages = sessionToolImages;
+    }
+  }
+
   return turns;
 }
 
@@ -1434,6 +1632,8 @@ export async function ingestKimiSessions(
                   sessionId: chunk.sessionId,
                   file: basename(filePath),
                   coreSummary: coreSummaries[j],
+                  sessionImages: chunk.sessionImages,
+                  sessionToolImages: chunk.sessionToolImages,
                 }));
               }
             }
@@ -1731,10 +1931,24 @@ export async function ingestCCTranscripts(
   store: MemoryStore,
   embedder: Embedder,
   sourcePath: string,
-  options: { limit?: number; verbose?: boolean; noDedup?: boolean; llm?: LLMClient | null; recentHours?: number } = {},
+  options: {
+    limit?: number;
+    verbose?: boolean;
+    noDedup?: boolean;
+    llm?: LLMClient | null;
+    recentHours?: number;
+    /**
+     * scope 前缀与来源标签。默认 "cc" —— 这个默认值是承重的：
+     * memory-boundaries.ts 的 TRANSCRIPT_SCOPE_PREFIXES 靠前缀把会话碎片降权到
+     * evidence 层，前缀写错等于让某个端的 shell 输出被当成"用户说过的话"。
+     * 新增来源时必须同时在那份清单里登记，别只在这里传个新字符串。
+     */
+    scopePrefix?: string;
+  } = {},
 ): Promise<IngestResult> {
+  const scopePrefix = options.scopePrefix ?? "cc";
   const result: IngestResult = {
-    source: "cc",
+    source: scopePrefix,
     filesProcessed: 0,
     chunksIngested: 0,
     chunksSkipped: 0,
@@ -1744,6 +1958,12 @@ export async function ingestCCTranscripts(
   };
 
   const dir = expandHome(sourcePath);
+  // session-digest.py 摘要调用留下的会话记录不 ingest（2026-08-24 审计：这类
+  // transcript 是原始会话 8000 字符采样的副本，ingest 后 scope/metadata 指向
+  // 摘要任务自身 sid——内容是真的、坐标是假的，已产生 1,950 条 evidence 污染）。
+  if (dir.includes("session-digest")) {
+    return result;
+  }
   if (!existsSync(dir)) {
     result.errors.push(`Directory not found: ${dir}`);
     return result;
@@ -1838,7 +2058,7 @@ export async function ingestCCTranscripts(
           // Without LLM: queue raw chunks for later extraction instead of storing garbage
           if (!options.llm) {
             queueForLaterExtraction(
-              dedupedChunks.map(c => ({ text: c.text, scope: `cc:${c.sessionId.slice(0, 8)}` }))
+              dedupedChunks.map(c => ({ text: c.text, scope: `${scopePrefix}:${c.sessionId.slice(0, 8)}` }))
             );
             result.chunksSkipped += dedupedTexts.length;
             continue;
@@ -1853,14 +2073,20 @@ export async function ingestCCTranscripts(
             const chunk = dedupedChunks[j];
             const ext = extractions[j];
             toStore.push(buildIngestedEntry({
-              source: "cc",
-              scope: `cc:${chunk.sessionId.slice(0, 8)}`,
+              // 必须跟 scope 前缀一致：memory-boundaries 有两道闸，isTranscriptScope 看 scope、
+              // isTranscriptSource 看这个字段。写死 "cc" 时降权仍然生效（cc 也在清单里），
+              // 所以错了不会报错、只会让「按来源过滤」静默失真——2026-08-20 接 minis 源时漏改这处，
+              // 库里出现 10 条 scope=minis: 而 source=cc 的记录。
+              source: scopePrefix,
+              scope: `${scopePrefix}:${chunk.sessionId.slice(0, 8)}`,
               text: dedupedTexts[j],
               vector: dedupedVectors[j],
               extraction: ext,
               sessionId: chunk.sessionId,
               file,
               coreSummary: coreSummaries[j],
+              sessionImages: chunk.sessionImages,
+              sessionToolImages: chunk.sessionToolImages,
             }));
           }
 

package/src/kg-extractor.ts

@@ -123,6 +123,23 @@ export class KGExtractor {
     this.kgStore = config.kgStore;
   }
 
+  /**
+   * Drop this memory's contribution to the graph.
+   *
+   * Triple ids are `sha256(scope + subject + predicate + object)` — derived from
+   * content, not from the source memory. So when a memory's text is replaced, the
+   * new text yields brand-new ids and the edges from the OLD text stay behind
+   * forever, competing with the new ones during retrieval. Callers that overwrite
+   * a memory's content must purge first, then re-extract.
+   *
+   * Delegates to KGStore.deleteBySource, which is reference-counted: an edge that
+   * other memories still attest to only loses this one source (mention_count -1);
+   * the row itself is deleted only when the last piece of evidence goes away.
+   */
+  async purgeForMemory(memoryId: string): Promise<void> {
+    await this.kgStore.deleteBySource(memoryId);
+  }
+
   /**
    * Extract triples from text and persist to KG store.
    * Returns the number of triples stored.

package/src/llm-client.ts

@@ -16,6 +16,19 @@
 import OpenAI from "openai";
 import { logInfo } from "./stderr-log.js";
 import { isEmotionScoringEnabled } from "./memory-schema.js";
+import { synthesisModel } from "./env-config.js";
+import {
+  CLUSTER_INSIGHT_PROMPT,
+  CLUSTER_PATTERN_PROMPT,
+  allocateClusterBudget,
+  numberClusterTexts,
+  parseSynthesisJson,
+  validateSynthesis,
+  type SynthesisVerdict,
+} from "./synthesis-contract.js";
+
+/** dream 合成单次调用的超时。离线批处理，宽松换稳定，见 `runSynthesis` 处的注释。 */
+const SYNTHESIS_TIMEOUT_MS = 60_000;
 
 // ============================================================================
 // LME-9: Circuit Breaker — LLM 降级策略
@@ -691,31 +704,64 @@ export class LLMClient {
     }
   }
 
+  // --------------------------------------------------------------------------
+  // dream 合成（契约见 synthesis-contract.ts）
+  //
+  // 这两个方法一起取代了原来的「`generateL0` 当 insight 用 + `extractPattern` 找性格
+  // 模式」。三点结构性差别，不是提示词微调：
+  //   1. 有弃权路径 —— 炼不出结论时返回 `abstained`，不再硬凑一句进库；
+  //   2. 强制 evidence 编号 —— 说不出出处的结论不写库；
+  //   3. 输入按成员等额分配预算 —— 不再让簇的前 2,000 字吃光整个上下文。
+  // 三者都在 `SynthesisVerdict` 里有形状，调用方据此分开计数，不再退化成一个 null。
+  // --------------------------------------------------------------------------
+
   /**
-   * 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.
+   * 从一簇相关记忆里提炼一条**可复用结论**（规则/因果/决策/踩坑/判断转折）。
+   * 提炼不出来返回 `abstained` —— 这条路径是新的，老 `generateL0` 只会在 LLM 失败时
+   * 不产出，「这簇不值得留」从来没有表达方式。
    */
-  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}`,
-    );
+  async synthesizeClusterInsight(clusterTexts: string[]): Promise<SynthesisVerdict> {
+    return this.runSynthesis(clusterTexts, CLUSTER_INSIGHT_PROMPT, "conclusion", 1);
+  }
+
+  /**
+   * 从一簇相关记忆里提炼**跨条目才成立**的结论。
+   * evidence ≥2 是定义性要求：只有一条支撑的东西按定义不是跨条目模式。
+   */
+  async synthesizeClusterPattern(clusterTexts: string[]): Promise<SynthesisVerdict> {
+    if (clusterTexts.length < 3) return { status: "abstained" };
+    return this.runSynthesis(clusterTexts, CLUSTER_PATTERN_PROMPT, "pattern", 2);
+  }
+
+  private async runSynthesis(
+    clusterTexts: string[],
+    system: string,
+    textField: string,
+    minEvidence: number,
+  ): Promise<SynthesisVerdict> {
+    if (clusterTexts.length === 0) return { status: "abstained" };
+
+    const budgeted = allocateClusterBudget(clusterTexts);
+    const user = `记忆条目（共 ${clusterTexts.length} 条）：\n${numberClusterTexts(budgeted)}`;
+    // max_tokens 放宽到 400：默认的 500 是给整段回复的，而这里只要一个小 JSON；
+    // 给足余量是为了避免 evidence 数组被截断——截断的 JSON 会整条判 unparsable，
+    // 一条本可用的结论就这么丢了。
+    // max_tokens 沿用默认 500，不另设：2026-08-23 实测 60 次合成调用 finish_reason
+    // 全为 stop、completion_tokens 最大仅 132，输出侧根本够不到上限。
+    const raw = await this.chatRaw(system, user, {
+      model: synthesisModel(),
+      // 默认 15s 是给 2,000 字输入定的。等额预算后单次输入可达 12,000 字，更强的
+      // 合成模型也更慢；沿用 15s 会把「模型正在正常工作」误判成失败，而 dream 是
+      // 离线批处理，等一会儿不影响任何人。
+      timeoutMs: SYNTHESIS_TIMEOUT_MS,
+    });
 
-    if (!result || !result.hasPattern || !result.pattern) return null;
-    return result.pattern;
+    return validateSynthesis({
+      parsed: parseSynthesisJson(raw),
+      textField,
+      memberCount: clusterTexts.length,
+      minEvidence,
+    });
   }
 
   /**
@@ -843,24 +889,39 @@ export class LLMClient {
   // --------------------------------------------------------------------------
 
   private async chat(system: string, user: string): Promise<string | null> {
+    return this.chatRaw(system, user);
+  }
+
+  /**
+   * `chat()` 的可调版：允许按调用点覆盖模型与 token 上限，其余行为（熔断、超时、
+   * 温度、异常语义）完全一致。
+   *
+   * 加这一层而不是给 `chat()` 加参数，是为了让「默认调用」的形状一个字不变 ——
+   * 现有十来个调用点不该因为合成这一处的需要而被动改签名。
+   */
+  private async chatRaw(
+    system: string,
+    user: string,
+    opts?: { model?: string; maxTokens?: number; timeoutMs?: number },
+  ): 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);
+    const timeout = setTimeout(() => controller.abort(), opts?.timeoutMs ?? this.timeoutMs);
 
     try {
       const response = await this.client.chat.completions.create(
         {
-          model: this.model,
+          model: opts?.model || this.model,
           messages: [
             { role: "system", content: system },
             { role: "user", content: user },
           ],
           temperature: this.temperature,
-          max_tokens: 500,
+          max_tokens: opts?.maxTokens ?? 500,
         },
         { signal: controller.signal },
       );