recallnest 2.6.0 → 3.0.0

package/src/ingest.ts

@@ -1731,10 +1731,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,
@@ -1838,7 +1852,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,8 +1867,12 @@ 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,

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 },
       );

package/src/mcp-server.ts

@@ -9,7 +9,7 @@
  * Tool tiers:
  * - core: Always exposed (7 tools)
  * - advanced: Exposed by default, includes core (30 tools)
- * - full: All tools including governance (43 tools)
+ * - full: All tools including governance (44 tools)
  *
  * Control: RECALLNEST_MCP_TIER=core|advanced|full
  */
@@ -79,6 +79,7 @@ const TOOL_TIERS: Record<string, ToolTier> = {
   distill_session: "advanced",
   scan_skill_promotions: "governance",
   promote_scan: "governance",
+  promote_synthesis: "governance",
   manage_alias: "governance",
   forget_memory: "advanced",
 

package/src/mcp-tools-advanced.ts

@@ -633,10 +633,11 @@ registerTool(
   "dream",
   "Run a full memory consolidation cycle (Orient, Gather, Consolidate, Prune). Side effect: may archive low-value entries and generate insight memories. Use when memory count is high and you need periodic maintenance.",
   {
-    scope: z.string().min(1).max(160).optional().describe("Scope to consolidate, e.g. 'project:myapp'. Omit to consolidate across all scopes"),
+    scope: z.string().min(1).max(160).optional().describe("Scope to consolidate, e.g. 'project:myapp'. Matched exactly by default — a scope name is treated as itself, not as a prefix family. Omit to consolidate across all scopes"),
     force: z.boolean().default(false).describe("Set to true to force consolidation even if recent write count is below the automatic threshold"),
+    familyMatch: z.boolean().default(false).describe("Set to true to also consolidate child scopes sharing this prefix (e.g. 'memory' would additionally pull in 'memory:pivot'). Off by default: merging sibling scopes into one clustering round mixes unrelated material."),
   },
-  async ({ scope, force }) => {
+  async ({ scope, force, familyMatch }) => {
     const resolvedScope = scope || "project:default";
     const components = getComponents();
     const result = await runDream({
@@ -646,6 +647,10 @@ registerTool(
       scope: resolvedScope,
       force,
       kgStore: getKGStore(),
+      // MCP 调用方给的都是具体 scope 名，family 语义在这里是意外面：
+      // `dream({scope: "memory"})` 会连 `memory:pivot` 一起卷进去（2026-08-16 实测）。
+      // 默认改精确是**行为变更**，要 family 得显式要。
+      scopeMatch: familyMatch ? "family" : "exact",
     });
     return {
       content: [{ type: "text" as const, text: formatDreamResult(result) }],

package/src/mcp-tools-core.ts

@@ -13,6 +13,7 @@ import { buildSessionCheckpointResult } from "./session-engine.js";
 import { formatCheckpointSaved, formatCheckpointSummary, formatResumeContext } from "./session-output.js";
 import { matchesTemporalConstraint, type TemporalConstraint } from "./temporal-parser.js";
 import { buildManagedCheckpointObservation, buildManagedResumeObservation } from "./workflow-observation-managed.js";
+import { PROCESS_READER_ID, recentRecallHits } from "./recall-ledger.js";
 import { buildWorkflowObservationRecord } from "./workflow-observation-engine.js";
 import type { ToolRegistryDeps } from "./mcp-tool-deps.js";
 import type { RetrievalResult } from "./retriever.js";
@@ -65,7 +66,16 @@ export function registerCoreTools(deps: ToolRegistryDeps): void {
 
   async function saveManagedObservation(observation: Parameters<typeof buildWorkflowObservationRecord>[0]): Promise<void> {
     try {
-      const record = buildWorkflowObservationRecord(observation);
+      // P0 join key：managed observation 是最该带它的一类——`resume_context` 本身
+      // 就是「读了一批记忆」的动作，它的成败与那批记忆直接相关。
+      // （api-server 那份同名函数刻意不加：HTTP server 一个进程服务多个客户端，
+      //  「一进程 ≈ 一会话」的前提在那里不成立，加了只会 join 出假配对。）
+      const recalledIds = recentRecallHits();
+      const record = buildWorkflowObservationRecord({
+        readerId: PROCESS_READER_ID,
+        ...(recalledIds.length > 0 ? { recalledIds } : {}),
+        ...(observation as Record<string, unknown>),
+      });
       await workflowObservationStore.save(record);
     } catch (error) {
       console.error("[RecallNest MCP] Failed to persist managed workflow observation:", error);

package/src/mcp-tools-governance.ts

@@ -8,13 +8,20 @@ import { formatConflictAudit, formatConflictClusters, formatConflictEscalation,
 import { ConflictStatusSchema } from "./conflict-schema.js";
 import { ConsolidationEngine, formatConsolidationResult } from "./consolidation-engine.js";
 import { archiveDirtyBriefAsset, listDirtyBriefAssets } from "./memory-assets.js";
-import { scanMemoryPromotions, buildPromoteScanDeps, formatPromoteScanResult } from "./memory-promotion.js";
+import {
+  scanMemoryPromotions,
+  scanSynthesisPromotions,
+  buildPromoteScanDeps,
+  formatPromoteScanResult,
+  formatSynthesisPromoteResult,
+} from "./memory-promotion.js";
 import { aliasMapFilePath, expandQuery, explainUserAliases, listUserAliases, removeUserAlias, upsertUserAlias } from "./query-expander.js";
 import { recordSkillOutcome } from "./skill-engine.js";
 import { scanForPromotions, formatPromotionResult } from "./skill-promotion.js";
 import { buildWorkflowEvidence, buildWorkflowObservationRecord, inspectWorkflowDashboard, inspectWorkflowHealth } from "./workflow-observation-engine.js";
 import { formatWorkflowEvidencePack, formatWorkflowHealthDashboard, formatWorkflowHealthReport, formatWorkflowObservationSaved } from "./workflow-observation-output.js";
 import { WorkflowObservationOutcomeSchema } from "./workflow-observation-schema.js";
+import { PROCESS_READER_ID, recentRecallHits } from "./recall-ledger.js";
 import type { ToolRegistryDeps } from "./mcp-tool-deps.js";
 import { withLock } from "./distill-lock.js";
 
@@ -36,8 +43,14 @@ registerTool(
     tools: z.array(z.string().min(1).max(60)).max(6).default([]).describe("Optional tools involved"),
     skillId: z.string().min(1).max(128).optional().describe("Optional skill id to bump. When present and outcome is success, the skill's successCount increments; otherwise failureCount increments. Missing/corrupt skills are skipped silently (does not block observation write)."),
     idempotencyKey: z.string().min(1).max(160).optional().describe("Optional stable request key; repeated saves with the same key replace the prior observation"),
+    recalledIds: z.array(z.string().min(1).max(128)).max(64).optional().describe("Optional memory ids this task actually used. Omit to auto-fill from what this session retrieved in the last 30 minutes — that auto-fill is what makes (memory, outcome) value back-propagation possible."),
   },
-  async ({ workflowId, outcome, summary, scope, source, signal, task, tags, tools, skillId, idempotencyKey }) => {
+  async ({ workflowId, outcome, summary, scope, source, signal, task, tags, tools, skillId, idempotencyKey, recalledIds }) => {
+    // P0 join key：不传就用本进程的检索账本自动补。这一步是价值回溯的前提——
+    // 少了它，库里就只剩「有结果没参与者」和「有参与者没结果」两堆对不上的数据。
+    const resolvedRecalledIds = recalledIds && recalledIds.length > 0
+      ? recalledIds
+      : recentRecallHits();
     const record = buildWorkflowObservationRecord({
       workflowId,
       outcome,
@@ -50,6 +63,8 @@ registerTool(
       tools,
       skillId,
       idempotencyKey,
+      readerId: PROCESS_READER_ID,
+      ...(resolvedRecalledIds.length > 0 ? { recalledIds: resolvedRecalledIds } : {}),
     });
     const stored = await workflowObservationStore.save(record);
 
@@ -332,6 +347,7 @@ registerTool(
         getById: store.getById.bind(store),
         vectorSearch: store.vectorSearch.bind(store),
         update: async () => null, // no-op in dry-run
+        patchMetadataBatch: async () => 0, // no-op in dry-run（3a 批量写通道，2026-08-14）
       };
       const engine = new ConsolidationEngine(readOnlyStore, { clusterThreshold, mergeThreshold, maxEntriesPerRun: maxEntries }, getKGStore());
       const result = await engine.run(scope);
@@ -377,11 +393,13 @@ registerTool(
   {
     scope: z.string().min(1).max(160).describe("Project scope to scan for promotion candidates"),
     minOccurrences: z.number().min(2).max(20).default(3).describe("Minimum similar cases to trigger a promotion suggestion"),
+    minDistinctSources: z.number().min(1).max(10).default(2).describe("How many DIFFERENT sources (episodes) a cluster must span. Counting similar entries is not the same as counting distinct experiences — the same pothole hit three times is one experience, not a rule. Set 1 to disable this check. Abstains (never rejects) when the entries carry no source pointer."),
   },
-  async ({ scope, minOccurrences }) => {
+  async ({ scope, minOccurrences, minDistinctSources }) => {
     const { store } = getComponents();
     const result = await scanForPromotions(store, scope, {
       minCaseOccurrences: minOccurrences,
+      minDistinctSources,
     });
 
     return {
@@ -472,4 +490,28 @@ registerTool(
     };
   },
 );
+
+registerTool(
+  "promote_synthesis",
+  "Scan dream-synthesized conclusions (cluster insights and cross-memory patterns, which are written on the evidence layer and therefore excluded from stable memory) and promote the well-supported ones into a durable copy. Eligibility comes from the conclusion's own validated evidence set, not from repetition. Default dry-run (no writes); when dryRun=false it writes durable entries through the same promote path as promote_memory, so canonicalKey dedup makes re-runs a revision rather than a duplicate. The synthesized row itself is never modified.",
+  {
+    scope: z.string().min(1).max(160).describe("Scope to scan, e.g. memory"),
+    dryRun: z.boolean().default(true).describe("When true (default), only report candidates without writing"),
+    minDistinctEvidence: z.number().int().min(2).max(20).default(2).describe("Min distinct, still-active evidence memories behind the conclusion"),
+    minImportance: z.number().min(0).max(1).default(0.6).describe("Min importance of the synthesized conclusion itself"),
+  },
+  async ({ scope, dryRun, minDistinctEvidence, minImportance }) => {
+    const { store, embedder } = getComponents();
+    const kgExtractor = getKGExtractor();
+    const deps = buildPromoteScanDeps({ store, embedder, conflictStore, kgExtractor });
+    const result = await scanSynthesisPromotions(deps, scope, { dryRun, minDistinctEvidence, minImportance });
+
+    return {
+      content: [{
+        type: "text" as const,
+        text: formatSynthesisPromoteResult(result),
+      }],
+    };
+  },
+);
 }

package/src/memory-evolution.ts

@@ -115,6 +115,22 @@ export function patchEvolution(
   return JSON.stringify(parsed);
 }
 
+/**
+ * patchEvolution 的对象版：给 patchMetadataBatch 的 patchFn 用（那条通道进出都是
+ * 已解析的 metadata 对象，不该为了复用字符串版而反复 stringify/parse）。
+ * 就地修改并返回同一对象，语义与 patchEvolution 一致（浅合并 evolution 子对象）。
+ */
+export function patchEvolutionOnMeta(
+  meta: Record<string, unknown>,
+  patch: Partial<EvolutionMetadata>,
+): Record<string, unknown> {
+  const existing = meta.evolution !== null && typeof meta.evolution === "object" && !Array.isArray(meta.evolution)
+    ? (meta.evolution as Partial<EvolutionMetadata>)
+    : undefined;
+  meta.evolution = { ...existing, ...patch };
+  return meta;
+}
+
 // ---------------------------------------------------------------------------
 // Predicates
 // ---------------------------------------------------------------------------

package/src/memory-output.ts

@@ -1,3 +1,4 @@
+import { formatAgeLabel } from "./age-label.js";
 import type { MemoryEntry } from "./store.js";
 import type { RetrievalResult } from "./retriever.js";
 import type { RetrievalProfileName } from "./retrieval-profiles.js";
@@ -41,6 +42,7 @@ export interface DistilledEvidence {
   source: string;
   scope: string;
   date: string;
+  age: string;
   retrievalPath: string;
   snippet: string;
 }
@@ -332,6 +334,7 @@ function buildSearchRow(index: number, query: string, result: RetrievalResult):
     getTierLabel(result).padEnd(10),
     getSourceLabel(result).padEnd(7),
     getDateLabel(result.entry.timestamp),
+    formatAgeLabel(result.entry.timestamp).padEnd(5),
     getRetrievalPath(result).padEnd(20),
     getFileLabel(result),
     cleanSnippet(pickBestSnippet(query, result.entry.text), 120),
@@ -374,13 +377,13 @@ export function formatFullResults(
     `Profile : ${context.profile}`,
     `Hits    : ${results.length}`,
     "",
-    "#  ID       Score Category     Tier       Source  Date       Retrieval Path       File / Snippet",
-    "-- -------- ----- ------------ ---------- ------- ---------- -------------------- --------------",
+    "#  ID       Score Category     Tier       Source  Date       Age   Retrieval Path       File / Snippet",
+    "-- -------- ----- ------------ ---------- ------- ---------- ----- -------------------- --------------",
   ];
 
   for (let i = 0; i < results.length; i++) {
     const row = buildSearchRow(i, context.query, results[i]);
-    lines.push(`${row[0]} ${row[1]} ${row[2]} ${row[3]} ${row[4]} ${row[5]} ${row[6]} ${row[7]} ${row[8]} | ${row[9]}`);
+    lines.push(`${row[0]} ${row[1]} ${row[2]} ${row[3]} ${row[4]} ${row[5]} ${row[6]} ${row[7]} ${row[8]} ${row[9]} | ${row[10]}`);
     lines.push(`   prov : ${getProvenanceSummary(results[i])}`);
     // Full mode: append metadata details
     const meta = parseMetadata(results[i].entry);
@@ -424,13 +427,13 @@ export function formatSearchResults(
     `Profile : ${context.profile}`,
     `Hits    : ${results.length}`,
     "",
-    "#  ID       Score Category     Tier       Source  Date       Retrieval Path       File / Snippet",
-    "-- -------- ----- ------------ ---------- ------- ---------- -------------------- --------------",
+    "#  ID       Score Category     Tier       Source  Date       Age   Retrieval Path       File / Snippet",
+    "-- -------- ----- ------------ ---------- ------- ---------- ----- -------------------- --------------",
   ];
 
   for (let i = 0; i < results.length; i++) {
     const row = buildSearchRow(i, context.query, results[i]);
-    lines.push(`${row[0]} ${row[1]} ${row[2]} ${row[3]} ${row[4]} ${row[5]} ${row[6]} ${row[7]} ${row[8]} | ${row[9]}`);
+    lines.push(`${row[0]} ${row[1]} ${row[2]} ${row[3]} ${row[4]} ${row[5]} ${row[6]} ${row[7]} ${row[8]} ${row[9]} | ${row[10]}`);
     lines.push(`   prov : ${getProvenanceSummary(results[i])}`);
     // Freshness: only shown for memories that declared dependsOn (opt-in, cheap check).
     const fresh = evaluateEntryFreshness(results[i].entry.metadata, freshnessCache);
@@ -529,7 +532,7 @@ export function formatExplainResults(
     const session = getSessionLabel(result);
     const why = buildWhyMatched(context.query, result);
 
-    lines.push(`${i + 1}. ${result.entry.id.slice(0, 8)} | ${score} | ${getSourceLabel(result)} | ${getDateLabel(result.entry.timestamp)}`);
+    lines.push(`${i + 1}. ${result.entry.id.slice(0, 8)} | ${score} | ${getSourceLabel(result)} | ${getDateLabel(result.entry.timestamp)} (${formatAgeLabel(result.entry.timestamp)})`);
     lines.push(`   category: ${getCategoryLabel(result)}`);
     lines.push(`   tier    : ${getTierLabel(result)}`);
     lines.push(`   path    : ${retrieval}`);
@@ -592,6 +595,7 @@ export function summarizeResults(
       source: getSourceLabel(result),
       scope: result.entry.scope,
       date: getDateLabel(result.entry.timestamp),
+      age: formatAgeLabel(result.entry.timestamp),
       retrievalPath: getRetrievalPath(result),
       snippet: pickBestSnippet(context.query, normalizeRecallText(result)),
     });
@@ -654,7 +658,7 @@ export function distillResults(
 
   lines.push("", "Evidence");
   summary.evidence.forEach((item, index) => {
-    lines.push(`${index + 1}. ${item.source} | ${item.date} | ${item.retrievalPath} | ${item.snippet}`);
+    lines.push(`${index + 1}. ${item.source} | ${item.date} (${item.age}) | ${item.retrievalPath} | ${item.snippet}`);
   });
 
   lines.push("", "Reusable Memory Candidates");