@phren/cli 0.0.4 → 0.0.6

package/mcp/dist/mcp-session.js

@@ -169,7 +169,7 @@ function findMostRecentSummaryWithProject(phrenPath) {
         if (fs.existsSync(fastPath)) {
             const data = JSON.parse(fs.readFileSync(fastPath, "utf-8"));
             if (data.summary)
-                return { summary: data.summary, project: data.project };
+                return { summary: data.summary, project: data.project, endedAt: data.endedAt };
         }
     }
     catch (err) {
@@ -181,7 +181,7 @@ function findMostRecentSummaryWithProject(phrenPath) {
     if (results.length === 0)
         return { summary: null };
     const best = results[0]; // already sorted newest-mtime-first
-    return { summary: best.data.summary, project: best.data.project };
+    return { summary: best.data.summary, project: best.data.project, endedAt: best.data.endedAt };
 }
 /** Resolve session file from an explicit sessionId or a previously-bound connectionId. */
 function resolveSessionFile(phrenPath, sessionId, connectionId) {
@@ -338,6 +338,45 @@ function hasCompletedTasksInSession(phrenPath, sessionId, project) {
     const artifacts = getSessionArtifacts(phrenPath, sessionId, project);
     return artifacts.tasks.some((task) => task.section === "Done" && task.checked);
 }
+/** Compute what changed since the last session ended. */
+export function computeSessionDiff(phrenPath, project, lastSessionEnd) {
+    const projectDir = path.join(phrenPath, project);
+    const findingsPath = path.join(projectDir, "FINDINGS.md");
+    if (!fs.existsSync(findingsPath))
+        return { newFindings: 0, superseded: 0, tasksCompleted: 0 };
+    const content = fs.readFileSync(findingsPath, "utf8");
+    const lines = content.split("\n");
+    let currentDate = null;
+    let newFindings = 0;
+    let superseded = 0;
+    const cutoff = lastSessionEnd.slice(0, 10);
+    for (const line of lines) {
+        const dateMatch = line.match(/^## (\d{4}-\d{2}-\d{2})$/);
+        if (dateMatch) {
+            currentDate = dateMatch[1];
+            continue;
+        }
+        if (!line.startsWith("- ") || !currentDate)
+            continue;
+        if (currentDate >= cutoff) {
+            newFindings++;
+            if (line.includes('status "superseded"'))
+                superseded++;
+        }
+    }
+    // Count completed tasks since last session
+    const tasksPath = path.join(projectDir, "TASKS.md");
+    let tasksCompleted = 0;
+    if (fs.existsSync(tasksPath)) {
+        const taskContent = fs.readFileSync(tasksPath, "utf8");
+        const doneMatch = taskContent.match(/## Done[\s\S]*/);
+        if (doneMatch) {
+            const doneLines = doneMatch[0].split("\n").filter(l => l.startsWith("- "));
+            tasksCompleted = doneLines.length;
+        }
+    }
+    return { newFindings, superseded, tasksCompleted };
+}
 export function register(server, ctx) {
     const { phrenPath } = ctx;
     server.registerTool("session_start", {
@@ -364,6 +403,7 @@ export function register(server, ctx) {
         const priorEnded = prior ? null : findMostRecentSummaryWithProject(phrenPath);
         const priorSummary = prior?.summary ?? priorEnded?.summary ?? null;
         const priorProject = prior?.project ?? priorEnded?.project;
+        const priorEndedAt = prior?.endedAt ?? priorEnded?.endedAt;
         // Create new session with unique ID in its own file
         const sessionId = crypto.randomUUID();
         const next = {
@@ -447,6 +487,25 @@ export function register(server, ctx) {
                 debugError("session_start checkpointsRead", err);
             }
         }
+        // Compute context diff since last session
+        if (activeProject && isValidProjectName(activeProject) && priorEndedAt) {
+            try {
+                const diff = computeSessionDiff(phrenPath, activeProject, priorEndedAt);
+                if (diff.newFindings > 0 || diff.superseded > 0 || diff.tasksCompleted > 0) {
+                    const diffParts = [];
+                    if (diff.newFindings > 0)
+                        diffParts.push(`${diff.newFindings} new finding${diff.newFindings === 1 ? "" : "s"}`);
+                    if (diff.superseded > 0)
+                        diffParts.push(`${diff.superseded} superseded`);
+                    if (diff.tasksCompleted > 0)
+                        diffParts.push(`${diff.tasksCompleted} task${diff.tasksCompleted === 1 ? "" : "s"} in done`);
+                    parts.push(`## Since last session\n${diffParts.join(", ")}.`);
+                }
+            }
+            catch (err) {
+                debugError("session_start contextDiff", err);
+            }
+        }
         const message = parts.length > 0
             ? `Session started (${sessionId.slice(0, 8)}).\n\n${parts.join("\n\n")}`
             : `Session started (${sessionId.slice(0, 8)}). No prior context found.`;

package/mcp/dist/memory-ui-data.js

@@ -8,7 +8,7 @@ import { readCustomHooks } from "./hooks.js";
 import { hookConfigPaths, hookConfigRoots } from "./provider-adapters.js";
 import { getAllSkills } from "./skill-registry.js";
 import { resolveTaskFilePath, readTasks, TASKS_FILENAME } from "./data-tasks.js";
-import { buildIndex, queryRows } from "./shared-index.js";
+import { buildIndex, queryDocBySourceKey, queryRows } from "./shared-index.js";
 import { readProjectTopics, classifyTopicForText } from "./project-topics.js";
 import { entryScoreKey } from "./governance-scores.js";
 function extractGithubUrl(content) {
@@ -264,17 +264,16 @@ export async function buildGraph(phrenPath, profile, focusProject) {
     catch {
         // task loading failed — continue with other data sources
     }
-    // ── Fragments (entity graph) ───────────────────────────────────────
+    // ── Fragments (fragment graph) ──────────────────────────────────────
     let db = null;
     try {
         db = await buildIndex(phrenPath, profile);
         const rows = queryRows(db, `SELECT e.id, e.name, e.type, COUNT(DISTINCT el.source_doc) as ref_count
        FROM entities e JOIN entity_links el ON el.target_id = e.id WHERE e.type != 'document'
        GROUP BY e.id, e.name, e.type ORDER BY ref_count DESC LIMIT 500`, []);
-        const refRows = queryRows(db, `SELECT e.id, el.source_doc, d.content, d.filename
+        const refRows = queryRows(db, `SELECT e.id, el.source_doc
        FROM entities e
        JOIN entity_links el ON el.target_id = e.id
-       LEFT JOIN docs d ON d.source_key = el.source_doc
        WHERE e.type != 'document'`, []);
         const refsByEntity = new Map();
         const seenEntityDoc = new Set();
@@ -291,8 +290,9 @@ export async function buildGraph(phrenPath, profile, focusProject) {
                     continue;
                 seenEntityDoc.add(entityDocKey);
                 const project = projectFromSourceDoc(doc);
-                const content = typeof row[2] === "string" ? row[2] : "";
-                const filename = typeof row[3] === "string" ? row[3] : "";
+                const docRow = queryDocBySourceKey(db, phrenPath, doc);
+                const content = docRow?.content ?? "";
+                const filename = docRow?.filename ?? "";
                 const scoreKey = project && filename && content ? entryScoreKey(project, filename, content) : undefined;
                 const refs = refsByEntity.get(entityId) ?? [];
                 refs.push({ doc, project, scoreKey });
@@ -326,7 +326,7 @@ export async function buildGraph(phrenPath, profile, focusProject) {
                     entityType: type,
                     refDocs: refs,
                 });
-                // Link entity to each project it appears in
+                // Link fragment to each project it appears in
                 const linkedProjects = new Set();
                 for (const ref of refs) {
                     if (ref.project && projectSet.has(ref.project))
@@ -339,7 +339,7 @@ export async function buildGraph(phrenPath, profile, focusProject) {
         }
     }
     catch {
-        // entity loading failed — continue with other data sources
+        // fragment loading failed — continue with other data sources
     }
     finally {
         if (db) {

package/mcp/dist/phren-art.js

@@ -1,8 +1,12 @@
 /**
- * Phren character ASCII/Unicode art and spinner for CLI presence.
+ * Phren character ASCII/Unicode art, animation engine, and spinner for CLI presence.
  *
  * Based on the pixel art: purple 8-bit brain with diamond eyes,
  * smile, little legs, and cyan sparkle.
+ *
+ * Animation system provides lifelike movement through composable effects:
+ * bob, blink, sparkle, and lean — all driven by setTimeout with randomized
+ * intervals for organic timing.
  */
 const ESC = "\x1b[";
 const RESET = `${ESC}0m`;
@@ -14,6 +18,7 @@ const DARK_PURPLE = `${ESC}38;5;57m`; // deep purple — shadow/outline
 const LIGHT_PURPLE = `${ESC}38;5;141m`; // lavender — brain highlights
 const MID_PURPLE = `${ESC}38;5;98m`; // mid tone
 const NAVY = `${ESC}38;5;18m`; // darkest outline
+// ── Art constants (24px wide, truecolor half-blocks) ─────────────────────────
 /**
  * Phren truecolor art (24px wide, generated from phren-transparent.png).
  * Uses half-block ▀ with RGB foreground+background for pixel-faithful rendering.
@@ -33,6 +38,268 @@ export const PHREN_ART = [
     "                        ",
     "                        ",
 ];
+/** The art width in visible columns */
+const ART_WIDTH = 24;
+// ── Sparkle row: the cyan pixels at row 2 ────────────────────────────────────
+// Sparkle uses ▄ half-blocks with cyan truecolor. For animation we cycle through
+// decorative unicode characters at different brightness levels.
+const SPARKLE_ROW = 2;
+const SPARKLE_CHARS = ["\u2726", "\u2727", "\u2736", " "]; // ✦ ✧ ✶ (dim/blank)
+// ── Eye detection: dark navy pixels in row 6 (fg R<30, G<45, B<120) ──────────
+// Row 6 has two eye pixels at segments 1 and 5 (visual positions 7 and 11).
+// When blinking, we replace their dark fg color with the surrounding body purple.
+const EYE_ROW = 6;
+// Dark-pixel fg threshold
+const EYE_R_MAX = 30;
+const EYE_G_MAX = 45;
+const EYE_B_MAX = 120;
+// Body-purple color to use when "closing" eyes (average of surrounding pixels)
+const BLINK_COLOR = "146;130;250";
+/**
+ * Flip a single art line horizontally. Reverses the order of colored pixel
+ * segments and swaps leading/trailing whitespace so the character faces right.
+ * Half-block characters (▀ ▄) are horizontally symmetric so no char swap needed.
+ */
+function flipLine(line) {
+    const stripped = line.replace(/\x1b\[[^m]*m/g, "");
+    const leadSpaces = stripped.match(/^( *)/)[1].length;
+    const trailSpaces = stripped.match(/( *)$/)[1].length;
+    // Parse pixel segments: each is one or two ANSI color codes followed by a block char.
+    // We strip any leading reset (\x1b[0m) from captured codes — it's an artifact from
+    // the original per-pixel reset pattern and will be re-added during reassembly.
+    const pixels = [];
+    const pixelRegex = /((?:\x1b\[[^m]*m)+)([\u2580\u2584])/g;
+    let match;
+    while ((match = pixelRegex.exec(line)) !== null) {
+        const codes = match[1].replace(/\x1b\[0m/g, "");
+        if (codes)
+            pixels.push({ codes, char: match[2] });
+    }
+    if (pixels.length === 0)
+        return line; // blank or space-only line
+    const reversed = [...pixels].reverse();
+    const newLead = " ".repeat(trailSpaces);
+    const newTrail = " ".repeat(leadSpaces);
+    let result = newLead;
+    for (const px of reversed) {
+        result += px.codes + px.char + "\x1b[0m";
+    }
+    result += newTrail;
+    return result;
+}
+/**
+ * Generate horizontally flipped art (facing right).
+ */
+function generateFlippedArt(art) {
+    return art.map(flipLine);
+}
+/** Pre-computed right-facing art */
+export const PHREN_ART_RIGHT = generateFlippedArt(PHREN_ART);
+/** Random integer in [min, max] inclusive */
+function randInt(min, max) {
+    return Math.floor(Math.random() * (max - min + 1)) + min;
+}
+/**
+ * Replace eye pixels on a single line with the blink color.
+ * Eye pixels are identified by their dark navy fg color (R<30, G<45, B<120).
+ * We replace the fg color code while preserving the bg code and character.
+ */
+function applyBlinkToLine(line) {
+    // Match ANSI color sequences: each pixel is \e[38;2;R;G;Bm (optionally with \e[48;2;...m) then a block char
+    // We scan for fg codes that match the eye threshold and replace them with the blink color
+    return line.replace(/\x1b\[38;2;(\d+);(\d+);(\d+)m/g, (full, rStr, gStr, bStr) => {
+        const r = Number(rStr);
+        const g = Number(gStr);
+        const b = Number(bStr);
+        if (r < EYE_R_MAX && g < EYE_G_MAX && b < EYE_B_MAX) {
+            return `\x1b[38;2;${BLINK_COLOR}m`;
+        }
+        return full;
+    });
+}
+/**
+ * Replace the sparkle pixels on the sparkle row with the current sparkle character.
+ * The sparkle row has two cyan ▄ half-blocks. During sparkle animation we replace
+ * them with decorative Unicode characters from SPARKLE_CHARS.
+ */
+function applySparkleToLine(line, frame, active) {
+    if (!active)
+        return line;
+    const sparkleChar = SPARKLE_CHARS[frame % SPARKLE_CHARS.length];
+    if (sparkleChar === " ") {
+        // Dim: replace the cyan-colored segments with spaces (they disappear)
+        return line.replace(/\x1b\[38;2;\d+;2\d\d;2\d\dm[\u2580\u2584]\x1b\[0m/g, " ");
+    }
+    // Replace the half-block characters with the sparkle unicode char, keeping the cyan color
+    return line.replace(/(\x1b\[38;2;\d+;2\d\d;2\d\dm)[\u2580\u2584](\x1b\[0m)/g, `$1${sparkleChar}$2`);
+}
+/**
+ * Apply lean (horizontal shift) to a line.
+ * Positive offset = shift right (prepend spaces, trim from end).
+ * Negative offset = shift left (trim from start, append spaces).
+ */
+function applyLean(line, offset) {
+    if (offset === 0)
+        return line;
+    if (offset > 0) {
+        // Shift right: prepend spaces
+        return " ".repeat(offset) + line;
+    }
+    // Shift left: remove leading spaces (up to |offset|)
+    const trimCount = Math.min(-offset, line.match(/^( *)/)[1].length);
+    return line.slice(trimCount);
+}
+/**
+ * Create an animated phren character controller.
+ *
+ * @param options.facing - 'left' (default, original) or 'right' (flipped)
+ * @param options.size - art width; unused but reserved for future scaling (default 24)
+ */
+export function createPhrenAnimator(options) {
+    const facing = options?.facing ?? "left";
+    const baseArt = facing === "right" ? PHREN_ART_RIGHT : PHREN_ART;
+    const state = {
+        bobUp: false,
+        isBlinking: false,
+        sparkleFrame: 0,
+        sparkleActive: false,
+        leanOffset: 0,
+    };
+    const timers = [];
+    function scheduleTimer(fn, ms) {
+        const t = setTimeout(fn, ms);
+        timers.push(t);
+    }
+    // ── Bob animation: toggles bobUp every ~500ms ──────────────────────────
+    function scheduleBob() {
+        scheduleTimer(() => {
+            state.bobUp = !state.bobUp;
+            scheduleBob();
+        }, 500);
+    }
+    // ── Blink animation: eyes close for 150ms, random 2-8s intervals ──────
+    function scheduleBlink() {
+        const interval = randInt(2000, 8000);
+        scheduleTimer(() => {
+            // Perform blink
+            state.isBlinking = true;
+            scheduleTimer(() => {
+                state.isBlinking = false;
+                // 30% chance of double-blink
+                if (Math.random() < 0.3) {
+                    scheduleTimer(() => {
+                        state.isBlinking = true;
+                        scheduleTimer(() => {
+                            state.isBlinking = false;
+                            scheduleBlink();
+                        }, 150);
+                    }, 200);
+                }
+                else {
+                    scheduleBlink();
+                }
+            }, 150);
+        }, interval);
+    }
+    // ── Sparkle animation: fast cycle during bursts, long pauses between ───
+    function scheduleSparkle() {
+        // Wait 1-5 seconds before next sparkle burst
+        const pause = randInt(1000, 5000);
+        scheduleTimer(() => {
+            state.sparkleActive = true;
+            state.sparkleFrame = 0;
+            sparkleStep(0);
+        }, pause);
+    }
+    function sparkleStep(step) {
+        if (step >= SPARKLE_CHARS.length) {
+            // Burst complete
+            state.sparkleActive = false;
+            scheduleSparkle();
+            return;
+        }
+        state.sparkleFrame = step;
+        scheduleTimer(() => {
+            sparkleStep(step + 1);
+        }, 200);
+    }
+    // ── Lean animation: shift 1 col left or right every 4-10s, hold 1-2s ──
+    function scheduleLean() {
+        const interval = randInt(4000, 10000);
+        scheduleTimer(() => {
+            const direction = Math.random() < 0.5 ? -1 : 1;
+            state.leanOffset = direction;
+            const holdTime = randInt(1000, 2000);
+            scheduleTimer(() => {
+                state.leanOffset = 0;
+                scheduleLean();
+            }, holdTime);
+        }, interval);
+    }
+    return {
+        getFrame() {
+            let lines = baseArt.map((line, i) => {
+                let result = line;
+                // Apply blink to the eye row
+                if (state.isBlinking && i === EYE_ROW) {
+                    result = applyBlinkToLine(result);
+                }
+                // Apply sparkle to sparkle row
+                if (i === SPARKLE_ROW) {
+                    result = applySparkleToLine(result, state.sparkleFrame, state.sparkleActive);
+                }
+                // Apply lean
+                result = applyLean(result, state.leanOffset);
+                return result;
+            });
+            // Apply bob: when bobUp, prepend a blank line (shift everything down visually)
+            if (state.bobUp) {
+                lines = ["", ...lines.slice(0, -1)];
+            }
+            return lines;
+        },
+        start() {
+            scheduleBob();
+            scheduleBlink();
+            scheduleSparkle();
+            scheduleLean();
+        },
+        stop() {
+            for (const t of timers) {
+                clearTimeout(t);
+            }
+            timers.length = 0;
+        },
+    };
+}
+// ── Startup frames (pre-baked, no timers) ────────────────────────────────────
+/**
+ * Returns 4 pre-baked animation frames for shell startup display.
+ * No timers needed — the caller cycles through them manually.
+ *
+ * Frames: [neutral, bob-up, neutral, bob-down(sparkle)]
+ *
+ * @param facing - 'left' (default) or 'right'
+ */
+export function getPhrenStartupFrames(facing) {
+    const art = facing === "right" ? PHREN_ART_RIGHT : PHREN_ART;
+    // Frame 0: neutral
+    const frame0 = [...art];
+    // Frame 1: bob up (prepend blank line, drop last line)
+    const frame1 = ["", ...art.slice(0, -1)];
+    // Frame 2: neutral (same as frame 0)
+    const frame2 = [...art];
+    // Frame 3: bob down with sparkle burst — shift down by removing first line, append blank
+    const frame3WithSparkle = art.map((line, i) => {
+        if (i === SPARKLE_ROW) {
+            return applySparkleToLine(line, 0, true); // ✦ sparkle
+        }
+        return line;
+    });
+    const frame3 = [...frame3WithSparkle.slice(1), ""];
+    return [frame0, frame1, frame2, frame3];
+}
+// ── Legacy exports (unchanged) ───────────────────────────────────────────────
 /** Single-line compact phren for inline use */
 export const PHREN_INLINE = `${PURPLE}◆${RESET}`;
 /** Phren spinner frames for search/sync operations — cycles through in purple */

package/mcp/dist/phren-core.js

@@ -1,6 +1,6 @@
 // Shared Phren result types, validation tags, and low-level helpers.
 /**
- * Minimal cross-domain starter set for entity/conflict detection.
+ * Minimal cross-domain starter set for fragment/conflict detection.
  *
  * Kept intentionally small: only terms that are genuinely universal across
  * disciplines (languages, infra primitives, version control). Framework-specific
@@ -9,8 +9,8 @@
  */
 export const UNIVERSAL_TECH_TERMS_RE = /\b(Python|Rust|Go|Java|TypeScript|JavaScript|Docker|Kubernetes|AWS|GCP|Azure|SQL|Git)\b/gi;
 /**
- * Additional entity patterns beyond CamelCase and acronyms.
- * Each pattern has a named group so callers can identify the entity type.
+ * Additional fragment patterns beyond CamelCase and acronyms.
+ * Each pattern has a named group so callers can identify the fragment type.
  */
 export const EXTRA_ENTITY_PATTERNS = [
     // Semantic version numbers: v1.2.3, 2.0.0-beta.1
@@ -91,7 +91,7 @@ export const FINDING_TAGS = FINDING_TYPES;
 /** Canonical set of known observation tags — derived from FINDING_TYPES */
 export const KNOWN_OBSERVATION_TAGS = new Set(FINDING_TYPES);
 /** Document types in the FTS index */
-export const DOC_TYPES = ["claude", "findings", "reference", "skills", "summary", "task", "changelog", "canonical", "memory-queue", "skill", "other"];
+export const DOC_TYPES = ["claude", "findings", "reference", "skills", "summary", "task", "changelog", "canonical", "review-queue", "skill", "other"];
 // ── Cache eviction helper ────────────────────────────────────────────────────
 const CACHE_MAX = 1000;
 const CACHE_EVICT = 100;

package/mcp/dist/phren-paths.js

@@ -433,7 +433,7 @@ export function computePhrenLiveStateToken(phrenPath) {
     for (const projectDir of projectDirs) {
         const project = path.basename(projectDir);
         parts.push(`project:${project}`);
-        for (const file of ["CLAUDE.md", "summary.md", "FINDINGS.md", "tasks.md", "MEMORY_QUEUE.md", "CANONICAL_MEMORIES.md", "topic-config.json", "phren.project.yaml"]) {
+        for (const file of ["CLAUDE.md", "summary.md", "FINDINGS.md", "tasks.md", "review.md", "truths.md", "topic-config.json", "phren.project.yaml"]) {
             pushFileToken(parts, path.join(projectDir, file));
         }
         pushDirTokens(parts, path.join(projectDir, "reference"));

package/mcp/dist/profile-store.js

@@ -209,7 +209,7 @@ function buildProjectCard(dir) {
         .split("\n")
         .map((line) => line.trim())
         .find((line) => line && !line.startsWith("#")) || "";
-    const docs = ["CLAUDE.md", "FINDINGS.md", "summary.md", "MEMORY_QUEUE.md"]
+    const docs = ["CLAUDE.md", "FINDINGS.md", "summary.md", "review.md"]
         .filter((file) => fs.existsSync(path.join(dir, file)));
     const taskFile = TASK_FILE_ALIASES.find((file) => fs.existsSync(path.join(dir, file)));
     if (taskFile)

package/mcp/dist/query-correlation.js

@@ -0,0 +1,147 @@
+// query-correlation.ts — Lightweight query-to-finding correlation tracker.
+// Tracks which queries led to which documents being selected (and later rated "helpful"),
+// then uses that data to pre-warm results for recurring query patterns.
+//
+// Gated behind PHREN_FEATURE_QUERY_CORRELATION env var (disabled by default).
+// Storage: JSONL append to .runtime/query-correlations.jsonl, last-500 window.
+import * as fs from "fs";
+import { runtimeFile, debugLog } from "./shared.js";
+import { isFeatureEnabled, errorMessage } from "./utils.js";
+const CORRELATION_FILENAME = "query-correlations.jsonl";
+const RECENT_WINDOW = 500;
+const MIN_TOKEN_OVERLAP = 2;
+const MIN_TOKEN_LENGTH = 3;
+/**
+ * Check if query correlation feature is enabled via env var.
+ */
+export function isQueryCorrelationEnabled() {
+    return isFeatureEnabled("PHREN_FEATURE_QUERY_CORRELATION", false);
+}
+/**
+ * Log query-to-finding correlations after snippet selection.
+ * Called from handleHookPrompt after selectSnippets.
+ */
+export function logCorrelations(phrenPath, keywords, selected, sessionId) {
+    if (!isQueryCorrelationEnabled())
+        return;
+    if (!selected.length || !keywords.trim())
+        return;
+    try {
+        const correlationFile = runtimeFile(phrenPath, CORRELATION_FILENAME);
+        const lines = [];
+        for (const sel of selected) {
+            const entry = {
+                timestamp: new Date().toISOString(),
+                keywords: keywords.slice(0, 200),
+                project: sel.doc.project,
+                filename: sel.doc.filename,
+                sessionId,
+            };
+            lines.push(JSON.stringify(entry));
+        }
+        fs.appendFileSync(correlationFile, lines.join("\n") + "\n");
+    }
+    catch (err) {
+        debugLog(`query-correlation log failed: ${errorMessage(err)}`);
+    }
+}
+/**
+ * Mark correlations from a session as "helpful" when positive feedback is received.
+ * This retroactively stamps entries so that future correlation lookups weight them higher.
+ */
+export function markCorrelationsHelpful(phrenPath, sessionId, docKey) {
+    if (!isQueryCorrelationEnabled())
+        return;
+    try {
+        const correlationFile = runtimeFile(phrenPath, CORRELATION_FILENAME);
+        if (!fs.existsSync(correlationFile))
+            return;
+        const raw = fs.readFileSync(correlationFile, "utf8");
+        const lines = raw.split("\n").filter(Boolean);
+        let modified = false;
+        const updated = lines.map((line) => {
+            try {
+                const entry = JSON.parse(line);
+                if (entry.sessionId === sessionId &&
+                    `${entry.project}/${entry.filename}` === docKey &&
+                    !entry.helpful) {
+                    entry.helpful = true;
+                    modified = true;
+                    return JSON.stringify(entry);
+                }
+            }
+            catch {
+                // keep original line
+            }
+            return line;
+        });
+        if (modified) {
+            fs.writeFileSync(correlationFile, updated.join("\n") + "\n");
+        }
+    }
+    catch (err) {
+        debugLog(`query-correlation mark-helpful failed: ${errorMessage(err)}`);
+    }
+}
+/**
+ * Tokenize a keyword string for overlap comparison.
+ */
+function tokenize(text) {
+    return new Set(text
+        .toLowerCase()
+        .split(/\s+/)
+        .filter((w) => w.length >= MIN_TOKEN_LENGTH));
+}
+/**
+ * Find documents that historically correlate with the given query keywords.
+ * Returns doc keys (project/filename) sorted by correlation strength.
+ *
+ * Only looks at the last RECENT_WINDOW entries for performance.
+ * Entries marked "helpful" get a 2x weight boost.
+ */
+export function getCorrelatedDocs(phrenPath, keywords, limit = 3) {
+    if (!isQueryCorrelationEnabled())
+        return [];
+    try {
+        const correlationFile = runtimeFile(phrenPath, CORRELATION_FILENAME);
+        if (!fs.existsSync(correlationFile))
+            return [];
+        const raw = fs.readFileSync(correlationFile, "utf8");
+        const lines = raw.split("\n").filter(Boolean);
+        // Only look at last RECENT_WINDOW entries to keep it fast
+        const recent = lines.slice(-RECENT_WINDOW);
+        const queryTokens = tokenize(keywords);
+        if (queryTokens.size === 0)
+            return [];
+        const docScores = new Map();
+        for (const line of recent) {
+            try {
+                const entry = JSON.parse(line);
+                const entryTokens = tokenize(entry.keywords);
+                // Calculate overlap between current query and past query
+                let overlap = 0;
+                for (const t of queryTokens) {
+                    if (entryTokens.has(t))
+                        overlap++;
+                }
+                if (overlap >= MIN_TOKEN_OVERLAP) {
+                    const key = `${entry.project}/${entry.filename}`;
+                    // Helpful entries get a 2x weight boost
+                    const weight = entry.helpful ? overlap * 2 : overlap;
+                    docScores.set(key, (docScores.get(key) ?? 0) + weight);
+                }
+            }
+            catch {
+                // skip malformed lines
+            }
+        }
+        return [...docScores.entries()]
+            .sort((a, b) => b[1] - a[1])
+            .slice(0, limit)
+            .map(([key]) => key);
+    }
+    catch (err) {
+        debugLog(`query-correlation lookup failed: ${errorMessage(err)}`);
+        return [];
+    }
+}

package/mcp/dist/shared-content.js

@@ -3,6 +3,6 @@ export { checkConsolidationNeeded, validateFindingsFormat, stripTaskDoneSection,
 export { filterTrustedFindings, filterTrustedFindingsDetailed, } from "./content-citation.js";
 export { scanForSecrets, resolveCoref, isDuplicateFinding, detectConflicts, extractDynamicEntities, checkSemanticDedup, checkSemanticConflicts, } from "./content-dedup.js";
 export { countActiveFindings, autoArchiveToReference, } from "./content-archive.js";
-export { upsertCanonical, addFindingToFile, addFindingsToFile, } from "./content-learning.js";
-export { FINDING_LIFECYCLE_STATUSES, parseFindingLifecycle, buildLifecycleComments, isInactiveFindingLine, } from "./finding-lifecycle.js";
+export { upsertCanonical, addFindingToFile, addFindingsToFile, autoDetectFindingType, } from "./content-learning.js";
+export { FINDING_LIFECYCLE_STATUSES, FINDING_TYPE_DECAY, extractFindingType, parseFindingLifecycle, buildLifecycleComments, isInactiveFindingLine, } from "./finding-lifecycle.js";
 export { METADATA_REGEX, parseStatus, parseStatusField, parseSupersession, parseSupersedesRef, parseContradiction, parseAllContradictions, parseFindingId, parseCreatedDate, isCitationLine, isArchiveStart, isArchiveEnd, stripLifecycleMetadata, stripRelationMetadata, stripAllMetadata, stripComments, addMetadata, } from "./content-metadata.js";