@danielmarbach/mnemonic-mcp 0.26.1 → 0.27.0

package/build/index.js

@@ -12,13 +12,14 @@ import { enrichTemporalHistory } from "./temporal-interpretation.js";
 import { getOrBuildProjection } from "./projections.js";
 import { invalidateActiveProjectCache, getOrBuildVaultEmbeddings, getOrBuildVaultNoteList, getRecentSessionNoteAccesses, getRecentSessionAccessNote, getSessionCachedNote, getSessionCachedProjection, getSessionCachedProjectionTokens, recordSessionNoteAccess, setSessionCachedNote, setSessionCachedProjection, setSessionCachedProjectionTokens, } from "./cache.js";
 import { performance } from "perf_hooks";
-import { filterRelationships, mergeRelationshipsFromNotes, normalizeMergePlanSourceIds, resolveEffectiveConsolidationMode, } from "./consolidate.js";
+import { aggregateMergeRisk, buildConsolidateNoteEvidence, buildGroupWarnings, filterRelationships, mergeRelationshipsFromNotes, normalizeMergePlanSourceIds, resolveEffectiveConsolidationMode, } from "./consolidate.js";
 import { suggestAutoRelationships } from "./auto-relate.js";
 import { computeRecallMetadataBoost, computeHybridScore, selectRecallResults, selectWorkflowResults, applyLexicalReranking, enrichRescueCandidateScores, resolveDiscoveredVaults, applyCanonicalExplanationPromotion, applyGraphSpreadingActivation, assignDenseRanks, detectTemporalQueryHint, computeTemporalRecencyBoost, shouldApplyTemporalFiltering, isWithinTemporalFilterWindow, } from "./recall.js";
 import { shouldTriggerLexicalRescue, prepareTfIdfCorpusFromTokenizedDocuments, rankDocumentsByTfIdf, LEXICAL_RESCUE_CANDIDATE_LIMIT, LEXICAL_RESCUE_THRESHOLD, LEXICAL_RESCUE_RESULT_LIMIT, tokenize, } from "./lexical.js";
 import { getRelationshipPreview } from "./relationships.js";
 import { MarkdownLintError, cleanMarkdown } from "./markdown.js";
 import { applySemanticPatches } from "./semantic-patch.js";
+import { hasActualChanges, computeFieldsModified } from "./update-detect-changes.js";
 import { MnemonicConfigStore, readVaultSchemaVersion } from "./config.js";
 import { CONSOLIDATION_MODES, PROTECTED_BRANCH_BEHAVIORS, PROJECT_POLICY_SCOPES, WRITE_SCOPES, isProtectedBranch, resolveProtectedBranchBehavior, resolveProtectedBranchPatterns, resolveConsolidationMode, resolveWriteScope, } from "./project-memory-policy.js";
 import { classifyTheme, classifyThemeWithGraduation, computeThemesWithGraduation, summarizePreview, titleCaseTheme, daysSinceUpdate, withinThemeScore, anchorScore, computeConnectionDiversity, workingStateScore, extractNextAction, } from "./project-introspection.js";
@@ -438,6 +439,34 @@ function formatRelationshipPreview(preview) {
         : "";
     return `**related (${preview.totalDirectRelations}):** ${shown}${more}`;
 }
+function toRecallFreshness(updatedAt) {
+    const updated = new Date(updatedAt);
+    if (Number.isNaN(updated.getTime())) {
+        return "older";
+    }
+    const ageDays = Math.max(0, (Date.now() - updated.getTime()) / (1000 * 60 * 60 * 24));
+    if (ageDays <= 1)
+        return "today";
+    if (ageDays <= 7)
+        return "thisWeek";
+    if (ageDays <= 31)
+        return "thisMonth";
+    return "older";
+}
+function toRecallRankBand(semanticRank) {
+    if (semanticRank !== undefined && semanticRank <= 3)
+        return "top3";
+    if (semanticRank !== undefined && semanticRank <= 10)
+        return "top10";
+    return "lower";
+}
+function formatRetrievalEvidenceHint(evidence, role) {
+    const rolePart = role ?? "untyped";
+    const supersedesPart = evidence.superseded
+        ? ` | supersedes ${evidence.supersededCount ?? 1} note${(evidence.supersededCount ?? 1) === 1 ? "" : "s"}`
+        : "";
+    return `${evidence.rankBand} | channels: ${evidence.channels.join(", ")} | ${evidence.projectRelevant ? "project-relevant" : "cross-project"}\n${rolePart}, ${evidence.freshness}${supersedesPart}`;
+}
 // ── Git commit message helpers ────────────────────────────────────────────────
 /**
  * Extract a short human-readable summary from note content.
@@ -1899,7 +1928,8 @@ server.registerTool("recall", {
         "Returns:\n" +
         "- Ranked memory matches with scores, vault label, tags, lifecycle, and updated time\n" +
         "- Bounded 1-hop relationship previews automatically attached to top results\n" +
-        "- In temporal mode, optional compact history entries for top matches\n\n" +
+        "- In temporal mode, optional compact history entries for top matches\n" +
+        "- Optional retrieval evidence via `evidence: \"compact\"` for why a result ranked\n\n" +
         "Read-only.\n\n" +
         "Typical next step:\n" +
         "- Use `get`, `update`, `relate`, or `consolidate` based on the results.",
@@ -1916,6 +1946,7 @@ server.registerTool("recall", {
         minSimilarity: z.number().min(0).max(1).optional().default(DEFAULT_MIN_SIMILARITY),
         mode: z.enum(["default", "temporal", "workflow"]).optional().default("default").describe("Use `temporal` for compact git-backed history, or `workflow` for RPIR-oriented chain reconstruction."),
         verbose: z.boolean().optional().default(false).describe("Only meaningful with `mode: \"temporal\"`. Adds richer stats-based history context without returning raw diffs."),
+        evidence: z.enum(["compact"]).optional().describe("Optional retrieval rationale. Omit for default output; use `compact` for bounded rank and lineage signals."),
         tags: z.array(z.string()).optional().describe("Filter results to notes with all of these tags."),
         scope: z
             .enum(["project", "global", "all"])
@@ -1927,7 +1958,7 @@ server.registerTool("recall", {
         lifecycle: z.enum(["temporary", "permanent"]).optional().describe("Filter results by lifecycle. Useful for recovering working-state with `lifecycle: temporary` after `project_memory_summary` orientation."),
     }),
     outputSchema: RecallResultSchema,
-}, async ({ query, cwd, limit, minSimilarity, mode, verbose, tags, scope, lifecycle }) => {
+}, async ({ query, cwd, limit, minSimilarity, mode, verbose, evidence, tags, scope, lifecycle }) => {
     const t0Recall = performance.now();
     await ensureBranchSynced(cwd);
     const project = await resolveProject(cwd);
@@ -2048,12 +2079,14 @@ server.registerTool("recall", {
     };
     const strongestSemanticScore = scored.reduce((max, candidate) => max === undefined ? candidate.score : Math.max(max, candidate.score), undefined);
     const reranked = applyLexicalReranking(scored, query, getProjectionText);
+    const semanticCandidateIds = new Set(reranked.map((candidate) => candidate.id));
     // Apply graph spreading activation: traverse related notes and boost their scores
     const preSpreadIds = new Set(reranked.map((c) => c.id));
     const getNoteRelationships = (id) => {
         return noteRelationships.get(id);
     };
     const withGraphSpread = applyGraphSpreadingActivation(reranked, getNoteRelationships);
+    const graphDiscoveredIds = new Set(withGraphSpread.filter((candidate) => !semanticCandidateIds.has(candidate.id)).map((candidate) => candidate.id));
     // Resolve correct vault for graph-discovered candidates that inherited their
     // entry point's vault instead of their own.
     await resolveDiscoveredVaults(withGraphSpread, preSpreadIds, async (id) => {
@@ -2073,6 +2106,7 @@ server.registerTool("recall", {
         candidate.semanticRank = rank;
     });
     let promoted = applyCanonicalExplanationPromotion(withGraphSpread);
+    let rescueCandidateIds = new Set();
     // Lexical rescue: when semantic results are weak, scan projections for additional candidates.
     // Skip rescue when the caller set a strict minSimilarity above the default,
     // because rescue candidates lack genuine semantic backing.
@@ -2080,6 +2114,7 @@ server.registerTool("recall", {
     if (rescueAllowed && shouldTriggerLexicalRescue(strongestSemanticScore, scored.length)) {
         const rescueCandidates = await collectLexicalRescueCandidates(vaults, query, temporalQueryHint, project ?? undefined, scope, tags, lifecycle, promoted);
         promoted.push(...rescueCandidates);
+        rescueCandidateIds = new Set(rescueCandidates.map((candidate) => candidate.id));
         enrichRescueCandidateScores(promoted, query, getProjectionText);
         promoted = applyCanonicalExplanationPromotion(promoted);
     }
@@ -2098,7 +2133,7 @@ server.registerTool("recall", {
     // Determine how many top results get relationship expansion
     // Top 1 by default, top 3 if result count is small
     const recallRelationshipLimit = top.length <= 3 ? 3 : 1;
-    for (const [index, { id, score, vault, boosted }] of top.entries()) {
+    for (const [index, { id, score, vault, boosted, semanticRank, lexicalRank, canonicalExplanationScore, metadata, isCurrentProject }] of top.entries()) {
         const note = await readCachedNote(vault, id);
         if (note) {
             const centrality = note.relatedTo?.length ?? 0;
@@ -2135,8 +2170,30 @@ server.registerTool("recall", {
             const provenanceLine = provenance || confidence
                 ? `\n**confidence:** ${confidence ?? "medium"}${provenance?.recentlyChanged ? " | **recently changed**" : ""}`
                 : "";
+            const supersededRelations = (note.relatedTo ?? []).filter((rel) => rel.type === "supersedes");
+            const retrievalEvidence = evidence === "compact"
+                ? {
+                    channels: [
+                        semanticRank !== undefined ? "semantic" : undefined,
+                        lexicalRank !== undefined ? "lexical" : undefined,
+                        graphDiscoveredIds.has(id) ? "graph" : undefined,
+                        rescueCandidateIds.has(id) ? "rescue" : undefined,
+                        canonicalExplanationScore !== undefined && canonicalExplanationScore > 0 ? "canonical" : undefined,
+                        temporalQueryHint ? "temporal-boost" : undefined,
+                    ].filter((value) => value !== undefined),
+                    rankBand: toRecallRankBand(semanticRank),
+                    projectRelevant: isCurrentProject,
+                    freshness: toRecallFreshness(note.updatedAt),
+                    superseded: supersededRelations.length > 0,
+                    supersededBy: supersededRelations.length > 0 ? supersededRelations[0]?.id : undefined,
+                    supersededCount: supersededRelations.length > 0 ? supersededRelations.length : undefined,
+                }
+                : undefined;
+            const evidenceLine = retrievalEvidence
+                ? `\n${formatRetrievalEvidenceHint(retrievalEvidence, metadata?.role)}`
+                : "";
             // Suppress raw related IDs when enriched preview is shown to avoid duplication
-            sections.push(`${formatNote(note, score, relationships === undefined)}${provenanceLine}${formattedHistory}${formattedRelationships}`);
+            sections.push(`${formatNote(note, score, relationships === undefined)}${provenanceLine}${evidenceLine}${formattedHistory}${formattedRelationships}`);
             structuredResults.push({
                 id,
                 title: note.title,
@@ -2153,6 +2210,7 @@ server.registerTool("recall", {
                 history,
                 historySummary,
                 relationships,
+                retrievalEvidence,
             });
             if (project) {
                 setSessionCachedNote(project.id, vault.storage.vaultPath, note);
@@ -2316,64 +2374,136 @@ server.registerTool("update", {
         }
     }
     const cleanedContent = content === undefined ? undefined : await cleanMarkdown(content);
-    const updated = {
-        ...note,
-        title: title ?? note.title,
-        content: patchedContent ?? cleanedContent ?? note.content,
-        tags: tags ?? note.tags,
-        lifecycle: lifecycle ?? note.lifecycle,
-        ...(role !== undefined ? { role } : (note.role ? { role: note.role } : {})),
-        alwaysLoad: alwaysLoad !== undefined ? alwaysLoad : note.alwaysLoad,
-        updatedAt: now,
-    };
-    if (updated.project) {
-        const accessCandidates = getRecentSessionNoteAccesses(updated.project)
+    const resolvedTitle = title ?? note.title;
+    const resolvedContent = patchedContent ?? cleanedContent ?? note.content;
+    const resolvedTags = tags ?? note.tags;
+    const resolvedLifecycle = lifecycle ?? note.lifecycle;
+    const resolvedRole = role !== undefined ? role : (note.role ? note.role : undefined);
+    const resolvedAlwaysLoad = alwaysLoad !== undefined ? alwaysLoad : note.alwaysLoad;
+    let relatedToChanged = false;
+    let resolvedRelatedTo = note.relatedTo;
+    if (note.project) {
+        const accessCandidates = getRecentSessionNoteAccesses(note.project)
             .map((entry) => {
-            const cachedNote = getSessionCachedNote(updated.project, entry.vaultPath, entry.noteId)
-                ?? getRecentSessionAccessNote(updated.project, entry.vaultPath, entry.noteId);
+            const cachedNote = getSessionCachedNote(note.project, entry.vaultPath, entry.noteId)
+                ?? getRecentSessionAccessNote(note.project, entry.vaultPath, entry.noteId);
             return cachedNote
                 ? { note: cachedNote, accessedAt: entry.accessedAt, accessKind: entry.accessKind, score: entry.score }
                 : null;
         })
             .filter((entry) => entry !== null);
-        const autoRelationships = suggestAutoRelationships(updated, accessCandidates);
+        const autoRelationships = suggestAutoRelationships({
+            ...note,
+            title: resolvedTitle,
+            content: resolvedContent,
+            tags: resolvedTags,
+            lifecycle: resolvedLifecycle,
+            alwaysLoad: resolvedAlwaysLoad,
+        }, accessCandidates);
         if (autoRelationships.length > 0) {
-            const existing = [...(updated.relatedTo ?? [])];
+            const existing = [...(note.relatedTo ?? [])];
             for (const relationship of autoRelationships) {
                 if (!existing.some((rel) => rel.id === relationship.id && rel.type === relationship.type)) {
                     existing.push(relationship);
                 }
             }
-            updated.relatedTo = existing;
-        }
+            resolvedRelatedTo = existing;
+            relatedToChanged = true;
+        }
+    }
+    const changes = computeFieldsModified({
+        patchedContent,
+        originalContent: note.content,
+        contentExplicitlyProvided: content !== undefined,
+        semanticPatchProvided: semanticPatch !== undefined && semanticPatch.length > 0,
+        newTitle: resolvedTitle,
+        originalTitle: note.title,
+        titleExplicitlyProvided: title !== undefined,
+        newLifecycle: resolvedLifecycle,
+        originalLifecycle: note.lifecycle,
+        lifecycleExplicitlyProvided: lifecycle !== undefined,
+        newRole: resolvedRole,
+        originalRole: note.role,
+        roleExplicitlySet: role !== undefined,
+        newTags: resolvedTags,
+        originalTags: note.tags,
+        tagsExplicitlyProvided: tags !== undefined,
+        newAlwaysLoad: resolvedAlwaysLoad,
+        originalAlwaysLoad: note.alwaysLoad,
+        alwaysLoadExplicitlyProvided: alwaysLoad !== undefined,
+        relatedToChanged,
+    });
+    const hasChanges = hasActualChanges({
+        content: cleanedContent,
+        originalContent: note.content,
+        title,
+        originalTitle: note.title,
+        tags,
+        originalTags: note.tags,
+        lifecycle,
+        originalLifecycle: note.lifecycle,
+        role,
+        originalRole: note.role,
+        roleExplicitlySet: role !== undefined,
+        alwaysLoad,
+        originalAlwaysLoad: note.alwaysLoad,
+        semanticPatchApplied: semanticPatch !== undefined && semanticPatch.length > 0,
+        relatedToChanged,
+    });
+    if (!hasChanges) {
+        const noOpPersistence = {
+            notePath: vault.storage.notePath(id),
+            embeddingPath: vault.storage.embeddingPath(id),
+            embedding: { status: "skipped", model: embedModel, reason: "no-changes" },
+            git: {
+                commit: "skipped",
+                push: "skipped",
+                commitReason: "no-changes",
+                pushReason: "no-changes",
+            },
+            durability: "local-only",
+        };
+        return {
+            content: [{ type: "text", text: `No changes to memory '${id}'` }],
+            structuredContent: {
+                action: "updated",
+                id,
+                title: note.title,
+                fieldsModified: [],
+                timestamp: note.updatedAt,
+                project: noteProjectRef(note),
+                lifecycle: note.lifecycle,
+                role: note.role,
+                persistence: noOpPersistence,
+            },
+        };
     }
+    const updated = {
+        ...note,
+        title: resolvedTitle,
+        content: resolvedContent,
+        tags: resolvedTags,
+        lifecycle: resolvedLifecycle,
+        ...(role !== undefined ? { role: resolvedRole } : (note.role ? { role: note.role } : {})),
+        alwaysLoad: resolvedAlwaysLoad,
+        updatedAt: now,
+        relatedTo: resolvedRelatedTo,
+    };
     await vault.storage.writeNote(updated);
-    let embeddingStatus = { status: "written" };
-    try {
-        const text = await embedTextForNote(vault.storage, updated);
-        const vector = await embed(text);
-        await vault.storage.writeEmbedding({ id, model: embedModel, embedding: vector, updatedAt: now });
+    const shouldReembed = patchedContent !== undefined || cleanedContent !== undefined;
+    let embeddingStatus = { status: "skipped", reason: shouldReembed ? undefined : "metadata-only" };
+    if (shouldReembed) {
+        try {
+            const text = await embedTextForNote(vault.storage, updated);
+            const vector = await embed(text);
+            await vault.storage.writeEmbedding({ id, model: embedModel, embedding: vector, updatedAt: now });
+            embeddingStatus = { status: "written" };
+        }
+        catch (err) {
+            embeddingStatus = { status: "skipped", reason: err instanceof Error ? err.message : String(err) };
+            console.error(`[embedding] Re-embed failed for '${id}': ${err}`);
+        }
     }
-    catch (err) {
-        embeddingStatus = { status: "skipped", reason: err instanceof Error ? err.message : String(err) };
-        console.error(`[embedding] Re-embed failed for '${id}': ${err}`);
-    }
-    // Build change summary (LLM-provided or auto-generated)
-    const changes = [];
-    if (title !== undefined && title !== note.title)
-        changes.push("title");
-    if (content !== undefined)
-        changes.push("content");
-    if (semanticPatch !== undefined)
-        changes.push("semanticPatch");
-    if (tags !== undefined)
-        changes.push("tags");
-    if (lifecycle !== undefined && lifecycle !== note.lifecycle)
-        changes.push("lifecycle");
-    if (role !== undefined && role !== note.role)
-        changes.push("role");
-    if (alwaysLoad !== undefined && alwaysLoad !== note.alwaysLoad)
-        changes.push("alwaysLoad");
     const changeDesc = changes.length > 0 ? `Updated ${changes.join(", ")}` : "No changes";
     const commitSummary = summary ?? changeDesc;
     const commitBody = formatCommitBody({
@@ -4260,7 +4390,8 @@ server.registerTool("consolidate", {
         "- The canonical memory, source ids, resulting relationships, and persistence status\n\n" +
         "Side effects: creates or updates the canonical note, modifies or removes source notes according to mode, git commits, and may push.\n\n" +
         "Typical next step:\n" +
-        "- Use `get` to inspect the canonical note and `recall` to confirm duplication is reduced.",
+        "- Use `get` to inspect the canonical note and `recall` to confirm duplication is reduced.\n" +
+        "- Evidence defaults on for consolidate analysis strategies and execute-merge (lifecycle, risk, warnings).",
     annotations: {
         readOnlyHint: false,
         destructiveHint: true,
@@ -4280,7 +4411,8 @@ server.registerTool("consolidate", {
         ])
             .describe("What to do: 'dry-run' = full analysis without changes, 'detect-duplicates' = find similar pairs, " +
             "'find-clusters' = group by theme and relationships, 'suggest-merges' = actionable merge recommendations, " +
-            "'execute-merge' = perform a merge (requires mergePlan), 'prune-superseded' = delete notes marked as superseded"),
+            "'execute-merge' = perform a merge (requires mergePlan), 'prune-superseded' = delete notes marked as superseded. " +
+            "Use `evidence: true` on analysis strategies for trust/risk signals."),
         mode: z
             .enum(CONSOLIDATION_MODES)
             .optional()
@@ -4292,6 +4424,10 @@ server.registerTool("consolidate", {
             .optional()
             .default(0.85)
             .describe("Cosine similarity threshold for duplicate detection (0.85 default)"),
+        evidence: z
+            .boolean()
+            .optional()
+            .describe("Confidence signals for analysis strategies and execute-merge (lifecycle, risk, warnings). Default true for safety."),
         mergePlan: z
             .object({
             sourceIds: z.array(z.string()).min(2).describe("Ids of notes to merge into one consolidated note"),
@@ -4310,7 +4446,7 @@ server.registerTool("consolidate", {
             "When true, consolidate can commit on a protected branch without changing project policy."),
     }),
     outputSchema: ConsolidateResultSchema,
-}, async ({ cwd, strategy, mode, threshold, mergePlan, allowProtectedBranch = false }) => {
+}, async ({ cwd, strategy, mode, threshold, evidence = true, mergePlan, allowProtectedBranch = false }) => {
     await ensureBranchSynced(cwd);
     const project = await resolveProject(cwd);
     if (!project && cwd) {
@@ -4330,16 +4466,16 @@ server.registerTool("consolidate", {
     const defaultConsolidationMode = resolveConsolidationMode(policy);
     switch (strategy) {
         case "detect-duplicates":
-            return detectDuplicates(projectNotes, threshold, project);
+            return detectDuplicates(projectNotes, threshold, project, evidence);
         case "find-clusters":
             return findClusters(projectNotes, project);
         case "suggest-merges":
-            return suggestMerges(projectNotes, threshold, defaultConsolidationMode, project, mode);
+            return suggestMerges(projectNotes, threshold, defaultConsolidationMode, project, mode, evidence);
         case "execute-merge": {
             if (!mergePlan) {
                 return { content: [{ type: "text", text: "execute-merge strategy requires a mergePlan with sourceIds and targetTitle." }], isError: true };
             }
-            const mergeResult = await executeMerge(entries, mergePlan, defaultConsolidationMode, project, cwd, mode, policy, allowProtectedBranch);
+            const mergeResult = await executeMerge(entries, mergePlan, defaultConsolidationMode, project, cwd, mode, policy, allowProtectedBranch, evidence);
             invalidateActiveProjectCache();
             return mergeResult;
         }
@@ -4349,20 +4485,22 @@ server.registerTool("consolidate", {
             return pruneResult;
         }
         case "dry-run":
-            return dryRunAll(projectNotes, threshold, defaultConsolidationMode, project, mode);
+            return dryRunAll(projectNotes, threshold, defaultConsolidationMode, project, mode, evidence);
         default:
             return { content: [{ type: "text", text: `Unknown strategy: ${strategy}` }], isError: true };
     }
 });
 // Consolidate helper functions
-async function detectDuplicates(entries, threshold, project) {
+async function detectDuplicates(entries, threshold, project, evidence) {
     const lines = [];
     lines.push(`Duplicate detection for ${project?.name ?? "global"} (similarity > ${threshold}):`);
     lines.push("");
     const checked = new Set();
     let foundCount = 0;
     const duplicates = [];
+    const duplicatePairs = [];
     const embeddings = await loadEmbeddingsByNoteId(entries);
+    const allNotes = entries.map((entry) => entry.note);
     for (let i = 0; i < entries.length; i++) {
         const entryA = entries[i];
         if (checked.has(entryA.note.id))
@@ -4379,10 +4517,22 @@ async function detectDuplicates(entries, threshold, project) {
                 continue;
             const similarity = cosineSimilarity(embeddingA, embeddingB);
             if (similarity >= threshold) {
+                const noteAEvidence = buildConsolidateNoteEvidence(entryA.note, allNotes, entryA.note);
+                const noteBEvidence = buildConsolidateNoteEvidence(entryB.note, allNotes, entryA.note);
+                const groupWarnings = buildGroupWarnings([entryA.note, entryB.note], entryA.note);
+                const pairRisk = aggregateMergeRisk([noteAEvidence.mergeRisk, noteBEvidence.mergeRisk]);
                 foundCount++;
                 lines.push(`${foundCount}. ${entryA.note.title} (${entryA.note.id})`);
                 lines.push(`   └── ${entryB.note.title} (${entryB.note.id})`);
                 lines.push(`   Similarity: ${similarity.toFixed(3)}`);
+                if (evidence) {
+                    lines.push(`   A: ${noteAEvidence.lifecycle}, ${noteAEvidence.role ?? "untyped"} | ${Math.round(noteAEvidence.ageDays)}d old | rel: ${noteAEvidence.relatedCount} | supersedes: ${noteAEvidence.supersededCount ?? 0} | risk: ${noteAEvidence.mergeRisk}`);
+                    lines.push(`   B: ${noteBEvidence.lifecycle}, ${noteBEvidence.role ?? "untyped"} | ${Math.round(noteBEvidence.ageDays)}d old | rel: ${noteBEvidence.relatedCount} | supersedes: ${noteBEvidence.supersededCount ?? 0} | risk: ${noteBEvidence.mergeRisk}`);
+                    if (groupWarnings.length > 0) {
+                        lines.push(`   Warnings: ${groupWarnings.join("; ")}`);
+                    }
+                    lines.push(`   Merge risk: ${pairRisk}`);
+                }
                 lines.push("");
                 checked.add(entryA.note.id);
                 checked.add(entryB.note.id);
@@ -4391,6 +4541,15 @@ async function detectDuplicates(entries, threshold, project) {
                     noteB: { id: entryB.note.id, title: entryB.note.title },
                     similarity,
                 });
+                if (evidence) {
+                    duplicatePairs.push({
+                        similarity,
+                        noteA: noteAEvidence,
+                        noteB: noteBEvidence,
+                        warnings: groupWarnings.length > 0 ? groupWarnings : undefined,
+                        mergeRisk: pairRisk,
+                    });
+                }
             }
         }
     }
@@ -4407,6 +4566,7 @@ async function detectDuplicates(entries, threshold, project) {
         project: toProjectRef(project),
         notesProcessed: entries.length,
         notesModified: 0,
+        duplicatePairs: evidence ? duplicatePairs : undefined,
     };
     return { content: [{ type: "text", text: lines.join("\n") }], structuredContent };
 }
@@ -4499,7 +4659,7 @@ function findClusters(entries, project) {
     };
     return { content: [{ type: "text", text: lines.join("\n") }], structuredContent };
 }
-async function suggestMerges(entries, threshold, defaultConsolidationMode, project, explicitMode) {
+async function suggestMerges(entries, threshold, defaultConsolidationMode, project, explicitMode, evidence = false) {
     const lines = [];
     const modeLabel = explicitMode ?? `${defaultConsolidationMode} (project/default; all-temporary merges auto-delete)`;
     lines.push(`Merge suggestions for ${project?.name ?? "global"} (mode: ${modeLabel}):`);
@@ -4507,7 +4667,9 @@ async function suggestMerges(entries, threshold, defaultConsolidationMode, proje
     const checked = new Set();
     let suggestionCount = 0;
     const suggestions = [];
+    const mergeSuggestions = [];
     const embeddings = await loadEmbeddingsByNoteId(entries);
+    const allNotes = entries.map((entry) => entry.note);
     for (let i = 0; i < entries.length; i++) {
         const entryA = entries[i];
         if (checked.has(entryA.note.id))
@@ -4552,7 +4714,19 @@ async function suggestMerges(entries, threshold, defaultConsolidationMode, proje
                     }
                 }
             })();
+            const noteEvidence = sources.map((source) => buildConsolidateNoteEvidence(source.note, allNotes, entryA.note));
+            const mergeWarnings = buildGroupWarnings(sources.map((source) => source.note), entryA.note);
+            const mergeRisk = aggregateMergeRisk(noteEvidence.map((e) => e.mergeRisk));
             lines.push(`   Mode: ${effectiveMode} (${modeDescription})`);
+            if (evidence) {
+                for (const note of noteEvidence) {
+                    lines.push(`   Evidence: ${note.title} | ${note.lifecycle}, ${note.role ?? "untyped"} | ${Math.round(note.ageDays)}d | rel:${note.relatedCount} | risk:${note.mergeRisk}`);
+                }
+                if (mergeWarnings.length > 0) {
+                    lines.push(`   Warnings: ${mergeWarnings.join("; ")}`);
+                }
+                lines.push(`   Merge risk: ${mergeRisk}`);
+            }
             lines.push("   To execute:");
             lines.push(`     consolidate({ strategy: "execute-merge", mergePlan: {`);
             lines.push(`       sourceIds: [${sources.map((s) => `"${s.note.id}"`).join(", ")}],`);
@@ -4564,6 +4738,16 @@ async function suggestMerges(entries, threshold, defaultConsolidationMode, proje
                 sourceIds: sources.map((s) => s.note.id),
                 similarities: similar.map((s) => ({ id: s.entry.note.id, similarity: s.similarity })),
             });
+            if (evidence) {
+                mergeSuggestions.push({
+                    targetTitle: `${entryA.note.title} (consolidated)`,
+                    sourceIds: sources.map((source) => source.note.id),
+                    mode: effectiveMode,
+                    notes: noteEvidence,
+                    warnings: mergeWarnings.length > 0 ? mergeWarnings : undefined,
+                    mergeRisk,
+                });
+            }
             checked.add(entryA.note.id);
             for (const s of similar)
                 checked.add(s.entry.note.id);
@@ -4581,6 +4765,7 @@ async function suggestMerges(entries, threshold, defaultConsolidationMode, proje
         project: toProjectRef(project),
         notesProcessed: entries.length,
         notesModified: 0,
+        mergeSuggestions: evidence ? mergeSuggestions : undefined,
     };
     return { content: [{ type: "text", text: lines.join("\n") }], structuredContent };
 }
@@ -4594,7 +4779,7 @@ async function loadEmbeddingsByNoteId(entries) {
     }));
     return embeddings;
 }
-async function executeMerge(entries, mergePlan, defaultConsolidationMode, project, cwd, explicitMode, policy, allowProtectedBranch = false) {
+async function executeMerge(entries, mergePlan, defaultConsolidationMode, project, cwd, explicitMode, policy, allowProtectedBranch = false, evidence = true) {
     const sourceIds = normalizeMergePlanSourceIds(mergePlan.sourceIds);
     const targetTitle = mergePlan.targetTitle.trim();
     const { content: customContent, description, summary, tags } = mergePlan;
@@ -4872,12 +5057,33 @@ async function executeMerge(entries, mergePlan, defaultConsolidationMode, projec
             throw new Error(`Unknown consolidation mode: ${_exhaustive}`);
         }
     }
+    let executeMergeEvidence;
+    if (evidence) {
+        const allNotes = entries.map((entry) => entry.note);
+        const noteEvidence = sourceEntries.map((entry) => buildConsolidateNoteEvidence(entry.note, allNotes, sourceEntries[0]?.note));
+        const mergeWarnings = buildGroupWarnings(sourceEntries.map((entry) => entry.note), sourceEntries[0]?.note);
+        const mergeRisk = aggregateMergeRisk(noteEvidence.map((e) => e.mergeRisk));
+        lines.push("  Evidence:");
+        for (const note of noteEvidence) {
+            lines.push(`    ${note.title} | ${note.lifecycle}, ${note.role ?? "untyped"} | ${Math.round(note.ageDays)}d | rel:${note.relatedCount} | risk:${note.mergeRisk}`);
+        }
+        if (mergeWarnings.length > 0) {
+            lines.push(`  Warnings: ${mergeWarnings.join("; ")}`);
+        }
+        lines.push(`  Merge risk: ${mergeRisk}`);
+        executeMergeEvidence = {
+            notes: noteEvidence,
+            warnings: mergeWarnings.length > 0 ? mergeWarnings : undefined,
+            mergeRisk,
+        };
+    }
     const structuredContent = {
         action: "consolidated",
         strategy: "execute-merge",
         project: toProjectRef(project),
         notesProcessed: entries.length,
         notesModified: vaultChanges.size,
+        executeMergeEvidence,
         persistence,
         retry,
     };
@@ -5038,14 +5244,14 @@ async function pruneSuperseded(entries, consolidationMode, project, cwd, policy,
     };
     return { content: [{ type: "text", text: lines.join("\n") }], structuredContent };
 }
-async function dryRunAll(entries, threshold, defaultConsolidationMode, project, explicitMode) {
+async function dryRunAll(entries, threshold, defaultConsolidationMode, project, explicitMode, evidence = false) {
     const lines = [];
     lines.push(`Consolidation analysis for ${project?.name ?? "global"}:`);
     const modeLabel = explicitMode ?? `${defaultConsolidationMode} (project/default; all-temporary merges auto-delete)`;
     lines.push(`Mode: ${modeLabel} | Threshold: ${threshold}`);
     lines.push("");
     // Run all analysis strategies
-    const dupes = await detectDuplicates(entries, threshold, project);
+    const dupes = await detectDuplicates(entries, threshold, project, evidence);
     lines.push("=== DUPLICATE DETECTION ===");
     lines.push(dupes.content[0]?.text ?? "No output");
     lines.push("");
@@ -5053,7 +5259,7 @@ async function dryRunAll(entries, threshold, defaultConsolidationMode, project,
     lines.push("=== CLUSTER ANALYSIS ===");
     lines.push(clusters.content[0]?.text ?? "No output");
     lines.push("");
-    const merges = await suggestMerges(entries, threshold, defaultConsolidationMode, project, explicitMode);
+    const merges = await suggestMerges(entries, threshold, defaultConsolidationMode, project, explicitMode, evidence);
     lines.push("=== MERGE SUGGESTIONS ===");
     lines.push(merges.content[0]?.text ?? "No output");
     const structuredContent = {
@@ -5062,6 +5268,10 @@ async function dryRunAll(entries, threshold, defaultConsolidationMode, project,
         project: toProjectRef(project),
         notesProcessed: entries.length,
         notesModified: 0,
+        duplicatePairs: dupes.structuredContent.duplicatePairs,
+        mergeSuggestions: merges.structuredContent.mergeSuggestions,
+        themeGroups: clusters.structuredContent.themeGroups,
+        relationshipClusters: clusters.structuredContent.relationshipClusters,
     };
     return { content: [{ type: "text", text: lines.join("\n") }], structuredContent };
 }
@@ -5104,6 +5314,7 @@ server.registerPrompt("mnemonic-workflow-hint", {
                     "- When unsure, prefer `recall` over `remember`.\n" +
                     "- For repo-related tasks, pass `cwd` so mnemonic can route project memories correctly.\n\n" +
                     "Workflow: `recall`/`list` -> `get` -> `update` or `remember` -> `relate`/`consolidate`/`move_memory`. Use `discover_tags` only when tag choice is ambiguous.\n\n" +
+                    "When a merge/prune decision is uncertain, use optional evidence enrichment: `recall` with `evidence: \"compact\"` and `consolidate` analysis strategies with `evidence: true`. Evidence improves confidence but is not required.\n\n" +
                     "Roles are optional prioritization hints, not schema. Lifecycle still governs durability. When `lifecycle` is omitted, `remember` applies soft defaults based on role: `research`, `plan`, and `review` default to `temporary`; `decision`, `summary`, and `reference` default to `permanent`. Explicit `lifecycle` always overrides the role-based default. Inferred roles are internal hints only. Prioritization is language-independent by default.\n\n" +
                     "### Working-state continuity\n\n" +
                     "Preserve in-progress work as temporary notes when continuation value is high. Recovery happens after project orientation.\n\n" +
@@ -5144,6 +5355,8 @@ server.registerPrompt("mnemonic-workflow-hint", {
                     "- Existing bug note found by `recall` -> inspect with `get` -> refine with `update`.\n" +
                     "- No matching note found by `recall` -> optional `discover_tags` with note context -> create with `remember`.\n" +
                     "- Two notes overlap heavily -> inspect -> clean up with `consolidate`.\n" +
+                    "- Unsure why a recall hit ranked high -> rerun `recall` with `evidence: \"compact\"`.\n" +
+                    "- Unsure whether to merge/prune -> run `consolidate` analysis with `evidence: true` before `execute-merge` or `prune-superseded`.\n" +
                     "- Resume work: `project_memory_summary` -> `recall` (lifecycle: temporary) -> continue from temporary notes.\n\n" +
                     "### semanticPatch format\n\n" +
                     "When using `update` with `semanticPatch`:\n" +