sensorium-mcp 3.0.54 → 3.0.55

package/dist/data/memory/narrative.js

@@ -2,11 +2,11 @@
  * Temporal Narrative Generator
  *
  * Produces multi-resolution narratives from episodes and semantic notes:
- * - day:       detailed events (~500 tokens)
- * - week:      key decisions and progress (~300 tokens)
- * - month:     high-level arc (~200 tokens)
- * - quarter:   strategic 3-month arc (~150 tokens)
- * - half_year: bird's-eye 6-month arc (~120 tokens)
+ * - day:       detailed events (~400 tokens)
+ * - week:      key decisions and progress (~800 tokens)
+ * - month:     high-level arc (~1200 tokens)
+ * - quarter:   strategic 3-month arc (~2000 tokens)
+ * - half_year: bird's-eye 6-month arc (~2500 tokens)
  *
  * These narratives replace raw note dumps in bootstrap and give the agent
  * coherent temporal awareness across long-running sessions.
@@ -25,7 +25,7 @@ const NARRATIVE_FILLER_PHRASES = [
     /\bseveral enhancements\b/i,
     /\bsignificant (evolution|strides|developments?)\b/i,
     /\boverall.{0,20}(positive|good|well)\b/i,
-    /\bpivotal moments?\b/i,
+    /\bpivotal (moments?|decisions?|turning)\b/i,
     /\bcrucial (step|milestone|decision)\b/i,
     /\bnotable (milestone|achievement|development)\b/i,
     /\bsubstantial (progress|improvement)\b/i,
@@ -34,6 +34,22 @@ const NARRATIVE_FILLER_PHRASES = [
     /\bas I (navigated|reflected|observed|witnessed)\b/i,
     /\bthis (prompted|led) me to reflect\b/i,
     /\bI (noticed|observed|witnessed) a (critical|pivotal|key)\b/i,
+    /\bmarked by a series of\b/i,
+    /\bpart of a broader effort\b/i,
+    /\bshaped the (direction|trajectory)\b/i,
+    /\bturning points? that\b/i,
+    /\bset the stage for\b/i,
+    /\bnot only .{5,40} but also\b/i,
+    /\bculminating in\b/i,
+    /\bthe focus remains on\b/i,
+    /\bdriven by a commitment\b/i,
+    /\bthis decision to\b/i,
+    /\bthe current status reflects\b/i,
+    /\bresulting in a more\b/i,
+    /\bleading to more\b/i,
+    /\baddress(ed|ing) the root causes? of\b/i,
+    /\benhancing overall\b/i,
+    /\baligning with\b/i,
 ];
 function findFillerPhrase(text) {
     for (const pattern of NARRATIVE_FILLER_PHRASES) {
@@ -43,6 +59,64 @@ function findFillerPhrase(text) {
     }
     return null;
 }
+function findDateViolation(text, periodStart, periodEnd) {
+    const startDate = new Date(periodStart);
+    const endDate = new Date(periodEnd);
+    const validYears = new Set();
+    for (let y = startDate.getFullYear(); y <= endDate.getFullYear(); y++)
+        validYears.add(y);
+    // Check standalone year references (e.g. "in 2025", "2025–2026")
+    const yearMatches = text.matchAll(/\b(20\d{2})\b/g);
+    for (const m of yearMatches) {
+        const year = parseInt(m[1], 10);
+        if (!validYears.has(year))
+            return `year ${year} outside valid range ${[...validYears].join("–")}`;
+    }
+    // Check month+year combos (e.g. "March 2026", "Apr 2025")
+    const monthNames = ["january", "february", "march", "april", "may", "june", "july", "august", "september", "october", "november", "december"];
+    const monthPattern = /\b(Jan(?:uary)?|Feb(?:ruary)?|Mar(?:ch)?|Apr(?:il)?|May|June?|July?|Aug(?:ust)?|Sep(?:tember)?|Oct(?:ober)?|Nov(?:ember)?|Dec(?:ember)?)\s+(20\d{2})\b/gi;
+    for (const m of text.matchAll(monthPattern)) {
+        const monthStr = m[1].toLowerCase().slice(0, 3);
+        const monthIdx = monthNames.findIndex((mn) => mn.startsWith(monthStr));
+        const year = parseInt(m[2], 10);
+        if (monthIdx === -1)
+            continue;
+        const refDate = new Date(year, monthIdx, 15);
+        const windowStart = new Date(startDate);
+        windowStart.setDate(windowStart.getDate() - 7);
+        const windowEnd = new Date(endDate);
+        windowEnd.setDate(windowEnd.getDate() + 7);
+        if (refDate < windowStart || refDate > windowEnd) {
+            return `"${m[0]}" falls outside the period ${periodStart.slice(0, 10)} to ${periodEnd.slice(0, 10)}`;
+        }
+    }
+    return null;
+}
+function findLowDensitySentences(text) {
+    const sentences = text.split(/(?<=[.!?])\s+/).filter(s => s.length > 20);
+    if (sentences.length === 0)
+        return { count: 0, total: 0, examples: [] };
+    const identifierPattern = /\b(?:\d{4}[-/]\d{2}[-/]\d{2}|\d{1,2}:\d{2}|v\d+\.\d+|#\d+|ID\s*\d+|\d{3,}|(?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)\w*\s+\d{1,2}|(?:Monday|Tuesday|Wednesday|Thursday|Friday|Saturday|Sunday))/i;
+    const quotedNamePattern = /['"][^'"]+['"]|`[^`]+`/;
+    const namedEntityPattern = /thread\s*\d+|ID\s*\d+|(?:MCP|API|LLM|GPT|SQL|WAL|CLI|SDK|PR|CI|CD)\b/i;
+    const midSentenceProperNoun = (s) => {
+        const afterFirst = s.replace(/^\S+\s+/, "");
+        return /\b[A-Z][a-z]{2,}/.test(afterFirst);
+    };
+    const hasNumber = (s) => /\d+/.test(s);
+    const lowDensity = [];
+    for (const sentence of sentences) {
+        const hasIdentifier = identifierPattern.test(sentence);
+        const hasProperNoun = midSentenceProperNoun(sentence);
+        const hasQuotedName = quotedNamePattern.test(sentence);
+        const hasEntity = namedEntityPattern.test(sentence);
+        const hasNum = hasNumber(sentence);
+        if (!hasIdentifier && !hasProperNoun && !hasQuotedName && !hasEntity && !hasNum) {
+            lowDensity.push(sentence.slice(0, 80));
+        }
+    }
+    return { count: lowDensity.length, total: sentences.length, examples: lowDensity.slice(0, 3) };
+}
 /** Cooldown per resolution before regenerating */
 const COOLDOWNS = {
     day: 2 * 60 * 60 * 1000, // 2 hours
@@ -53,11 +127,23 @@ const COOLDOWNS = {
 };
 /** Target output token count per resolution */
 const OUTPUT_TOKEN_TARGETS = {
-    day: 500,
-    week: 300,
-    month: 200,
-    quarter: 150,
-    half_year: 120,
+    day: 400,
+    week: 800,
+    month: 1600,
+    quarter: 3000,
+    half_year: 4000,
+};
+const INPUT_CHAR_BUDGETS = {
+    day: { episodes: 30_000, notes: 10_000 },
+    week: { episodes: 50_000, notes: 15_000 },
+    month: { episodes: 60_000, notes: 20_000 },
+    quarter: { episodes: 80_000, notes: 25_000 },
+    half_year: { episodes: 100_000, notes: 30_000 },
+};
+const CHILD_RESOLUTION = {
+    month: "week",
+    quarter: "month",
+    half_year: "quarter",
 };
 const NARRATIVE_MODEL = process.env.NARRATIVE_MODEL || process.env.CONSOLIDATION_MODEL || "gpt-4o";
 // ─── Period Calculation ──────────────────────────────────────────────────────
@@ -96,6 +182,12 @@ function getPeriodBounds(resolution) {
     const _exhaustive = resolution;
     throw new Error(`Unhandled narrative resolution: ${_exhaustive}`);
 }
+function getEarliestEpisodeDate(db, threadId) {
+    const row = db
+        .prepare(`SELECT MIN(timestamp) as earliest FROM episodes WHERE thread_id = ?`)
+        .get(threadId);
+    return row?.earliest ?? null;
+}
 // ─── Source Data Collection ──────────────────────────────────────────────────
 function getEpisodesInPeriod(db, threadId, start, end) {
     const rows = db
@@ -149,33 +241,95 @@ function getNotesInPeriod(db, threadId, start) {
         qualityScore: r.quality_score ?? null,
     }));
 }
+// ─── Child Narrative Retrieval ──────────────────────────────────────────────
+function getChildNarratives(db, threadId, resolution, start, end) {
+    const child = CHILD_RESOLUTION[resolution];
+    if (!child)
+        return [];
+    const rows = db
+        .prepare(`SELECT * FROM temporal_narratives
+       WHERE thread_id = ? AND resolution = ? AND period_start >= ? AND period_start <= ?
+       ORDER BY period_start ASC`)
+        .all(threadId, child, start, end);
+    return rows.map((r) => ({
+        id: r.id,
+        threadId: r.thread_id,
+        resolution: r.resolution,
+        periodStart: r.period_start,
+        periodEnd: r.period_end,
+        narrative: r.narrative,
+        sourceEpisodeCount: r.source_episode_count,
+        sourceNoteCount: r.source_note_count,
+        model: r.model,
+        createdAt: r.created_at,
+    }));
+}
+function formatChildNarrativesForLLM(narratives) {
+    return narratives
+        .map((n) => {
+        const fmtDate = (d) => new Date(d).toLocaleDateString("en-US", { month: "short", day: "numeric", year: "numeric" });
+        return `--- ${n.resolution} narrative (${fmtDate(n.periodStart)} – ${fmtDate(n.periodEnd)}, ${n.sourceEpisodeCount} episodes) ---\n${n.narrative}`;
+    })
+        .join("\n\n");
+}
 // ─── Content Extraction ──────────────────────────────────────────────────────
 function extractEpisodeText(ep) {
     const content = ep.content;
-    const text = (content.text || content.caption || content.message || "");
-    return text.slice(0, 300);
+    const text = (content.text || content.raw || content.caption || content.message || "");
+    return text.slice(0, 1500);
+}
+function formatEpisodeLine(ep, text) {
+    const ts = ep.timestamp.slice(0, 16).replace("T", " ");
+    const imp = ep.importance != null && ep.importance !== 0.5 ? ` [imp: ${ep.importance.toFixed(1)}]` : "";
+    const tags = ep.topicTags.length > 0 ? ` [tags: ${ep.topicTags.join(", ")}]` : "";
+    return `[${ts}] (${ep.type}/${ep.modality})${imp}${tags} ${text}`;
 }
 function formatEpisodesForLLM(episodes, maxChars) {
-    const lines = [];
-    let chars = 0;
-    for (const ep of episodes) {
+    const importanceBudget = Math.round(maxChars * 0.3);
+    // Pool 1: top episodes by importance (guaranteed inclusion)
+    const byImportance = [...episodes].sort((a, b) => (b.importance ?? 0.5) - (a.importance ?? 0.5));
+    const selected = new Set();
+    const pool1 = [];
+    let pool1Chars = 0;
+    for (const ep of byImportance) {
         const text = extractEpisodeText(ep);
         if (!text.trim())
             continue;
-        const ts = ep.timestamp.slice(0, 16).replace("T", " ");
-        const line = `[${ts}] (${ep.type}/${ep.modality}) ${text}`;
-        if (chars + line.length > maxChars)
+        const line = formatEpisodeLine(ep, text);
+        if (pool1Chars + line.length > importanceBudget)
             break;
-        lines.push(line);
-        chars += line.length;
+        pool1.push({ ep, line });
+        selected.add(ep.episodeId);
+        pool1Chars += line.length;
     }
-    return lines.join("\n");
+    // Pool 2: chronological fill (remaining budget)
+    const remainingBudget = maxChars - pool1Chars;
+    const chronological = [...episodes]
+        .filter(ep => !selected.has(ep.episodeId))
+        .sort((a, b) => (a.timestamp < b.timestamp ? -1 : 1));
+    const pool2 = [];
+    let pool2Chars = 0;
+    for (const ep of chronological) {
+        const text = extractEpisodeText(ep);
+        if (!text.trim())
+            continue;
+        const line = formatEpisodeLine(ep, text);
+        if (pool2Chars + line.length > remainingBudget)
+            break;
+        pool2.push({ ep, line });
+        pool2Chars += line.length;
+    }
+    // Merge both pools and sort chronologically for coherent reading
+    return [...pool1, ...pool2]
+        .sort((a, b) => (a.ep.timestamp < b.ep.timestamp ? -1 : 1))
+        .map(x => x.line)
+        .join("\n");
 }
 function formatNotesForLLM(notes, maxChars) {
     const lines = [];
     let chars = 0;
     for (const n of notes) {
-        const line = `- [${n.type}] ${n.content.slice(0, 200)} (conf: ${n.confidence.toFixed(2)})`;
+        const line = `- [${n.type}] ${n.content.slice(0, 600)} (conf: ${n.confidence.toFixed(2)})`;
         if (chars + line.length > maxChars)
             break;
         lines.push(line);
@@ -188,28 +342,59 @@ function buildPrompt(resolution, episodesText, notesText, episodeCount, periodLa
     const startYear = new Date(periodStart).getFullYear();
     const endYear = new Date().getFullYear();
     const instructions = {
-        day: `Write a detailed narrative of what happened today (${periodLabel}). Include specific events, decisions made, problems encountered, and outcomes. Use chronological order. Be concrete — mention specific features, fixes, discussions. For each major event, explain WHY it happened and what it caused. Don't just list what happened — explain the chain of consequences. Target ~500 tokens.`,
-        week: `Write a concise narrative of the key developments this past week (${periodLabel}). For each development, explain: what triggered it, what decision was made, and what resulted. Connect events causally — show how Monday's decision led to Wednesday's outcome. Group by causal chains, not just themes. Target ~300 tokens.`,
-        month: `Write a narrative arc for this past month (${periodLabel}). Structure around 2-3 major cause-effect chains: what problem or opportunity emerged, what decisions were made in response, and how those decisions played out. Name specific features, tools, or systems — not abstractions. End with what's unresolved. Target ~200 tokens.`,
-        quarter: `Write a narrative arc for this quarter (${periodLabel}). Identify 2-3 pivotal decisions or turning points. For each: what was the situation before, what changed, and what was the lasting impact. Show how the project's direction evolved through concrete cause-and-effect, not vague 'themes'. Target ~150 tokens.`,
-        half_year: `Write a bird's-eye narrative for this half-year (${periodLabel}). Capture the 1-2 biggest transformations: where the project started, what specific events or decisions caused the shift, and where it stands now. Every claim must reference a concrete event or decision — no unsupported generalizations like 'significant progress' or 'notable improvements'. Target ~120 tokens.`,
+        day: `Write a narrative of what happened today (${periodLabel}). Tell the story chronologically — what happened, why, what it caused. Include timestamps (hours:minutes) for each event. Write in flowing prose, connecting events with cause and effect. Be specific: name systems, threads, versions, IDs. Target ~400 tokens.`,
+        week: `Write a narrative of the key developments this week (${periodLabel}). Tell the story chronologically by day. For each event: what triggered it, what was decided, what resulted. Connect events across days — show how Monday's decision led to Wednesday's outcome. Write in flowing prose, not a list. Use day-level dates, no hours. Target ~800 tokens.`,
+        month: `Write a chronological decision log for this month (${periodLabel}). Format: "Date — decision/event. Reason. Result." One entry per line. Each entry should have enough context to stand alone — a reader who sees only this entry should understand why it matters. Only include: decisions that changed project direction, bugs that broke something, features shipped. Skip routine fixes, code reviews, type errors, status checks. Day-level dates, no hours. End with unresolved items. Target ~1600 tokens.`,
+        quarter: `Write a chronological decision log for this quarter (${periodLabel}). Format: "Date — decision/event. Reason. Result." One entry per line. Each entry should have enough context to stand alone — explain what problem existed before, what decision was made, and what changed after. Only include: decisions that changed project direction, major bugs, features shipped, architectural changes. Skip routine fixes, minor code reviews, type errors. Episodes marked [imp: 0.6+] are operator-priority — include them. Day-level dates, strict chronological order. End with unresolved items. Target ~3000 tokens.`,
+        half_year: `Write a chronological decision log for this half-year (${periodLabel}). Format: "Date — decision/event. Reason. Result." One entry per line. Each entry should have enough context to stand alone — explain the situation before, what decision was made, and what changed as a result. Only include: decisions that changed project direction, major bugs, features shipped, architectural changes. Skip routine fixes, minor code reviews, type errors. Episodes marked [imp: 0.6+] are operator-priority — include them. Day-level dates, strict chronological order. End with current state. Target ~4000 tokens.`,
     };
-    return `You are a temporal memory narrator. You create coherent stories from raw interaction data.
+    const styleByResolution = {
+        day: `STYLE:
+- Write flowing prose, not bullet points or numbered lists. Connect events into a story.
+- First person for yourself ("I did..."), third person for the operator ("The operator...").
+- Name every system, thread, feature by exact name with IDs where available.
+- Be concrete — every sentence needs at least one identifier (name, version, date, ID, number).
+- Preserve cause-and-effect chains: "X happened because Y, which led to Z."
+- No filler phrases: "significant progress", "notable improvement", "pivotal moment", "crucial step".
+- NEVER open with "In [Month]..." or "During [Month]..." — start with what happened.
+- NEVER write introductory or concluding paragraphs that summarize.`,
+        week: `STYLE:
+- Write flowing prose, not bullet points or numbered lists. Connect events into a weekly story.
+- First person for yourself ("I did..."), third person for the operator ("The operator...").
+- Name every system, thread, feature by exact name with IDs where available.
+- Be concrete — every sentence needs at least one identifier (name, version, date, ID, number).
+- Preserve cause-and-effect chains across days.
+- No filler phrases: "significant progress", "notable improvement", "pivotal moment", "crucial step".
+- NEVER open with "In [Month]..." or "During [Month]..." — start with what happened.
+- NEVER write introductory or concluding paragraphs that summarize.`,
+        month: `STYLE:
+- Each log entry: 1-2 sentences with full context. A reader should understand the entry without reading others.
+- First person for yourself ("I did..."), third person for the operator ("The operator...").
+- Name every system, thread, feature by exact name with IDs where available.
+- No filler phrases: "significant progress", "notable improvement", "pivotal moment", "crucial step".
+- NEVER open with "In [Month]..." or "During [Month]..." or "The period was marked by...".
+- NEVER write introductory or concluding paragraphs.`,
+        quarter: `STYLE:
+- Each log entry: 1-3 sentences with full context. Explain the situation before the decision, not just the decision itself.
+- First person for yourself ("I did..."), third person for the operator ("The operator...").
+- Name every system, thread, feature by exact name with IDs where available.
+- No filler phrases: "significant progress", "notable improvement", "pivotal moment", "crucial step".
+- NEVER open with "In [Month]..." or "During [Month]..." or "The period was marked by...".
+- NEVER write introductory or concluding paragraphs.`,
+        half_year: `STYLE:
+- Each log entry: 1-3 sentences with full context. Explain the situation before the decision, not just the decision itself.
+- First person for yourself ("I did..."), third person for the operator ("The operator...").
+- Name every system, thread, feature by exact name with IDs where available.
+- No filler phrases: "significant progress", "notable improvement", "pivotal moment", "crucial step".
+- NEVER open with "In [Month]..." or "During [Month]..." or "The period was marked by...".
+- NEVER write introductory or concluding paragraphs.`,
+    };
+    return `You are a temporal memory narrator. You create concise records from raw interaction data.
 
 ${instructions[resolution]}
 
-FORMAT RULES:
-- Write in first person for yourself ("I did...", "I noticed...") and third person for the operator ("The operator...")
-- Use concrete timestamps when referencing specific events
-- Preserve causal chains: "X happened, which led to Y, resulting in Z"
-- Do NOT list facts — weave them into a narrative
-- Do NOT use bullet points — write flowing paragraphs
-- End with current status / what's next
-- NEVER use filler phrases like: "significant progress/evolution/strides", "notable improvement/milestone/achievement", "various features", "several enhancements", "pivotal moments", "crucial step/milestone/decision", "substantial/remarkable/meaningful progress", "overall good/positive", "as I navigated/reflected/observed", "this prompted me to reflect", "I noticed a critical/key ..."
-- Every claim must be grounded in a specific event, decision, or outcome from the source data
-- If you can't point to specific evidence, don't include it
-- NEVER open with a date-setting sentence like "In [Month Year]..." or "During [Month Year]..." — start with what actually happened
-- Only use years that appear in the period range (${startYear}${startYear !== endYear ? `–${endYear}` : ""}) — never substitute today's year for an earlier period
+${styleByResolution[resolution]}
+- Only use years in the range ${startYear}${startYear !== endYear ? `–${endYear}` : ""}.
 
 SOURCE DATA (${episodeCount} episodes):
 
@@ -219,7 +404,52 @@ ${episodesText || "(no episodes in this period)"}
 === Relevant Knowledge ===
 ${notesText || "(no notes)"}
 
-Write the narrative now. Plain text, no markdown headers.`;
+Write now. Plain text, no markdown.`;
+}
+function buildHierarchicalPrompt(resolution, childNarrativesText, childResolution, childCount, periodLabel, periodStart) {
+    const startYear = new Date(periodStart).getFullYear();
+    const endYear = new Date().getFullYear();
+    const instructions = {
+        month: `Write a chronological decision log for this month (${periodLabel}). You have ${childCount} weekly narratives below. Format: "Date — decision/event. Reason. Result." One entry per line. Each entry should have enough context to stand alone — a reader who sees only this entry should understand why it matters. Preserve important context from the weekly narratives — don't compress away the reasons and consequences. Only include: decisions that changed project direction, bugs that broke something, features shipped. Skip routine fixes, code reviews, type errors. Day-level dates, no hours. End with unresolved items. Target ~1600 tokens.`,
+        quarter: `Write a chronological decision log for this quarter (${periodLabel}). You have ${childCount} monthly narratives and possibly top-importance raw episodes below. Format: "Date — decision/event. Reason. Result." One entry per line. Each entry should have enough context to stand alone — explain what problem existed before, what decision was made, and what changed after. Don't just extract dates and facts from the monthly narratives — preserve the WHY and the consequences. Only include: decisions that changed project direction, major bugs, features shipped, architectural changes. Raw episodes marked [imp: 0.6+] are operator-priority — include them. Day-level dates, strict chronological order. End with unresolved items. Target ~3000 tokens.`,
+        half_year: `Write a chronological decision log for this half-year (${periodLabel}). You have ${childCount} quarterly narratives and possibly top-importance raw episodes below. Format: "Date — decision/event. Reason. Result." One entry per line. Each entry should have enough context to stand alone — explain the situation before, what decision was made, and what changed as a result. Don't just extract dates and facts — preserve the full story behind each entry from the source narratives. Only include: decisions that changed project direction, major bugs, features shipped, architectural changes. Raw episodes marked [imp: 0.6+] are operator-priority — include them. Day-level dates, strict chronological order. End with current state. Target ~4000 tokens.`,
+    };
+    return `You are a temporal memory narrator. You create concise decision logs by synthesizing lower-resolution narratives.
+
+${instructions[resolution]}
+
+STYLE:
+- Each log entry: 1-3 sentences with full context. Explain the situation, not just the fact.
+- First person for yourself ("I did..."), third person for the operator ("The operator...").
+- Name every system, thread, feature by exact name with IDs where available.
+- Every sentence must have at least one identifier (name, version, date, ID, number).
+- No filler phrases: "significant progress", "notable improvement", "pivotal moment", "crucial step", "driven by", "shaped the direction", "the focus remains on".
+- NEVER open with "In [Month]..." or "During [Month]..." or "The period was marked by...".
+- NEVER write introductory or concluding paragraphs.
+- Only use years in the range ${startYear}${startYear !== endYear ? `–${endYear}` : ""}.
+
+SOURCE: ${childCount} ${childResolution} narratives
+
+${childNarrativesText}
+
+Write now. Plain text, no markdown.`;
+}
+function buildFlatPrompt(db, knowledgeThreadId, resolution, start, end, periodLabel) {
+    const episodes = getEpisodesInPeriod(db, knowledgeThreadId, start, end);
+    const minEpisodes = resolution === "day" ? 3 : 5;
+    if (episodes.length < minEpisodes)
+        return null;
+    const notes = getNotesInPeriod(db, knowledgeThreadId, start);
+    const budget = INPUT_CHAR_BUDGETS[resolution];
+    const episodesText = formatEpisodesForLLM(episodes, budget.episodes);
+    if (episodesText.length < 200 && notes.length === 0)
+        return null;
+    const notesText = formatNotesForLLM(notes, budget.notes);
+    return {
+        prompt: buildPrompt(resolution, episodesText, notesText, episodes.length, periodLabel, start),
+        episodeCount: episodes.length,
+        noteCount: notes.length,
+    };
 }
 // ─── Cooldown Check ──────────────────────────────────────────────────────────
 function getLastNarrative(db, threadId, resolution) {
@@ -243,6 +473,30 @@ function getLastNarrative(db, threadId, resolution) {
         createdAt: row.created_at,
     };
 }
+function getCurrentNarrative(db, threadId, resolution) {
+    const row = db
+        .prepare(`SELECT * FROM temporal_narratives
+       WHERE thread_id = ? AND resolution = ?
+         AND period_start <= datetime('now')
+         AND period_end >= datetime('now', '-1 day')
+       ORDER BY julianday(period_end) - julianday(period_start) DESC, created_at DESC
+       LIMIT 1`)
+        .get(threadId, resolution);
+    if (!row)
+        return null;
+    return {
+        id: row.id,
+        threadId: row.thread_id,
+        resolution: row.resolution,
+        periodStart: row.period_start,
+        periodEnd: row.period_end,
+        narrative: row.narrative,
+        sourceEpisodeCount: row.source_episode_count,
+        sourceNoteCount: row.source_note_count,
+        model: row.model,
+        createdAt: row.created_at,
+    };
+}
 function isCooldownActive(db, threadId, resolution) {
     const last = getLastNarrative(db, threadId, resolution);
     if (!last)
@@ -251,25 +505,64 @@ function isCooldownActive(db, threadId, resolution) {
     return elapsed < COOLDOWNS[resolution];
 }
 // ─── Generation ──────────────────────────────────────────────────────────────
-async function generateNarrative(db, threadId, resolution) {
+function getChildWindowDays(resolution) {
+    switch (resolution) {
+        case "week": return 1;
+        case "month": return 7;
+        case "quarter": return 30;
+        case "half_year": return 90;
+        default: return 0;
+    }
+}
+function enumerateChildWindows(resolution, parentStart, parentEnd) {
+    const childRes = CHILD_RESOLUTION[resolution];
+    if (!childRes)
+        return [];
+    const windowDays = getChildWindowDays(resolution);
+    if (windowDays === 0)
+        return [];
+    const windows = [];
+    const pEnd = new Date(parentEnd);
+    const cur = new Date(parentStart);
+    cur.setUTCHours(0, 0, 0, 0);
+    while (cur < pEnd) {
+        const wEnd = new Date(cur);
+        wEnd.setUTCDate(wEnd.getUTCDate() + windowDays);
+        if (wEnd > pEnd)
+            wEnd.setTime(pEnd.getTime());
+        windows.push({ start: cur.toISOString(), end: wEnd.toISOString() });
+        cur.setUTCDate(cur.getUTCDate() + windowDays);
+    }
+    return windows;
+}
+async function backfillChildNarratives(db, threadId, resolution, parentStart, parentEnd) {
+    const childRes = CHILD_RESOLUTION[resolution];
+    if (!childRes)
+        return;
+    const knowledgeThreadId = resolveKnowledgeThreadId(threadId);
+    const existing = getChildNarratives(db, knowledgeThreadId, resolution, parentStart, parentEnd);
+    const existingStarts = new Set(existing.map(n => n.periodStart.slice(0, 10)));
+    const windows = enumerateChildWindows(resolution, parentStart, parentEnd);
+    for (const w of windows) {
+        if (existingStarts.has(w.start.slice(0, 10)))
+            continue;
+        const episodes = getEpisodesInPeriod(db, knowledgeThreadId, w.start, w.end);
+        if (episodes.length < 5)
+            continue;
+        log.info(`[narrative] backfilling ${childRes} for ${w.start.slice(0, 10)} — ${w.end.slice(0, 10)} (${episodes.length} episodes)`);
+        await generateNarrative(db, threadId, childRes, { start: w.start, end: w.end });
+    }
+}
+async function generateNarrative(db, threadId, resolution, periodOverride) {
     const apiKey = process.env.OPENAI_API_KEY;
     if (!apiKey)
         throw new Error("OPENAI_API_KEY not set");
     const knowledgeThreadId = resolveKnowledgeThreadId(threadId);
-    const { start, end } = getPeriodBounds(resolution);
-    const episodes = getEpisodesInPeriod(db, knowledgeThreadId, start, end);
-    // Sparse-thread guard: require minimum episode count to prevent fabricated narratives.
-    // Day narratives need fewer episodes; longer resolutions need more signal to be useful.
-    const minEpisodes = resolution === "day" ? 3 : 5;
-    if (episodes.length < minEpisodes)
-        return null;
-    const notes = getNotesInPeriod(db, knowledgeThreadId, start);
-    const maxChars = OUTPUT_TOKEN_TARGETS[resolution] * 16; // ~4 chars/token × 4 for source data headroom
-    const episodesText = formatEpisodesForLLM(episodes, maxChars * 2);
-    // Content density check: if episode text is too thin, skip generation to avoid fabrication
-    if (episodesText.length < 200 && notes.length === 0)
-        return null;
-    const notesText = formatNotesForLLM(notes, maxChars);
+    const bounds = periodOverride ?? getPeriodBounds(resolution);
+    // Clamp period start to earliest actual episode to prevent hallucinated dates
+    const earliest = getEarliestEpisodeDate(db, knowledgeThreadId);
+    const start = earliest && earliest > bounds.start ? earliest : bounds.start;
+    const end = bounds.end;
     const fmtShort = (d) => new Date(d).toLocaleDateString("en-US", { month: "short", day: "numeric", year: "numeric" });
     const fmtRange = `${fmtShort(start)} – ${fmtShort(end)}`;
     const periodLabels = {
@@ -280,27 +573,114 @@ async function generateNarrative(db, threadId, resolution) {
         half_year: `Half-year: ${fmtRange}`,
     };
     const periodLabel = periodLabels[resolution];
-    const prompt = buildPrompt(resolution, episodesText, notesText, episodes.length, periodLabel, start);
+    // Hierarchical composition: week+ resolutions compose from child narratives when available
+    const childRes = CHILD_RESOLUTION[resolution];
+    let prompt;
+    let sourceEpisodeCount;
+    let sourceNoteCount;
+    if (childRes) {
+        await backfillChildNarratives(db, threadId, resolution, start, end);
+        const children = getChildNarratives(db, knowledgeThreadId, resolution, start, end);
+        if (children.length > 0) {
+            const childText = formatChildNarrativesForLLM(children);
+            const coveredPeriods = new Set(children.flatMap(c => {
+                const dates = [];
+                const cur = new Date(c.periodStart);
+                const stop = new Date(c.periodEnd);
+                while (cur <= stop) {
+                    dates.push(cur.toISOString().slice(0, 10));
+                    cur.setUTCDate(cur.getUTCDate() + 1);
+                }
+                return dates;
+            }));
+            const episodes = getEpisodesInPeriod(db, knowledgeThreadId, start, end);
+            const gapEpisodes = episodes.filter(ep => !coveredPeriods.has(ep.timestamp.slice(0, 10)));
+            const budget = INPUT_CHAR_BUDGETS[resolution];
+            const gapText = gapEpisodes.length > 0 ? formatEpisodesForLLM(gapEpisodes, budget.episodes) : "";
+            // For quarter/half_year: inject top-20 highest-importance raw episodes so strategic
+            // decisions survive hierarchical compression
+            let topEpisodesText = "";
+            if (resolution === "quarter" || resolution === "half_year") {
+                const topN = [...episodes]
+                    .filter(ep => (ep.importance ?? 0.5) >= 0.6)
+                    .sort((a, b) => (b.importance ?? 0.5) - (a.importance ?? 0.5))
+                    .slice(0, 20);
+                if (topN.length > 0) {
+                    topEpisodesText = topN.map(ep => {
+                        const text = extractEpisodeText(ep);
+                        return text.trim() ? formatEpisodeLine(ep, text) : "";
+                    }).filter(Boolean).join("\n");
+                }
+            }
+            const parts = [`=== ${children.length} ${childRes} narrative(s) ===\n${childText}`];
+            if (topEpisodesText)
+                parts.push(`=== Top-importance raw episodes (for detail recovery) ===\n${topEpisodesText}`);
+            if (gapEpisodes.length > 0)
+                parts.push(`=== Raw episodes from uncovered periods ===\n${gapText}`);
+            const source = parts.join("\n\n");
+            prompt = buildHierarchicalPrompt(resolution, source, childRes, children.length, periodLabel, start);
+            sourceEpisodeCount = children.reduce((sum, c) => sum + c.sourceEpisodeCount, 0) + gapEpisodes.length;
+            sourceNoteCount = 0;
+            log.info(`[narrative] ${resolution}: ${children.length} ${childRes} narratives + ${gapEpisodes.length} gap episodes`);
+        }
+        else {
+            log.info(`[narrative] ${resolution}: no ${childRes} narratives available, falling back to raw episodes`);
+            const fallback = buildFlatPrompt(db, knowledgeThreadId, resolution, start, end, periodLabel);
+            if (!fallback)
+                return null;
+            prompt = fallback.prompt;
+            sourceEpisodeCount = fallback.episodeCount;
+            sourceNoteCount = fallback.noteCount;
+        }
+    }
+    else {
+        const fallback = buildFlatPrompt(db, knowledgeThreadId, resolution, start, end, periodLabel);
+        if (!fallback)
+            return null;
+        prompt = fallback.prompt;
+        sourceEpisodeCount = fallback.episodeCount;
+        sourceNoteCount = fallback.noteCount;
+    }
     const narrative = await chatCompletion([{ role: "user", content: prompt }], apiKey, {
         model: NARRATIVE_MODEL,
         temperature: 0.3,
-        maxTokens: OUTPUT_TOKEN_TARGETS[resolution],
+        maxTokens: Math.round(OUTPUT_TOKEN_TARGETS[resolution] * 1.5),
         timeoutMs: 60_000,
     });
     if (!narrative?.trim())
         return null;
-    // ─── Quality gate: reject filler language, retry once ──────────────────
+    // ─── Quality gate: reject filler language, date errors, and low density, retry once ───
     let finalNarrative = narrative.trim();
     const fillerMatch = findFillerPhrase(finalNarrative);
-    if (fillerMatch) {
-        log.warn(`[narrative] filler phrase detected (${fillerMatch}) in ${resolution} narrative — retrying`);
-        const retryPrompt = buildPrompt(resolution, episodesText, notesText, episodes.length, periodLabel, start)
-            + "\n\nRewrite the narrative using no filler phrases. Every claim must reference a specific event or decision from the source data.";
-        const retried = await chatCompletion([{ role: "system", content: "You are a temporal memory narrator." }, { role: "assistant", content: finalNarrative }, { role: "user", content: retryPrompt }], apiKey, { model: NARRATIVE_MODEL, temperature: 0.3, maxTokens: OUTPUT_TOKEN_TARGETS[resolution], timeoutMs: 60_000 });
+    const dateViolation = findDateViolation(finalNarrative, start, end);
+    const density = findLowDensitySentences(finalNarrative);
+    const densityRatio = density.total > 0 ? density.count / density.total : 0;
+    const hasDensityProblem = densityRatio > 0.35;
+    if (fillerMatch || dateViolation || hasDensityProblem) {
+        const issues = [];
+        if (fillerMatch)
+            issues.push(`filler phrase "${fillerMatch}"`);
+        if (dateViolation)
+            issues.push(`date violation: ${dateViolation}`);
+        if (hasDensityProblem)
+            issues.push(`${density.count}/${density.total} sentences lack identifiers (${(densityRatio * 100).toFixed(0)}%)`);
+        log.warn(`[narrative] quality issue in ${resolution} narrative (${issues.join(", ")}) — retrying`);
+        const corrections = [];
+        if (fillerMatch)
+            corrections.push("Rewrite using no filler phrases.");
+        if (dateViolation)
+            corrections.push(`Fix date error: ${dateViolation}. Only reference dates within the period ${start.slice(0, 10)} to ${end.slice(0, 10)}. Do NOT substitute the current year for dates in earlier periods.`);
+        if (hasDensityProblem)
+            corrections.push(`${density.count} sentences contain no identifiers (names, dates, numbers, IDs). Examples: ${density.examples.map(s => `"${s}..."`).join("; ")}. Every sentence must contain at least one concrete identifier.`);
+        const retryPrompt = prompt + "\n\n" + corrections.join(" ") + " Every claim must reference a specific event or decision from the source data.";
+        const retried = await chatCompletion([{ role: "user", content: retryPrompt }], apiKey, { model: NARRATIVE_MODEL, temperature: 0.3, maxTokens: Math.round(OUTPUT_TOKEN_TARGETS[resolution] * 1.5), timeoutMs: 60_000 });
         if (retried?.trim()) {
             const retryFiller = findFillerPhrase(retried.trim());
-            if (retryFiller) {
-                log.warn(`[narrative] retry still contains filler (${retryFiller}) in ${resolution} — keeping original`);
+            const retryDate = findDateViolation(retried.trim(), start, end);
+            const retryDensity = findLowDensitySentences(retried.trim());
+            const retryDensityRatio = retryDensity.total > 0 ? retryDensity.count / retryDensity.total : 0;
+            if (retryFiller || retryDate || retryDensityRatio > 0.35) {
+                log.warn(`[narrative] retry still has issues in ${resolution} — keeping original`);
             }
             else {
                 finalNarrative = retried.trim();
@@ -316,7 +696,7 @@ async function generateNarrative(db, threadId, resolution) {
        source_episode_count = excluded.source_episode_count,
        source_note_count = excluded.source_note_count,
        model = excluded.model,
-       created_at = datetime('now')`).run(knowledgeThreadId, resolution, start, end, finalNarrative, episodes.length, notes.length, NARRATIVE_MODEL);
+       created_at = datetime('now')`).run(knowledgeThreadId, resolution, start, end, finalNarrative, sourceEpisodeCount, sourceNoteCount, NARRATIVE_MODEL);
     return getLastNarrative(db, knowledgeThreadId, resolution);
 }
 // ─── Public API ──────────────────────────────────────────────────────────────
@@ -371,9 +751,9 @@ export function getNarrativesForBootstrap(db, threadId) {
     };
     try {
         for (const res of ["day", "week", "month", "quarter", "half_year"]) {
-            const last = getLastNarrative(db, threadId, res);
-            if (last) {
-                result[res] = last.narrative;
+            const narrative = getCurrentNarrative(db, threadId, res) ?? getLastNarrative(db, threadId, res);
+            if (narrative) {
+                result[res] = narrative.narrative;
             }
         }
     }