@phren/cli 0.0.32 → 0.0.34

package/mcp/dist/tools/search.js

@@ -6,7 +6,7 @@ import { isValidProjectName, errorMessage } from "../utils.js";
 import { readFindings } from "../data/access.js";
 import { debugLog, runtimeFile, DOC_TYPES, FINDING_TAGS, isMemoryScopeVisible, normalizeMemoryScope, } from "../shared.js";
 import { FINDING_LIFECYCLE_STATUSES, parseFindingLifecycle, } from "../shared/content.js";
-import { decodeStringRow, queryRows, queryDocRows, queryEntityLinks, logEntityMiss, extractSnippet, queryDocBySourceKey, normalizeMemoryId, } from "../shared/index.js";
+import { decodeStringRow, queryRows, queryDocRows, queryFragmentLinks, logFragmentMiss, extractSnippet, queryDocBySourceKey, normalizeMemoryId, } from "../shared/index.js";
 import { runCustomHooks } from "../hooks.js";
 import { entryScoreKey, getQualityMultiplier, getRetentionPolicy } from "../shared/governance.js";
 import { callLlm } from "../content/dedup.js";
@@ -118,412 +118,537 @@ function filterTaskContentByScope(content, activeScope) {
     }
     return out.join("\n");
 }
-export function register(server, ctx) {
-    const { phrenPath, profile } = ctx;
-    server.registerTool("get_memory_detail", {
-        title: "◆ phren · memory detail",
-        description: "Fetch the full content of a specific memory entry by its ID. Use this after receiving a compact " +
-            "memory index from the hook-prompt (when PHREN_FEATURE_PROGRESSIVE_DISCLOSURE is enabled). " +
-            "The id format is `mem:project/path/to/file.md` as shown in the memory index.",
-        inputSchema: z.object({
-            id: z.string().describe("Memory ID in the format `mem:project/path/to/file.md` (e.g. `mem:my-app/reference/api/auth.md`). " +
-                "Returned by the hook-prompt compact index when PHREN_FEATURE_PROGRESSIVE_DISCLOSURE=1."),
-        }),
-    }, async ({ id: rawId }) => {
-        // Normalize ID: decode URL encoding and normalize path separators
-        let id;
-        try {
-            id = normalizeMemoryId(rawId);
-        }
-        catch {
-            return mcpResponse({ ok: false, error: `Invalid memory ID format: "${rawId}" contains malformed URL encoding.` });
-        }
-        const match = id.match(/^mem:([^/]+)\/(.+)$/);
-        if (!match) {
-            return mcpResponse({ ok: false, error: `Invalid memory ID format "${rawId}". Expected mem:project/path/to/file.md.` });
-        }
-        const [, project] = match;
-        if (!isValidProjectName(project)) {
-            return mcpResponse({ ok: false, error: `Invalid project name: "${project}"` });
-        }
+// ── Handlers ─────────────────────────────────────────────────────────────────
+async function handleGetMemoryDetail(ctx, { id: rawId }) {
+    const { phrenPath } = ctx;
+    // Normalize ID: decode URL encoding and normalize path separators
+    let id;
+    try {
+        id = normalizeMemoryId(rawId);
+    }
+    catch {
+        return mcpResponse({ ok: false, error: `Invalid memory ID format: "${rawId}" contains malformed URL encoding.` });
+    }
+    const match = id.match(/^mem:([^/]+)\/(.+)$/);
+    if (!match) {
+        return mcpResponse({ ok: false, error: `Invalid memory ID format "${rawId}". Expected mem:project/path/to/file.md.` });
+    }
+    const [, project] = match;
+    if (!isValidProjectName(project)) {
+        return mcpResponse({ ok: false, error: `Invalid project name: "${project}"` });
+    }
+    const db = ctx.db();
+    const doc = queryDocBySourceKey(db, phrenPath, id.slice(4));
+    if (!doc) {
+        return mcpResponse({ ok: false, error: `Memory not found: ${id}` });
+    }
+    // Extract metadata from filesystem and content
+    let updatedAt = null;
+    let createdAt = null;
+    try {
+        const stat = fs.statSync(doc.path);
+        updatedAt = stat.mtime.toISOString();
+        createdAt = stat.birthtime.toISOString();
+    }
+    catch (err) {
+        logger.debug("search", `search_knowledge statFile: ${errorMessage(err)}`);
+    }
+    // Extract tags from content (e.g. [decision], [pitfall], [pattern])
+    const tagMatches = doc.content.match(/\[(decision|pitfall|pattern|tradeoff|architecture|bug)\]/gi);
+    const tags = tagMatches ? [...new Set(tagMatches.map(t => t.slice(1, -1).toLowerCase()))] : [];
+    // Get quality score if available
+    const scoreKey = entryScoreKey(doc.project, doc.filename, doc.content);
+    const qualityMultiplier = getQualityMultiplier(phrenPath, scoreKey);
+    return mcpResponse({
+        ok: true,
+        message: `[${id.slice(4)}] (${doc.type})\n\n${doc.content}`,
+        data: {
+            id,
+            project: doc.project,
+            filename: doc.filename,
+            type: doc.type,
+            content: doc.content,
+            path: doc.path,
+            created_at: createdAt,
+            updated_at: updatedAt,
+            tags: tags.length > 0 ? tags : undefined,
+            score: qualityMultiplier,
+            rank: undefined,
+            relevance_score: undefined,
+        },
+    });
+}
+async function handleSearchKnowledge(ctx, { query, limit, project, type, tag, since, status, include_history, synthesize }) {
+    const { phrenPath } = ctx;
+    try {
+        if (query.length > 1000)
+            return mcpResponse({ ok: false, error: "Search query exceeds 1000 character limit." });
         const db = ctx.db();
-        const doc = queryDocBySourceKey(db, phrenPath, id.slice(4));
-        if (!doc) {
-            return mcpResponse({ ok: false, error: `Memory not found: ${id}` });
-        }
-        // Extract metadata from filesystem and content
-        let updatedAt = null;
-        let createdAt = null;
-        try {
-            const stat = fs.statSync(doc.path);
-            updatedAt = stat.mtime.toISOString();
-            createdAt = stat.birthtime.toISOString();
-        }
-        catch (err) {
-            logger.debug("search", `search_knowledge statFile: ${errorMessage(err)}`);
+        const maxResults = limit ?? 5;
+        const filterType = type === "skills" ? "skill" : type;
+        const filterTag = tag?.toLowerCase();
+        const filterStatus = status;
+        const includeHistory = include_history ?? false;
+        const filterProject = project?.trim();
+        if (filterProject && !isValidProjectName(filterProject)) {
+            return mcpResponse({ ok: false, error: `Invalid project name: "${project}"` });
         }
-        // Extract tags from content (e.g. [decision], [pitfall], [pattern])
-        const tagMatches = doc.content.match(/\[(decision|pitfall|pattern|tradeoff|architecture|bug)\]/gi);
-        const tags = tagMatches ? [...new Set(tagMatches.map(t => t.slice(1, -1).toLowerCase()))] : [];
-        // Get quality score if available
-        const scoreKey = entryScoreKey(doc.project, doc.filename, doc.content);
-        const qualityMultiplier = getQualityMultiplier(phrenPath, scoreKey);
-        return mcpResponse({
-            ok: true,
-            message: `[${id.slice(4)}] (${doc.type})\n\n${doc.content}`,
-            data: {
-                id,
-                project: doc.project,
-                filename: doc.filename,
-                type: doc.type,
-                content: doc.content,
-                path: doc.path,
-                created_at: createdAt,
-                updated_at: updatedAt,
-                tags: tags.length > 0 ? tags : undefined,
-                score: qualityMultiplier,
-                // Relevance metadata: rank and relevance_score are populated when
-                // the detail is fetched as part of a search result set. When fetched
-                // directly by ID they are not available.
-                rank: undefined,
-                relevance_score: undefined,
-            },
+        const fetchLimit = (filterTag || since || filterStatus) ? Math.min(maxResults * 5, 200) : maxResults;
+        const retrieval = await searchKnowledgeRows(db, {
+            query,
+            maxResults,
+            fetchLimit,
+            filterProject,
+            filterType,
+            phrenPath,
         });
-    });
-    server.registerTool("search_knowledge", {
-        title: "◆ phren · search",
-        description: "Search the user's phren. Call this at the start of any session to get project context, and any time the user asks about their codebase, stack, architecture, past decisions, commands, conventions, or findings. Prefer this over asking the user to re-explain things they've already told phren.",
-        inputSchema: z.object({
-            query: z.string().describe("Search query (supports FTS5 syntax: AND, OR, NOT, phrase matching with quotes)"),
-            limit: z.number().min(1).max(20).optional().describe("Max results to return (1-20, default 5)"),
-            project: z.string().optional().describe("Filter by project name."),
-            type: z.enum(DOC_TYPES)
-                .optional()
-                .describe("Filter by document type: claude, findings, reference, summary, task, skill"),
-            tag: z.preprocess(value => typeof value === "string" ? value.toLowerCase() : value, z.enum(FINDING_TAGS))
-                .optional()
-                .describe("Filter findings by type tag: decision, pitfall, pattern, tradeoff, architecture, bug."),
-            since: z.string().optional().describe('Filter findings by creation date. Formats: "7d" (last 7 days), "30d" (last 30 days), "YYYY-MM" (since start of month), "YYYY-MM-DD" (since date).'),
-            status: z.enum(FINDING_LIFECYCLE_STATUSES).optional().describe("Filter findings by lifecycle status: active, superseded, contradicted, stale, invalid_citation, or retracted."),
-            include_history: z.boolean().optional().describe("When true, include historical findings (superseded/retracted). Default false."),
-            synthesize: z.boolean().optional().describe("When true, generate a short synthesis paragraph from the top results using an LLM. Requires PHREN_LLM_ENDPOINT, ANTHROPIC_API_KEY, or OPENAI_API_KEY."),
-        }),
-    }, async ({ query, limit, project, type, tag, since, status, include_history, synthesize }) => {
-        try {
-            if (query.length > 1000)
-                return mcpResponse({ ok: false, error: "Search query exceeds 1000 character limit." });
-            const db = ctx.db();
-            const maxResults = limit ?? 5;
-            const filterType = type === "skills" ? "skill" : type;
-            const filterTag = tag?.toLowerCase();
-            const filterStatus = status;
-            const includeHistory = include_history ?? false;
-            const filterProject = project?.trim();
-            if (filterProject && !isValidProjectName(filterProject)) {
-                return mcpResponse({ ok: false, error: `Invalid project name: "${project}"` });
-            }
-            const fetchLimit = (filterTag || since || filterStatus) ? Math.min(maxResults * 5, 200) : maxResults;
-            const retrieval = await searchKnowledgeRows(db, {
-                query,
-                maxResults,
-                fetchLimit,
-                filterProject,
-                filterType,
-                phrenPath,
-            });
-            const safeQuery = retrieval.safeQuery;
-            if (!safeQuery)
-                return mcpResponse({ ok: false, error: "Search query is empty after sanitization." });
-            let rows = retrieval.rows ?? [];
-            const usedFallback = retrieval.usedFallback;
-            // Merge federated store results when PHREN_FEDERATION_PATHS is set and no project filter
-            // (federation is global by nature — per-project filter only makes sense within a single store)
-            if (!filterProject) {
-                try {
-                    const federatedRows = await searchFederatedStores(phrenPath, {
-                        query,
-                        maxResults,
-                        fetchLimit,
-                        filterType,
+        const safeQuery = retrieval.safeQuery;
+        if (!safeQuery)
+            return mcpResponse({ ok: false, error: "Search query is empty after sanitization." });
+        let rows = retrieval.rows ?? [];
+        const usedFallback = retrieval.usedFallback;
+        // Merge federated store results when PHREN_FEDERATION_PATHS is set and no project filter
+        // (federation is global by nature — per-project filter only makes sense within a single store)
+        if (!filterProject) {
+            try {
+                const federatedRows = await searchFederatedStores(phrenPath, {
+                    query,
+                    maxResults,
+                    fetchLimit,
+                    filterType,
+                });
+                if (federatedRows.length > 0) {
+                    // Dedup by path to avoid duplicates if stores share files
+                    const localPaths = new Set(rows.map((r) => r.path || `${r.project}/${r.filename}`));
+                    const uniqueFederated = federatedRows.filter((r) => {
+                        const key = r.path || `${r.project}/${r.filename}`;
+                        return !localPaths.has(key);
                     });
-                    if (federatedRows.length > 0) {
-                        // Dedup by path to avoid duplicates if stores share files
-                        const localPaths = new Set(rows.map((r) => r.path || `${r.project}/${r.filename}`));
-                        const uniqueFederated = federatedRows.filter((r) => {
-                            const key = r.path || `${r.project}/${r.filename}`;
-                            return !localPaths.has(key);
-                        });
-                        rows = [...rows, ...uniqueFederated];
-                    }
+                    rows = [...rows, ...uniqueFederated];
                 }
-                catch (err) {
-                    if (process.env.PHREN_DEBUG) {
-                        logger.debug("search", `search_knowledge federation: ${errorMessage(err)}`);
-                    }
+            }
+            catch (err) {
+                if (process.env.PHREN_DEBUG) {
+                    logger.debug("search", `search_knowledge federation: ${errorMessage(err)}`);
                 }
             }
+        }
+        if (rows.length === 0) {
+            logSearchMiss(phrenPath, query, filterProject);
+            return mcpResponse({ ok: true, message: "No results found.", data: { query, results: [] } });
+        }
+        const activeScope = resolveActiveSessionScope(phrenPath, filterProject);
+        if (activeScope) {
+            rows = rows
+                .map((row) => {
+                if (row.type === "findings") {
+                    const filteredContent = filterFindingsContentByScope(row.content, activeScope);
+                    const hasVisible = filteredContent.split("\n").some((line) => line.startsWith("- "));
+                    return hasVisible ? { ...row, content: filteredContent } : null;
+                }
+                if (row.type === "task") {
+                    const filteredContent = filterTaskContentByScope(row.content, activeScope);
+                    const hasVisible = filteredContent.split("\n").some((line) => line.startsWith("- "));
+                    return hasVisible ? { ...row, content: filteredContent } : null;
+                }
+                return row;
+            })
+                .filter((row) => Boolean(row));
             if (rows.length === 0) {
                 logSearchMiss(phrenPath, query, filterProject);
                 return mcpResponse({ ok: true, message: "No results found.", data: { query, results: [] } });
             }
-            const activeScope = resolveActiveSessionScope(phrenPath, filterProject);
-            if (activeScope) {
-                rows = rows
-                    .map((row) => {
-                    if (row.type === "findings") {
-                        const filteredContent = filterFindingsContentByScope(row.content, activeScope);
-                        const hasVisible = filteredContent.split("\n").some((line) => line.startsWith("- "));
-                        return hasVisible ? { ...row, content: filteredContent } : null;
-                    }
-                    if (row.type === "task") {
-                        const filteredContent = filterTaskContentByScope(row.content, activeScope);
-                        const hasVisible = filteredContent.split("\n").some((line) => line.startsWith("- "));
-                        return hasVisible ? { ...row, content: filteredContent } : null;
-                    }
-                    return row;
-                })
-                    .filter((row) => Boolean(row));
-                if (rows.length === 0) {
-                    logSearchMiss(phrenPath, query, filterProject);
-                    return mcpResponse({ ok: true, message: "No results found.", data: { query, results: [] } });
-                }
+        }
+        // Filter by observation tag if requested
+        if (filterTag && rows) {
+            const tagPattern = `[${filterTag.toLowerCase()}]`;
+            rows = rows.filter(row => row.content.toLowerCase().includes(tagPattern));
+            if (rows.length === 0) {
+                logSearchMiss(phrenPath, query, filterProject);
+                return mcpResponse({ ok: true, message: `No results found with tag [${filterTag}].`, data: { query, results: [] } });
             }
-            // Filter by observation tag if requested
-            if (filterTag && rows) {
-                const tagPattern = `[${filterTag.toLowerCase()}]`;
-                rows = rows.filter(row => row.content.toLowerCase().includes(tagPattern));
-                if (rows.length === 0) {
-                    logSearchMiss(phrenPath, query, filterProject);
-                    return mcpResponse({ ok: true, message: `No results found with tag [${filterTag}].`, data: { query, results: [] } });
-                }
+        }
+        // Filter by since date if requested
+        if (since && rows) {
+            let sinceDate = null;
+            const daysMatch = since.match(/^(\d+)d$/);
+            if (daysMatch) {
+                sinceDate = new Date(Date.now() - parseInt(daysMatch[1], 10) * 86400000);
             }
-            // Filter by since date if requested
-            if (since && rows) {
-                let sinceDate = null;
-                const daysMatch = since.match(/^(\d+)d$/);
-                if (daysMatch) {
-                    sinceDate = new Date(Date.now() - parseInt(daysMatch[1], 10) * 86400000);
+            else if (/^\d{4}-\d{2}$/.test(since)) {
+                // Validate month is 01-12
+                const [, mm] = since.split("-");
+                const month = parseInt(mm, 10);
+                if (month < 1 || month > 12) {
+                    return mcpResponse({ ok: false, error: `Invalid since value "${since}": month must be 01-12.` });
                 }
-                else if (/^\d{4}-\d{2}$/.test(since)) {
-                    // Validate month is 01-12
-                    const [, mm] = since.split("-");
-                    const month = parseInt(mm, 10);
-                    if (month < 1 || month > 12) {
-                        return mcpResponse({ ok: false, error: `Invalid since value "${since}": month must be 01-12.` });
-                    }
-                    sinceDate = new Date(`${since}-01T00:00:00Z`);
-                }
-                else if (/^\d{4}-\d{2}-\d{2}$/.test(since)) {
-                    // Validate month and day strictly (reject impossible dates like 2026-02-31)
-                    const [, mm, dd] = since.split("-");
-                    const month = parseInt(mm, 10);
-                    const day = parseInt(dd, 10);
-                    if (month < 1 || month > 12 || day < 1 || day > 31) {
-                        return mcpResponse({ ok: false, error: `Invalid since value "${since}": month or day out of range.` });
-                    }
-                    const candidate = new Date(`${since}T00:00:00Z`);
-                    // new Date() normalizes impossible dates (e.g. Feb 31 → Mar 3); detect by comparing parsed month/day
-                    if (candidate.getUTCMonth() + 1 !== month || candidate.getUTCDate() !== day) {
-                        return mcpResponse({ ok: false, error: `Invalid since value "${since}": date does not exist on the calendar.` });
-                    }
-                    sinceDate = candidate;
-                }
-                else if (since) {
-                    return mcpResponse({ ok: false, error: `Invalid since format "${since}". Use "7d", "YYYY-MM", or "YYYY-MM-DD".` });
+                sinceDate = new Date(`${since}-01T00:00:00Z`);
+            }
+            else if (/^\d{4}-\d{2}-\d{2}$/.test(since)) {
+                // Validate month and day strictly (reject impossible dates like 2026-02-31)
+                const [, mm, dd] = since.split("-");
+                const month = parseInt(mm, 10);
+                const day = parseInt(dd, 10);
+                if (month < 1 || month > 12 || day < 1 || day > 31) {
+                    return mcpResponse({ ok: false, error: `Invalid since value "${since}": month or day out of range.` });
                 }
-                if (sinceDate && !isNaN(sinceDate.getTime())) {
-                    const sinceMs = sinceDate.getTime();
-                    rows = rows.filter(row => {
-                        const createdDates = [...row.content.matchAll(/<!-- created: (\d{4}-\d{2}-\d{2}) -->/g)];
-                        if (createdDates.length === 0)
-                            return true;
-                        return createdDates.some(m => new Date(`${m[1]}T00:00:00Z`).getTime() >= sinceMs);
-                    });
-                    if (rows.length === 0) {
-                        logSearchMiss(phrenPath, query, filterProject);
-                        return mcpResponse({ ok: true, message: `No results found since ${since}.`, data: { query, results: [] } });
-                    }
+                const candidate = new Date(`${since}T00:00:00Z`);
+                // new Date() normalizes impossible dates (e.g. Feb 31 → Mar 3); detect by comparing parsed month/day
+                if (candidate.getUTCMonth() + 1 !== month || candidate.getUTCDate() !== day) {
+                    return mcpResponse({ ok: false, error: `Invalid since value "${since}": date does not exist on the calendar.` });
                 }
+                sinceDate = candidate;
             }
-            const lifecycleByRowKey = new Map();
-            if (rows) {
-                const filteredRows = [];
-                for (const row of rows) {
-                    if (row.type !== "findings") {
-                        if (filterStatus)
-                            continue;
-                        filteredRows.push(row);
-                        continue;
-                    }
-                    const summary = summarizeFindingStatuses(row.content, includeHistory, filterStatus);
-                    if (!summary)
-                        continue;
-                    lifecycleByRowKey.set(findingRowKey(row), summary);
-                    filteredRows.push(row);
-                }
-                rows = filteredRows;
+            else if (since) {
+                return mcpResponse({ ok: false, error: `Invalid since format "${since}". Use "7d", "YYYY-MM", or "YYYY-MM-DD".` });
+            }
+            if (sinceDate && !isNaN(sinceDate.getTime())) {
+                const sinceMs = sinceDate.getTime();
+                rows = rows.filter(row => {
+                    const createdDates = [...row.content.matchAll(/<!-- created: (\d{4}-\d{2}-\d{2}) -->/g)];
+                    if (createdDates.length === 0)
+                        return true;
+                    return createdDates.some(m => new Date(`${m[1]}T00:00:00Z`).getTime() >= sinceMs);
+                });
                 if (rows.length === 0) {
                     logSearchMiss(phrenPath, query, filterProject);
-                    return mcpResponse({ ok: true, message: "No results found after lifecycle filters.", data: { query, results: [] } });
+                    return mcpResponse({ ok: true, message: `No results found since ${since}.`, data: { query, results: [] } });
                 }
             }
-            rows = rankResults(rows, "general", null, filterProject ?? null, phrenPath, db, undefined, query, { skipTaskFilter: true, filterType: filterType ?? null });
-            // Apply trust filter — same as hook-prompt uses — to strip stale/low-confidence findings
-            try {
-                const policy = getRetentionPolicy(phrenPath);
-                const trustResult = applyTrustFilter(rows, policy.ttlDays, policy.minInjectConfidence, policy.decay, phrenPath);
-                rows = trustResult.rows;
-            }
-            catch (err) {
-                debugLog(`search_knowledge trustFilter: ${errorMessage(err)}`);
+        }
+        const lifecycleByRowKey = new Map();
+        if (rows) {
+            const filteredRows = [];
+            for (const row of rows) {
+                if (row.type !== "findings") {
+                    if (filterStatus)
+                        continue;
+                    filteredRows.push(row);
+                    continue;
+                }
+                const summary = summarizeFindingStatuses(row.content, includeHistory, filterStatus);
+                if (!summary)
+                    continue;
+                lifecycleByRowKey.set(findingRowKey(row), summary);
+                filteredRows.push(row);
             }
-            rows = rows
-                .map((row, idx) => ({ row, idx }))
-                .sort((a, b) => {
-                const aBucket = a.row.type === "findings" ? lifecycleSortBucket(lifecycleByRowKey.get(findingRowKey(a.row))) : 1;
-                const bBucket = b.row.type === "findings" ? lifecycleSortBucket(lifecycleByRowKey.get(findingRowKey(b.row))) : 1;
-                if (aBucket !== bBucket)
-                    return aBucket - bBucket;
-                return a.idx - b.idx;
-            })
-                .map(entry => entry.row);
-            if (rows.length > maxResults) {
-                rows = rows.slice(0, maxResults);
+            rows = filteredRows;
+            if (rows.length === 0) {
+                logSearchMiss(phrenPath, query, filterProject);
+                return mcpResponse({ ok: true, message: "No results found after lifecycle filters.", data: { query, results: [] } });
             }
-            const results = rows.map((row) => {
-                const snippet = extractSnippet(row.content, query);
-                const lifecycle = row.type === "findings" ? lifecycleByRowKey.get(findingRowKey(row)) : undefined;
-                const federationSource = "federationSource" in row ? row.federationSource : undefined;
-                return {
-                    project: row.project,
-                    filename: row.filename,
-                    type: row.type,
-                    snippet,
-                    path: row.path,
-                    status: lifecycle?.primaryStatus,
-                    statuses: lifecycle?.statuses,
-                    ...(federationSource ? { federation_source: federationSource } : {}),
-                };
-            });
-            let relatedFragments = [];
-            try {
-                const terms = query.toLowerCase().split(/\s+/).filter(t => t.length > 2);
-                for (const term of terms) {
-                    const links = queryEntityLinks(db, term);
-                    if (links.related.length > 0) {
-                        relatedFragments.push(...links.related);
-                    }
-                    else {
-                        logEntityMiss(phrenPath, term, "search_knowledge", filterProject);
-                    }
+        }
+        rows = rankResults(rows, "general", null, filterProject ?? null, phrenPath, db, undefined, query, { skipTaskFilter: true, filterType: filterType ?? null });
+        // Apply trust filter — same as hook-prompt uses — to strip stale/low-confidence findings
+        try {
+            const policy = getRetentionPolicy(phrenPath);
+            const trustResult = applyTrustFilter(rows, policy.ttlDays, policy.minInjectConfidence, policy.decay, phrenPath);
+            rows = trustResult.rows;
+        }
+        catch (err) {
+            debugLog(`search_knowledge trustFilter: ${errorMessage(err)}`);
+        }
+        rows = rows
+            .map((row, idx) => ({ row, idx }))
+            .sort((a, b) => {
+            const aBucket = a.row.type === "findings" ? lifecycleSortBucket(lifecycleByRowKey.get(findingRowKey(a.row))) : 1;
+            const bBucket = b.row.type === "findings" ? lifecycleSortBucket(lifecycleByRowKey.get(findingRowKey(b.row))) : 1;
+            if (aBucket !== bBucket)
+                return aBucket - bBucket;
+            return a.idx - b.idx;
+        })
+            .map(entry => entry.row);
+        if (rows.length > maxResults) {
+            rows = rows.slice(0, maxResults);
+        }
+        const results = rows.map((row) => {
+            const snippet = extractSnippet(row.content, query);
+            const lifecycle = row.type === "findings" ? lifecycleByRowKey.get(findingRowKey(row)) : undefined;
+            const federationSource = "federationSource" in row ? row.federationSource : undefined;
+            return {
+                project: row.project,
+                filename: row.filename,
+                type: row.type,
+                snippet,
+                path: row.path,
+                status: lifecycle?.primaryStatus,
+                statuses: lifecycle?.statuses,
+                ...(federationSource ? { federation_source: federationSource } : {}),
+            };
+        });
+        let relatedFragments = [];
+        try {
+            const terms = query.toLowerCase().split(/\s+/).filter(t => t.length > 2);
+            for (const term of terms) {
+                const links = queryFragmentLinks(db, term);
+                if (links.related.length > 0) {
+                    relatedFragments.push(...links.related);
+                }
+                else {
+                    logFragmentMiss(phrenPath, term, "search_knowledge", filterProject);
                 }
-                relatedFragments = [...new Set(relatedFragments)].slice(0, 10);
-            }
-            catch (err) {
-                logger.debug("search", `fragment query: ${errorMessage(err)}`);
             }
-            const formatted = results.map((r) => {
-                const fedNote = r.federation_source ? ` [from: ${r.federation_source}]` : "";
-                return `### ${r.project}/${r.filename} (${r.type})${fedNote}\n${r.snippet}\n\n\`${r.path}\``;
-            });
-            // Memory synthesis: generate a concise paragraph from top results when requested
-            let synthesis;
-            if (synthesize && results.length > 0) {
+            relatedFragments = [...new Set(relatedFragments)].slice(0, 10);
+        }
+        catch (err) {
+            logger.debug("search", `fragment query: ${errorMessage(err)}`);
+        }
+        const formatted = results.map((r) => {
+            const fedNote = r.federation_source ? ` [from: ${r.federation_source}]` : "";
+            return `### ${r.project}/${r.filename} (${r.type})${fedNote}\n${r.snippet}\n\n\`${r.path}\``;
+        });
+        // Memory synthesis: generate a concise paragraph from top results when requested
+        let synthesis;
+        if (synthesize && results.length > 0) {
+            try {
+                const synthKey = createHash("sha256").update([query, filterProject ?? "", filterType ?? "", filterTag ?? "", since ?? ""].join("|")).digest("hex").slice(0, 16);
+                const synthCachePath = runtimeFile(phrenPath, "synth-cache.json");
+                let synthCache = {};
                 try {
-                    const synthKey = createHash("sha256").update([query, filterProject ?? "", filterType ?? "", filterTag ?? "", since ?? ""].join("|")).digest("hex").slice(0, 16);
-                    const synthCachePath = runtimeFile(phrenPath, "synth-cache.json");
-                    let synthCache = {};
-                    try {
-                        synthCache = JSON.parse(fs.readFileSync(synthCachePath, "utf8"));
-                    }
-                    catch (err) {
-                        logger.debug("search", `search_knowledge synthCacheRead: ${errorMessage(err)}`);
-                    }
-                    const cached = synthCache[synthKey];
-                    const SYNTH_CACHE_TTL_MS = 30 * 60 * 1000; // 30 minutes
-                    if (cached && Date.now() - cached.ts < SYNTH_CACHE_TTL_MS) {
-                        synthesis = cached.result;
-                    }
-                    else {
-                        const snippets = results.slice(0, 5).map((r, i) => `[${i + 1}] ${r.snippet}`).join("\n");
-                        const synthPrompt = `Summarize these search results for "${query}" in 2-3 sentences. No headers, no lists. Plain paragraph only.\n\n${snippets}`;
-                        synthesis = await callLlm(synthPrompt, undefined, 300);
-                        if (synthesis) {
-                            synthCache[synthKey] = { result: synthesis, ts: Date.now() };
-                            // Trim cache to 100 entries
-                            const cacheKeys = Object.keys(synthCache);
-                            if (cacheKeys.length > 100) {
-                                const oldest = cacheKeys.sort((a, b) => synthCache[a].ts - synthCache[b].ts).slice(0, cacheKeys.length - 100);
-                                for (const k of oldest)
-                                    delete synthCache[k];
-                            }
-                            try {
-                                fs.writeFileSync(synthCachePath, JSON.stringify(synthCache));
-                            }
-                            catch (err) {
-                                logger.debug("search", `synthCache write: ${errorMessage(err)}`);
-                            }
-                        }
-                    }
+                    synthCache = JSON.parse(fs.readFileSync(synthCachePath, "utf8"));
                 }
                 catch (err) {
-                    debugLog(`search synthesis failed: ${errorMessage(err)}`);
+                    logger.debug("search", `search_knowledge synthCacheRead: ${errorMessage(err)}`);
+                }
+                const cached = synthCache[synthKey];
+                const SYNTH_CACHE_TTL_MS = 30 * 60 * 1000; // 30 minutes
+                if (cached && Date.now() - cached.ts < SYNTH_CACHE_TTL_MS) {
+                    synthesis = cached.result;
+                }
+                else {
+                    const snippets = results.slice(0, 5).map((r, i) => `[${i + 1}] ${r.snippet}`).join("\n");
+                    const synthPrompt = `Summarize these search results for "${query}" in 2-3 sentences. No headers, no lists. Plain paragraph only.\n\n${snippets}`;
+                    synthesis = await callLlm(synthPrompt, undefined, 300);
+                    if (synthesis) {
+                        synthCache[synthKey] = { result: synthesis, ts: Date.now() };
+                        // Trim cache to 100 entries
+                        const cacheKeys = Object.keys(synthCache);
+                        if (cacheKeys.length > 100) {
+                            const oldest = cacheKeys.sort((a, b) => synthCache[a].ts - synthCache[b].ts).slice(0, cacheKeys.length - 100);
+                            for (const k of oldest)
+                                delete synthCache[k];
+                        }
+                        try {
+                            fs.writeFileSync(synthCachePath, JSON.stringify(synthCache));
+                        }
+                        catch (err) {
+                            logger.debug("search", `synthCache write: ${errorMessage(err)}`);
+                        }
+                    }
                 }
             }
-            const fallbackNote = usedFallback ? " (keyword fallback)" : "";
-            const fragmentNote = relatedFragments.length > 0 ? `\n\nRelated fragments: ${relatedFragments.join(", ")}` : "";
-            const synthesisBlock = synthesis ? `\n\n${synthesis}\n\n---\n\n` : "\n\n";
-            runCustomHooks(phrenPath, "post-search", { PHREN_QUERY: query, PHREN_RESULT_COUNT: String(results.length) });
-            return mcpResponse({
-                ok: true,
-                message: `Found ${results.length} result(s) for "${query}"${fallbackNote}:${synthesisBlock}${formatted.join("\n\n---\n\n")}${fragmentNote}`,
-                data: { query, count: results.length, results, fallback: usedFallback, relatedFragments: relatedFragments.length > 0 ? relatedFragments : undefined, ...(synthesis ? { synthesis } : {}) },
-            });
+            catch (err) {
+                debugLog(`search synthesis failed: ${errorMessage(err)}`);
+            }
         }
-        catch (err) {
-            return mcpResponse({ ok: false, error: `Search error: ${errorMessage(err)}`, errorCode: "INTERNAL_ERROR" });
+        const fallbackNote = usedFallback ? " (keyword fallback)" : "";
+        const fragmentNote = relatedFragments.length > 0 ? `\n\nRelated fragments: ${relatedFragments.join(", ")}` : "";
+        const synthesisBlock = synthesis ? `\n\n${synthesis}\n\n---\n\n` : "\n\n";
+        runCustomHooks(phrenPath, "post-search", { PHREN_QUERY: query, PHREN_RESULT_COUNT: String(results.length) });
+        return mcpResponse({
+            ok: true,
+            message: `Found ${results.length} result(s) for "${query}"${fallbackNote}:${synthesisBlock}${formatted.join("\n\n---\n\n")}${fragmentNote}`,
+            data: { query, count: results.length, results, fallback: usedFallback, relatedFragments: relatedFragments.length > 0 ? relatedFragments : undefined, ...(synthesis ? { synthesis } : {}) },
+        });
+    }
+    catch (err) {
+        return mcpResponse({ ok: false, error: `Search error: ${errorMessage(err)}`, errorCode: "INTERNAL_ERROR" });
+    }
+}
+async function handleGetProjectSummary(ctx, { name }) {
+    const { phrenPath } = ctx;
+    const db = ctx.db();
+    const docs = queryDocRows(db, "SELECT project, filename, type, content, path FROM docs WHERE project = ?", [name]);
+    if (!docs) {
+        const projectRows = queryRows(db, "SELECT DISTINCT project FROM docs ORDER BY project", []);
+        const names = projectRows ? projectRows.map(row => decodeStringRow(row, 1, "get_project_summary.projects")[0]) : [];
+        return mcpResponse({ ok: false, error: `Project "${name}" not found.`, data: { available: names } });
+    }
+    const summaryDoc = docs.find(doc => doc.type === "summary");
+    const claudeDoc = docs.find(doc => doc.type === "claude");
+    const indexedFiles = docs.map(doc => ({ filename: doc.filename, type: doc.type, path: doc.path }));
+    const parts = [`# ${name}`];
+    if (summaryDoc) {
+        parts.push(`\n## Summary\n${summaryDoc.content}`);
+    }
+    else {
+        parts.push("\n*No summary.md found for this project.*");
+    }
+    if (claudeDoc) {
+        parts.push(`\n## CLAUDE.md path\n\`${claudeDoc.path}\``);
+    }
+    const fileList = indexedFiles.map((f) => `- ${f.filename} (${f.type})`).join("\n");
+    parts.push(`\n## Indexed files\n${fileList}`);
+    return mcpResponse({
+        ok: true,
+        message: parts.join("\n"),
+        data: {
+            name,
+            summary: summaryDoc?.content ?? null,
+            claudeMdPath: claudeDoc?.path ?? null,
+            files: indexedFiles,
+        },
+    });
+}
+async function handleListProjects(ctx, { page, page_size }) {
+    const { phrenPath, profile } = ctx;
+    const db = ctx.db();
+    const projectRows = queryRows(db, "SELECT DISTINCT project FROM docs ORDER BY project", []);
+    if (!projectRows)
+        return mcpResponse({ ok: true, message: "No projects indexed.", data: { projects: [], total: 0 } });
+    const projects = projectRows.map(row => decodeStringRow(row, 1, "list_projects.projects")[0]);
+    const pageSize = page_size ?? 20;
+    const pageNum = page ?? 1;
+    const start = Math.max(0, (pageNum - 1) * pageSize);
+    const end = start + pageSize;
+    const pageProjects = projects.slice(start, end);
+    const totalPages = Math.max(1, Math.ceil(projects.length / pageSize));
+    if (pageNum > totalPages) {
+        return mcpResponse({ ok: false, error: `Page ${pageNum} out of range. Total pages: ${totalPages}.` });
+    }
+    const badgeTypes = ["claude", "findings", "summary", "task"];
+    const badgeLabels = { claude: "CLAUDE.md", findings: "FINDINGS", summary: "summary", task: "task" };
+    const projectList = pageProjects.map((proj) => {
+        const rows = queryDocRows(db, "SELECT project, filename, type, content, path FROM docs WHERE project = ?", [proj]) ?? [];
+        const types = rows.map(row => row.type);
+        const summaryRow = rows.find(row => row.type === "summary");
+        const claudeRow = rows.find(row => row.type === "claude");
+        const source = summaryRow?.content ?? claudeRow?.content;
+        let brief = "";
+        if (source) {
+            const firstLine = source.split("\n").find(l => l.trim() && !l.startsWith("#"));
+            brief = firstLine?.trim() || "";
         }
+        const badges = badgeTypes.filter(t => types.includes(t)).map(t => badgeLabels[t]);
+        return { name: proj, brief, badges, fileCount: rows.length };
+    });
+    const lines = [`# Phren Projects (${projects.length})`];
+    if (profile)
+        lines.push(`Profile: ${profile}`);
+    lines.push(`Page: ${pageNum}/${totalPages} (page_size=${pageSize})`);
+    lines.push(`Path: ${phrenPath}\n`);
+    for (const p of projectList) {
+        lines.push(`## ${p.name}`);
+        if (p.brief)
+            lines.push(p.brief);
+        lines.push(`[${p.badges.join(" | ")}] - ${p.fileCount} file(s)\n`);
+    }
+    return mcpResponse({
+        ok: true,
+        message: lines.join("\n"),
+        data: { projects: projectList, total: projects.length, page: pageNum, totalPages, pageSize },
     });
+}
+async function handleGetFindings(ctx, { project, limit, include_superseded, include_history, status }) {
+    const { phrenPath } = ctx;
+    if (!isValidProjectName(project))
+        return mcpResponse({ ok: false, error: `Invalid project name: "${project}"` });
+    const includeHistory = include_history ?? include_superseded ?? false;
+    // Always read with archive so we can compute historyCount without a second read
+    const result = readFindings(phrenPath, project, { includeArchived: true });
+    if (!result.ok)
+        return mcpResponse({ ok: false, error: result.error });
+    const allItems = result.data;
+    const historyCount = allItems.filter(f => f.tier === "archived" || HISTORY_FINDING_STATUSES.has(f.status)).length;
+    const visibleItems = includeHistory
+        ? allItems
+        : allItems.filter(f => f.tier !== "archived" && !HISTORY_FINDING_STATUSES.has(f.status));
+    // Apply scope filter: only show findings visible to the active scope
+    const activeScope = resolveActiveSessionScope(phrenPath, project);
+    const scopedItems = activeScope
+        ? visibleItems.filter(f => {
+            const itemScope = normalizeMemoryScope(f.scope);
+            return isMemoryScopeVisible(itemScope, activeScope);
+        })
+        : visibleItems;
+    const filteredItems = status ? scopedItems.filter(f => f.status === status) : scopedItems;
+    if (!filteredItems.length) {
+        const msg = historyCount > 0 && !includeHistory
+            ? `No findings found for "${project}" with current filters. ${historyCount} historical finding(s) hidden. Pass include_history=true to show history.`
+            : `No findings found for "${project}".`;
+        return mcpResponse({ ok: true, message: msg, data: { project, findings: [], total: 0, status: status ?? null, include_history: includeHistory, historyCount } });
+    }
+    const capped = filteredItems.slice(0, limit ?? 50).map(entry => ({
+        ...entry,
+        lifecycle: {
+            status: entry.status,
+            status_updated: entry.status_updated,
+            status_reason: entry.status_reason,
+            status_ref: entry.status_ref,
+        },
+    }));
+    const lines = capped.map((entry) => {
+        const metadata = [];
+        metadata.push(`status=${entry.status}`);
+        if (entry.taskItem)
+            metadata.push(`task=${entry.taskItem}`);
+        if (entry.sessionId)
+            metadata.push(`session=${entry.sessionId.slice(0, 8)}`);
+        if (entry.scope)
+            metadata.push(`scope=${entry.scope}`);
+        if (entry.actor)
+            metadata.push(`actor=${entry.actor}`);
+        if (entry.tool)
+            metadata.push(`tool=${entry.tool}`);
+        if (entry.model)
+            metadata.push(`model=${entry.model}`);
+        if (entry.supersedes)
+            metadata.push(`supersedes="${entry.supersedes.slice(0, 30)}"`);
+        if (entry.supersededBy)
+            metadata.push(`superseded_by="${entry.supersededBy.slice(0, 30)}"`);
+        if (entry.contradicts?.length)
+            metadata.push(`contradicts=${entry.contradicts.length}`);
+        if (entry.tier === "archived")
+            metadata.push("tier=archived");
+        const idLabel = entry.stableId ? `${entry.id}|fid:${entry.stableId}` : entry.id;
+        return `- [${idLabel}] ${entry.date}: ${entry.text}${entry.confidence !== undefined ? ` [confidence ${entry.confidence.toFixed(2)}]` : ""}${metadata.length > 0 ? ` [${metadata.join(" ")}]` : ""}${entry.citation ? ` (${entry.citation})` : ""}`;
+    });
+    const hiddenHistoryCount = includeHistory ? 0 : historyCount;
+    const historyNote = hiddenHistoryCount > 0 ? ` (${hiddenHistoryCount} historical hidden)` : "";
+    return mcpResponse({
+        ok: true,
+        message: `Findings for ${project} (${capped.length}/${filteredItems.length})${historyNote}:\n` + lines.join("\n"),
+        data: { project, findings: capped, total: filteredItems.length, status: status ?? null, include_history: includeHistory, historyCount: hiddenHistoryCount },
+    });
+}
+// ── Registration ─────────────────────────────────────────────────────────────
+export function register(server, ctx) {
+    server.registerTool("get_memory_detail", {
+        title: "◆ phren · memory detail",
+        description: "Fetch the full content of a specific memory entry by its ID. Use this after receiving a compact " +
+            "memory index from the hook-prompt (when PHREN_FEATURE_PROGRESSIVE_DISCLOSURE is enabled). " +
+            "The id format is `mem:project/path/to/file.md` as shown in the memory index.",
+        inputSchema: z.object({
+            id: z.string().describe("Memory ID in the format `mem:project/path/to/file.md` (e.g. `mem:my-app/reference/api/auth.md`). " +
+                "Returned by the hook-prompt compact index when PHREN_FEATURE_PROGRESSIVE_DISCLOSURE=1."),
+        }),
+    }, (params) => handleGetMemoryDetail(ctx, params));
+    server.registerTool("search_knowledge", {
+        title: "◆ phren · search",
+        description: "Search the user's phren. Call this at the start of any session to get project context, and any time the user asks about their codebase, stack, architecture, past decisions, commands, conventions, or findings. Prefer this over asking the user to re-explain things they've already told phren.",
+        inputSchema: z.object({
+            query: z.string().describe("Search query (supports FTS5 syntax: AND, OR, NOT, phrase matching with quotes)"),
+            limit: z.number().min(1).max(20).optional().describe("Max results to return (1-20, default 5)"),
+            project: z.string().optional().describe("Filter by project name."),
+            type: z.enum(DOC_TYPES)
+                .optional()
+                .describe("Filter by document type: claude, findings, reference, summary, task, skill"),
+            tag: z.preprocess(value => typeof value === "string" ? value.toLowerCase() : value, z.enum(FINDING_TAGS))
+                .optional()
+                .describe("Filter findings by type tag: decision, pitfall, pattern, tradeoff, architecture, bug."),
+            since: z.string().optional().describe('Filter findings by creation date. Formats: "7d" (last 7 days), "30d" (last 30 days), "YYYY-MM" (since start of month), "YYYY-MM-DD" (since date).'),
+            status: z.enum(FINDING_LIFECYCLE_STATUSES).optional().describe("Filter findings by lifecycle status: active, superseded, contradicted, stale, invalid_citation, or retracted."),
+            include_history: z.boolean().optional().describe("When true, include historical findings (superseded/retracted). Default false."),
+            synthesize: z.boolean().optional().describe("When true, generate a short synthesis paragraph from the top results using an LLM. Requires PHREN_LLM_ENDPOINT, ANTHROPIC_API_KEY, or OPENAI_API_KEY."),
+        }),
+    }, (params) => handleSearchKnowledge(ctx, params));
     server.registerTool("get_project_summary", {
         title: "◆ phren · project",
         description: "Get a project's summary card and available docs. Call this when starting work on a specific project to orient yourself: what it is, the stack, current status, and how to run it.",
         inputSchema: z.object({
             name: z.string().describe("Project name (e.g. 'my-app', 'backend', 'frontend')"),
         }),
-    }, async ({ name }) => {
-        const db = ctx.db();
-        const docs = queryDocRows(db, "SELECT project, filename, type, content, path FROM docs WHERE project = ?", [name]);
-        if (!docs) {
-            const projectRows = queryRows(db, "SELECT DISTINCT project FROM docs ORDER BY project", []);
-            const names = projectRows ? projectRows.map(row => decodeStringRow(row, 1, "get_project_summary.projects")[0]) : [];
-            return mcpResponse({ ok: false, error: `Project "${name}" not found.`, data: { available: names } });
-        }
-        const summaryDoc = docs.find(doc => doc.type === "summary");
-        const claudeDoc = docs.find(doc => doc.type === "claude");
-        const indexedFiles = docs.map(doc => ({ filename: doc.filename, type: doc.type, path: doc.path }));
-        const parts = [`# ${name}`];
-        if (summaryDoc) {
-            parts.push(`\n## Summary\n${summaryDoc.content}`);
-        }
-        else {
-            parts.push("\n*No summary.md found for this project.*");
-        }
-        if (claudeDoc) {
-            parts.push(`\n## CLAUDE.md path\n\`${claudeDoc.path}\``);
-        }
-        const fileList = indexedFiles.map((f) => `- ${f.filename} (${f.type})`).join("\n");
-        parts.push(`\n## Indexed files\n${fileList}`);
-        return mcpResponse({
-            ok: true,
-            message: parts.join("\n"),
-            data: {
-                name,
-                summary: summaryDoc?.content ?? null,
-                claudeMdPath: claudeDoc?.path ?? null,
-                files: indexedFiles,
-            },
-        });
-    });
+    }, (params) => handleGetProjectSummary(ctx, params));
     server.registerTool("list_projects", {
         title: "◆ phren · projects",
         description: "List all projects in the active phren profile with a brief summary of each. " +
@@ -532,54 +657,7 @@ export function register(server, ctx) {
             page: z.number().int().min(1).optional().describe("1-based page number (default 1)."),
             page_size: z.number().int().min(1).max(50).optional().describe("Page size (default 20, max 50)."),
         }),
-    }, async ({ page, page_size }) => {
-        const db = ctx.db();
-        const projectRows = queryRows(db, "SELECT DISTINCT project FROM docs ORDER BY project", []);
-        if (!projectRows)
-            return mcpResponse({ ok: true, message: "No projects indexed.", data: { projects: [], total: 0 } });
-        const projects = projectRows.map(row => decodeStringRow(row, 1, "list_projects.projects")[0]);
-        const pageSize = page_size ?? 20;
-        const pageNum = page ?? 1;
-        const start = Math.max(0, (pageNum - 1) * pageSize);
-        const end = start + pageSize;
-        const pageProjects = projects.slice(start, end);
-        const totalPages = Math.max(1, Math.ceil(projects.length / pageSize));
-        if (pageNum > totalPages) {
-            return mcpResponse({ ok: false, error: `Page ${pageNum} out of range. Total pages: ${totalPages}.` });
-        }
-        const badgeTypes = ["claude", "findings", "summary", "task"];
-        const badgeLabels = { claude: "CLAUDE.md", findings: "FINDINGS", summary: "summary", task: "task" };
-        const projectList = pageProjects.map((proj) => {
-            const rows = queryDocRows(db, "SELECT project, filename, type, content, path FROM docs WHERE project = ?", [proj]) ?? [];
-            const types = rows.map(row => row.type);
-            const summaryRow = rows.find(row => row.type === "summary");
-            const claudeRow = rows.find(row => row.type === "claude");
-            const source = summaryRow?.content ?? claudeRow?.content;
-            let brief = "";
-            if (source) {
-                const firstLine = source.split("\n").find(l => l.trim() && !l.startsWith("#"));
-                brief = firstLine?.trim() || "";
-            }
-            const badges = badgeTypes.filter(t => types.includes(t)).map(t => badgeLabels[t]);
-            return { name: proj, brief, badges, fileCount: rows.length };
-        });
-        const lines = [`# Phren Projects (${projects.length})`];
-        if (profile)
-            lines.push(`Profile: ${profile}`);
-        lines.push(`Page: ${pageNum}/${totalPages} (page_size=${pageSize})`);
-        lines.push(`Path: ${phrenPath}\n`);
-        for (const p of projectList) {
-            lines.push(`## ${p.name}`);
-            if (p.brief)
-                lines.push(p.brief);
-            lines.push(`[${p.badges.join(" | ")}] - ${p.fileCount} file(s)\n`);
-        }
-        return mcpResponse({
-            ok: true,
-            message: lines.join("\n"),
-            data: { projects: projectList, total: projects.length, page: pageNum, totalPages, pageSize },
-        });
-    });
+    }, (params) => handleListProjects(ctx, params));
     server.registerTool("get_findings", {
         title: "◆ phren · findings",
         description: "List recent findings for a project without requiring a search query.",
@@ -590,75 +668,5 @@ export function register(server, ctx) {
             include_history: z.boolean().optional().describe("When true, include historical findings (superseded/retracted). Default false."),
             status: z.enum(FINDING_LIFECYCLE_STATUSES).optional().describe("Filter findings by lifecycle status."),
         }),
-    }, async ({ project, limit, include_superseded, include_history, status }) => {
-        if (!isValidProjectName(project))
-            return mcpResponse({ ok: false, error: `Invalid project name: "${project}"` });
-        const includeHistory = include_history ?? include_superseded ?? false;
-        // Always read with archive so we can compute historyCount without a second read
-        const result = readFindings(phrenPath, project, { includeArchived: true });
-        if (!result.ok)
-            return mcpResponse({ ok: false, error: result.error });
-        const allItems = result.data;
-        const historyCount = allItems.filter(f => f.tier === "archived" || HISTORY_FINDING_STATUSES.has(f.status)).length;
-        const visibleItems = includeHistory
-            ? allItems
-            : allItems.filter(f => f.tier !== "archived" && !HISTORY_FINDING_STATUSES.has(f.status));
-        // Apply scope filter: only show findings visible to the active scope
-        const activeScope = resolveActiveSessionScope(phrenPath, project);
-        const scopedItems = activeScope
-            ? visibleItems.filter(f => {
-                const itemScope = normalizeMemoryScope(f.scope);
-                return isMemoryScopeVisible(itemScope, activeScope);
-            })
-            : visibleItems;
-        const filteredItems = status ? scopedItems.filter(f => f.status === status) : scopedItems;
-        if (!filteredItems.length) {
-            const msg = historyCount > 0 && !includeHistory
-                ? `No findings found for "${project}" with current filters. ${historyCount} historical finding(s) hidden. Pass include_history=true to show history.`
-                : `No findings found for "${project}".`;
-            return mcpResponse({ ok: true, message: msg, data: { project, findings: [], total: 0, status: status ?? null, include_history: includeHistory, historyCount } });
-        }
-        const capped = filteredItems.slice(0, limit ?? 50).map(entry => ({
-            ...entry,
-            lifecycle: {
-                status: entry.status,
-                status_updated: entry.status_updated,
-                status_reason: entry.status_reason,
-                status_ref: entry.status_ref,
-            },
-        }));
-        const lines = capped.map((entry) => {
-            const metadata = [];
-            metadata.push(`status=${entry.status}`);
-            if (entry.taskItem)
-                metadata.push(`task=${entry.taskItem}`);
-            if (entry.sessionId)
-                metadata.push(`session=${entry.sessionId.slice(0, 8)}`);
-            if (entry.scope)
-                metadata.push(`scope=${entry.scope}`);
-            if (entry.actor)
-                metadata.push(`actor=${entry.actor}`);
-            if (entry.tool)
-                metadata.push(`tool=${entry.tool}`);
-            if (entry.model)
-                metadata.push(`model=${entry.model}`);
-            if (entry.supersedes)
-                metadata.push(`supersedes="${entry.supersedes.slice(0, 30)}"`);
-            if (entry.supersededBy)
-                metadata.push(`superseded_by="${entry.supersededBy.slice(0, 30)}"`);
-            if (entry.contradicts?.length)
-                metadata.push(`contradicts=${entry.contradicts.length}`);
-            if (entry.tier === "archived")
-                metadata.push("tier=archived");
-            const idLabel = entry.stableId ? `${entry.id}|fid:${entry.stableId}` : entry.id;
-            return `- [${idLabel}] ${entry.date}: ${entry.text}${entry.confidence !== undefined ? ` [confidence ${entry.confidence.toFixed(2)}]` : ""}${metadata.length > 0 ? ` [${metadata.join(" ")}]` : ""}${entry.citation ? ` (${entry.citation})` : ""}`;
-        });
-        const hiddenHistoryCount = includeHistory ? 0 : historyCount;
-        const historyNote = hiddenHistoryCount > 0 ? ` (${hiddenHistoryCount} historical hidden)` : "";
-        return mcpResponse({
-            ok: true,
-            message: `Findings for ${project} (${capped.length}/${filteredItems.length})${historyNote}:\n` + lines.join("\n"),
-            data: { project, findings: capped, total: filteredItems.length, status: status ?? null, include_history: includeHistory, historyCount: hiddenHistoryCount },
-        });
-    });
+    }, (params) => handleGetFindings(ctx, params));
 }