@danielmarbach/mnemonic-mcp 0.13.1 → 0.14.0

package/build/index.js

@@ -7,12 +7,13 @@ import path from "path";
 import { promises as fs } from "fs";
 import { NOTE_LIFECYCLES } from "./storage.js";
 import { embed, cosineSimilarity, embedModel } from "./embeddings.js";
+import { buildTemporalHistoryEntry, computeConfidence, getNoteProvenance } from "./provenance.js";
 import { filterRelationships, mergeRelationshipsFromNotes, normalizeMergePlanSourceIds, resolveEffectiveConsolidationMode, } from "./consolidate.js";
 import { selectRecallResults } from "./recall.js";
 import { cleanMarkdown } from "./markdown.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, summarizePreview, titleCaseTheme } from "./project-introspection.js";
+import { classifyTheme, summarizePreview, titleCaseTheme, withinThemeScore, anchorScore, buildThemeCache, computeConnectionDiversity, } from "./project-introspection.js";
 import { detectProject, getCurrentGitBranch, resolveProjectIdentity } from "./project.js";
 import { VaultManager } from "./vault.js";
 import { checkBranchChange } from "./branch-tracker.js";
@@ -276,6 +277,8 @@ const VAULT_PATH = process.env["VAULT_PATH"]
     : defaultVaultPath();
 const DEFAULT_RECALL_LIMIT = 5;
 const DEFAULT_MIN_SIMILARITY = 0.3;
+const TEMPORAL_HISTORY_NOTE_LIMIT = 5;
+const TEMPORAL_HISTORY_COMMIT_LIMIT = 5;
 async function readPackageVersion() {
     const packageJsonPath = path.resolve(import.meta.dirname, "../package.json");
     const packageJson = JSON.parse(await fs.readFile(packageJsonPath, "utf8"));
@@ -389,6 +392,17 @@ function formatNote(note, score) {
         `**tags:** ${note.tags.join(", ") || "none"} | **${describeLifecycle(note.lifecycle)}** | **updated:** ${note.updatedAt}${relStr}\n\n` +
         note.content);
 }
+function formatTemporalHistory(history) {
+    if (history.length === 0) {
+        return "**history:** no git history found";
+    }
+    const lines = ["**history:**"];
+    for (const entry of history) {
+        const summary = entry.summary ? ` — ${entry.summary}` : "";
+        lines.push(`- \`${entry.commitHash.slice(0, 7)}\` ${entry.timestamp} — ${entry.message}${summary}`);
+    }
+    return lines.join("\n");
+}
 // ── Git commit message helpers ────────────────────────────────────────────────
 /**
  * Extract a short human-readable summary from note content.
@@ -1594,15 +1608,18 @@ server.registerTool("get_project_memory_policy", {
 server.registerTool("recall", {
     title: "Recall",
     description: "Semantic search over stored memories using embeddings.\n\n" +
+        "Supports opt-in temporal mode (`mode: \"temporal\"`) to enrich top semantic matches with compact git-backed history.\n\n" +
         "Use this when:\n" +
         "- You know the topic but not the exact memory id\n" +
         "- You are starting a session and want relevant prior context\n" +
-        "- You want to check whether a memory already exists before creating another one\n\n" +
+        "- You want to check whether a memory already exists before creating another one\n" +
+        "- You explicitly want to inspect how a note evolved over time\n\n" +
         "Do not use this when:\n" +
         "- You already know the exact id; use `get`\n" +
         "- You just want to browse by tags or scope; use `list`\n\n" +
         "Returns:\n" +
-        "- Ranked memory matches with scores, vault label, tags, lifecycle, and updated time\n\n" +
+        "- Ranked memory matches with scores, vault label, tags, lifecycle, and updated time\n" +
+        "- In temporal mode, optional compact history entries for top matches\n\n" +
         "Read-only.\n\n" +
         "Typical next step:\n" +
         "- Use `get`, `update`, `relate`, or `consolidate` based on the results.",
@@ -1616,6 +1633,8 @@ server.registerTool("recall", {
         cwd: projectParam,
         limit: z.number().int().min(1).max(20).optional().default(DEFAULT_RECALL_LIMIT),
         minSimilarity: z.number().min(0).max(1).optional().default(DEFAULT_MIN_SIMILARITY),
+        mode: z.enum(["default", "temporal"]).optional().default("default").describe("Temporal history is opt-in. Use `temporal` to enrich top semantic matches with compact git-backed history."),
+        verbose: z.boolean().optional().default(false).describe("Only meaningful with `mode: \"temporal\"`. Adds richer stats-based history context without returning raw diffs."),
         tags: z.array(z.string()).optional().describe("Filter results to notes with all of these tags."),
         scope: z
             .enum(["project", "global", "all"])
@@ -1626,7 +1645,7 @@ server.registerTool("recall", {
             "'all' = both, with project notes boosted (default)"),
     }),
     outputSchema: RecallResultSchema,
-}, async ({ query, cwd, limit, minSimilarity, tags, scope }) => {
+}, async ({ query, cwd, limit, minSimilarity, mode, verbose, tags, scope }) => {
     await ensureBranchSynced(cwd);
     const project = await resolveProject(cwd);
     const queryVec = await embed(query);
@@ -1687,10 +1706,27 @@ server.registerTool("recall", {
         : `Recall results (global):`;
     const sections = [];
     const structuredResults = [];
-    for (const { id, score, vault, boosted } of top) {
+    for (const [index, { id, score, vault, boosted }] of top.entries()) {
         const note = await readCachedNote(vault, id);
         if (note) {
-            sections.push(formatNote(note, score));
+            const centrality = note.relatedTo?.length ?? 0;
+            const filePath = `${vault.notesRelDir}/${id}.md`;
+            const provenance = await getNoteProvenance(vault.git, filePath);
+            const confidence = computeConfidence(note.lifecycle, note.updatedAt, centrality);
+            let history;
+            if (mode === "temporal") {
+                if (index < TEMPORAL_HISTORY_NOTE_LIMIT) {
+                    const commits = await vault.git.getFileHistory(filePath, TEMPORAL_HISTORY_COMMIT_LIMIT);
+                    history = await Promise.all(commits.map(async (commit) => {
+                        const stats = await vault.git.getCommitStats(filePath, commit.hash);
+                        return buildTemporalHistoryEntry(commit, stats, verbose);
+                    }));
+                }
+            }
+            const formattedHistory = mode === "temporal" && history !== undefined
+                ? `\n\n${formatTemporalHistory(history)}`
+                : "";
+            sections.push(`${formatNote(note, score)}${formattedHistory}`);
             structuredResults.push({
                 id,
                 title: note.title,
@@ -1702,6 +1738,9 @@ server.registerTool("recall", {
                 tags: note.tags,
                 lifecycle: note.lifecycle,
                 updatedAt: note.updatedAt,
+                provenance,
+                confidence,
+                history,
             });
         }
     }
@@ -2461,77 +2500,298 @@ server.registerTool("project_memory_summary", {
         cwd: z.string().describe("Absolute project working directory. Pass this whenever the task is project-related so routing, search boosting, policy, and vault selection work correctly."),
         maxPerTheme: z.number().int().min(1).max(5).optional().default(3),
         recentLimit: z.number().int().min(1).max(10).optional().default(5),
+        anchorLimit: z.number().int().min(1).max(10).optional().default(5),
+        includeRelatedGlobal: z.boolean().optional().default(false),
+        relatedGlobalLimit: z.number().int().min(1).max(5).optional().default(3),
     }),
     outputSchema: ProjectSummaryResultSchema,
-}, async ({ cwd, maxPerTheme, recentLimit }) => {
+}, async ({ cwd, maxPerTheme, recentLimit, anchorLimit, includeRelatedGlobal, relatedGlobalLimit }) => {
     await ensureBranchSynced(cwd);
     const { project, entries } = await collectVisibleNotes(cwd, "all");
     if (!project) {
         return { content: [{ type: "text", text: `Could not detect a project for: ${cwd}` }], isError: true };
     }
-    if (entries.length === 0) {
-        const structuredContent = { action: "project_summary_shown", project: { id: project.id, name: project.name }, notes: { total: 0, projectVault: 0, mainVault: 0, privateProject: 0 }, themes: {}, recent: [] };
+    // Separate project-scoped notes (for themes/anchors) from global notes
+    const projectEntries = entries.filter(e => e.note.project === project.id || e.vault.isProject);
+    // Empty-project case: no project-scoped notes exist
+    if (projectEntries.length === 0) {
+        const structuredContent = {
+            action: "project_summary_shown",
+            project: { id: project.id, name: project.name },
+            notes: { total: 0, projectVault: 0, mainVault: 0, privateProject: 0 },
+            themes: {},
+            recent: [],
+            anchors: [],
+            orientation: {
+                primaryEntry: { id: "", title: "No notes", rationale: "Empty project vault" },
+                suggestedNext: [],
+            },
+        };
         return { content: [{ type: "text", text: `No memories found for project ${project.name}.` }], structuredContent };
     }
     const policyLine = await formatProjectPolicyLine(project.id);
+    // Build theme cache for connection diversity scoring (project-scoped only)
+    const themeCache = buildThemeCache(projectEntries.map(e => e.note));
+    // Categorize by theme (project-scoped only)
     const themed = new Map();
-    for (const entry of entries) {
+    for (const entry of projectEntries) {
         const theme = classifyTheme(entry.note);
         const bucket = themed.get(theme) ?? [];
         bucket.push(entry);
         themed.set(theme, bucket);
     }
+    // Theme order for display
     const themeOrder = ["overview", "decisions", "tooling", "bugs", "architecture", "quality", "other"];
-    const projectVaultCount = entries.filter((entry) => entry.vault.isProject).length;
-    const mainVaultCount = entries.length - projectVaultCount;
+    // Calculate notes distribution (project-scoped only)
+    const projectVaultCount = projectEntries.filter(e => e.vault.isProject).length;
+    const mainVaultProjectEntries = projectEntries.filter(e => !e.vault.isProject);
+    const mainVaultCount = mainVaultProjectEntries.length;
+    const totalProjectNotes = projectEntries.length;
+    // Build output sections
     const sections = [];
     sections.push(`Project summary: **${project.name}**`);
     sections.push(`- id: \`${project.id}\``);
     sections.push(`- ${policyLine.replace(/^Policy:\s*/, "policy: ")}`);
-    sections.push(`- memories: ${entries.length} (project-vault: ${projectVaultCount}, main-vault: ${mainVaultCount})`);
-    const mainVaultProjectEntries = entries.filter((entry) => !entry.vault.isProject && entry.note.project === project.id);
+    sections.push(`- memories: ${totalProjectNotes} (project-vault: ${projectVaultCount}, main-vault: ${mainVaultCount})`);
     if (mainVaultProjectEntries.length > 0) {
         sections.push(`- private project memories: ${mainVaultProjectEntries.length}`);
     }
-    const themes = [];
+    const themes = {};
     for (const theme of themeOrder) {
         const bucket = themed.get(theme);
-        if (!bucket || bucket.length === 0) {
+        if (!bucket || bucket.length === 0)
             continue;
-        }
-        const top = bucket.slice(0, maxPerTheme);
+        // Sort by within-theme score
+        const sorted = [...bucket].sort((a, b) => withinThemeScore(b.note) - withinThemeScore(a.note));
+        const top = sorted.slice(0, maxPerTheme);
         sections.push(`\n${titleCaseTheme(theme)}:`);
-        sections.push(...top.map((entry) => `- ${entry.note.title} (\`${entry.note.id}\`)`));
-        themes.push({
-            name: theme,
+        sections.push(...top.map(e => `- ${e.note.title} (\`${e.note.id}\`)`));
+        themes[theme] = {
             count: bucket.length,
-            examples: top.map((entry) => entry.note.title),
-        });
+            examples: top.map(e => ({
+                id: e.note.id,
+                title: e.note.title,
+                updatedAt: e.note.updatedAt,
+            })),
+        };
     }
-    const recent = [...entries]
+    // Recent notes (project-scoped only)
+    const recent = [...projectEntries]
         .sort((a, b) => b.note.updatedAt.localeCompare(a.note.updatedAt))
         .slice(0, recentLimit);
-    sections.push(`\nRecent:`);
-    sections.push(...recent.map((entry) => `- ${entry.note.updatedAt} — ${entry.note.title}`));
-    const themeCounts = {};
-    for (const theme of themes) {
-        themeCounts[theme.name] = theme.count;
+    sections.push(`\nRecent activity (start here):`);
+    sections.push(...recent.map(e => `- ${e.note.updatedAt} — ${e.note.title}`));
+    // Anchor notes with diversity constraint (project-scoped only)
+    // Separate tagged anchors (can have no relationships) from scored anchors (need relationships)
+    const taggedAnchorEntries = projectEntries.filter(e => e.note.lifecycle === "permanent" &&
+        e.note.tags.some(t => t.toLowerCase() === "anchor" || t.toLowerCase() === "alwaysload"));
+    const scoredAnchorCandidates = projectEntries
+        .filter(e => e.note.lifecycle === "permanent" && (e.note.relatedTo?.length ?? 0) > 0)
+        .map(e => ({
+        entry: e,
+        score: anchorScore(e.note, themeCache),
+        theme: classifyTheme(e.note),
+    }))
+        .filter(x => x.score > -Infinity)
+        .sort((a, b) => b.score - a.score);
+    // Score tagged anchors too, so they can compete for primaryEntry
+    const scoredTaggedAnchors = taggedAnchorEntries
+        .map(e => ({
+        entry: e,
+        score: anchorScore(e.note, themeCache),
+        theme: classifyTheme(e.note),
+    }))
+        .sort((a, b) => b.score - a.score);
+    // Enforce max 2 per theme for scored anchors
+    const anchorThemeCounts = new Map();
+    const anchors = [];
+    const anchorIds = new Set();
+    // Add tagged anchors first (capped at 10 total across all themes), scored by anchorScore
+    for (const candidate of scoredTaggedAnchors.slice(0, 10)) {
+        if (anchors.length >= 10)
+            break;
+        anchors.push({
+            id: candidate.entry.note.id,
+            title: candidate.entry.note.title,
+            centrality: candidate.entry.note.relatedTo?.length ?? 0,
+            connectionDiversity: computeConnectionDiversity(candidate.entry.note, themeCache),
+            updatedAt: candidate.entry.note.updatedAt,
+        });
+        anchorIds.add(candidate.entry.note.id);
+    }
+    // Add scored anchors with theme diversity constraint
+    for (const candidate of scoredAnchorCandidates) {
+        if (anchors.length >= 10)
+            break;
+        if (anchorIds.has(candidate.entry.note.id))
+            continue;
+        const theme = candidate.theme;
+        const themeCount = anchorThemeCounts.get(theme) ?? 0;
+        if (themeCount >= 2)
+            continue;
+        anchors.push({
+            id: candidate.entry.note.id,
+            title: candidate.entry.note.title,
+            centrality: candidate.entry.note.relatedTo?.length ?? 0,
+            connectionDiversity: computeConnectionDiversity(candidate.entry.note, themeCache),
+            updatedAt: candidate.entry.note.updatedAt,
+        });
+        anchorIds.add(candidate.entry.note.id);
+        anchorThemeCounts.set(theme, themeCount + 1);
     }
+    if (anchors.length > 0) {
+        sections.push(`\nAnchors:`);
+        sections.push(...anchors.slice(0, 5).map(a => `- ${a.title} (\`${a.id}\`) — centrality: ${a.centrality}, diversity: ${a.connectionDiversity}`));
+    }
+    // Compute orientation after anchors are computed (for text output)
+    let relatedGlobal;
+    if (includeRelatedGlobal) {
+        const anchorEmbeddings = await Promise.all(anchors.slice(0, 5).map(async (a) => {
+            for (const vault of vaultManager.allKnownVaults()) {
+                const emb = await vault.storage.readEmbedding(a.id);
+                if (emb)
+                    return { id: a.id, embedding: emb.embedding };
+            }
+            return null;
+        }));
+        const validAnchors = anchorEmbeddings.filter((e) => e !== null);
+        if (validAnchors.length > 0) {
+            // Get global notes (not project-scoped)
+            const globalEntries = entries.filter(e => !e.note.project);
+            const globalCandidates = [];
+            for (const entry of globalEntries) {
+                const emb = await entry.vault.storage.readEmbedding(entry.note.id);
+                if (!emb)
+                    continue;
+                // Find max similarity to any anchor
+                let maxSim = 0;
+                for (const anchor of validAnchors) {
+                    const sim = cosineSimilarity(anchor.embedding, emb.embedding);
+                    if (sim > maxSim)
+                        maxSim = sim;
+                }
+                if (maxSim > 0.4) {
+                    globalCandidates.push({
+                        id: entry.note.id,
+                        title: entry.note.title,
+                        similarity: maxSim,
+                        preview: summarizePreview(entry.note.content, 100),
+                    });
+                }
+            }
+            globalCandidates.sort((a, b) => b.similarity - a.similarity);
+            if (globalCandidates.length > 0) {
+                relatedGlobal = {
+                    notes: globalCandidates.slice(0, relatedGlobalLimit),
+                    computedAt: new Date().toISOString(),
+                };
+                sections.push(`\nRelated Global:`);
+                sections.push(...relatedGlobal.notes.map(n => `- ${n.title} (\`${n.id}\`) — similarity: ${n.similarity.toFixed(2)}`));
+            }
+        }
+    }
+    // Compute orientation layer for actionable guidance
+    const primaryAnchor = anchors[0];
+    // Build noteId -> vault lookup for provenance enrichment
+    const noteVaultMap = new Map();
+    for (const entry of projectEntries) {
+        noteVaultMap.set(entry.note.id, entry.vault);
+    }
+    // Helper to enrich an anchor with provenance and confidence
+    const enrichOrientationNote = async (anchor) => {
+        const vault = noteVaultMap.get(anchor.id);
+        if (!vault)
+            return {};
+        const filePath = `${vault.notesRelDir}/${anchor.id}.md`;
+        const provenance = await getNoteProvenance(vault.git, filePath);
+        const confidence = computeConfidence("permanent", anchor.updatedAt, anchor.centrality);
+        return { provenance, confidence };
+    };
+    const primaryEnriched = primaryAnchor ? await enrichOrientationNote(primaryAnchor) : {};
+    const suggestedEnriched = await Promise.all(anchors.slice(1, 4).map(enrichOrientationNote));
+    // Enrich fallback primaryEntry when no anchors exist
+    let fallbackEnriched = {};
+    if (!primaryAnchor && recent[0]) {
+        const fallbackNote = recent[0].note;
+        const vault = noteVaultMap.get(fallbackNote.id);
+        if (vault) {
+            const filePath = `${vault.notesRelDir}/${fallbackNote.id}.md`;
+            const provenance = await getNoteProvenance(vault.git, filePath);
+            const confidence = computeConfidence(fallbackNote.lifecycle, fallbackNote.updatedAt, 0);
+            fallbackEnriched = { provenance, confidence };
+        }
+    }
+    const orientation = {
+        primaryEntry: primaryAnchor
+            ? {
+                id: primaryAnchor.id,
+                title: primaryAnchor.title,
+                rationale: `Centrality ${primaryAnchor.centrality}, connects ${primaryAnchor.connectionDiversity} themes`,
+                ...primaryEnriched,
+            }
+            : {
+                id: recent[0]?.note.id ?? projectEntries[0]?.note.id ?? "",
+                title: recent[0]?.note.title ?? projectEntries[0]?.note.title ?? "No notes",
+                rationale: recent[0]
+                    ? "Most recent note — no high-centrality anchors found"
+                    : "Only note available",
+                ...fallbackEnriched,
+            },
+        suggestedNext: anchors.slice(1, 4).map((a, i) => ({
+            id: a.id,
+            title: a.title,
+            rationale: `Centrality ${a.centrality}, connects ${a.connectionDiversity} themes`,
+            ...suggestedEnriched[i],
+        })),
+    };
+    // Warning for taxonomy dilution
+    const otherBucket = themed.get("other");
+    const otherCount = otherBucket?.length ?? 0;
+    const otherRatio = projectEntries.length > 0 ? otherCount / projectEntries.length : 0;
+    if (otherRatio > 0.3) {
+        orientation.warnings = [
+            `${Math.round(otherRatio * 100)}% of notes in "other" bucket — consider improving thematic classification`,
+        ];
+    }
+    // Orientation text output
+    sections.push(`\nOrientation:`);
+    sections.push(`Start with: ${orientation.primaryEntry.title} (\`${orientation.primaryEntry.id}\`)`);
+    sections.push(`  Rationale: ${orientation.primaryEntry.rationale}`);
+    if (orientation.primaryEntry.confidence) {
+        sections.push(`  Confidence: ${orientation.primaryEntry.confidence}`);
+    }
+    if (orientation.suggestedNext.length > 0) {
+        sections.push(`Then check:`);
+        for (const next of orientation.suggestedNext) {
+            sections.push(`  - ${next.title} (\`${next.id}\`) — ${next.rationale}${next.confidence ? ` [${next.confidence}]` : ""}`);
+        }
+    }
+    if (orientation.warnings && orientation.warnings.length > 0) {
+        sections.push(`Warnings:`);
+        for (const w of orientation.warnings) {
+            sections.push(`  - ${w}`);
+        }
+    }
+    // Related global notes (optional, anchor-based similarity)
     const structuredContent = {
         action: "project_summary_shown",
         project: { id: project.id, name: project.name },
         notes: {
-            total: entries.length,
+            total: totalProjectNotes,
             projectVault: projectVaultCount,
             mainVault: mainVaultCount,
             privateProject: mainVaultProjectEntries.length,
         },
-        themes: themeCounts,
-        recent: recent.map((entry) => ({
-            id: entry.note.id,
-            title: entry.note.title,
-            updatedAt: entry.note.updatedAt,
+        themes,
+        recent: recent.map(e => ({
+            id: e.note.id,
+            title: e.note.title,
+            updatedAt: e.note.updatedAt,
+            theme: classifyTheme(e.note),
         })),
+        anchors,
+        orientation,
+        relatedGlobal,
     };
     return { content: [{ type: "text", text: sections.join("\n") }], structuredContent };
 });