sensorium-mcp 3.0.103 → 3.1.0-refactor.1

package/dist/data/memory/narrative.js

@@ -12,155 +12,18 @@
  * coherent temporal awareness across long-running sessions.
  */
 import { chatCompletion } from "../../integrations/openai/chat.js";
+import { buildPrompt, buildHierarchicalPrompt } from "../../llm/prompts/narrative.js";
+import { findFillerPhrase, findDateViolation, findLowDensitySentences, } from "./narrative-lint.js";
+import { CHILD_RESOLUTION, INPUT_CHAR_BUDGETS, MIN_HISTORY_DAYS, NARRATIVE_MODEL, OUTPUT_TOKEN_TARGETS, enumerateChildWindows, } from "./narrative-resolutions.js";
+import { getChildNarratives, getCurrentNarrative, getLastNarrative, isCooldownActive, } from "./narrative-store.js";
+import { extractEpisodeText, formatChildNarrativesForLLM, formatEpisodeLine, formatEpisodesForLLM, formatNotesForLLM, getEarliestEpisodeDate, getEpisodesInPeriod, getHistorySpanDays, getNotesInPeriod, } from "./narrative-sources.js";
 import { getThread } from "./thread-registry.js";
-import { parseJsonArray, parseJsonObject } from "./utils.js";
-import { errorMessage } from "../../utils.js";
-import { log } from "../../logger.js";
-// ─── Constants ───────────────────────────────────────────────────────────────
-const NARRATIVE_FILLER_PHRASES = [
-    /\bsignificant progress\b/i,
-    /\bnotable improvements?\b/i,
-    /\bvarious features\b/i,
-    /\bseveral enhancements\b/i,
-    /\bsignificant (evolution|strides|developments?)\b/i,
-    /\boverall.{0,20}(positive|good|well)\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,
-    /\bremarkable (progress|growth|improvement)\b/i,
-    /\bmeaningful (progress|improvement|change)\b/i,
-    /\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) {
-        const match = pattern.exec(text);
-        if (match)
-            return match[0];
-    }
-    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
-    week: 12 * 60 * 60 * 1000, // 12 hours
-    month: 24 * 60 * 60 * 1000, // 24 hours
-    quarter: 7 * 24 * 60 * 60 * 1000, // 7 days
-    half_year: 14 * 24 * 60 * 60 * 1000, // 14 days
-};
-/** Target output token count per resolution */
-const OUTPUT_TOKEN_TARGETS = {
-    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",
-};
-/** Minimum episode-history span (days) before a resolution becomes eligible.
- *  Without this, a young thread with ≥5 episodes gets month/quarter/half_year
- *  narratives that just re-summarize the same few days under coarser labels.
- *  A resolution needs at least one full child-period of real history to mean
- *  anything, so month wants a week, quarter a month, half_year a quarter. */
-const MIN_HISTORY_DAYS = {
-    day: 0,
-    week: 0,
-    month: 7,
-    quarter: 30,
-    half_year: 90,
-};
-const NARRATIVE_MODEL = process.env.NARRATIVE_MODEL || process.env.CONSOLIDATION_MODEL || "gpt-4o";
+import { errorMessage } from "../../lib/utils.js";
+import { log } from "../../lib/logger.js";
 // ─── Period Calculation ──────────────────────────────────────────────────────
 /** Max backward reach for a day narrative when catching a cross-midnight gap. */
 const DAY_GAP_MAX_LOOKBACK_MS = 3 * 24 * 60 * 60 * 1000;
-function getPeriodBounds(db, threadId, resolution) {
+export function getPeriodBounds(db, threadId, resolution) {
     const now = new Date();
     const end = now.toISOString();
     if (resolution === "day") {
@@ -208,289 +71,7 @@ function getPeriodBounds(db, threadId, 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;
-}
-/** Days of episode history a thread has (earliest episode → now); 0 if none. */
-function getHistorySpanDays(db, threadId) {
-    const earliest = getEarliestEpisodeDate(db, threadId);
-    if (!earliest)
-        return 0;
-    return (Date.now() - new Date(earliest).getTime()) / 86_400_000;
-}
-// ─── Source Data Collection ──────────────────────────────────────────────────
-function getEpisodesInPeriod(db, threadId, start, end) {
-    const rows = db
-        .prepare(`SELECT * FROM episodes
-       WHERE thread_id = ? AND timestamp >= ? AND timestamp <= ?
-       ORDER BY timestamp ASC`)
-        .all(threadId, start, end);
-    // Inline light rowToEpisode to avoid circular dep
-    return rows.map((r) => ({
-        episodeId: r.episode_id,
-        sessionId: r.session_id,
-        threadId: r.thread_id,
-        timestamp: r.timestamp,
-        type: r.type,
-        modality: r.modality,
-        content: parseJsonObject(r.content),
-        topicTags: parseJsonArray(r.topic_tags),
-        importance: r.importance,
-        consolidated: r.consolidated === 1,
-        accessedCount: r.accessed_count,
-        lastAccessed: r.last_accessed,
-        createdAt: r.created_at,
-    }));
-}
-function getNotesInPeriod(db, threadId, start) {
-    const rows = db
-        .prepare(`SELECT * FROM semantic_notes
-       WHERE thread_id = ? AND valid_to IS NULL AND created_at >= ?
-       ORDER BY access_count DESC LIMIT 30`)
-        .all(threadId, start);
-    return rows.map((r) => ({
-        noteId: r.note_id,
-        type: r.type,
-        content: r.content,
-        keywords: parseJsonArray(r.keywords),
-        confidence: r.confidence,
-        sourceEpisodes: parseJsonArray(r.source_episodes),
-        linkedNotes: parseJsonArray(r.linked_notes),
-        linkReasons: parseJsonObject(r.link_reasons),
-        validFrom: r.valid_from,
-        validTo: r.valid_to,
-        supersededBy: r.superseded_by,
-        accessCount: r.access_count,
-        lastAccessed: r.last_accessed,
-        createdAt: r.created_at,
-        updatedAt: r.updated_at,
-        priority: r.priority ?? 0,
-        threadId: r.thread_id,
-        isGuardrail: r.is_guardrail === 1,
-        pinned: r.pinned === 1,
-        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.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 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 line = formatEpisodeLine(ep, text);
-        if (pool1Chars + line.length > importanceBudget)
-            break;
-        pool1.push({ ep, line });
-        selected.add(ep.episodeId);
-        pool1Chars += line.length;
-    }
-    // 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, 600)} (conf: ${n.confidence.toFixed(2)})`;
-        if (chars + line.length > maxChars)
-            break;
-        lines.push(line);
-        chars += line.length;
-    }
-    return lines.join("\n");
-}
-// ─── LLM Prompts ─────────────────────────────────────────────────────────────
-function buildPrompt(resolution, episodesText, notesText, episodeCount, periodLabel, periodStart) {
-    const startYear = new Date(periodStart).getFullYear();
-    const endYear = new Date().getFullYear();
-    const instructions = {
-        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.`,
-    };
-    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]}
-
-${styleByResolution[resolution]}
-- Only use years in the range ${startYear}${startYear !== endYear ? `–${endYear}` : ""}.
-
-SOURCE DATA (${episodeCount} episodes):
-
-=== Recent Episodes ===
-${episodesText || "(no episodes in this period)"}
-
-=== Relevant Knowledge ===
-${notesText || "(no notes)"}
-
-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.`;
-}
+// ─── Prompt Assembly ─────────────────────────────────────────────────────────
 function buildFlatPrompt(db, knowledgeThreadId, resolution, start, end, periodLabel) {
     const episodes = getEpisodesInPeriod(db, knowledgeThreadId, start, end);
     const minEpisodes = resolution === "day" ? 3 : 5;
@@ -508,97 +89,14 @@ function buildFlatPrompt(db, knowledgeThreadId, resolution, start, end, periodLa
         noteCount: notes.length,
     };
 }
-// ─── Cooldown Check ──────────────────────────────────────────────────────────
-function getLastNarrative(db, threadId, resolution) {
-    const row = db
-        .prepare(`SELECT * FROM temporal_narratives
-       WHERE thread_id = ? AND resolution = ?
-       ORDER BY period_start 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 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)
-        return false;
-    const elapsed = Date.now() - new Date(last.createdAt).getTime();
-    return elapsed < COOLDOWNS[resolution];
-}
 // ─── Generation ──────────────────────────────────────────────────────────────
-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 = threadId;
     const existing = getChildNarratives(db, knowledgeThreadId, resolution, parentStart, parentEnd);
-    const existingStarts = new Set(existing.map(n => n.periodStart.slice(0, 10)));
+    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)))
@@ -640,7 +138,7 @@ async function generateNarrative(db, threadId, resolution, periodOverride) {
         const children = getChildNarratives(db, knowledgeThreadId, resolution, start, end);
         if (children.length > 0) {
             const childText = formatChildNarrativesForLLM(children);
-            const coveredPeriods = new Set(children.flatMap(c => {
+            const coveredPeriods = new Set(children.flatMap((c) => {
                 const dates = [];
                 const cur = new Date(c.periodStart);
                 const stop = new Date(c.periodEnd);
@@ -651,7 +149,7 @@ async function generateNarrative(db, threadId, resolution, periodOverride) {
                 return dates;
             }));
             const episodes = getEpisodesInPeriod(db, knowledgeThreadId, start, end);
-            const gapEpisodes = episodes.filter(ep => !coveredPeriods.has(ep.timestamp.slice(0, 10)));
+            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
@@ -659,14 +157,17 @@ async function generateNarrative(db, threadId, resolution, periodOverride) {
             let topEpisodesText = "";
             if (resolution === "quarter" || resolution === "half_year") {
                 const topN = [...episodes]
-                    .filter(ep => (ep.importance ?? 0.5) >= 0.6)
+                    .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 => {
+                    topEpisodesText = topN
+                        .map((ep) => {
                         const text = extractEpisodeText(ep);
                         return text.trim() ? formatEpisodeLine(ep, text) : "";
-                    }).filter(Boolean).join("\n");
+                    })
+                        .filter(Boolean)
+                        .join("\n");
                 }
             }
             const parts = [`=== ${children.length} ${childRes} narrative(s) ===\n${childText}`];
@@ -676,7 +177,8 @@ async function generateNarrative(db, threadId, resolution, periodOverride) {
                 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;
+            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`);
         }
@@ -728,9 +230,17 @@ async function generateNarrative(db, threadId, resolution, periodOverride) {
         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 });
+            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());
             const retryDate = findDateViolation(retried.trim(), start, end);