sensorium-mcp 3.0.54 → 3.0.56

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,63 @@ 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 narrative overview of this quarter (${periodLabel}) organized by initiative. Group by subsystem (e.g. "Dashboard", "Memory system", "Narrative pipeline", "Session management"). For each initiative, write 1-2 flowing paragraphs that tell the STORY of how it evolved: what the state was at the start of the quarter, what problems appeared, what decisions were made and why, and where it ended up. Reference specific dates, versions, and IDs as evidence within the prose — but do NOT use a list or log format. The reader should understand the arc of each initiative from a connected narrative, not from scanning dated entries. Include initiatives where direction changed, major bugs appeared, features shipped, or architecture shifted. Episodes marked [imp: 0.6+] are operator-priority — weave them in. End with a short "Unresolved" section. Target ~3000 tokens.`,
+        half_year: `Write a high-level evolution summary for this half-year (${periodLabel}). Do NOT repeat the quarterly grouped changelog — instead, synthesize it into 5-8 thematic arcs that show HOW the project evolved. For each arc: what the system looked like at the start, what forces drove change, and where it ended up. Example arcs: "Memory system evolution", "Session management maturity", "Narrative pipeline development". Within each arc, reference specific dates and versions as evidence, but the focus is the trajectory, not individual events. End with a "Current state" section: what works, what's fragile, what's next. 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:
+- Start each initiative with its name on its own line, then write 1-2 prose paragraphs. NO dated entries, NO log format.
+- Write flowing connected narrative — "The memory system entered the quarter with X problem. In April, Y happened because Z, which led to W by May."
+- 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.
+- Reference dates and versions naturally within prose, not as entry prefixes.
+- Show cross-month cause-effect — how one month's decisions shaped the next.
+- 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:
+- Write in thematic arc paragraphs, not a chronological list. Each arc = 1-2 paragraphs.
+- 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.
+- Within each arc, reference specific dates and versions as evidence of the trajectory.
+- 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 an introductory paragraph. Start directly with the first arc.`,
+    };
+    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 +408,72 @@ ${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 narrative overview of this quarter (${periodLabel}) organized by initiative. You have ${childCount} monthly narratives and possibly top-importance raw episodes below. Group by subsystem (e.g. "Dashboard", "Memory system", "Narrative pipeline", "Session management"). For each initiative, write 1-2 flowing paragraphs that tell the STORY of how it evolved: what the state was at the start, what problems appeared, what decisions were made and why, and where it ended up. Reference specific dates, versions, and IDs within the prose — but do NOT use a list or log format. Synthesize the monthly narratives into a connected story, don't just re-list their entries. The reader should understand each initiative's arc from prose, not from scanning dated lines. Raw episodes marked [imp: 0.6+] are operator-priority — weave them in. End with a short "Unresolved" section. Target ~3000 tokens.`,
+        half_year: `Write a high-level evolution summary for this half-year (${periodLabel}). You have ${childCount} quarterly changelogs and possibly top-importance raw episodes below. Do NOT repeat the quarterly grouped changelogs — instead, synthesize them into 5-8 thematic arcs that show HOW the project evolved over 6 months. For each arc: what the system looked like at the start of the period, what forces drove change (operator feedback, bugs, scaling needs), and where it ended up. Example arcs: "Memory system evolution", "Session management maturity", "Narrative pipeline development". Within each arc, reference specific dates and versions as evidence, but the focus is the trajectory — not individual events. End with a "Current state" section: what works, what's fragile, what's next. Target ~4000 tokens.`,
+    };
+    const styleByResolution = {
+        month: `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.`,
+        quarter: `STYLE:
+- Start each initiative with its name on its own line, then write 1-2 prose paragraphs. NO dated entries, NO log format.
+- Write flowing connected narrative that tells the story of each initiative's evolution.
+- 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.
+- Reference dates and versions naturally within prose, not as entry prefixes.
+- 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.`,
+        half_year: `STYLE:
+- Write in thematic arc paragraphs. Each arc = 1-2 paragraphs showing system evolution.
+- 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.
+- Reference dates and versions as evidence of the trajectory within prose.
+- 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.`,
+    };
+    return `You are a temporal memory narrator. You synthesize lower-resolution narratives into higher-level summaries.
+
+${instructions[resolution]}
+
+${styleByResolution[resolution] || ""}
+- 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 +497,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 +529,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 +597,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 +720,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 +775,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;
             }
         }
     }