@chiligpt/memory 0.1.0

package/dist/core/narrative.js

@@ -0,0 +1,765 @@
+/**
+ * Narrative layer — NarrativeNode schema, CRUD, and hub construction (F-61, F-63, F-64).
+ *
+ * NarrativeNodes are hub nodes in the three-layer memory architecture.
+ * They aggregate ContextNode spoke references and summarise high-level
+ * project themes. Maximum 20 active hubs; excess archived to archive/narratives/.
+ */
+// ---------------------------------------------------------------------------
+// FIX-02: Generic directory basenames — not injected as identity topics
+// ---------------------------------------------------------------------------
+const GENERIC_DIRS = new Set(["src", "app", "lib", "dist", "packages", "build", "out", "tmp"]);
+// ---------------------------------------------------------------------------
+// FIX-01: BM25F tokenizer and index types
+// ---------------------------------------------------------------------------
+const BM25_K1 = 1.2;
+const BM25_B = 0.75;
+/** Field weights for BM25F scoring. */
+const FIELD_WEIGHTS = {
+    topics: 3.0,
+    title: 2.0,
+    summary: 1.0,
+    spoke: 1.5,
+};
+const STOP_WORDS = new Set([
+    "with", "from", "this", "that", "have", "been", "will", "into", "also",
+    "each", "their", "when", "then", "than", "they", "what", "some",
+]);
+/**
+ * Code-aware tokenizer: splits on whitespace, hyphens, underscores, camelCase
+ * boundaries, and path separators. Filters to length ≥ 4 and removes stop words.
+ * Exported for use in read-path.ts scanOrphanNodes.
+ */
+export function tokenizeBM25(text) {
+    // Expand camelCase: "AuthService" → "Auth Service"
+    const expanded = text
+        .replace(/([a-z])([A-Z])/g, "$1 $2")
+        .replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2");
+    // Split on whitespace, hyphens, underscores, path separators, dots
+    const raw = expanded.split(/[\s\-_/\\.]+/);
+    return raw
+        .map((t) => t.toLowerCase())
+        .filter((t) => t.length >= 4 && !STOP_WORDS.has(t));
+}
+function buildFreqMap(tokens) {
+    const m = new Map();
+    for (const t of tokens)
+        m.set(t, (m.get(t) ?? 0) + 1);
+    return m;
+}
+// ---------------------------------------------------------------------------
+// F-61: In-memory narrative cache (FIX-01 BM25F index; FIX-06 sort; FIX-04 context filter)
+// ---------------------------------------------------------------------------
+/** Session-scoped cache for all active NarrativeNodes (AC-61-02). */
+export class NarrativeCache {
+    hubs = new Map();
+    _bm25 = null;
+    /** Load all records from disk into cache. O(N) — acceptable at startup. */
+    build(nodes) {
+        this.hubs.clear();
+        this._bm25 = null;
+        for (const node of nodes) {
+            this.hubs.set(node.id, node);
+        }
+    }
+    get(id) {
+        return this.hubs.get(id);
+    }
+    /**
+     * All active hubs, newest first.
+     * FIX-06: sort key is latestSpokeAt (actual session activity), falling back to updatedAt.
+     */
+    all() {
+        return [...this.hubs.values()].sort((a, b) => (b.latestSpokeAt ?? b.updatedAt) - (a.latestSpokeAt ?? a.updatedAt));
+    }
+    set(node) {
+        this.hubs.set(node.id, node);
+        this._bm25 = null;
+    }
+    update(id, patch) {
+        const node = this.hubs.get(id);
+        if (!node)
+            return;
+        this.hubs.set(id, { ...node, ...patch });
+        this._bm25 = null;
+    }
+    remove(id) {
+        this.hubs.delete(id);
+        this._bm25 = null;
+    }
+    get size() {
+        return this.hubs.size;
+    }
+    // ---------------------------------------------------------------------------
+    // FIX-01: BM25F index construction
+    // ---------------------------------------------------------------------------
+    /**
+     * Build the BM25F index from current hubs + spoke ContextNodes for supplementary field.
+     * Called once at session_start after build(). O(N × T) — fast at ≤500 hubs.
+     */
+    buildIndex(allContextNodes) {
+        const contextMap = new Map(allContextNodes.map((n) => [n.id, n]));
+        const hubEntries = [];
+        for (const hub of this.hubs.values()) {
+            const topicsTokens = tokenizeBM25(hub.topics.join(" "));
+            const titleTokens = tokenizeBM25(hub.title);
+            const summaryTokens = tokenizeBM25(hub.summary);
+            // Spoke supplementary field: topics union + searchTerms + filePaths + modules from spoke nodes.
+            // F-106: Seed from persisted spokeTopics union first (efficient), then fall through to spoke
+            // node scan for searchTerms/filePaths/modules not yet covered by spokeTopics.
+            // F-108: include searchTerms — query-side vocabulary generated at write time.
+            const spokeTexts = hub.spokeTopics?.length ? [...hub.spokeTopics] : [];
+            const cwdBasenames = new Set();
+            for (const spokeId of hub.spokeNodeIds) {
+                const node = contextMap.get(spokeId);
+                if (!node)
+                    continue;
+                // Only add topics if spokeTopics not yet populated (old hubs without F-106 field)
+                if (!hub.spokeTopics?.length && node.topics?.length)
+                    spokeTexts.push(...node.topics);
+                if (node.searchTerms?.length)
+                    spokeTexts.push(...node.searchTerms);
+                if (node.relevantFilePaths?.length)
+                    spokeTexts.push(...node.relevantFilePaths);
+                if (node.relevantModules?.length)
+                    spokeTexts.push(...node.relevantModules);
+                const basename = node.workingDirectory?.split("/").pop()?.toLowerCase();
+                if (basename && basename.length > 2)
+                    cwdBasenames.add(basename);
+            }
+            const spokeTokens = tokenizeBM25(spokeTexts.join(" "));
+            hubEntries.push({
+                hubId: hub.id,
+                fields: {
+                    topics: buildFreqMap(topicsTokens),
+                    title: buildFreqMap(titleTokens),
+                    summary: buildFreqMap(summaryTokens),
+                    spoke: buildFreqMap(spokeTokens),
+                },
+                fieldLengths: {
+                    topics: topicsTokens.length,
+                    title: titleTokens.length,
+                    summary: summaryTokens.length,
+                    spoke: spokeTokens.length,
+                },
+                cwdBasenames,
+            });
+        }
+        // Compute IDF: document frequency per token across all hubs
+        const df = new Map();
+        for (const entry of hubEntries) {
+            const allTokensInHub = new Set([
+                ...entry.fields.topics.keys(),
+                ...entry.fields.title.keys(),
+                ...entry.fields.summary.keys(),
+                ...entry.fields.spoke.keys(),
+            ]);
+            for (const token of allTokensInHub) {
+                df.set(token, (df.get(token) ?? 0) + 1);
+            }
+        }
+        // Average field lengths for length normalisation
+        const N = hubEntries.length;
+        const avgLengths = N === 0
+            ? { topics: 1, title: 1, summary: 1, spoke: 1 }
+            : {
+                topics: hubEntries.reduce((s, e) => s + e.fieldLengths.topics, 0) / N,
+                title: hubEntries.reduce((s, e) => s + e.fieldLengths.title, 0) / N,
+                summary: hubEntries.reduce((s, e) => s + e.fieldLengths.summary, 0) / N,
+                spoke: hubEntries.reduce((s, e) => s + e.fieldLengths.spoke, 0) / N,
+            };
+        this._bm25 = { hubs: new Map(hubEntries.map((e) => [e.hubId, e])), df, avgLengths, totalHubs: N };
+    }
+    /**
+     * Rank hubs by composite BM25F score for the given query string.
+     * Returns hubs with score > 0, sorted descending. Top 5 returned.
+     *
+     * Composite score = BM25F × temporal decay × cwd affinity (FIX-01, FIX-03).
+     * Returns empty array when index not built — caller should fall back to full-text scan.
+     */
+    rankByQuery(topic, cwd) {
+        const index = this._bm25;
+        if (!index || index.totalHubs === 0)
+            return [];
+        let queryTokens = tokenizeBM25(topic);
+        // AC-FIX-01-06: short/symbol query — keep original lowercased as single token
+        if (queryTokens.length === 0)
+            queryTokens = [topic.toLowerCase().slice(0, 20).trim()].filter(Boolean);
+        if (queryTokens.length === 0)
+            return [];
+        const cwdBasename = cwd?.split("/").pop()?.toLowerCase();
+        const scores = new Map();
+        for (const [hubId, entry] of index.hubs) {
+            let bm25Score = 0;
+            for (const token of queryTokens) {
+                const df = index.df.get(token) ?? 0;
+                if (df === 0)
+                    continue;
+                const idf = Math.log((index.totalHubs - df + 0.5) / (df + 0.5) + 1);
+                let weightedFreq = 0;
+                const fields = [
+                    ["topics", "topics"],
+                    ["title", "title"],
+                    ["summary", "summary"],
+                    ["spoke", "spoke"],
+                ];
+                for (const [field, weightKey] of fields) {
+                    const freq = entry.fields[field].get(token) ?? 0;
+                    if (freq === 0)
+                        continue;
+                    const avgLen = index.avgLengths[field] || 1;
+                    const len = entry.fieldLengths[field];
+                    const normFreq = freq / (1 - BM25_B + BM25_B * (len / avgLen));
+                    weightedFreq += FIELD_WEIGHTS[weightKey] * normFreq;
+                }
+                bm25Score += idf * (weightedFreq / (weightedFreq + BM25_K1));
+            }
+            if (bm25Score <= 0)
+                continue;
+            // Exact phrase bonus: 2+ consecutive query tokens adjacent in title or topics
+            if (queryTokens.length >= 2) {
+                const hub = this.hubs.get(hubId);
+                if (hub) {
+                    const titleTokens = tokenizeBM25(hub.title);
+                    const topicsFlat = tokenizeBM25(hub.topics.join(" "));
+                    outer: for (let i = 0; i < queryTokens.length - 1; i++) {
+                        const t1 = queryTokens[i];
+                        const t2 = queryTokens[i + 1];
+                        for (const toks of [titleTokens, topicsFlat]) {
+                            for (let j = 0; j < toks.length - 1; j++) {
+                                if (toks[j] === t1 && toks[j + 1] === t2) {
+                                    bm25Score += BM25_K1;
+                                    break outer;
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+            // Temporal decay: e^(-0.005 × daysSinceUpdate) — uses latestSpokeAt per FIX-03
+            const hub = this.hubs.get(hubId);
+            if (!hub)
+                continue;
+            const anchorTs = hub.latestSpokeAt ?? hub.updatedAt;
+            const daysSince = (Date.now() - anchorTs) / 86_400_000;
+            let finalScore = bm25Score * Math.exp(-0.005 * daysSince);
+            // cwd affinity: 1.5× boost when spoke nodes share current project basename
+            if (cwdBasename && !GENERIC_DIRS.has(cwdBasename) && entry.cwdBasenames.has(cwdBasename)) {
+                finalScore *= 1.5;
+            }
+            scores.set(hubId, finalScore);
+        }
+        return [...scores.entries()]
+            .sort((a, b) => b[1] - a[1])
+            .slice(0, 5)
+            .map(([id]) => this.hubs.get(id))
+            .filter(Boolean);
+    }
+    /**
+     * FIX-04: Return hubs for system prompt injection filtered by cwd relevance.
+     * Primary: hubs whose spokes come from the current cwd.
+     * Fallback: 3 most recently active hubs when no cwd match exists.
+     * Hard cap: never more than `max` hubs injected.
+     */
+    getHubsForContext(cwd, max = 5) {
+        const all = this.all();
+        if (!cwd || all.length === 0)
+            return all.slice(0, max);
+        const cwdBasename = cwd.split("/").pop()?.toLowerCase();
+        if (!cwdBasename || GENERIC_DIRS.has(cwdBasename))
+            return all.slice(0, max);
+        const matched = [];
+        for (const hub of all) {
+            const entry = this._bm25?.hubs.get(hub.id);
+            if (entry?.cwdBasenames.has(cwdBasename)) {
+                matched.push(hub);
+            }
+        }
+        if (matched.length > 0)
+            return matched.slice(0, max);
+        // Fallback: 3 most recently active hubs as orientation context
+        return all.slice(0, Math.min(3, max));
+    }
+}
+// ---------------------------------------------------------------------------
+// F-61: CRUD over layer3-narrative.jsonl
+// ---------------------------------------------------------------------------
+export async function createNarrativeNode(storage, cache, node) {
+    await storage.append("narratives", node);
+    cache.set(node);
+}
+export async function updateNarrativeNode(storage, cache, id, patch) {
+    await storage.update("narratives", id, patch);
+    cache.update(id, patch);
+}
+export async function loadAllNarrativeNodes(storage) {
+    const all = await storage.readAll("narratives");
+    return all.filter((n) => !n._archived);
+}
+// ---------------------------------------------------------------------------
+// F-62: Narrative injection content (FIX-04: cwd filter, 5-hub cap, 150-char truncation)
+// ---------------------------------------------------------------------------
+const ACTIVATION_PROTOCOL = "When the user references past work, a specific file, decision, or change not present " +
+    "in the current session context — do not answer from assumption. Call " +
+    "memory_entity_lookup(name, type) or memory_query(topic) before responding.";
+/**
+ * Build the system prompt append block for the narrative layer (F-62).
+ * FIX-04: accepts pre-filtered hubs and total hub count for "N of M" header.
+ * Summaries truncated to 150 chars. Hub coverage range included when available (FIX-03).
+ */
+export function buildNarrativeSystemPromptBlock(hubs, totalCount) {
+    const lines = [];
+    const total = totalCount ?? hubs.length;
+    if (hubs.length === 0) {
+        lines.push("[MEMORY: Project Narrative]", "");
+        lines.push("[MEMORY: No narrative index yet — will build over time]");
+    }
+    else {
+        lines.push(`[MEMORY: Project Narrative — showing ${hubs.length} of ${total} hubs for current project]`, "");
+        for (const hub of hubs) {
+            const truncatedSummary = hub.summary.length > 150
+                ? hub.summary.slice(0, 150) + "..."
+                : hub.summary;
+            const coverage = hub.earliestSpokeAt && hub.latestSpokeAt
+                ? ` | coverage: ${new Date(hub.earliestSpokeAt).toISOString().split("T")[0]} → ${new Date(hub.latestSpokeAt).toISOString().split("T")[0]}`
+                : "";
+            lines.push(`Hub: ${hub.title}`);
+            lines.push(`  Topics: ${hub.topics.join(", ")}`);
+            lines.push(`  Summary: ${truncatedSummary}`);
+            lines.push(`  Sessions: ${hub.spokeNodeIds.length} entries${coverage}`);
+            lines.push("");
+        }
+    }
+    lines.push(ACTIVATION_PROTOCOL);
+    return lines.join("\n");
+}
+// ---------------------------------------------------------------------------
+// F-63: Spoke assignment (FIX-05: BM25F pre-filter; FIX-03: latestSpokeAt update)
+// ---------------------------------------------------------------------------
+const SPOKE_SYSTEM_PROMPT = "You are a memory routing assistant. Given a new session summary and a list of narrative hubs, " +
+    "determine if the summary belongs to exactly one hub. Respond with JSON only.";
+function buildSpokeAssignmentPrompt(newNode, hubs) {
+    const hubText = hubs
+        .map((h, i) => `[${i + 1}] ID: ${h.id}\nTitle: ${h.title}\nTopics: ${h.topics.join(", ")}\nSummary: ${h.summary}`)
+        .join("\n\n");
+    return [
+        {
+            role: "user",
+            timestamp: Date.now(),
+            content: `New session summary:
+User: ${newNode.userContext}
+Agent: ${newNode.agentContext}
+Topics: ${newNode.topics.join(", ")}
+
+Narrative hubs:
+${hubText}
+
+Does this summary belong to exactly one of the hubs above? If yes, return its ID. If no, return null.
+Respond with JSON only: { "hubId": "<id>" | null }`,
+        },
+    ];
+}
+async function assignSpoke(newNode, hubs, storage, cache, complete) {
+    if (hubs.length === 0)
+        return null;
+    // FIX-05: Pre-filter hub candidates using BM25F — pass only plausible candidates to LLM.
+    // Falls back to full hub list when the BM25 index is not yet built (e.g. first session start).
+    const queryText = `${newNode.topics.join(" ")} ${newNode.userContext} ${newNode.agentContext}`;
+    const ranked = cache.rankByQuery(queryText);
+    // When the index isn't built, rankByQuery returns [] — fall back to all hubs (capped at 5)
+    const candidates = ranked.length > 0 ? ranked.slice(0, 5) : hubs.slice(0, 5);
+    // AC-FIX-05-03: If BM25F returned results but none scored above zero, skip LLM entirely.
+    // When falling back to all hubs, always proceed to LLM.
+    if (ranked.length > 0 && candidates.length === 0)
+        return null;
+    const messages = buildSpokeAssignmentPrompt(newNode, candidates);
+    let raw;
+    try {
+        const response = await complete(messages, { systemPrompt: SPOKE_SYSTEM_PROMPT });
+        const textBlock = Array.isArray(response.content)
+            ? response.content.find((b) => b.type === "text")
+            : null;
+        raw = textBlock ? textBlock.text : "";
+    }
+    catch {
+        return null;
+    }
+    const cleaned = raw.replace(/^```(?:json)?\n?/m, "").replace(/\n?```$/m, "").trim();
+    let hubId = null;
+    try {
+        const parsed = JSON.parse(cleaned);
+        hubId = typeof parsed.hubId === "string" ? parsed.hubId : null;
+    }
+    catch {
+        return null;
+    }
+    // Validate the returned hub ID is from the candidate list (not the full hub list)
+    if (!hubId || !candidates.find((h) => h.id === hubId))
+        return null;
+    const hub = cache.get(hubId);
+    if (!hub)
+        return null;
+    const updatedSpokes = [...hub.spokeNodeIds, newNode.id];
+    // FIX-03: Maintain earliestSpokeAt / latestSpokeAt on spoke add
+    const nodeTs = newNode.timestamp ?? Date.now();
+    const earliestSpokeAt = hub.earliestSpokeAt !== undefined
+        ? Math.min(hub.earliestSpokeAt, nodeTs)
+        : nodeTs;
+    const latestSpokeAt = hub.latestSpokeAt !== undefined
+        ? Math.max(hub.latestSpokeAt, nodeTs)
+        : nodeTs;
+    // F-106: Maintain spokeTopics union — append new spoke's topics, deduplicated
+    const updatedSpokeTopics = [...new Set([...(hub.spokeTopics ?? []), ...newNode.topics])];
+    await updateNarrativeNode(storage, cache, hubId, {
+        spokeNodeIds: updatedSpokes,
+        spokeTopics: updatedSpokeTopics,
+        updatedAt: Date.now(),
+        earliestSpokeAt,
+        latestSpokeAt,
+    });
+    return hubId;
+}
+// ---------------------------------------------------------------------------
+// F-63: Hub creation (FIX-02: cwd basename topic; FIX-03: spoke timestamps)
+// ---------------------------------------------------------------------------
+const HUB_CREATION_SYSTEM_PROMPT = "You are a memory organisation assistant. Create a narrative hub title and summary that captures " +
+    "a theme common to the provided session summaries. Respond with JSON only.";
+function commonTopics(nodes) {
+    const topicCounts = new Map();
+    for (const node of nodes) {
+        for (const topic of node.topics) {
+            topicCounts.set(topic, (topicCounts.get(topic) ?? 0) + 1);
+        }
+    }
+    return [...topicCounts.entries()].filter(([, count]) => count >= 2).map(([topic]) => topic);
+}
+function existingHubCoversTopics(hubs, topics) {
+    const topicSet = new Set(topics);
+    for (const hub of hubs) {
+        const matches = hub.topics.filter((t) => topicSet.has(t));
+        if (matches.length >= 2)
+            return true;
+    }
+    return false;
+}
+/**
+ * FIX-02: Extract the dominant working directory basename from a set of context nodes.
+ * Returns null when no clear majority basename exists or basename is generic.
+ */
+function extractDominantBasename(nodes) {
+    const basenames = nodes
+        .map((n) => n.workingDirectory?.split("/").pop()?.toLowerCase())
+        .filter((b) => !!b && b.length > 2 && !GENERIC_DIRS.has(b));
+    if (basenames.length === 0)
+        return null;
+    const counts = new Map();
+    for (const b of basenames)
+        counts.set(b, (counts.get(b) ?? 0) + 1);
+    const dominant = [...counts.entries()].sort((a, b) => b[1] - a[1])[0];
+    // Only inject if dominant appears on ≥50% of nodes
+    return dominant && dominant[1] >= nodes.length / 2 ? dominant[0] : null;
+}
+async function tryCreateHub(candidateNodes, storage, cache, complete) {
+    const allNodes = await storage.readAll("context");
+    const hubs = cache.all();
+    const unassignedNodes = allNodes.filter((n) => !hubs.some((h) => h.spokeNodeIds.includes(n.id)));
+    if (unassignedNodes.length < 3)
+        return null;
+    const shared = commonTopics(unassignedNodes);
+    if (shared.length < 2)
+        return null;
+    if (existingHubCoversTopics(hubs, shared))
+        return null;
+    // FIX-02: Inject dominant cwd basename as an identity topic
+    const dominantBasename = extractDominantBasename(unassignedNodes);
+    const allTopics = dominantBasename ? [...new Set([...shared, dominantBasename])] : shared;
+    const nodeText = unassignedNodes
+        .slice(0, 5)
+        .map((n) => `User: ${n.userContext}\nAgent: ${n.agentContext}`)
+        .join("\n\n");
+    const messages = [
+        {
+            role: "user",
+            timestamp: Date.now(),
+            content: `Create a narrative hub for these session summaries that share common topics: ${allTopics.join(", ")}
+
+Session summaries:
+${nodeText}
+
+Respond with JSON only:
+{ "title": "<short hub title>", "summary": "<2-3 sentence hub summary>" }`,
+        },
+    ];
+    let raw;
+    try {
+        const response = await complete(messages, { systemPrompt: HUB_CREATION_SYSTEM_PROMPT });
+        const textBlock = Array.isArray(response.content)
+            ? response.content.find((b) => b.type === "text")
+            : null;
+        raw = textBlock ? textBlock.text : "";
+    }
+    catch {
+        return null;
+    }
+    const cleaned = raw.replace(/^```(?:json)?\n?/m, "").replace(/\n?```$/m, "").trim();
+    let title = null;
+    let summary = null;
+    try {
+        const parsed = JSON.parse(cleaned);
+        title = typeof parsed.title === "string" ? parsed.title : null;
+        summary = typeof parsed.summary === "string" ? parsed.summary : null;
+    }
+    catch {
+        return null;
+    }
+    if (!title || !summary)
+        return null;
+    // FIX-03: Set spoke timestamp range from the unassigned nodes
+    const spokeTimestamps = unassignedNodes.map((n) => n.timestamp ?? 0).filter((t) => t > 0);
+    const earliestSpokeAt = spokeTimestamps.length > 0 ? Math.min(...spokeTimestamps) : undefined;
+    const latestSpokeAt = spokeTimestamps.length > 0 ? Math.max(...spokeTimestamps) : undefined;
+    const now = Date.now();
+    // F-106: Initialize spokeTopics as union of all candidate node topics
+    const spokeTopics = [...new Set(unassignedNodes.flatMap((n) => n.topics))];
+    const hub = {
+        id: globalThis.crypto.randomUUID(),
+        title,
+        summary,
+        topics: allTopics,
+        spokeTopics,
+        spokeNodeIds: unassignedNodes.map((n) => n.id),
+        createdAt: now,
+        updatedAt: now,
+        earliestSpokeAt,
+        latestSpokeAt,
+    };
+    await createNarrativeNode(storage, cache, hub);
+    return hub;
+}
+// ---------------------------------------------------------------------------
+// F-63: Hub summary revision (FIX-07: founding + recent spokes for revision context)
+// ---------------------------------------------------------------------------
+const HUB_REVISION_SYSTEM_PROMPT = "You are a memory summarisation assistant. Revise the hub summary to incorporate new session data. Respond with JSON only.";
+async function tryReviseHub(hub, newSpokesAdded, storage, cache, complete) {
+    if (newSpokesAdded < 5)
+        return;
+    const allContextNodes = await storage.readAll("context");
+    // FIX-07: First 2 spokes (founding identity anchor) + last 3 (recent activity), deduplicated.
+    // For hubs with ≤5 spokes, uses all spokes.
+    const allSpokes = hub.spokeNodeIds
+        .map((id) => allContextNodes.find((n) => n.id === id))
+        .filter((n) => n !== undefined);
+    const founding = allSpokes.slice(0, 2);
+    const recent = allSpokes.slice(-3);
+    const spokeNodes = [...new Map([...founding, ...recent].map((n) => [n.id, n])).values()];
+    const nodeText = spokeNodes
+        .map((n) => `User: ${n.userContext}\nAgent: ${n.agentContext}`)
+        .join("\n\n");
+    const messages = [
+        {
+            role: "user",
+            timestamp: Date.now(),
+            content: `Update the hub summary to reflect recent activity while preserving the founding context.
+
+Hub: "${hub.title}"
+Current summary: ${hub.summary}
+Topics: ${hub.topics.join(", ")}
+
+Sessions (founding + recent):
+${nodeText}
+
+Respond with JSON only: { "summary": "<revised 2-3 sentence summary>" }`,
+        },
+    ];
+    try {
+        const response = await complete(messages, { systemPrompt: HUB_REVISION_SYSTEM_PROMPT });
+        const textBlock = Array.isArray(response.content)
+            ? response.content.find((b) => b.type === "text")
+            : null;
+        const raw = textBlock ? textBlock.text : "";
+        const cleaned = raw.replace(/^```(?:json)?\n?/m, "").replace(/\n?```$/m, "").trim();
+        const parsed = JSON.parse(cleaned);
+        if (typeof parsed.summary === "string") {
+            await updateNarrativeNode(storage, cache, hub.id, {
+                summary: parsed.summary,
+                updatedAt: Date.now(),
+            });
+        }
+    }
+    catch {
+        // Non-fatal
+    }
+}
+// ---------------------------------------------------------------------------
+// F-64: 20-hub limit + LRU archival (FIX-06: latestSpokeAt for eviction sort)
+// ---------------------------------------------------------------------------
+const MAX_HUBS = 20;
+const MAX_NARRATIVE_TOKENS = 8_000;
+const CHARS_PER_TOKEN = 4;
+function estimateNarrativeTokens(hubs) {
+    const totalChars = hubs.reduce((sum, h) => sum + h.title.length + h.summary.length + h.topics.join(", ").length, 0);
+    return Math.ceil(totalChars / CHARS_PER_TOKEN);
+}
+async function enforceHubLimit(storage, cache) {
+    // FIX-06: Sort by latestSpokeAt (true session activity), fallback to updatedAt
+    const hubs = cache.all().sort((a, b) => (b.latestSpokeAt ?? b.updatedAt) - (a.latestSpokeAt ?? a.updatedAt));
+    const tokenEstimate = estimateNarrativeTokens(hubs);
+    const overTokens = tokenEstimate > MAX_NARRATIVE_TOKENS;
+    const target = overTokens ? MAX_HUBS - 1 : MAX_HUBS;
+    if (hubs.length <= target)
+        return;
+    // Archive least-recently-active hubs (tail of the sorted list)
+    const toArchive = hubs.slice(target);
+    for (const hub of toArchive) {
+        await storage.archive("narratives-archive", hub);
+        await storage.update("narratives", hub.id, { _archived: true });
+        cache.remove(hub.id);
+        if (overTokens) {
+            console.warn(`[memory] Narrative token budget exceeded — archiving hub "${hub.title}"`);
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// F-97: Lightweight narrative tick — mid-session hub summary refresh
+// ---------------------------------------------------------------------------
+/**
+ * Revises the most recently active hub's summary without full compaction.
+ * Called every ~20 agent turns to keep the narrative warm during long sessions.
+ * Best-effort: errors are swallowed by the caller.
+ */
+export async function runNarrativeTick(storage, cache, complete) {
+    const hubs = cache.all(); // sorted by latestSpokeAt ?? updatedAt
+    if (hubs.length === 0)
+        return;
+    await tryReviseHub(hubs[0], 5, storage, cache, complete);
+}
+// ---------------------------------------------------------------------------
+// F-96 + F-107: Eager hub formation — stub hub for single-node orphan prevention
+// ---------------------------------------------------------------------------
+const STUB_HUB_SYSTEM_PROMPT = "You are a memory summarisation assistant. Write a 2-sentence summary of this coding session. Respond with JSON only.";
+/**
+ * Builds a stub NarrativeNode from a single ContextNode.
+ * F-107: Makes one LLM call to generate a richer summary so the BM25F index
+ * has more surface area from the first session. Falls back to raw concatenation
+ * on any failure — stub creation never throws.
+ * FIX-02: Injects working directory basename as identity topic when meaningful.
+ * FIX-03: Sets earliestSpokeAt / latestSpokeAt from node timestamp.
+ */
+async function buildStubHub(node, complete) {
+    const now = Date.now();
+    const title = node.topics.length > 0
+        ? node.topics.slice(0, 2).join(", ")
+        : node.userContext.slice(0, 60).trimEnd();
+    // FIX-02: Inject cwd basename as identity topic when non-generic
+    const cwdBasename = node.workingDirectory?.split("/").pop()?.toLowerCase();
+    const injectBasename = cwdBasename && cwdBasename.length > 2 && !GENERIC_DIRS.has(cwdBasename)
+        ? cwdBasename
+        : null;
+    const topics = injectBasename
+        ? [...new Set([...node.topics, injectBasename])]
+        : node.topics;
+    // F-107: LLM-generated summary — falls back to raw concat on any failure
+    let summary = `${node.userContext} — ${node.agentContext}`.slice(0, 300);
+    try {
+        const messages = [{
+                role: "user",
+                timestamp: now,
+                content: `Write a 2-sentence summary of this coding session.\n\nUser: ${node.userContext}\nAgent: ${node.agentContext}\nTopics: ${topics.join(", ")}\n\nRespond with JSON only: { "summary": "<2 sentences>" }`,
+            }];
+        const response = await complete(messages, { systemPrompt: STUB_HUB_SYSTEM_PROMPT });
+        const textBlock = Array.isArray(response.content)
+            ? response.content.find((b) => b.type === "text")
+            : null;
+        const raw = textBlock ? textBlock.text : "";
+        const cleaned = raw.replace(/^```(?:json)?\n?/m, "").replace(/\n?```$/m, "").trim();
+        const parsed = JSON.parse(cleaned);
+        if (typeof parsed.summary === "string" && parsed.summary.length >= 20) {
+            summary = parsed.summary;
+        }
+    }
+    catch {
+        // Non-fatal — raw concatenation fallback already set above
+    }
+    // FIX-03: Spoke timestamps from the node
+    const nodeTs = node.timestamp ?? now;
+    return {
+        id: globalThis.crypto.randomUUID(),
+        title,
+        summary,
+        topics,
+        // F-106: spokeTopics initialized from the single founding node's topics
+        spokeTopics: [...topics],
+        spokeNodeIds: [node.id],
+        createdAt: now,
+        updatedAt: now,
+        earliestSpokeAt: nodeTs,
+        latestSpokeAt: nodeTs,
+    };
+}
+// ---------------------------------------------------------------------------
+// F-98: Dead hub detection — archive hubs whose all spokes have archived entities
+// ---------------------------------------------------------------------------
+/**
+ * Scans active hubs and archives any where every spoke ContextNode has
+ * `allEntitiesArchived: true`. These hubs consume system prompt token budget
+ * without providing usable recall.
+ *
+ * Returns count of hubs archived. No LLM calls. Safe at session_start and shutdown.
+ */
+export async function archiveDeadHubs(storage, cache) {
+    const allContextNodes = await storage.readAll("context");
+    const contextNodeMap = new Map(allContextNodes.map((n) => [n.id, n]));
+    const hubs = cache.all();
+    let archivedCount = 0;
+    for (const hub of hubs) {
+        if (hub.spokeNodeIds.length === 0)
+            continue;
+        const allSpokesArchivedOrMissing = hub.spokeNodeIds.every((id) => {
+            const node = contextNodeMap.get(id);
+            return !node || node.allEntitiesArchived === true;
+        });
+        if (allSpokesArchivedOrMissing) {
+            await storage.archive("narratives-archive", hub);
+            await storage.update("narratives", hub.id, { _archived: true });
+            cache.remove(hub.id);
+            archivedCount++;
+        }
+    }
+    return archivedCount;
+}
+// ---------------------------------------------------------------------------
+// Main entry point: post-compaction narrative construction
+// ---------------------------------------------------------------------------
+/**
+ * Called after a new ContextNode is written (F-57/F-58).
+ * Runs: spoke assignment → optional hub creation → optional hub revision → LRU enforcement.
+ * All operations are best-effort — errors are caught and logged.
+ */
+export async function updateNarrativeLayer(params) {
+    const { newNode, storage, cache, complete } = params;
+    const hubs = cache.all();
+    try {
+        // F-63: Spoke assignment (FIX-05: BM25F pre-filter inside assignSpoke)
+        const assignedHubId = await assignSpoke(newNode, hubs, storage, cache, complete);
+        // Revision trigger: revise hub summary every 5 spokes
+        if (assignedHubId) {
+            const hub = cache.get(assignedHubId);
+            if (hub && hub.spokeNodeIds.length % 5 === 0) {
+                await tryReviseHub(hub, 5, storage, cache, complete);
+            }
+        }
+        // F-63: Hub creation check (≥3 unassigned nodes with ≥2 common topics)
+        const createdHub = await tryCreateHub([newNode], storage, cache, complete);
+        // F-96 + F-107: Eager hub formation — create stub immediately to eliminate orphans
+        if (!assignedHubId && !createdHub) {
+            const stub = await buildStubHub(newNode, complete);
+            await createNarrativeNode(storage, cache, stub);
+        }
+        // F-64: Enforce hub limit
+        await enforceHubLimit(storage, cache);
+    }
+    catch (err) {
+        console.error("[memory] narrative update error:", err instanceof Error ? err.message : String(err));
+    }
+}
+//# sourceMappingURL=narrative.js.map