@chiligpt/memory 0.1.0

package/dist/core/read-path.js

@@ -0,0 +1,592 @@
+/**
+ * Memory read path — F-65 (session start retrieval), F-66 (per-turn injection),
+ * F-69 (active query tools: memory_entity_lookup, memory_query, memory_recall).
+ */
+import { validityScore } from "./entity.js";
+import { loadContextNodeWithSupersession, loadAllContextNodes, projectHealth } from "./context-graph.js";
+import { tokenizeBM25 } from "./narrative.js";
+import { loadSessionTree, resolveSessionFile } from "./session-tree-index.js";
+import { readJsonlFile } from "../storage/file-utils.js";
+// ---------------------------------------------------------------------------
+// Injection formatting
+// ---------------------------------------------------------------------------
+const CHARS_PER_TOKEN_APPROX = 4;
+function validityLabel(score) {
+    if (score > 0.7)
+        return "trusted";
+    if (score >= 0.3)
+        return "uncertain";
+    if (score >= 0)
+        return "degraded";
+    return "deprecated";
+}
+function formatContextNodeBlock(node, superseded, entityIndex, now) {
+    const date = new Date(node.timestamp).toISOString().split("T")[0];
+    const health = projectHealth(node, entityIndex, now);
+    const entityLines = [];
+    for (const id of node.entityPointerIds) {
+        const entity = entityIndex.getById(id);
+        if (!entity)
+            continue;
+        const score = validityScore(entity.eventMatrix, entity.type, now);
+        const daysAgo = Math.floor((now - entity.lastReferencedAt) / 86_400_000);
+        entityLines.push(`[ENTITY: ${entity.canonicalName} | ${entity.type} | validity: ${score.toFixed(2)} (${validityLabel(score)}) | ref: ${daysAgo}d ago]`);
+    }
+    const stalenessWarning = health.degradedCount > 0 || health.deprecatedCount > 0
+        ? ` [STALE: ${health.degradedCount} degraded, ${health.deprecatedCount} deprecated entities]`
+        : "";
+    const lines = [
+        `[RETRIEVED CONTEXT: ${node.sessionId}, ${date}]${stalenessWarning}`,
+        `User: ${node.userContext}`,
+        `Agent: ${node.agentContext}`,
+    ];
+    if (entityLines.length > 0) {
+        lines.push(...entityLines);
+    }
+    if (superseded) {
+        lines.push(`[SUPERSEDES: ${superseded.sessionId}, ${new Date(superseded.timestamp).toISOString().split("T")[0]}]`);
+        lines.push(`  User: ${superseded.userContext}`);
+    }
+    return lines.join("\n");
+}
+function estimateTokens(text) {
+    return Math.ceil(text.length / CHARS_PER_TOKEN_APPROX);
+}
+// ---------------------------------------------------------------------------
+// F-109: Query expansion via LLM before BM25F
+// ---------------------------------------------------------------------------
+const QUERY_EXPANSION_SYSTEM_PROMPT = "You are a search query assistant. Rewrite the given query as alternative phrasings. Respond with JSON only.";
+/**
+ * Expands a user query into up to 5 alternative phrasings using one LLM call.
+ * Returns the original query deduped with expansions. Best-effort — falls back
+ * to the original query on any failure.
+ */
+async function expandQuery(topic, complete) {
+    try {
+        const messages = [{
+                role: "user",
+                timestamp: Date.now(),
+                content: `Rewrite this search query as 4 alternative phrasings a developer might use to find the same past conversation.\n\nQuery: "${topic}"\n\nRespond with JSON only: { "terms": ["<alt1>", "<alt2>", "<alt3>", "<alt4>"] }`,
+            }];
+        const response = await complete(messages, { systemPrompt: QUERY_EXPANSION_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 (Array.isArray(parsed.terms)) {
+            const terms = parsed.terms.filter((t) => typeof t === "string" && t.length > 0);
+            return [...new Set([topic, ...terms])].slice(0, 5);
+        }
+    }
+    catch {
+        // Non-fatal — original query used as sole term
+    }
+    return [topic];
+}
+// ---------------------------------------------------------------------------
+// FIX-01: rankHubsByQuery — BM25F ranked retrieval replacing matchHubsByTopic
+// ---------------------------------------------------------------------------
+/**
+ * Returns hubs ranked by BM25F score for the query (via NarrativeCache.rankByQuery).
+ * Falls back to full-text substring scan when the BM25 index is not yet built
+ * (cold start, stub hubs before first buildIndex call).
+ */
+function rankHubsByQuery(topic, narrativeCache, cwd) {
+    const ranked = narrativeCache.rankByQuery(topic, cwd);
+    if (ranked.length > 0)
+        return ranked;
+    // Fallback: basic full-text substring scan for cold-start safety
+    const q = topic.toLowerCase();
+    return narrativeCache.all().filter((h) => h.topics.some((t) => t.toLowerCase().includes(q) || q.includes(t.toLowerCase())) ||
+        h.title.toLowerCase().includes(q) ||
+        h.summary.toLowerCase().includes(q));
+}
+/**
+ * Finds ContextNodes not assigned to any hub and filters by topic overlap.
+ * FIX-01: uses same code-aware tokenizer as BM25F ranking for consistency.
+ */
+async function scanOrphanNodes(topic, storage, narrativeCache) {
+    const queryTokens = tokenizeBM25(topic);
+    const q = topic.toLowerCase();
+    const allSpokeIds = new Set(narrativeCache.all().flatMap((h) => h.spokeNodeIds));
+    const allNodes = await loadAllContextNodes(storage);
+    const orphanNodes = allNodes.filter((n) => !allSpokeIds.has(n.id));
+    const orphanMatches = orphanNodes
+        .filter((n) => {
+        if (queryTokens.length > 0) {
+            // Token-based overlap match
+            const nodeTokens = new Set(tokenizeBM25(n.topics.join(" ")));
+            return queryTokens.some((t) => nodeTokens.has(t));
+        }
+        // Fallback: substring match for very short / symbol queries
+        return n.topics.some((t) => t.toLowerCase().includes(q) || q.includes(t.toLowerCase()));
+    })
+        .sort((a, b) => b.timestamp - a.timestamp)
+        .slice(0, 5);
+    return { orphanMatches, totalOrphans: orphanNodes.length };
+}
+// ---------------------------------------------------------------------------
+// F-65: Session start context retrieval
+// ---------------------------------------------------------------------------
+/**
+ * Retrieve context nodes relevant to the current session (AC-65-01, AC-65-02, AC-65-03).
+ * Called once at before_agent_start on the first agent turn.
+ */
+export async function buildSessionStartInjection(params) {
+    const { storage, entityIndex, narrativeCache, cwd, sessionPrompt } = params;
+    const now = Date.now();
+    const hubs = narrativeCache.all();
+    if (hubs.length === 0)
+        return null;
+    // F-105: Use BM25F rankByQuery instead of naive substring match so semantically
+    // relevant hubs surface even when the session prompt shares no exact topic keywords.
+    const querySignal = [sessionPrompt ?? "", cwd.split("/").pop() ?? ""].filter(Boolean).join(" ");
+    let matchingHubs = querySignal.trim()
+        ? rankHubsByQuery(querySignal, narrativeCache, cwd)
+        : [];
+    // Cold-start heuristic: fall back to most recently active hub when BM25F returns nothing
+    if (matchingHubs.length === 0 && hubs.length > 0) {
+        matchingHubs = [hubs[0]]; // already sorted by latestSpokeAt ?? updatedAt
+    }
+    const blocks = [];
+    const seenContextIds = new Set();
+    for (const hub of matchingHubs) {
+        // Get recent spokes (up to 3 per hub)
+        for (const spokeId of hub.spokeNodeIds.slice(-3).reverse()) {
+            if (seenContextIds.has(spokeId))
+                continue;
+            seenContextIds.add(spokeId);
+            // AC-65-03: always use loadContextNodeWithSupersession
+            const [node, superseded] = await loadContextNodeWithSupersession(storage, spokeId);
+            if (!node)
+                continue;
+            // Update lastReferencedAt on entities (AC-69-03 pattern)
+            for (const id of node.entityPointerIds) {
+                const entity = entityIndex.getById(id);
+                if (entity) {
+                    entityIndex.update(id, { lastReferencedAt: now });
+                    await storage.update("entities", id, { lastReferencedAt: now });
+                }
+            }
+            blocks.push(formatContextNodeBlock(node, superseded, entityIndex, now));
+        }
+    }
+    if (blocks.length === 0)
+        return null;
+    return `[MEMORY: Session Start Context]\n\n${blocks.join("\n\n")}`;
+}
+// ---------------------------------------------------------------------------
+// F-66: Per-turn entity-driven injection
+// ---------------------------------------------------------------------------
+// Regex patterns for entity mention extraction (no LLM — AC-66-03)
+const FILENAME_PATTERN = /(?:^|\s)([\w./-]+\.\w{1,6})(?:\s|$)/gm;
+const CAMEL_CASE_PATTERN = /\b([A-Z][a-z]+(?:[A-Z][a-z]+)+)\b/g;
+const QUOTED_PATTERN = /["'`]([^"'`\n]{2,50})["'`]/g;
+function extractEntityMentions(text) {
+    const mentions = new Set();
+    let m;
+    const fn = new RegExp(FILENAME_PATTERN.source, FILENAME_PATTERN.flags);
+    while ((m = fn.exec(text)) !== null)
+        mentions.add(m[1]);
+    const cc = new RegExp(CAMEL_CASE_PATTERN.source, CAMEL_CASE_PATTERN.flags);
+    while ((m = cc.exec(text)) !== null)
+        mentions.add(m[1]);
+    const qt = new RegExp(QUOTED_PATTERN.source, QUOTED_PATTERN.flags);
+    while ((m = qt.exec(text)) !== null)
+        mentions.add(m[1]);
+    return [...mentions];
+}
+const MAX_PER_TURN_TOKENS = 1_500;
+/**
+ * Build per-turn entity-driven injection block (AC-66-01, AC-66-02, AC-66-03).
+ */
+export async function buildPerTurnInjection(params) {
+    const { userMessage, storage, entityIndex } = params;
+    const now = Date.now();
+    const mentions = extractEntityMentions(userMessage);
+    if (mentions.length === 0)
+        return null;
+    // Find all context nodes referencing the mentioned entities
+    const contextNodeIds = new Set();
+    const healthMap = new Map(); // contextNodeId -> meanValidity
+    for (const mention of mentions) {
+        // Try all entity types for this mention name
+        for (const type of ["file", "module", "concept", "decision", "person", "url"]) {
+            const entity = entityIndex.get(mention, type);
+            if (!entity)
+                continue;
+            // Update lastReferencedAt
+            entityIndex.update(entity.id, { lastReferencedAt: now });
+            await storage.update("entities", entity.id, { lastReferencedAt: now });
+            // Find context nodes referencing this entity
+            const allNodes = await loadAllContextNodes(storage);
+            for (const node of allNodes) {
+                if (node.entityPointerIds.includes(entity.id)) {
+                    contextNodeIds.add(node.id);
+                    if (!healthMap.has(node.id)) {
+                        const h = projectHealth(node, entityIndex, now);
+                        healthMap.set(node.id, h.meanValidity);
+                    }
+                }
+            }
+        }
+    }
+    if (contextNodeIds.size === 0)
+        return null;
+    // Sort by meanValidity descending
+    const sortedIds = [...contextNodeIds].sort((a, b) => (healthMap.get(b) ?? 0) - (healthMap.get(a) ?? 0));
+    const blocks = [];
+    let totalTokens = 0;
+    let truncated = false;
+    for (const id of sortedIds) {
+        const [node, superseded] = await loadContextNodeWithSupersession(storage, id);
+        if (!node)
+            continue;
+        const block = formatContextNodeBlock(node, superseded, entityIndex, now);
+        const blockTokens = estimateTokens(block);
+        if (totalTokens + blockTokens > MAX_PER_TURN_TOKENS) {
+            truncated = true;
+            break;
+        }
+        blocks.push(block);
+        totalTokens += blockTokens;
+    }
+    if (blocks.length === 0)
+        return null;
+    let result = `[MEMORY: Entity Context]\n\n${blocks.join("\n\n")}`;
+    if (truncated) {
+        result += "\n\n[MEMORY: Additional context truncated — token budget reached]";
+        console.warn("[memory] Per-turn injection truncated to fit token budget");
+    }
+    return result;
+}
+// ---------------------------------------------------------------------------
+// F-69: Active query tools
+// ---------------------------------------------------------------------------
+const MAX_QUERY_TOKENS = 2_000;
+/**
+ * memory_entity_lookup: O(1) entity lookup + context node retrieval (AC-69-01, AC-69-03).
+ * Falls back to searching all entity types when the specified type yields no match.
+ */
+export async function memoryEntityLookup(name, type, storage, entityIndex) {
+    const now = Date.now();
+    let entity = entityIndex.get(name, type);
+    // Type mismatch fallback: the agent may call with a different type than what was
+    // extracted (e.g. "python" as "concept" when it was indexed as "module").
+    if (!entity) {
+        const allTypes = ["file", "module", "concept", "decision", "person", "url"];
+        for (const t of allTypes) {
+            if (t === type)
+                continue;
+            const candidate = entityIndex.get(name, t);
+            if (candidate) {
+                entity = candidate;
+                break;
+            }
+        }
+    }
+    if (!entity) {
+        return `[MEMORY: No record of entity "${name}" (${type}). May predate memory system or not yet indexed.]`;
+    }
+    // AC-69-03: Update lastReferencedAt
+    entityIndex.update(entity.id, { lastReferencedAt: now });
+    await storage.update("entities", entity.id, { lastReferencedAt: now });
+    const score = validityScore(entity.eventMatrix, entity.type, now);
+    const lines = [
+        `[MEMORY: Entity — ${entity.canonicalName} | ${entity.type}]`,
+        `Validity: ${score.toFixed(2)} (${validityLabel(score)})`,
+        "",
+    ];
+    // Retrieve all context nodes referencing this entity, newest first
+    const allNodes = (await loadAllContextNodes(storage))
+        .filter((n) => n.entityPointerIds.includes(entity.id))
+        .sort((a, b) => b.timestamp - a.timestamp);
+    const blocks = [];
+    let totalTokens = estimateTokens(lines.join("\n"));
+    for (const node of allNodes) {
+        // AC-69-03: Update lastReferencedAt on context node entities
+        for (const id of node.entityPointerIds) {
+            const e = entityIndex.getById(id);
+            if (e) {
+                entityIndex.update(id, { lastReferencedAt: now });
+                await storage.update("entities", id, { lastReferencedAt: now });
+            }
+        }
+        const [loaded, superseded] = await loadContextNodeWithSupersession(storage, node.id);
+        if (!loaded)
+            continue;
+        const block = formatContextNodeBlock(loaded, superseded, entityIndex, now);
+        const blockTokens = estimateTokens(block);
+        if (totalTokens + blockTokens > MAX_QUERY_TOKENS)
+            break;
+        blocks.push(block);
+        totalTokens += blockTokens;
+    }
+    if (blocks.length > 0) {
+        lines.push(...blocks);
+    }
+    else {
+        lines.push("No context nodes referencing this entity.");
+    }
+    return lines.join("\n");
+}
+/**
+ * memory_query: BM25F-ranked hub matching + spoke context retrieval (AC-69-02, AC-69-03).
+ * FIX-01: rankHubsByQuery replaces binary matchHubsByTopic.
+ * F-93: orphan scan as safety-net lane.
+ * F-94: coverage signal in header.
+ * F-109: optional LLM query expansion before BM25F.
+ */
+export async function memoryQuery(topic, storage, entityIndex, narrativeCache, cwd, complete) {
+    const now = Date.now();
+    // F-109: Expand query into alternative phrasings before BM25F scoring
+    const queryTerms = complete ? await expandQuery(topic, complete) : [topic];
+    // FIX-01: BM25F ranked hub matching — union results across all expanded terms, max score wins
+    const allHubs = narrativeCache.all();
+    const hubScoreMap = new Map();
+    for (const term of queryTerms) {
+        for (const hub of rankHubsByQuery(term, narrativeCache, cwd)) {
+            if (!hubScoreMap.has(hub.id))
+                hubScoreMap.set(hub.id, hub);
+        }
+    }
+    const matchingHubs = [...hubScoreMap.values()];
+    const hubContextIds = [...new Set(matchingHubs.flatMap((h) => h.spokeNodeIds))];
+    // F-93: Scan orphan context nodes as a safety-net lane (use original topic for orphan scan)
+    const { orphanMatches, totalOrphans } = await scanOrphanNodes(topic, storage, narrativeCache);
+    // F-94: Coverage confidence signal
+    const header = `[MEMORY: Query — "${topic}" | searched: ${allHubs.length} hubs, ${totalOrphans} orphan nodes | hub matches: ${matchingHubs.length}, orphan matches: ${orphanMatches.length}]`;
+    const blocks = [header, ""];
+    let totalTokens = estimateTokens(header);
+    let truncated = false;
+    // Hub-matched spoke nodes
+    for (const id of hubContextIds) {
+        const [node, superseded] = await loadContextNodeWithSupersession(storage, id);
+        if (!node)
+            continue;
+        // AC-69-03: Update entity lastReferencedAt
+        for (const entityId of node.entityPointerIds) {
+            const entity = entityIndex.getById(entityId);
+            if (entity) {
+                entityIndex.update(entityId, { lastReferencedAt: now });
+                await storage.update("entities", entityId, { lastReferencedAt: now });
+            }
+        }
+        const block = formatContextNodeBlock(node, superseded, entityIndex, now);
+        const blockTokens = estimateTokens(block);
+        if (totalTokens + blockTokens > MAX_QUERY_TOKENS) {
+            truncated = true;
+            break;
+        }
+        blocks.push(block);
+        totalTokens += blockTokens;
+    }
+    // F-93: Orphan matches in a separate labeled section
+    if (orphanMatches.length > 0 && !truncated) {
+        blocks.push("[Orphan Matches]");
+        for (const node of orphanMatches) {
+            const [loaded, superseded] = await loadContextNodeWithSupersession(storage, node.id);
+            if (!loaded)
+                continue;
+            for (const entityId of loaded.entityPointerIds) {
+                const entity = entityIndex.getById(entityId);
+                if (entity) {
+                    entityIndex.update(entityId, { lastReferencedAt: now });
+                    await storage.update("entities", entityId, { lastReferencedAt: now });
+                }
+            }
+            const block = formatContextNodeBlock(loaded, superseded, entityIndex, now);
+            const blockTokens = estimateTokens(block);
+            if (totalTokens + blockTokens > MAX_QUERY_TOKENS) {
+                truncated = true;
+                break;
+            }
+            blocks.push(block);
+            totalTokens += blockTokens;
+        }
+    }
+    if (truncated) {
+        blocks.push("\n[MEMORY: Additional results truncated — token budget reached]");
+    }
+    if (blocks.length <= 2) {
+        blocks.push("No matching context found.");
+    }
+    return blocks.join("\n");
+}
+// ---------------------------------------------------------------------------
+// F-69: memory_recall — unified topic → context node → session turns in one hop
+// ---------------------------------------------------------------------------
+const MAX_RECALL_TOKENS = 4_000;
+function extractTurnText(content) {
+    if (typeof content === "string")
+        return content.trim();
+    if (Array.isArray(content)) {
+        return content
+            .filter((b) => b.type === "text" && typeof b.text === "string")
+            .map((b) => b.text)
+            .join(" ")
+            .trim();
+    }
+    return "";
+}
+/**
+ * Read session turns from a JSONL file.
+ * FIX-03: Each turn prefixed with [YYYY-MM-DD HH:mm] when the entry has a timestamp.
+ */
+function readSessionTurns(sessionFile, maxTurns) {
+    const records = readJsonlFile(sessionFile);
+    const turns = [];
+    for (const entry of records) {
+        if (entry.type !== "message")
+            continue;
+        if (!entry.role || (entry.role !== "user" && entry.role !== "assistant"))
+            continue;
+        const text = extractTurnText(entry.content);
+        if (!text)
+            continue;
+        const label = entry.role === "user" ? "User" : "Agent";
+        const ts = entry.timestamp
+            ? `[${new Date(entry.timestamp).toISOString().slice(0, 16).replace("T", " ")}] `
+            : "";
+        turns.push(`${ts}${label}: ${text}`);
+        if (turns.length >= maxTurns)
+            break;
+    }
+    return turns;
+}
+/**
+ * memory_recall: unified topic → context → Layer 1 session turns (one tool call).
+ * FIX-01: BM25F ranked hub matching replaces binary matchHubsByTopic.
+ * FIX-03: Optional fromDate/toDate date-range filtering on spoke ContextNodes.
+ *
+ * 1. Ranks narrative hubs by BM25F score for topic.
+ * 2. Loads context nodes from matching hubs (optionally filtered by date range).
+ * 3. Resolves and reads session JSONL for the best matching context node.
+ * Returns context summary + session turns with [YYYY-MM-DD HH:mm] timestamps.
+ */
+export async function memoryRecall(topic, storage, entityIndex, narrativeCache, maxTurns = 30, cwd, fromDate, toDate, complete) {
+    const now = Date.now();
+    // Step 1: BM25F hub ranking with optional F-109 query expansion
+    const queryTerms = complete ? await expandQuery(topic, complete) : [topic];
+    const allHubs = narrativeCache.all();
+    const hubScoreMap = new Map();
+    for (const term of queryTerms) {
+        for (const hub of rankHubsByQuery(term, narrativeCache, cwd)) {
+            if (!hubScoreMap.has(hub.id))
+                hubScoreMap.set(hub.id, hub);
+        }
+    }
+    const matchingHubs = [...hubScoreMap.values()];
+    let hubContextIds = [...new Set(matchingHubs.flatMap((h) => h.spokeNodeIds))];
+    // F-93: Scan orphan nodes as safety-net lane (use original topic)
+    const { orphanMatches, totalOrphans } = await scanOrphanNodes(topic, storage, narrativeCache);
+    // F-94: Coverage confidence signal
+    const header = `[MEMORY: Recall — "${topic}" | searched: ${allHubs.length} hubs, ${totalOrphans} orphan nodes | hub matches: ${matchingHubs.length}, orphan matches: ${orphanMatches.length}]`;
+    // FIX-03: Date range filter on spoke ContextNodes
+    if (fromDate || toDate) {
+        const allNodes = await loadAllContextNodes(storage);
+        const nodeMap = new Map(allNodes.map((n) => [n.id, n]));
+        hubContextIds = hubContextIds.filter((id) => {
+            const node = nodeMap.get(id);
+            if (!node)
+                return false;
+            if (fromDate && node.timestamp < fromDate.getTime())
+                return false;
+            if (toDate && node.timestamp > toDate.getTime())
+                return false;
+            return true;
+        });
+        // Also filter orphan matches by date range
+        const filteredOrphans = orphanMatches.filter((n) => {
+            if (fromDate && n.timestamp < fromDate.getTime())
+                return false;
+            if (toDate && n.timestamp > toDate.getTime())
+                return false;
+            return true;
+        });
+        if (hubContextIds.length === 0 && filteredOrphans.length === 0) {
+            return `${header}\n\nNo matching context found in the specified date range.`;
+        }
+    }
+    if (hubContextIds.length === 0 && orphanMatches.length === 0) {
+        return `${header}\n\nNo matching context found.`;
+    }
+    // Step 2: Load context nodes from hub spokes, then orphan matches
+    const contextBlocks = [];
+    let resolvedSessionFile = null;
+    let resolvedSessionId = null;
+    let totalTokens = estimateTokens(header);
+    async function loadAndAppend(id) {
+        const [node, superseded] = await loadContextNodeWithSupersession(storage, id);
+        if (!node)
+            return false;
+        for (const entityId of node.entityPointerIds) {
+            const entity = entityIndex.getById(entityId);
+            if (entity) {
+                entityIndex.update(entityId, { lastReferencedAt: now });
+                await storage.update("entities", entityId, { lastReferencedAt: now });
+            }
+        }
+        const block = formatContextNodeBlock(node, superseded, entityIndex, now);
+        const blockTokens = estimateTokens(block);
+        if (totalTokens + blockTokens > MAX_RECALL_TOKENS)
+            return false;
+        contextBlocks.push(block);
+        totalTokens += blockTokens;
+        // Capture the first (best) node's session file for Layer 1 retrieval
+        if (resolvedSessionFile === null) {
+            resolvedSessionId = node.sessionId;
+            if (node.sessionFile) {
+                resolvedSessionFile = node.sessionFile;
+            }
+            else {
+                const treeIndex = await loadSessionTree(storage);
+                resolvedSessionFile = resolveSessionFile(node.sessionId, treeIndex);
+            }
+        }
+        return true;
+    }
+    // Hub-matched spokes first
+    for (const id of hubContextIds) {
+        const ok = await loadAndAppend(id);
+        if (!ok)
+            break;
+    }
+    // F-93: Orphan matches — append under separate label if budget allows
+    if (orphanMatches.length > 0 && totalTokens < MAX_RECALL_TOKENS) {
+        contextBlocks.push("[Orphan Matches]");
+        for (const node of orphanMatches) {
+            const ok = await loadAndAppend(node.id);
+            if (!ok)
+                break;
+        }
+    }
+    if (contextBlocks.length === 0 || (contextBlocks.length === 1 && contextBlocks[0] === "[Orphan Matches]")) {
+        return `${header}\n\nNo matching context found.`;
+    }
+    // Step 3: Read session turns from Layer 1 (FIX-03: turns include timestamps)
+    const lines = [header, "", ...contextBlocks];
+    if (resolvedSessionFile) {
+        const turns = readSessionTurns(resolvedSessionFile, maxTurns);
+        if (turns.length > 0) {
+            const date = (() => {
+                const m = contextBlocks[0]?.match(/\[RETRIEVED CONTEXT: [^,]+, (\d{4}-\d{2}-\d{2})\]/);
+                return m?.[1] ?? "";
+            })();
+            const turnHeader = date
+                ? `[SESSION TURNS: ${resolvedSessionId}, ${date}]`
+                : `[SESSION TURNS: ${resolvedSessionId ?? "unknown"}]`;
+            lines.push("", turnHeader, ...turns);
+        }
+        else {
+            lines.push("", `[SESSION TURNS: No message entries found in session file]`);
+        }
+    }
+    else {
+        lines.push("", `[SESSION TURNS: Not available — sessionFile absent from context node and not found in session tree index]`);
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=read-path.js.map

package/dist/core/session-tree-index.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Session Tree Index — F-74 (persistent Layer 0 registry) and F-76 (traversal API).
+ *
+ * Records session tree topology across process invocations so the memory system
+ * can resolve ContextNode sessionIds to JSONL file paths without the live
+ * SessionManager being present.
+ *
+ * Adapted for @chili/memory: uses IMemoryStorage instead of direct file paths.
+ */
+import type { IMemoryStorage } from "../storage/adapter.js";
+export interface SessionTreeEntry {
+    /** Unique record ID (UUID). */
+    id: string;
+    /** The session ID for this entry. */
+    sessionId: string;
+    /** Absolute path to the session JSONL file. */
+    sessionFile: string;
+    /** Parent session JSONL file path (null for root sessions). */
+    parentSessionFile: string | null;
+    /** Working directory when the session started. */
+    cwd: string;
+    /** Unix timestamp (ms) when session_start fired. */
+    timestamp: number;
+}
+/**
+ * Record the current session in the persistent tree index.
+ * Called once per session_start. Append-only — entries are never modified.
+ */
+export declare function recordSessionStart(params: {
+    storage: IMemoryStorage;
+    sessionId: string;
+    sessionFile: string;
+    parentSessionFile: string | null;
+    cwd: string;
+}): Promise<void>;
+/**
+ * Load all entries from the session tree index.
+ * Returns an empty array if the collection is empty.
+ */
+export declare function loadSessionTree(storage: IMemoryStorage): Promise<SessionTreeEntry[]>;
+/**
+ * Resolve a session ID to its JSONL file path using the persistent index.
+ * O(N) linear scan — acceptable at expected session counts (<1,000).
+ * Returns null if the session ID is not recorded in the index.
+ */
+export declare function resolveSessionFile(sessionId: string, index: SessionTreeEntry[]): string | null;
+/**
+ * Walk parentSessionFile references back to the root.
+ * Returns the full ancestor chain for the given session file path,
+ * oldest entry first (root → ... → target).
+ * The entry for the target session itself is included as the last element.
+ */
+export declare function getAncestorChain(sessionFile: string, index: SessionTreeEntry[]): SessionTreeEntry[];
+export interface TreeRenderRow {
+    entry: SessionTreeEntry;
+    depth: number;
+    hasContextNode: boolean;
+    isCurrent: boolean;
+}
+/**
+ * Build a depth-annotated render list for all sessions in the index,
+ * sorted by timestamp within each depth level.
+ */
+export declare function buildTreeRenderRows(index: SessionTreeEntry[], currentSessionId: string, contextNodeSessionIds: Set<string>): TreeRenderRow[];
+/**
+ * Render tree rows as a compact ASCII string for display.
+ */
+export declare function renderSessionTree(rows: TreeRenderRow[]): string;
+//# sourceMappingURL=session-tree-index.d.ts.map

package/dist/core/session-tree-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-tree-index.d.ts","sourceRoot":"","sources":["../../src/core/session-tree-index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAM5D,MAAM,WAAW,gBAAgB;IAChC,+BAA+B;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,qCAAqC;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,+CAA+C;IAC/C,WAAW,EAAE,MAAM,CAAC;IACpB,+DAA+D;IAC/D,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,kDAAkD;IAClD,GAAG,EAAE,MAAM,CAAC;IACZ,oDAAoD;IACpD,SAAS,EAAE,MAAM,CAAC;CAClB;AAMD;;;GAGG;AACH,wBAAsB,kBAAkB,CAAC,MAAM,EAAE;IAChD,OAAO,EAAE,cAAc,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,GAAG,EAAE,MAAM,CAAC;CACZ,GAAG,OAAO,CAAC,IAAI,CAAC,CAWhB;AAMD;;;GAGG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAE1F;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,gBAAgB,EAAE,GAAG,MAAM,GAAG,IAAI,CAM9F;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,gBAAgB,EAAE,GAAG,gBAAgB,EAAE,CAkBnG;AAMD,MAAM,WAAW,aAAa;IAC7B,KAAK,EAAE,gBAAgB,CAAC;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,EAAE,OAAO,CAAC;IACxB,SAAS,EAAE,OAAO,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAClC,KAAK,EAAE,gBAAgB,EAAE,EACzB,gBAAgB,EAAE,MAAM,EACxB,qBAAqB,EAAE,GAAG,CAAC,MAAM,CAAC,GAChC,aAAa,EAAE,CAiCjB;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,aAAa,EAAE,GAAG,MAAM,CAe/D","sourcesContent":["/**\n * Session Tree Index — F-74 (persistent Layer 0 registry) and F-76 (traversal API).\n *\n * Records session tree topology across process invocations so the memory system\n * can resolve ContextNode sessionIds to JSONL file paths without the live\n * SessionManager being present.\n *\n * Adapted for @chili/memory: uses IMemoryStorage instead of direct file paths.\n */\n\nimport type { IMemoryStorage } from \"../storage/adapter.js\";\n\n// ---------------------------------------------------------------------------\n// F-74: SessionTreeEntry schema\n// ---------------------------------------------------------------------------\n\nexport interface SessionTreeEntry {\n\t/** Unique record ID (UUID). */\n\tid: string;\n\t/** The session ID for this entry. */\n\tsessionId: string;\n\t/** Absolute path to the session JSONL file. */\n\tsessionFile: string;\n\t/** Parent session JSONL file path (null for root sessions). */\n\tparentSessionFile: string | null;\n\t/** Working directory when the session started. */\n\tcwd: string;\n\t/** Unix timestamp (ms) when session_start fired. */\n\ttimestamp: number;\n}\n\n// ---------------------------------------------------------------------------\n// F-74: Write — append one entry at session_start\n// ---------------------------------------------------------------------------\n\n/**\n * Record the current session in the persistent tree index.\n * Called once per session_start. Append-only — entries are never modified.\n */\nexport async function recordSessionStart(params: {\n\tstorage: IMemoryStorage;\n\tsessionId: string;\n\tsessionFile: string;\n\tparentSessionFile: string | null;\n\tcwd: string;\n}): Promise<void> {\n\tconst { storage, sessionId, sessionFile, parentSessionFile, cwd } = params;\n\tconst entry: SessionTreeEntry = {\n\t\tid: globalThis.crypto.randomUUID(),\n\t\tsessionId,\n\t\tsessionFile,\n\t\tparentSessionFile,\n\t\tcwd,\n\t\ttimestamp: Date.now(),\n\t};\n\tawait storage.append<SessionTreeEntry>(\"session-tree\", entry);\n}\n\n// ---------------------------------------------------------------------------\n// F-76: Read — traversal API\n// ---------------------------------------------------------------------------\n\n/**\n * Load all entries from the session tree index.\n * Returns an empty array if the collection is empty.\n */\nexport async function loadSessionTree(storage: IMemoryStorage): Promise<SessionTreeEntry[]> {\n\treturn storage.readAll<SessionTreeEntry>(\"session-tree\");\n}\n\n/**\n * Resolve a session ID to its JSONL file path using the persistent index.\n * O(N) linear scan — acceptable at expected session counts (<1,000).\n * Returns null if the session ID is not recorded in the index.\n */\nexport function resolveSessionFile(sessionId: string, index: SessionTreeEntry[]): string | null {\n\t// Use the most recent entry for this sessionId (last wins, handles re-recordings)\n\tfor (let i = index.length - 1; i >= 0; i--) {\n\t\tif (index[i].sessionId === sessionId) return index[i].sessionFile;\n\t}\n\treturn null;\n}\n\n/**\n * Walk parentSessionFile references back to the root.\n * Returns the full ancestor chain for the given session file path,\n * oldest entry first (root → ... → target).\n * The entry for the target session itself is included as the last element.\n */\nexport function getAncestorChain(sessionFile: string, index: SessionTreeEntry[]): SessionTreeEntry[] {\n\t// Build a map from sessionFile → entry for O(1) parent lookups\n\tconst byFile = new Map<string, SessionTreeEntry>();\n\tfor (const entry of index) {\n\t\tbyFile.set(entry.sessionFile, entry);\n\t}\n\n\tconst chain: SessionTreeEntry[] = [];\n\tlet current = byFile.get(sessionFile);\n\n\t// Walk up the parent chain\n\twhile (current) {\n\t\tchain.unshift(current); // prepend so result is oldest-first\n\t\tif (!current.parentSessionFile) break;\n\t\tcurrent = byFile.get(current.parentSessionFile);\n\t}\n\n\treturn chain;\n}\n\n// ---------------------------------------------------------------------------\n// F-77: Tree rendering helpers (used by /memory tree command)\n// ---------------------------------------------------------------------------\n\nexport interface TreeRenderRow {\n\tentry: SessionTreeEntry;\n\tdepth: number;\n\thasContextNode: boolean;\n\tisCurrent: boolean;\n}\n\n/**\n * Build a depth-annotated render list for all sessions in the index,\n * sorted by timestamp within each depth level.\n */\nexport function buildTreeRenderRows(\n\tindex: SessionTreeEntry[],\n\tcurrentSessionId: string,\n\tcontextNodeSessionIds: Set<string>,\n): TreeRenderRow[] {\n\tif (index.length === 0) return [];\n\n\t// Deduplicate: keep only the most recent entry per sessionId\n\tconst latestBySessionId = new Map<string, SessionTreeEntry>();\n\tfor (const entry of index) {\n\t\tlatestBySessionId.set(entry.sessionId, entry);\n\t}\n\tconst entries = [...latestBySessionId.values()].sort((a, b) => a.timestamp - b.timestamp);\n\n\t// Build parent lookup by sessionFile\n\tconst byFile = new Map<string, SessionTreeEntry>();\n\tfor (const e of entries) byFile.set(e.sessionFile, e);\n\n\t// Compute depth for each entry\n\tfunction depth(entry: SessionTreeEntry): number {\n\t\tlet d = 0;\n\t\tlet cur = entry;\n\t\twhile (cur.parentSessionFile) {\n\t\t\tconst parent = byFile.get(cur.parentSessionFile);\n\t\t\tif (!parent) break;\n\t\t\td++;\n\t\t\tcur = parent;\n\t\t}\n\t\treturn d;\n\t}\n\n\treturn entries.map((entry) => ({\n\t\tentry,\n\t\tdepth: depth(entry),\n\t\thasContextNode: contextNodeSessionIds.has(entry.sessionId),\n\t\tisCurrent: entry.sessionId === currentSessionId,\n\t}));\n}\n\n/**\n * Render tree rows as a compact ASCII string for display.\n */\nexport function renderSessionTree(rows: TreeRenderRow[]): string {\n\tif (rows.length === 0) return \"[memory tree] No sessions recorded yet.\";\n\n\tconst lines: string[] = [\"[memory tree] Cross-session tree (oldest → newest):\", \"\"];\n\tfor (const row of rows) {\n\t\tconst indent = \"  \".repeat(row.depth);\n\t\tconst date = new Date(row.entry.timestamp).toISOString().split(\"T\")[0];\n\t\tconst cwd = row.entry.cwd.replace(/^.*\\/([^/]+)$/, \"$1\"); // basename only\n\t\tconst indexMark = row.hasContextNode ? \"\" : \" [no index]\";\n\t\tconst currentMark = row.isCurrent ? \" →\" : \"\";\n\t\tlines.push(`${indent}${row.entry.sessionId.slice(0, 8)} | ${date} | ${cwd}${indexMark}${currentMark}`);\n\t}\n\tlines.push(\"\");\n\tlines.push(`Total: ${rows.length} session(s)`);\n\treturn lines.join(\"\\n\");\n}\n"]}