@phren/cli 0.0.4 → 0.0.6

package/mcp/dist/cli-hooks.js

@@ -150,6 +150,26 @@ export async function handleHookPrompt() {
     if (!keywords)
         process.exit(0);
     debugLog(`hook-prompt keywords: "${keywords}"`);
+    // Session momentum: track topic frequencies within the session
+    let hotTopics = [];
+    if (sessionId) {
+        const topicFile = sessionMarker(getPhrenPath(), `topics-${sessionId}.json`);
+        let sessionTopics = {};
+        try {
+            if (fs.existsSync(topicFile)) {
+                sessionTopics = JSON.parse(fs.readFileSync(topicFile, 'utf8'));
+            }
+        }
+        catch { /* ignore parse errors */ }
+        for (const kw of keywordEntries) {
+            sessionTopics[kw] = (sessionTopics[kw] ?? 0) + 1;
+        }
+        fs.writeFileSync(topicFile, JSON.stringify(sessionTopics));
+        // Find hot topics (3+ mentions this session)
+        hotTopics = Object.entries(sessionTopics)
+            .filter(([, count]) => count >= 3)
+            .map(([topic]) => topic);
+    }
     const tIndex0 = Date.now();
     const db = await buildIndex(getPhrenPath(), profile);
     stage.indexMs = Date.now() - tIndex0;
@@ -197,9 +217,13 @@ export async function handleHookPrompt() {
         stage.rankMs = Date.now() - tRank0;
         if (!rows.length)
             process.exit(0);
-        const safeTokenBudget = clampInt(process.env.PHREN_CONTEXT_TOKEN_BUDGET, 550, 180, 10000);
+        let safeTokenBudget = clampInt(process.env.PHREN_CONTEXT_TOKEN_BUDGET, 550, 180, 10000);
         const safeLineBudget = clampInt(process.env.PHREN_CONTEXT_SNIPPET_LINES, 6, 2, 100);
         const safeCharBudget = clampInt(process.env.PHREN_CONTEXT_SNIPPET_CHARS, 520, 120, 10000);
+        // Session momentum: boost token budget for hot topics
+        if (hotTopics.length > 0) {
+            safeTokenBudget = Math.min(Math.floor(safeTokenBudget * 1.3), parseInt(process.env.PHREN_MAX_INJECT_TOKENS ?? '2000', 10));
+        }
         const tSelect0 = Date.now();
         const { selected, usedTokens } = selectSnippets(rows, keywords, safeTokenBudget, safeLineBudget, safeCharBudget);
         stage.selectMs = Date.now() - tSelect0;

package/mcp/dist/cli-search.js

@@ -16,7 +16,7 @@ const SEARCH_TYPES = new Set([
     "task",
     "changelog",
     "canonical",
-    "memory-queue",
+    "review-queue",
     "skill",
     "other",
 ]);
@@ -45,7 +45,7 @@ function printSearchUsage() {
     console.error("  phren search --project <name> [--type <type>] [--limit <n>] [--all]");
     console.error("  phren search --history                    Show recent searches");
     console.error("  phren search --from-history <n>           Re-run search #n from history");
-    console.error("  type: claude|summary|findings|reference|task|changelog|canonical|memory-queue|skill|other");
+    console.error("  type: claude|summary|findings|reference|task|changelog|canonical|review-queue|skill|other");
 }
 function validateAndNormalizeSearchOptions(phrenPath, queryParts, project, type, limit, showHistory, fromHistory, searchAll) {
     if (showHistory) {

package/mcp/dist/content-citation.js

@@ -1,9 +1,11 @@
 import * as fs from "fs";
+import { statSync } from "fs";
 import * as path from "path";
 import { debugLog, EXEC_TIMEOUT_MS, EXEC_TIMEOUT_QUICK_MS } from "./shared.js";
 import { errorMessage, runGitOrThrow } from "./utils.js";
 import { findingIdFromLine } from "./finding-impact.js";
 import { METADATA_REGEX, isArchiveStart, isArchiveEnd } from "./content-metadata.js";
+import { FINDING_TYPE_DECAY, extractFindingType, parseFindingLifecycle } from "./finding-lifecycle.js";
 export const FINDING_PROVENANCE_SOURCES = [
     "human",
     "agent",
@@ -270,6 +272,16 @@ function confidenceForAge(ageDays, decay) {
         return d90 - ((d90 - d120) * ((ageDays - 90) / 30));
     return d120; // don't decay further past d120; TTL handles final expiry
 }
+function wasFileModifiedAfter(filePath, findingDate) {
+    try {
+        const stat = statSync(filePath);
+        const fileModified = stat.mtime.toISOString().slice(0, 10);
+        return fileModified > findingDate;
+    }
+    catch {
+        return false; // File doesn't exist or can't stat — handled by citation validation
+    }
+}
 export function filterTrustedFindings(content, ttlDays) {
     return filterTrustedFindingsDetailed(content, { ttlDays }).content;
 }
@@ -282,6 +294,7 @@ export function filterTrustedFindingsDetailed(content, opts) {
         ...(options.decay || {}),
     };
     const highImpactFindingIds = options.highImpactFindingIds;
+    const impactCounts = options.impactCounts;
     const project = options.project;
     const lines = content.split("\n");
     const out = [];
@@ -356,11 +369,41 @@ export function filterTrustedFindingsDetailed(content, opts) {
         else {
             confidence = DEFAULT_UNDATED_CONFIDENCE;
         }
+        // Type-specific decay adjustment
+        const findingType = extractFindingType(line);
+        if (findingType) {
+            const typeConfig = FINDING_TYPE_DECAY[findingType];
+            if (typeConfig) {
+                // Override max age for this type
+                if (effectiveDate && typeConfig.maxAgeDays !== Infinity) {
+                    const age = ageDaysForDate(effectiveDate);
+                    if (age !== null && age > typeConfig.maxAgeDays) {
+                        issues.push({ date: effectiveDate || "unknown", bullet: line, reason: "stale" });
+                        if (citation)
+                            i++;
+                        continue;
+                    }
+                }
+                // Apply type-specific decay multiplier
+                confidence *= typeConfig.decayMultiplier;
+                // Decisions and anti-patterns get a floor boost (never drop below 0.6)
+                if (typeConfig.maxAgeDays === Infinity) {
+                    confidence = Math.max(confidence, 0.6);
+                }
+            }
+        }
         if (citation && !validateFindingCitation(citation)) {
             issues.push({ date: effectiveDate || "unknown", bullet: line, reason: "invalid_citation" });
             i++;
             continue;
         }
+        // If cited file was modified after finding was created, lower confidence
+        if (citation && effectiveDate && citation.file) {
+            const fileModifiedAfterFinding = wasFileModifiedAfter(citation.file, effectiveDate);
+            if (fileModifiedAfterFinding) {
+                confidence *= 0.7; // File changed since finding was written — may be stale
+            }
+        }
         if (!citation)
             confidence *= 0.8;
         const provenance = parseSourceComment(line)?.source ?? "unknown";
@@ -370,9 +413,29 @@ export function filterTrustedFindingsDetailed(content, opts) {
             confidence *= 0.9;
         if (project && highImpactFindingIds?.size) {
             const findingId = findingIdFromLine(line);
-            if (highImpactFindingIds.has(findingId))
-                confidence *= 1.15;
+            if (highImpactFindingIds.has(findingId)) {
+                // Get surface count for graduated boost
+                const surfaceCount = impactCounts?.get(findingId) ?? 3;
+                // Log-scaled: 3→1.15x, 10→1.28x, 30→1.38x, capped at 1.4x
+                const boost = Math.min(1.4, 1 + 0.1 * Math.log2(Math.max(3, surfaceCount)));
+                confidence *= boost;
+                // Decay resistance: confirmed findings decay 3x slower
+                if (effectiveDate) {
+                    const realAge = ageDaysForDate(effectiveDate);
+                    if (realAge !== null) {
+                        const slowedAge = Math.floor(realAge / 3);
+                        confidence = Math.max(confidence, confidenceForAge(slowedAge, decay));
+                    }
+                }
+            }
         }
+        const lifecycle = parseFindingLifecycle(line);
+        if (lifecycle?.status === "superseded")
+            confidence *= 0.25;
+        if (lifecycle?.status === "retracted")
+            confidence *= 0.1;
+        if (lifecycle?.status === "contradicted")
+            confidence *= 0.4;
         confidence = Math.max(0, Math.min(1, confidence));
         if (confidence < minConfidence) {
             issues.push({ date: effectiveDate || "unknown", bullet: line, reason: "stale" });

package/mcp/dist/content-dedup.js

@@ -187,7 +187,7 @@ export function jaccardSimilarity(a, b) {
 const PROSE_ENTITY_RE = UNIVERSAL_TECH_TERMS_RE;
 const POSITIVE_RE = /\b(always|prefer|should|must|works|recommend|enable)\b/i;
 const NEGATIVE_RE = /\b(never|avoid|don't|do not|shouldn't|must not|broken|deprecated|disable)\b/i;
-// ── Dynamic entity extraction ─────────────────────────────────────────────────
+// ── Dynamic fragment extraction ────────────────────────────────────────────────
 const ENTITY_CACHE_TTL_MS = 60 * 60 * 1000; // 1 hour
 // Patterns that suggest a token is a proper noun / tool name:
 //   - CamelCase word (at least one interior uppercase): PhotonMappingEngine, GameKit
@@ -257,7 +257,7 @@ function extractProseEntities(text, dynamicEntities) {
     let m;
     while ((m = re.exec(text)) !== null)
         found.add(m[0].toLowerCase());
-    // Match additional entity patterns (versions, env keys, file paths, error codes, dates)
+    // Match additional fragment patterns (versions, env keys, file paths, error codes, dates)
     for (const { re: pattern } of EXTRA_ENTITY_PATTERNS) {
         const pRe = new RegExp(pattern.source, pattern.flags);
         let pm;
@@ -265,7 +265,7 @@ function extractProseEntities(text, dynamicEntities) {
             found.add(pm[0].toLowerCase());
     }
     if (dynamicEntities) {
-        // Also check whether any dynamic entity appears (case-insensitive word match)
+        // Also check whether any dynamic fragment appears (case-insensitive word match)
         for (const entity of dynamicEntities) {
             const escaped = entity.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
             if (new RegExp(`\\b${escaped}\\b`, "i").test(text)) {

package/mcp/dist/content-learning.js

@@ -11,7 +11,7 @@ import { isDuplicateFinding, scanForSecrets, normalizeObservationTags, resolveCo
 import { validateFindingsFormat, validateFinding } from "./content-validate.js";
 import { countActiveFindings, autoArchiveToReference } from "./content-archive.js";
 import { resolveAutoFindingTaskItem, resolveFindingTaskReference, resolveFindingSessionId, } from "./finding-context.js";
-import { buildLifecycleComments, parseFindingLifecycle, stripLifecycleComments, } from "./finding-lifecycle.js";
+import { buildLifecycleComments, extractFindingType, parseFindingLifecycle, stripLifecycleComments, } from "./finding-lifecycle.js";
 import { METADATA_REGEX, } from "./content-metadata.js";
 /** Default cap for active findings before auto-archiving is triggered. */
 const DEFAULT_FINDINGS_CAP = 20;
@@ -107,6 +107,22 @@ function resolveFindingCitationInput(phrenPath, project, citationInput) {
     }
     return phrenOk(Object.keys(resolved).length > 0 ? resolved : undefined);
 }
+export function autoDetectFindingType(text) {
+    const lower = text.toLowerCase();
+    if (/\b(we decided|decision:|chose .+ over|went with)\b/.test(lower))
+        return 'decision';
+    if (/\b(bug:|bug in|found a bug|broken|crashes|fails when)\b/.test(lower))
+        return 'bug';
+    if (/\b(workaround:|work around|temporary fix|hack:)\b/.test(lower))
+        return 'workaround';
+    if (/\b(pattern:|always .+ before|never .+ without|best practice)\b/.test(lower))
+        return 'pattern';
+    if (/\b(pitfall:|gotcha:|watch out|careful with|trap:)\b/.test(lower))
+        return 'pitfall';
+    if (/\b(currently|as of|right now|at the moment|observation:)\b/.test(lower))
+        return 'context';
+    return null;
+}
 function prepareFinding(learning, project, fullHistory, extraAnnotations, citationInput, source, nowIso, inferredRepo, headCommit, phrenPath) {
     const secretType = scanForSecrets(learning);
     if (secretType) {
@@ -114,10 +130,17 @@ function prepareFinding(learning, project, fullHistory, extraAnnotations, citati
     }
     const today = (nowIso ?? new Date().toISOString()).slice(0, 10);
     const { text: tagNormalized, warning: tagWarning } = normalizeObservationTags(learning);
-    const normalizedLearning = resolveCoref(tagNormalized, {
+    let normalizedLearning = resolveCoref(tagNormalized, {
         project,
         file: citationInput?.file,
     });
+    const existingType = extractFindingType('- ' + normalizedLearning);
+    if (!existingType) {
+        const detected = autoDetectFindingType(normalizedLearning);
+        if (detected) {
+            normalizedLearning = `[${detected}] ${normalizedLearning}`;
+        }
+    }
     const fid = crypto.randomBytes(4).toString("hex");
     const fidComment = `<!-- fid:${fid} -->`;
     const createdComment = `<!-- created: ${today} -->`;
@@ -204,20 +227,20 @@ export function upsertCanonical(phrenPath, project, memory) {
     const resolvedDir = safeProjectPath(phrenPath, project);
     if (!resolvedDir || !fs.existsSync(resolvedDir))
         return phrenErr(`Project "${project}" not found in phren.`, PhrenError.PROJECT_NOT_FOUND);
-    const canonicalPath = path.join(resolvedDir, "CANONICAL_MEMORIES.md");
+    const canonicalPath = path.join(resolvedDir, "truths.md");
     const today = new Date().toISOString().slice(0, 10);
     const bullet = memory.startsWith("- ") ? memory : `- ${memory}`;
     withFileLock(canonicalPath, () => {
         if (!fs.existsSync(canonicalPath)) {
-            fs.writeFileSync(canonicalPath, `# ${project} Canonical Memories\n\n## Pinned\n\n${bullet} _(pinned ${today})_\n`);
+            fs.writeFileSync(canonicalPath, `# ${project} Truths\n\n## Truths\n\n${bullet} _(added ${today})_\n`);
         }
         else {
             const existing = fs.readFileSync(canonicalPath, "utf8");
-            const line = `${bullet} _(pinned ${today})_`;
+            const line = `${bullet} _(added ${today})_`;
             if (!existing.includes(bullet)) {
-                const updated = existing.includes("## Pinned")
-                    ? existing.replace("## Pinned", `## Pinned\n\n${line}`)
-                    : `${existing.trimEnd()}\n\n## Pinned\n\n${line}\n`;
+                const updated = existing.includes("## Truths")
+                    ? existing.replace("## Truths", `## Truths\n\n${line}`)
+                    : `${existing.trimEnd()}\n\n## Truths\n\n${line}\n`;
                 const content = updated.endsWith("\n") ? updated : updated + "\n";
                 const tmpPath = canonicalPath + `.tmp-${crypto.randomUUID()}`;
                 fs.writeFileSync(tmpPath, content);
@@ -226,7 +249,7 @@ export function upsertCanonical(phrenPath, project, memory) {
         }
     });
     appendAuditLog(phrenPath, "pin_memory", `project=${project} memory=${JSON.stringify(memory)}`);
-    return phrenOk(`Pinned canonical memory in ${project}.`);
+    return phrenOk(`Truth saved in ${project}.`);
 }
 export function addFindingToFile(phrenPath, project, learning, citationInput, opts) {
     const findingError = validateFinding(learning);

package/mcp/dist/data-access.js

@@ -54,6 +54,46 @@ function normalizeFindingGroupKey(item) {
 function findingTimelineDate(item) {
     return item.status_updated || item.date || "0000-00-00";
 }
+function collectFindingBulletLines(lines) {
+    const bulletLines = [];
+    let inArchiveBlock = false;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (isArchiveStart(line)) {
+            inArchiveBlock = true;
+            continue;
+        }
+        if (isArchiveEnd(line)) {
+            inArchiveBlock = false;
+            continue;
+        }
+        if (!line.startsWith("- "))
+            continue;
+        bulletLines.push({ line, i, archived: inArchiveBlock });
+    }
+    return bulletLines;
+}
+function findMatchingFindingBullet(bulletLines, needle, match) {
+    const fidNeedle = needle.replace(/^fid:/, "");
+    const fidMatch = /^[a-z0-9]{8}$/.test(fidNeedle)
+        ? bulletLines.filter(({ line }) => new RegExp(`<!--\\s*fid:${fidNeedle}\\s*-->`).test(line))
+        : [];
+    const exactMatches = bulletLines.filter(({ line }) => line.replace(/^-\s+/, "").replace(/<!--.*?-->/g, "").trim().toLowerCase() === needle);
+    const partialMatches = bulletLines.filter(({ line }) => line.toLowerCase().includes(needle));
+    if (fidMatch.length === 1)
+        return { kind: "found", idx: fidMatch[0].i };
+    if (exactMatches.length === 1)
+        return { kind: "found", idx: exactMatches[0].i };
+    if (exactMatches.length > 1) {
+        return { kind: "ambiguous", error: `"${match}" is ambiguous (${exactMatches.length} exact matches). Use a more specific phrase.` };
+    }
+    if (partialMatches.length === 1)
+        return { kind: "found", idx: partialMatches[0].i };
+    if (partialMatches.length > 1) {
+        return { kind: "ambiguous", error: `"${match}" is ambiguous (${partialMatches.length} partial matches). Use a more specific phrase.` };
+    }
+    return { kind: "not_found" };
+}
 export function readFindings(phrenPath, project, opts = {}) {
     const ensured = ensureProject(phrenPath, project);
     if (!ensured.ok)
@@ -210,35 +250,19 @@ export function removeFinding(phrenPath, project, match) {
     return withSafeLock(filePath, () => {
         const lines = fs.readFileSync(filePath, "utf8").split("\n");
         const needle = match.trim().toLowerCase();
-        const bulletLines = lines.map((line, i) => ({ line, i })).filter(({ line }) => line.startsWith("- "));
-        // 0) Stable finding ID match (fid:XXXXXXXX or just the 8-char hex)
-        const fidNeedle = needle.replace(/^fid:/, "");
-        const fidMatch = /^[a-z0-9]{8}$/.test(fidNeedle)
-            ? bulletLines.filter(({ line }) => new RegExp(`<!--\\s*fid:${fidNeedle}\\s*-->`).test(line))
-            : [];
-        // 1) Exact text match (strip bullet prefix + metadata for comparison)
-        const exactMatches = bulletLines.filter(({ line }) => line.replace(/^-\s+/, "").replace(/<!--.*?-->/g, "").trim().toLowerCase() === needle);
-        // 2) Unique partial substring match
-        const partialMatches = bulletLines.filter(({ line }) => line.toLowerCase().includes(needle));
-        let idx;
-        if (fidMatch.length === 1) {
-            idx = fidMatch[0].i;
-        }
-        else if (exactMatches.length === 1) {
-            idx = exactMatches[0].i;
-        }
-        else if (exactMatches.length > 1) {
-            return phrenErr(`"${match}" is ambiguous (${exactMatches.length} exact matches). Use a more specific phrase.`, PhrenError.AMBIGUOUS_MATCH);
-        }
-        else if (partialMatches.length === 1) {
-            idx = partialMatches[0].i;
-        }
-        else if (partialMatches.length > 1) {
-            return phrenErr(`"${match}" is ambiguous (${partialMatches.length} partial matches). Use a more specific phrase.`, PhrenError.AMBIGUOUS_MATCH);
+        const bulletLines = collectFindingBulletLines(lines);
+        const activeMatch = findMatchingFindingBullet(bulletLines.filter(({ archived }) => !archived), needle, match);
+        if (activeMatch.kind === "ambiguous") {
+            return phrenErr(activeMatch.error, PhrenError.AMBIGUOUS_MATCH);
         }
-        else {
+        if (activeMatch.kind === "not_found") {
+            const archivedMatch = findMatchingFindingBullet(bulletLines.filter(({ archived }) => archived), needle, match);
+            if (archivedMatch.kind === "ambiguous" || archivedMatch.kind === "found") {
+                return phrenErr(`Finding "${match}" is archived and read-only. Restore or re-add it before mutating history.`, PhrenError.VALIDATION_ERROR);
+            }
             return phrenErr(`No finding matching "${match}" in project "${project}". Try a different search term or check :findings view.`, PhrenError.NOT_FOUND);
         }
+        const idx = activeMatch.idx;
         const removeCount = isCitationLine(lines[idx + 1] || "") ? 2 : 1;
         const matched = lines[idx];
         lines.splice(idx, removeCount);
@@ -260,33 +284,19 @@ export function editFinding(phrenPath, project, oldText, newText) {
     return withSafeLock(findingsPath, () => {
         const lines = fs.readFileSync(findingsPath, "utf8").split("\n");
         const needle = oldText.trim().toLowerCase();
-        const bulletLines = lines.map((line, i) => ({ line, i })).filter(({ line }) => line.startsWith("- "));
-        // Stable finding ID match
-        const fidNeedle = needle.replace(/^fid:/, "");
-        const fidMatch = /^[a-z0-9]{8}$/.test(fidNeedle)
-            ? bulletLines.filter(({ line }) => new RegExp(`<!--\\s*fid:${fidNeedle}\\s*-->`).test(line))
-            : [];
-        const exactMatches = bulletLines.filter(({ line }) => line.replace(/^-\s+/, "").replace(/<!--.*?-->/g, "").trim().toLowerCase() === needle);
-        const partialMatches = bulletLines.filter(({ line }) => line.toLowerCase().includes(needle));
-        let idx;
-        if (fidMatch.length === 1) {
-            idx = fidMatch[0].i;
-        }
-        else if (exactMatches.length === 1) {
-            idx = exactMatches[0].i;
-        }
-        else if (exactMatches.length > 1) {
-            return phrenErr(`"${oldText}" is ambiguous (${exactMatches.length} exact matches). Use a more specific phrase.`, PhrenError.AMBIGUOUS_MATCH);
+        const bulletLines = collectFindingBulletLines(lines);
+        const activeMatch = findMatchingFindingBullet(bulletLines.filter(({ archived }) => !archived), needle, oldText);
+        if (activeMatch.kind === "ambiguous") {
+            return phrenErr(activeMatch.error, PhrenError.AMBIGUOUS_MATCH);
         }
-        else if (partialMatches.length === 1) {
-            idx = partialMatches[0].i;
-        }
-        else if (partialMatches.length > 1) {
-            return phrenErr(`"${oldText}" is ambiguous (${partialMatches.length} partial matches). Use a more specific phrase.`, PhrenError.AMBIGUOUS_MATCH);
-        }
-        else {
+        if (activeMatch.kind === "not_found") {
+            const archivedMatch = findMatchingFindingBullet(bulletLines.filter(({ archived }) => archived), needle, oldText);
+            if (archivedMatch.kind === "ambiguous" || archivedMatch.kind === "found") {
+                return phrenErr(`Finding "${oldText}" is archived and read-only. Restore or re-add it before mutating history.`, PhrenError.VALIDATION_ERROR);
+            }
             return phrenErr(`No finding matching "${oldText}" in project "${project}".`, PhrenError.NOT_FOUND);
         }
+        const idx = activeMatch.idx;
         // Preserve existing metadata comment (fid, citations, etc.)
         const existing = lines[idx];
         const metaMatch = existing.match(/(<!--.*?-->)/g);

package/mcp/dist/entrypoint.js

@@ -31,7 +31,7 @@ Usage:
   phren search <query> [--project <n>] [--type <t>] [--limit <n>]
                                          Search what phren remembers
   phren add-finding <project> "..."     Tell phren what you learned
-  phren pin <project> "..."             Pin a canonical memory
+  phren pin <project> "..."             Save a truth
   phren tasks                           Cross-project task view
   phren skill-list                      List installed skills
   phren doctor [--fix] [--check-data] [--agents]

package/mcp/dist/finding-impact.js

@@ -144,6 +144,29 @@ export function getHighImpactFindings(phrenPath, minSurfaceCount = 3) {
     };
     return new Set(ids);
 }
+export function getImpactSurfaceCounts(phrenPath, minSurfaces = 1) {
+    const file = impactLogFile(phrenPath);
+    if (!fs.existsSync(file))
+        return new Map();
+    const lines = fs.readFileSync(file, "utf8").split("\n").filter(Boolean);
+    const counts = new Map();
+    for (const line of lines) {
+        try {
+            const entry = JSON.parse(line);
+            if (entry.findingId) {
+                counts.set(entry.findingId, (counts.get(entry.findingId) ?? 0) + 1);
+            }
+        }
+        catch { }
+    }
+    // Filter by minimum
+    const filtered = new Map();
+    for (const [id, count] of counts) {
+        if (count >= minSurfaces)
+            filtered.set(id, count);
+    }
+    return filtered;
+}
 export function markImpactEntriesCompletedForSession(phrenPath, sessionId, project) {
     if (!sessionId)
         return 0;

package/mcp/dist/finding-lifecycle.js

@@ -6,6 +6,24 @@ const LIFECYCLE_PREFIX = "phren";
 import { withFileLock } from "./governance-locks.js";
 import { isValidProjectName, safeProjectPath } from "./utils.js";
 import { parseCreatedDate as parseCreatedDateMeta, parseStatusField, parseStatus, parseSupersession, parseContradiction, parseFindingId as parseFindingIdMeta, stripLifecycleMetadata, stripRelationMetadata, } from "./content-metadata.js";
+export const FINDING_TYPE_DECAY = {
+    'pattern': { maxAgeDays: 365, decayMultiplier: 1.0 }, // Slow decay, long-lived
+    'decision': { maxAgeDays: Infinity, decayMultiplier: 1.0 }, // Never decays
+    'pitfall': { maxAgeDays: 365, decayMultiplier: 1.0 }, // Slow decay
+    'anti-pattern': { maxAgeDays: Infinity, decayMultiplier: 1.0 }, // Never decays
+    'observation': { maxAgeDays: 14, decayMultiplier: 0.7 }, // Fast decay, short-lived
+    'workaround': { maxAgeDays: 60, decayMultiplier: 0.85 }, // Medium decay
+    'bug': { maxAgeDays: 30, decayMultiplier: 0.8 }, // Medium-fast decay
+    'tooling': { maxAgeDays: 180, decayMultiplier: 0.95 }, // Medium-slow decay
+    'context': { maxAgeDays: 30, decayMultiplier: 0.75 }, // Fast decay (contextual facts)
+};
+export function extractFindingType(line) {
+    const match = line.match(/\[(\w[\w-]*)\]/);
+    if (!match)
+        return null;
+    const tag = match[1].toLowerCase();
+    return tag in FINDING_TYPE_DECAY ? tag : null;
+}
 export const FINDING_LIFECYCLE_STATUSES = [
     "active",
     "superseded",

package/mcp/dist/governance-policy.js

@@ -387,7 +387,7 @@ export function appendReviewQueue(phrenPath, project, section, entries) {
     const resolvedDir = safeProjectPath(phrenPath, project);
     if (!resolvedDir || !fs.existsSync(resolvedDir))
         return phrenErr(`Project "${project}" not found in phren.`, PhrenError.PROJECT_NOT_FOUND);
-    const queuePath = path.join(resolvedDir, "MEMORY_QUEUE.md");
+    const queuePath = path.join(resolvedDir, "review.md");
     const today = new Date().toISOString().slice(0, 10);
     const normalized = [];
     for (const entry of entries) {

package/mcp/dist/governance-scores.js

@@ -270,7 +270,7 @@ export function recordInjection(phrenPath, key, sessionId) {
         debugLog(`Usage log rotation failed: ${errorMessage(err)}`);
     }
 }
-export function recordFeedback(phrenPath, key, feedback) {
+export function recordFeedback(phrenPath, key, feedback, sessionId) {
     const delta = {};
     if (feedback === "helpful")
         delta.helpful = 1;
@@ -280,6 +280,14 @@ export function recordFeedback(phrenPath, key, feedback) {
         delta.regressionPenalty = 1;
     appendScoreJournal(phrenPath, key, delta);
     appendAuditLog(phrenPath, "memory_feedback", `key=${key} feedback=${feedback}`);
+    // When feedback is "helpful", mark correlated query entries for future boost
+    if (feedback === "helpful" && sessionId) {
+        import("./query-correlation.js").then(({ markCorrelationsHelpful: markHelpful }) => {
+            const colonIdx = key.indexOf(":");
+            const docKey = colonIdx >= 0 ? key.slice(0, colonIdx) : key;
+            markHelpful(phrenPath, sessionId, docKey);
+        }).catch(() => { });
+    }
 }
 // Module-level cache for the journal aggregation used by getQualityMultiplier.
 // Invalidated whenever flushEntryScores runs (at which point the journal is cleared).

package/mcp/dist/link-checksums.js

@@ -34,7 +34,7 @@ export function updateFileChecksums(phrenPath, profileName) {
     const tracked = [];
     const dirs = getProjectDirs(phrenPath, profileName);
     for (const dir of dirs) {
-        for (const name of ["FINDINGS.md", ...TASK_FILE_ALIASES, "CANONICAL_MEMORIES.md"]) {
+        for (const name of ["FINDINGS.md", ...TASK_FILE_ALIASES, "truths.md"]) {
             const full = path.join(dir, name);
             if (!fs.existsSync(full))
                 continue;

package/mcp/dist/link-doctor.js

@@ -533,7 +533,7 @@ export async function runDoctor(phrenPath, fix = false, checkData = false) {
             const projectName = path.basename(projectDir);
             if (projectName === "global")
                 continue;
-            for (const mdFile of ["FINDINGS.md", ...TASK_FILE_ALIASES, "MEMORY_QUEUE.md", "CLAUDE.md", "REFERENCE.md"]) {
+            for (const mdFile of ["FINDINGS.md", ...TASK_FILE_ALIASES, "review.md", "CLAUDE.md", "REFERENCE.md"]) {
                 const filePath = path.join(projectDir, mdFile);
                 if (!fs.existsSync(filePath))
                     continue;

package/mcp/dist/mcp-memory.js

@@ -10,10 +10,10 @@ export function register(server, ctx) {
     const { phrenPath, withWriteQueue, updateFileInIndex } = ctx;
     server.registerTool("pin_memory", {
         title: "◆ phren · pin memory",
-        description: "Promote an important memory into CANONICAL_MEMORIES.md so retrieval prioritizes it.",
+        description: "Write a truth — a high-confidence, always-inject entry in truths.md that never decays.",
         inputSchema: z.object({
             project: z.string().describe("Project name."),
-            memory: z.string().describe("Canonical memory text to pin."),
+            memory: z.string().describe("Truth text."),
         }),
     }, async ({ project, memory }) => {
         if (!isValidProjectName(project))
@@ -22,8 +22,8 @@ export function register(server, ctx) {
             const result = upsertCanonical(phrenPath, project, memory);
             if (!result.ok)
                 return mcpResponse({ ok: false, error: result.error });
-            // Update FTS index so newly pinned memory is immediately searchable
-            const canonicalPath = path.join(phrenPath, project, "CANONICAL_MEMORIES.md");
+            // Update FTS index so newly added truth is immediately searchable
+            const canonicalPath = path.join(phrenPath, project, "truths.md");
             updateFileInIndex(canonicalPath);
             return mcpResponse({ ok: true, message: result.data, data: { project, memory } });
         });

package/mcp/dist/mcp-ops.js

@@ -294,7 +294,7 @@ export function register(server, ctx) {
     // ── get_review_queue ─────────────────────────────────────────────────────
     server.registerTool("get_review_queue", {
         title: "◆ phren · get review queue",
-        description: "List all items in a project's memory review queue (MEMORY_QUEUE.md), or across all projects when omitted. " +
+        description: "List all items in a project's review queue (review.md), or across all projects when omitted. " +
             "Returns items with their id, section (Review/Stale/Conflicts), date, text, confidence, and risky flag.",
         inputSchema: z.object({
             project: z.string().optional().describe("Project name. Omit to read the review queue across all projects in the active profile."),