@phren/cli 0.0.11 → 0.0.13

package/README.md

@@ -10,7 +10,7 @@
 </p>
 
 <p align="center">
-Every time you start a new session, your AI agent forgets everything it learned. Phren fixes that — findings, decisions, and patterns persist as markdown in a git repo you control. No database, no hosted service, no vendor lock-in. Works across sessions, projects, and machines.
+Every time you start a new session, your AI agent forgets everything it learned. Phren fixes that. Findings, decisions, and patterns persist as markdown in a git repo you control. No database, no hosted service, no vendor lock-in.
 </p>
 
 ---
@@ -25,18 +25,18 @@ That single command creates `~/.phren`, wires up MCP, installs hooks, and gives
 
 ## What phren tracks
 
-- **Findings** — bugs hit, patterns discovered, decisions and their reasoning. Tagged by type (`[pattern]`, `[decision]`, `[pitfall]`, `[observation]`) with per-type decay rates
-- **Fragments** — named concepts (auth, build, React) that connect findings across projects. When you search for a topic, phren pulls in everything linked to that fragment
-- **Tasks** — work items that persist across sessions with priority, pinning, and GitHub issue linking
-- **Sessions** — conversation boundaries with summaries and checkpoints, so the next session picks up where this one left off
-- **Skills** — reusable slash commands you teach phren. Drop them in `~/.phren/global/skills/` and they work everywhere
+- **Findings**: bugs hit, patterns discovered, decisions and their reasoning. Tagged by type (`[pattern]`, `[decision]`, `[pitfall]`, `[observation]`) with per-type decay rates
+- **Fragments**: named concepts (auth, build, React) that connect findings across projects. Search for a topic and phren pulls in everything linked to that fragment
+- **Tasks**: work items that persist across sessions with priority, pinning, and GitHub issue linking
+- **Sessions**: conversation boundaries with summaries and checkpoints, so the next session picks up where the last one left off
+- **Skills**: reusable slash commands you teach phren. Drop them in `~/.phren/global/skills/` and they work everywhere
 
 ## How it works
 
 - **Surfaces relevant context on every prompt** via hooks. Agents build on what they know instead of starting fresh
-- **Trust scores decay over time** — old findings lose confidence. Decisions never decay. Observations expire in 14 days
+- **Trust scores decay over time.** Old findings lose confidence. Decisions never decay. Observations expire in 14 days
 - **Syncs across machines** through git push/pull. No coordination service
-- **Works with Claude Code, Copilot, Cursor, and Codex** — one memory, every agent
+- **Works with Claude Code, Copilot, Cursor, and Codex.** One store, every agent
 - **Shell and web UI** for browsing, searching, and triaging (`phren` or `phren web-ui`)
 
 ## Quick start
@@ -45,7 +45,7 @@ That single command creates `~/.phren`, wires up MCP, installs hooks, and gives
 npx @phren/cli init          # set up phren (interactive walkthrough)
 ```
 
-Init detects your tools, registers MCP servers, and installs lifecycle hooks. After it finishes, open a prompt in any tracked project — phren is already injecting context.
+Init detects your tools, registers MCP servers, and installs lifecycle hooks. After it finishes, open a prompt in any tracked project. Phren is already injecting context.
 
 To add a project later, run `phren add` from that directory. To browse what phren knows, run `phren` to open the interactive shell.
 

package/mcp/dist/capabilities/cli.js

@@ -1,6 +1,6 @@
 export const cliManifest = {
     surface: "cli",
-    version: "1.31.1",
+    version: "0.0.13",
     actions: {
         // Finding management
         "finding.add": { implemented: true, handler: "cli-actions.ts:handleAddFinding" },

package/mcp/dist/capabilities/mcp.js

@@ -1,6 +1,6 @@
 export const mcpManifest = {
     surface: "mcp",
-    version: "1.31.1",
+    version: "0.0.13",
     actions: {
         // Finding management
         "finding.add": { implemented: true, handler: "index.ts:add_finding" },

package/mcp/dist/capabilities/vscode.js

@@ -1,6 +1,6 @@
 export const vscodeManifest = {
     surface: "vscode",
-    version: "1.31.1",
+    version: "0.0.13",
     actions: {
         // Finding management
         "finding.add": { implemented: true, handler: "extension.ts:phren.addFinding" },

package/mcp/dist/capabilities/web-ui.js

@@ -1,6 +1,6 @@
 export const webUiManifest = {
     surface: "web-ui",
-    version: "1.31.1",
+    version: "0.0.13",
     actions: {
         // Finding management
         "finding.add": { implemented: false, reason: "Web UI is read-only for findings (review queue only)" },

package/mcp/dist/cli-actions.js

@@ -14,35 +14,27 @@ import { runSearch, runFragmentSearch, parseFragmentSearchArgs, runRelatedDocs,
 import { resolveRuntimeProfile } from "./runtime-profile.js";
 import { getProjectConsolidationStatus, CONSOLIDATION_ENTRY_THRESHOLD } from "./content-validate.js";
 import { listAllSessions } from "./mcp-session.js";
-export async function handleSearch(opts, profile) {
-    const result = await runSearch(opts, getPhrenPath(), profile);
-    if (result.lines.length > 0) {
+async function runAndPrint(fn) {
+    const result = await fn();
+    if (result.lines.length > 0)
         console.log(result.lines.join("\n"));
-    }
     if (result.exitCode !== 0)
         process.exit(result.exitCode);
 }
+export async function handleSearch(opts, profile) {
+    await runAndPrint(() => runSearch(opts, getPhrenPath(), profile));
+}
 export async function handleFragmentSearch(args, profile) {
     const opts = parseFragmentSearchArgs(args);
     if (!opts)
         return;
-    const result = await runFragmentSearch(opts.query, getPhrenPath(), profile, opts);
-    if (result.lines.length > 0) {
-        console.log(result.lines.join("\n"));
-    }
-    if (result.exitCode !== 0)
-        process.exit(result.exitCode);
+    await runAndPrint(() => runFragmentSearch(opts.query, getPhrenPath(), profile, opts));
 }
 export async function handleRelatedDocs(args, profile) {
     const opts = parseRelatedDocsArgs(args);
     if (!opts)
         return;
-    const result = await runRelatedDocs(opts.entity, getPhrenPath(), profile, opts);
-    if (result.lines.length > 0) {
-        console.log(result.lines.join("\n"));
-    }
-    if (result.exitCode !== 0)
-        process.exit(result.exitCode);
+    await runAndPrint(() => runRelatedDocs(opts.entity, getPhrenPath(), profile, opts));
 }
 export async function handleAddFinding(project, learning) {
     if (!project || !learning) {
@@ -184,41 +176,46 @@ export async function handleDoctor(args) {
         if ((process.env.PHREN_DEBUG))
             process.stderr.write(`[phren] doctor searchMissAnalysis: ${errorMessage(err)}\n`);
     }
+    const semStatus = await getSemanticSearchStatus(getPhrenPath(), profile || undefined);
+    if (!semStatus.ollamaUrl) {
+        console.log("- ok  semantic-search: disabled (optional; enable for fuzzy/paraphrase-heavy retrieval)");
+    }
+    else if (!semStatus.available) {
+        console.log(`- warn semantic-search: Ollama not running at ${semStatus.ollamaUrl} (start Ollama or set PHREN_OLLAMA_URL=off to disable)`);
+    }
+    else if (!semStatus.modelReady) {
+        console.log(`- warn semantic-search: model ${semStatus.model} not pulled (run: ollama pull ${semStatus.model})`);
+    }
+    else {
+        console.log(`- ok  semantic-search: ${semStatus.model} ready, ${semStatus.coverage}`);
+    }
+    process.exit(result.ok ? 0 : 1);
+}
+async function getSemanticSearchStatus(phrenPath, profile) {
     try {
         const { checkOllamaAvailable, checkModelAvailable, getOllamaUrl, getEmbeddingModel } = await import("./shared-ollama.js");
         const { getEmbeddingCache, formatEmbeddingCoverage } = await import("./shared-embedding-cache.js");
         const { listIndexedDocumentPaths } = await import("./shared-index.js");
         const ollamaUrl = getOllamaUrl();
-        if (!ollamaUrl) {
-            console.log("- ok  semantic-search: disabled (optional; enable for fuzzy/paraphrase-heavy retrieval)");
-        }
-        else {
-            const available = await checkOllamaAvailable();
-            if (!available) {
-                console.log(`- warn semantic-search: Ollama not running at ${ollamaUrl} (start Ollama or set PHREN_OLLAMA_URL=off to disable)`);
-            }
-            else {
-                const model = getEmbeddingModel();
-                const modelReady = await checkModelAvailable();
-                if (!modelReady) {
-                    console.log(`- warn semantic-search: model ${model} not pulled (run: ollama pull ${model})`);
-                }
-                else {
-                    const phrenPath = getPhrenPath();
-                    const cache = getEmbeddingCache(phrenPath);
-                    await cache.load().catch(() => { });
-                    const allPaths = listIndexedDocumentPaths(phrenPath, profile || undefined);
-                    const coverage = cache.coverage(allPaths);
-                    console.log(`- ok  semantic-search: ${model} ready, ${formatEmbeddingCoverage(coverage)}`);
-                }
-            }
-        }
+        if (!ollamaUrl)
+            return { ollamaUrl: null };
+        const available = await checkOllamaAvailable();
+        if (!available)
+            return { ollamaUrl, available: false };
+        const model = getEmbeddingModel();
+        const modelReady = await checkModelAvailable();
+        if (!modelReady)
+            return { ollamaUrl, available: true, modelReady: false, model };
+        const cache = getEmbeddingCache(phrenPath);
+        await cache.load().catch(() => { });
+        const coverage = formatEmbeddingCoverage(cache.coverage(listIndexedDocumentPaths(phrenPath, profile)));
+        return { ollamaUrl, available: true, modelReady: true, model, coverage };
     }
     catch (err) {
         if ((process.env.PHREN_DEBUG))
-            process.stderr.write(`[phren] doctor ollamaStatus: ${errorMessage(err)}\n`);
+            process.stderr.write(`[phren] getSemanticSearchStatus: ${errorMessage(err)}\n`);
+        return { ollamaUrl: null, status: "error", error: errorMessage(err) };
     }
-    process.exit(result.ok ? 0 : 1);
 }
 export async function handleStatus() {
     const phrenPath = getPhrenPath();
@@ -231,34 +228,24 @@ export async function handleStatus() {
     console.log(`unsynced commits: ${runtime.lastSync?.unsyncedCommits ?? 0}`);
     if (runtime.lastSync?.lastPushDetail)
         console.log(`push detail: ${runtime.lastSync.lastPushDetail}`);
-    try {
-        const { getOllamaUrl, checkOllamaAvailable, checkModelAvailable, getEmbeddingModel } = await import("./shared-ollama.js");
-        const { getEmbeddingCache, formatEmbeddingCoverage } = await import("./shared-embedding-cache.js");
-        const { listIndexedDocumentPaths } = await import("./shared-index.js");
-        const ollamaUrl = getOllamaUrl();
-        if (!ollamaUrl) {
-            console.log("semantic-search: disabled (optional)");
-            return;
-        }
-        const available = await checkOllamaAvailable();
-        if (!available) {
-            console.log(`semantic-search: offline (${ollamaUrl})`);
-            return;
+    const semStatus = await getSemanticSearchStatus(phrenPath, profile || undefined);
+    if (!semStatus.ollamaUrl) {
+        const errStatus = semStatus;
+        if (errStatus.status === "error") {
+            console.log(`semantic-search: error (${errStatus.error ?? "unknown"})`);
         }
-        const model = getEmbeddingModel();
-        const modelReady = await checkModelAvailable();
-        if (!modelReady) {
-            console.log(`semantic-search: model missing (${model})`);
-            return;
+        else {
+            console.log("semantic-search: disabled (optional)");
         }
-        const cache = getEmbeddingCache(phrenPath);
-        await cache.load().catch(() => { });
-        const coverage = cache.coverage(listIndexedDocumentPaths(phrenPath, profile || undefined));
-        console.log(`semantic-search: ${model} ready, ${formatEmbeddingCoverage(coverage)}`);
     }
-    catch (err) {
-        if ((process.env.PHREN_DEBUG))
-            process.stderr.write(`[phren] handleStatus semanticSearch: ${errorMessage(err)}\n`);
+    else if (!semStatus.available) {
+        console.log(`semantic-search: offline (${semStatus.ollamaUrl})`);
+    }
+    else if (!semStatus.modelReady) {
+        console.log(`semantic-search: model missing (${semStatus.model})`);
+    }
+    else {
+        console.log(`semantic-search: ${semStatus.model} ready, ${semStatus.coverage}`);
     }
 }
 export async function handleQualityFeedback(args) {

package/mcp/dist/cli-config.js

@@ -253,7 +253,6 @@ function handleConfigSynonyms(args) {
     printSynonymsUsage();
     process.exit(1);
 }
-const proactivityConfigSnapshot = buildProactivitySnapshot;
 function handleConfigProactivity(subcommand, args) {
     const phrenPath = getPhrenPath();
     const { project: projectArg, rest: filteredArgs } = parseProjectArg(args);
@@ -273,7 +272,7 @@ function handleConfigProactivity(subcommand, args) {
             }, null, 2));
             return;
         }
-        console.log(JSON.stringify(proactivityConfigSnapshot(phrenPath), null, 2));
+        console.log(JSON.stringify(buildProactivitySnapshot(phrenPath), null, 2));
         return;
     }
     if (filteredArgs.length !== 1) {
@@ -315,7 +314,7 @@ function handleConfigProactivity(subcommand, args) {
             writeGovernanceInstallPreferences(phrenPath, { proactivityTask: level });
             break;
     }
-    console.log(JSON.stringify(proactivityConfigSnapshot(phrenPath), null, 2));
+    console.log(JSON.stringify(buildProactivitySnapshot(phrenPath), null, 2));
 }
 function projectOwnershipConfigSnapshot(phrenPath) {
     const prefs = readInstallPreferences(phrenPath);
@@ -545,7 +544,7 @@ export async function handleIndexPolicy(args) {
         }
         const result = updateIndexPolicy(getPhrenPath(), patch);
         if (!result.ok) {
-            console.log(result.error);
+            console.error(result.error);
             if (result.code === "PERMISSION_DENIED")
                 process.exit(1);
             return;
@@ -635,7 +634,7 @@ export async function handleRetentionPolicy(args) {
         }
         const result = updateRetentionPolicy(phrenPath, patch);
         if (!result.ok) {
-            console.log(result.error);
+            console.error(result.error);
             if (result.code === "PERMISSION_DENIED")
                 process.exit(1);
             return;

package/mcp/dist/cli-extract.js

@@ -240,9 +240,10 @@ export async function handleExtractMemories(projectArg, cwdArg, silent = false,
             console.log(`Skipped memory extraction for ${project}: findings proactivity is low.`);
         return;
     }
-    const days = Number.parseInt((process.env.PHREN_MEMORY_EXTRACT_WINDOW_DAYS) || "30", 10);
+    const rawDays = Number.parseInt((process.env.PHREN_MEMORY_EXTRACT_WINDOW_DAYS) || "30", 10);
+    const days = Number.isNaN(rawDays) ? 30 : Math.max(1, rawDays);
     const threshold = Number.parseFloat((process.env.PHREN_MEMORY_AUTO_ACCEPT) || String(getRetentionPolicy(getPhrenPath()).autoAcceptThreshold));
-    const records = parseGitLogRecords(repoRoot, Number.isNaN(days) ? 30 : days);
+    const records = parseGitLogRecords(repoRoot, days);
     const ghCandidates = isFeatureEnabled("PHREN_FEATURE_GH_MINING", false)
         ? await mineGithubCandidates(repoRoot)
         : [];

package/mcp/dist/cli-graph.js

@@ -1,7 +1,7 @@
 import { getPhrenPath } from "./shared.js";
 import { buildIndex, queryRows } from "./shared-index.js";
 import { resolveRuntimeProfile } from "./runtime-profile.js";
-import { errorMessage } from "./utils.js";
+import { isValidProjectName, errorMessage } from "./utils.js";
 /**
  * CLI: phren graph [--project <name>] [--limit <n>]
  * Displays the fragment knowledge graph as a table.
@@ -19,6 +19,10 @@ export async function handleGraphRead(args) {
             limit = Math.min(Math.max(parseInt(args[++i], 10) || 20, 1), 200);
         }
     }
+    if (project && !isValidProjectName(project)) {
+        console.error(`Invalid project name: "${project}".`);
+        process.exit(1);
+    }
     const db = await buildIndex(phrenPath, profile);
     let sql;
     let params;
@@ -75,6 +79,10 @@ export async function handleGraphLink(args) {
         process.exit(1);
     }
     const [project, findingText, fragmentName] = args;
+    if (!isValidProjectName(project)) {
+        console.error(`Invalid project name: "${project}".`);
+        process.exit(1);
+    }
     const phrenPath = getPhrenPath();
     const profile = resolveRuntimeProfile(phrenPath);
     const db = await buildIndex(phrenPath, profile);
@@ -95,7 +103,10 @@ export async function handleGraphLink(args) {
     try {
         db.run("INSERT OR IGNORE INTO entities (name, type, first_seen_at) VALUES (?, ?, ?)", [normalizedFragment, "fragment", new Date().toISOString().slice(0, 10)]);
     }
-    catch { /* best effort */ }
+    catch (err) {
+        if (process.env.PHREN_DEBUG)
+            process.stderr.write(`[phren] graph link insert fragment: ${errorMessage(err)}\n`);
+    }
     const fragmentResult = db.exec("SELECT id FROM entities WHERE name = ? AND type = ?", [normalizedFragment, "fragment"]);
     if (!fragmentResult?.length || !fragmentResult[0]?.values?.length) {
         console.error("Failed to create fragment.");
@@ -105,7 +116,10 @@ export async function handleGraphLink(args) {
     try {
         db.run("INSERT OR IGNORE INTO entities (name, type, first_seen_at) VALUES (?, ?, ?)", [sourceDoc, "document", new Date().toISOString().slice(0, 10)]);
     }
-    catch { /* best effort */ }
+    catch (err) {
+        if (process.env.PHREN_DEBUG)
+            process.stderr.write(`[phren] graph link insert document: ${errorMessage(err)}\n`);
+    }
     const docResult = db.exec("SELECT id FROM entities WHERE name = ? AND type = ?", [sourceDoc, "document"]);
     if (!docResult?.length || !docResult[0]?.values?.length) {
         console.error("Failed to create document fragment.");

package/mcp/dist/cli-hooks-output.js

@@ -116,7 +116,7 @@ export function buildHookOutput(selected, usedTokens, intent, gitCtx, detectedPr
         }
     }
     logImpact(phrenPathLocal, impactEntries);
-    parts.push("<phren-context>");
+    parts.push("</phren-context>");
     const changedCount = gitCtx?.changedFiles.size ?? 0;
     if (gitCtx) {
         const fileHits = selected.filter((r) => fileRelevanceBoost(r.doc.path, gitCtx.changedFiles) > 0).length;

package/mcp/dist/cli-hooks-session.js

@@ -749,7 +749,7 @@ export async function handleHookStop() {
                         }
                         catch (err) {
                             if (process.env.PHREN_DEBUG)
-                                process.stderr.write(`[phren] hookSessionStart transcriptParse: ${errorMessage(err)}\n`);
+                                process.stderr.write(`[phren] hookStop transcriptParse: ${errorMessage(err)}\n`);
                         }
                     }
                     captureInput = assistantTexts.join("\n");

package/mcp/dist/cli-hooks.js

@@ -164,7 +164,9 @@ export async function handleHookPrompt() {
         for (const kw of keywordEntries) {
             sessionTopics[kw] = (sessionTopics[kw] ?? 0) + 1;
         }
-        fs.writeFileSync(topicFile, JSON.stringify(sessionTopics));
+        const topicTmp = `${topicFile}.tmp-${process.pid}`;
+        fs.writeFileSync(topicTmp, JSON.stringify(sessionTopics));
+        fs.renameSync(topicTmp, topicFile);
         // Find hot topics (3+ mentions this session)
         hotTopics = Object.entries(sessionTopics)
             .filter(([, count]) => count >= 3)
@@ -352,7 +354,7 @@ export async function handleHookPrompt() {
                 parts.push(`Findings ready for consolidation:`);
                 parts.push(notices.join("\n"));
                 parts.push(`Run phren-consolidate when ready.`);
-                parts.push(`<phren-notice>`);
+                parts.push(`</phren-notice>`);
             }
             if (noticeFile) {
                 try {
@@ -374,7 +376,7 @@ export async function handleHookPrompt() {
     }
     catch (err) {
         const msg = errorMessage(err);
-        process.stdout.write(`\n<phren-error>phren hook failed: ${msg}. Check ~/.phren/.runtime/debug.log for details.<phren-error>\n`);
+        process.stdout.write(`\n<phren-error>phren hook failed: ${msg}. Check ~/.phren/.runtime/debug.log for details.</phren-error>\n`);
         debugLog(`hook-prompt error: ${msg}`);
         process.exit(0);
     }

package/mcp/dist/cli.js

@@ -108,7 +108,7 @@ export async function runCliCommand(command, args) {
         case "session-context":
             return handleSessionContext();
         default:
-            console.error(`Unknown command: ${command}`);
+            console.error(`Unknown command: ${command}\nRun 'phren --help' for available commands.`);
             process.exit(1);
     }
 }

package/mcp/dist/content-archive.js

@@ -77,12 +77,11 @@ function parseActiveEntries(content) {
 /**
  * Check whether a bullet already exists in a reference file (already archived).
  */
-function isAlreadyArchived(referenceDir, bullet) {
+/** Build a Set of normalized bullet strings from all .md files in referenceDir. */
+function buildArchivedBulletSet(referenceDir) {
+    const bulletSet = new Set();
     if (!fs.existsSync(referenceDir))
-        return false;
-    const normalizedBullet = stripComments(bullet).replace(/^-\s+/, "").trim().toLowerCase();
-    if (!normalizedBullet)
-        return false;
+        return bulletSet;
     try {
         const stack = [referenceDir];
         while (stack.length > 0) {
@@ -100,17 +99,23 @@ function isAlreadyArchived(referenceDir, bullet) {
                     if (!line.startsWith("- "))
                         continue;
                     const normalizedLine = stripComments(line).replace(/^-\s+/, "").trim().toLowerCase();
-                    if (normalizedLine === normalizedBullet)
-                        return true;
+                    if (normalizedLine)
+                        bulletSet.add(normalizedLine);
                 }
             }
         }
     }
     catch (err) {
         if ((process.env.PHREN_DEBUG))
-            process.stderr.write(`[phren] isDuplicateInReference: ${errorMessage(err)}\n`);
+            process.stderr.write(`[phren] buildArchivedBulletSet: ${errorMessage(err)}\n`);
     }
-    return false;
+    return bulletSet;
+}
+function isAlreadyArchived(archivedSet, bullet) {
+    const normalizedBullet = stripComments(bullet).replace(/^-\s+/, "").trim().toLowerCase();
+    if (!normalizedBullet)
+        return false;
+    return archivedSet.has(normalizedBullet);
 }
 /**
  * Archive the oldest entries from FINDINGS.md into reference/{topic}.md files.
@@ -152,8 +157,11 @@ export function autoArchiveToReference(phrenPath, project, keepCount) {
                     throw wxErr;
                 }
             }
-            catch {
-                return phrenErr("Consolidation already running", PhrenError.LOCK_TIMEOUT);
+            catch (innerErr) {
+                if (innerErr.code === "EEXIST" || innerErr.code === "ENOENT") {
+                    return phrenErr("Consolidation already running", PhrenError.LOCK_TIMEOUT);
+                }
+                throw innerErr;
             }
         }
         else {
@@ -173,9 +181,10 @@ export function autoArchiveToReference(phrenPath, project, keepCount) {
             const referenceDir = path.join(resolvedDir, "reference");
             const { topics } = readProjectTopics(phrenPath, project);
             const today = new Date().toISOString().slice(0, 10);
+            const archivedSet = buildArchivedBulletSet(referenceDir);
             const actuallyArchived = [];
             for (const entry of toArchive) {
-                if (isAlreadyArchived(referenceDir, entry.bullet)) {
+                if (isAlreadyArchived(archivedSet, entry.bullet)) {
                     debugLog(`auto_archive: skipping already-archived entry: "${entry.bullet.slice(0, 60)}"`);
                     continue;
                 }

package/mcp/dist/content-citation.js

@@ -1,5 +1,4 @@
 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";
@@ -170,8 +169,16 @@ function resolveCitationFile(citation) {
 }
 // Session-scoped caches for git I/O during citation validation.
 // Keyed by "repo\0commit" and "repo\0file\0line" respectively.
+const MAX_CACHE_ENTRIES = 500;
 const commitExistsCache = new Map();
 const blameCache = new Map();
+function evictOldest(cache) {
+    if (cache.size <= MAX_CACHE_ENTRIES)
+        return;
+    const first = cache.keys().next().value;
+    if (first !== undefined)
+        cache.delete(first);
+}
 function commitExists(repoPath, commit) {
     const key = `${repoPath}\0${commit}`;
     const cached = commitExistsCache.get(key);
@@ -180,11 +187,13 @@ function commitExists(repoPath, commit) {
     try {
         runGitOrThrow(repoPath, ["cat-file", "-e", `${commit}^{commit}`], EXEC_TIMEOUT_QUICK_MS);
         commitExistsCache.set(key, true);
+        evictOldest(commitExistsCache);
         return true;
     }
     catch (err) {
         debugLog(`commitExists: commit ${commit} not found in ${repoPath}: ${errorMessage(err)}`);
         commitExistsCache.set(key, false);
+        evictOldest(commitExistsCache);
         return false;
     }
 }
@@ -197,11 +206,13 @@ function cachedBlame(repoPath, relFile, line) {
         const out = runGitOrThrow(repoPath, ["blame", "-L", `${line},${line}`, "--porcelain", relFile], 10_000).trim();
         const first = out.split("\n")[0] || "";
         blameCache.set(key, first);
+        evictOldest(blameCache);
         return first;
     }
     catch (err) {
         debugLog(`cachedBlame: git blame failed for ${relFile}:${line}: ${errorMessage(err)}`);
         blameCache.set(key, false);
+        evictOldest(blameCache);
         return false;
     }
 }
@@ -274,7 +285,7 @@ function confidenceForAge(ageDays, decay) {
 }
 function wasFileModifiedAfter(filePath, findingDate) {
     try {
-        const stat = statSync(filePath);
+        const stat = fs.statSync(filePath);
         const fileModified = stat.mtime.toISOString().slice(0, 10);
         return fileModified > findingDate;
     }

package/mcp/dist/content-learning.js

@@ -378,7 +378,7 @@ export function addFindingToFile(phrenPath, project, learning, citationInput, op
     if (!result.ok)
         return result;
     if (typeof result.data === "string")
-        return phrenOk(result.data);
+        return phrenOk({ message: result.data, status: "skipped" });
     appendAuditLog(phrenPath, "add_finding", `project=${project}${result.data.created ? " created=true" : ""} citation_commit=${result.data.citation.commit ?? "none"} citation_file=${result.data.citation.file ?? "none"}`);
     const cap = Number.parseInt((process.env.PHREN_FINDINGS_CAP) || "", 10) || DEFAULT_FINDINGS_CAP;
     const activeCount = countActiveFindings(result.data.content);
@@ -390,10 +390,12 @@ export function addFindingToFile(phrenPath, project, learning, citationInput, op
     }
     if (result.data.created) {
         const createdMsg = `Created FINDINGS.md for "${project}" and added insight.`;
-        return phrenOk(result.data.tagWarning ? `${createdMsg} Warning: ${result.data.tagWarning}` : createdMsg);
+        const message = result.data.tagWarning ? `${createdMsg} Warning: ${result.data.tagWarning}` : createdMsg;
+        return phrenOk({ message, status: "created" });
     }
     const addedMsg = `Added finding to ${project}: ${result.data.bullet} (with citation metadata)`;
-    return phrenOk(result.data.tagWarning ? `${addedMsg} Warning: ${result.data.tagWarning}` : addedMsg);
+    const message = result.data.tagWarning ? `${addedMsg} Warning: ${result.data.tagWarning}` : addedMsg;
+    return phrenOk({ message, status: "added" });
 }
 export function addFindingsToFile(phrenPath, project, learnings, opts) {
     if (!isValidProjectName(project))
@@ -402,8 +404,8 @@ export function addFindingsToFile(phrenPath, project, learnings, opts) {
     if (!resolvedDir)
         return phrenErr(`Invalid project name: "${project}".`, PhrenError.INVALID_PROJECT_NAME);
     const learningsPath = path.join(resolvedDir, "FINDINGS.md");
-    const today = new Date().toISOString().slice(0, 10);
     const nowIso = new Date().toISOString();
+    const today = nowIso.slice(0, 10);
     const resolvedCitationInputResult = resolveFindingCitationInput(phrenPath, project);
     if (!resolvedCitationInputResult.ok)
         return resolvedCitationInputResult;

package/mcp/dist/content-metadata.js

@@ -172,6 +172,16 @@ export function stripAllMetadata(line) {
 export function stripComments(text) {
     return text.replace(METADATA_REGEX.anyComment, "").trim();
 }
+/** Normalize finding text for comparison: strips bullet prefix, HTML comments, confidence tags, normalizes whitespace, lowercases. */
+export function normalizeFindingText(raw) {
+    return raw
+        .replace(/^-\s+/, "")
+        .replace(/<!--.*?-->/g, " ")
+        .replace(/\[confidence\s+[01](?:\.\d+)?\]/gi, " ")
+        .replace(/\s+/g, " ")
+        .trim()
+        .toLowerCase();
+}
 // ---------------------------------------------------------------------------
 // Add helpers — append metadata comments to a line
 // ---------------------------------------------------------------------------

package/mcp/dist/core-finding.js

@@ -18,7 +18,7 @@ export function addFinding(phrenPath, project, finding, citation, findingType) {
     if (!result.ok) {
         return { ok: false, message: result.error };
     }
-    return { ok: true, message: result.data, data: { project, finding: taggedFinding } };
+    return { ok: true, message: result.data.message, data: { project, finding: taggedFinding } };
 }
 /**
  * Remove a finding by partial text match.