@danielmarbach/mnemonic-mcp 0.16.0 → 0.18.0

package/build/index.js

@@ -9,13 +9,15 @@ import { NOTE_LIFECYCLES } from "./storage.js";
 import { embed, cosineSimilarity, embedModel } from "./embeddings.js";
 import { buildTemporalHistoryEntry, computeConfidence, getNoteProvenance } from "./provenance.js";
 import { getOrBuildProjection } from "./projections.js";
+import { invalidateActiveProjectCache, getOrBuildVaultEmbeddings, getOrBuildVaultNoteList, getSessionCachedNote, } from "./cache.js";
+import { performance } from "perf_hooks";
 import { filterRelationships, mergeRelationshipsFromNotes, normalizeMergePlanSourceIds, resolveEffectiveConsolidationMode, } from "./consolidate.js";
 import { selectRecallResults } from "./recall.js";
 import { getRelationshipPreview } from "./relationships.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, withinThemeScore, anchorScore, buildThemeCache, computeConnectionDiversity, } from "./project-introspection.js";
+import { classifyTheme, classifyThemeWithGraduation, computeThemesWithGraduation, 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";
@@ -360,6 +362,8 @@ async function ensureBranchSynced(cwd) {
     }
     const mainBackfill = await backfillEmbeddingsAfterSync(vaultManager.main.storage, "main vault", [], true);
     console.error(`[branch] Main vault embedded ${mainBackfill.embedded} notes`);
+    // Vault contents changed — discard session cache so next access rebuilds from fresh state
+    invalidateActiveProjectCache();
     return true;
 }
 function formatProjectIdentityText(identity) {
@@ -689,9 +693,22 @@ function buildMutationRetryContract(args) {
     if (args.commit.status !== "failed") {
         return undefined;
     }
+    const recoveryKind = args.preferredRecovery ?? (args.mutationApplied
+        ? "manual-exact-git-recovery"
+        : "no-manual-recovery");
+    const recoveryReason = recoveryKind === "rerun-tool-call-serial"
+        ? "Tool-level reconciliation exists for this mutation; rerun the same tool call serially for the affected vault."
+        : recoveryKind === "manual-exact-git-recovery"
+            ? "Mutation is already persisted on disk; manual git recovery is allowed only with the exact attemptedCommit values."
+            : "Mutation was not applied deterministically; manual git recovery is not authorized.";
     return {
+        recovery: {
+            kind: recoveryKind,
+            allowed: recoveryKind !== "no-manual-recovery",
+            reason: recoveryReason,
+        },
         attemptedCommit: {
-            message: args.commitMessage,
+            subject: args.commitMessage,
             body: args.commitBody,
             files: args.files,
             cwd: args.cwd,
@@ -704,19 +721,69 @@ function buildMutationRetryContract(args) {
         rationale: args.mutationApplied
             ? "Mutation is already persisted on disk; commit can be retried deterministically."
             : "Mutation was not applied; retry may require re-running the operation.",
+        instructions: {
+            sourceOfTruth: recoveryKind === "manual-exact-git-recovery" ? "attemptedCommit" : "tool-response",
+            useExactSubject: recoveryKind === "manual-exact-git-recovery",
+            useExactBody: recoveryKind === "manual-exact-git-recovery",
+            useExactFiles: recoveryKind === "manual-exact-git-recovery",
+            forbidInferenceFromHistory: true,
+            forbidInferenceFromTitleOrSummary: true,
+            forbidParallelSameVaultRetries: true,
+            preferToolReconciliation: recoveryKind === "rerun-tool-call-serial",
+            rerunSameToolCallSerially: recoveryKind === "rerun-tool-call-serial",
+        },
     };
 }
 function formatRetrySummary(retry) {
     if (!retry) {
         return undefined;
     }
-    const safety = retry.retrySafe ? "safe" : "requires review";
     const opLabel = retry.attemptedCommit.operation === "add" ? "add" : "commit";
     const error = retry.attemptedCommit.error;
-    return [
-        `Retry: ${safety} | vault=${retry.attemptedCommit.vault} | files=${retry.attemptedCommit.files.length}`,
-        `Git ${opLabel} error: ${error}`,
-    ].join("\n");
+    const lines = [];
+    switch (retry.recovery.kind) {
+        case "rerun-tool-call-serial":
+            lines.push("Recovery: rerun same tool call serially");
+            lines.push(retry.recovery.reason);
+            lines.push("Rerun the same mnemonic tool call one time for the affected vault.");
+            lines.push("Do not replay same-vault mutations in parallel.");
+            lines.push("Manual git recovery is not authorized for this failure.");
+            lines.push("Git failure:");
+            lines.push(`${opLabel}: ${error}`);
+            break;
+        case "manual-exact-git-recovery":
+            lines.push("Recovery: manual exact git recovery allowed");
+            lines.push(retry.recovery.reason);
+            lines.push("Use only the exact values below. Do not infer from git history, note title, summary, or repo state.");
+            lines.push("");
+            lines.push("Commit subject:");
+            lines.push(retry.attemptedCommit.subject);
+            if (retry.attemptedCommit.body) {
+                lines.push("");
+                lines.push("Commit body:");
+                lines.push(retry.attemptedCommit.body);
+            }
+            lines.push("");
+            lines.push("Files:");
+            for (const file of retry.attemptedCommit.files) {
+                lines.push(`- ${file}`);
+            }
+            lines.push("");
+            lines.push("Git failure:");
+            lines.push(`${opLabel}: ${error}`);
+            break;
+        case "no-manual-recovery":
+            lines.push("Recovery: no manual recovery authorized");
+            lines.push(retry.recovery.reason);
+            lines.push("Git failure:");
+            lines.push(`${opLabel}: ${error}`);
+            break;
+        default: {
+            const _exhaustive = retry.recovery.kind;
+            throw new Error(`Unknown recovery kind: ${_exhaustive}`);
+        }
+    }
+    return lines.join("\n");
 }
 function formatPersistenceSummary(persistence) {
     const parts = [
@@ -727,14 +794,14 @@ function formatPersistenceSummary(persistence) {
     if (persistence.embedding.reason) {
         lines[0] += ` | embedding reason=${persistence.embedding.reason}`;
     }
-    if (persistence.git.commit === "failed" && persistence.git.commitError) {
+    const retrySummary = formatRetrySummary(persistence.retry);
+    if (!retrySummary && persistence.git.commit === "failed" && persistence.git.commitError) {
         const opLabel = persistence.git.commitOperation === "add" ? "add" : "commit";
         lines.push(`Git ${opLabel} error: ${persistence.git.commitError}`);
     }
     if (persistence.git.push === "failed" && persistence.git.pushError) {
         lines.push(`Git push error: ${persistence.git.pushError}`);
     }
-    const retrySummary = formatRetrySummary(persistence.retry);
     if (retrySummary) {
         lines.push(retrySummary);
     }
@@ -782,7 +849,7 @@ function vaultMatchesStorageScope(vault, storedIn) {
     // "project-vault" covers the primary project vault and all submodule vaults.
     return vault.isProject;
 }
-async function collectVisibleNotes(cwd, scope = "all", tags, storedIn = "any") {
+async function collectVisibleNotes(cwd, scope = "all", tags, storedIn = "any", sessionProjectId) {
     const project = await resolveProject(cwd);
     const vaults = await vaultManager.searchOrder(cwd);
     let filterProject = undefined;
@@ -793,8 +860,23 @@ async function collectVisibleNotes(cwd, scope = "all", tags, storedIn = "any") {
     const seen = new Set();
     const entries = [];
     for (const vault of vaults) {
-        const vaultNotes = await vault.storage.listNotes(filterProject !== undefined ? { project: filterProject } : undefined);
-        for (const note of vaultNotes) {
+        let rawNotes;
+        if (sessionProjectId) {
+            const cached = await getOrBuildVaultNoteList(sessionProjectId, vault);
+            if (cached !== undefined) {
+                // Apply project filter on the full cached list
+                rawNotes = filterProject !== undefined
+                    ? cached.filter((n) => filterProject === null ? !n.project : n.project === filterProject)
+                    : cached;
+            }
+            else {
+                rawNotes = await vault.storage.listNotes(filterProject !== undefined ? { project: filterProject } : undefined);
+            }
+        }
+        else {
+            rawNotes = await vault.storage.listNotes(filterProject !== undefined ? { project: filterProject } : undefined);
+        }
+        for (const note of rawNotes) {
             if (seen.has(note.id)) {
                 continue;
             }
@@ -950,6 +1032,7 @@ server.registerTool("detect_project", {
         "- Use `recall` or `project_memory_summary` to orient on existing memory.",
     annotations: {
         readOnlyHint: true,
+        destructiveHint: false,
         idempotentHint: true,
         openWorldHint: false,
     },
@@ -1004,6 +1087,7 @@ server.registerTool("get_project_identity", {
         "- Use `set_project_identity` only if the wrong remote is defining identity.",
     annotations: {
         readOnlyHint: true,
+        destructiveHint: false,
         idempotentHint: true,
         openWorldHint: false,
     },
@@ -1160,6 +1244,7 @@ server.registerTool("list_migrations", {
         "- Run `execute_migration` with `dryRun: true` first.",
     annotations: {
         readOnlyHint: true,
+        destructiveHint: false,
         idempotentHint: true,
         openWorldHint: false,
     },
@@ -1442,6 +1527,7 @@ server.registerTool("remember", {
         timestamp: now,
         persistence,
     };
+    invalidateActiveProjectCache();
     return {
         content: [{ type: "text", text: textContent }],
         structuredContent,
@@ -1580,6 +1666,7 @@ server.registerTool("get_project_memory_policy", {
         "- Call `remember` with explicit `scope` for a one-off override, or `set_project_memory_policy` to change defaults.",
     annotations: {
         readOnlyHint: true,
+        destructiveHint: false,
         idempotentHint: true,
         openWorldHint: false,
     },
@@ -1653,6 +1740,7 @@ server.registerTool("recall", {
         "- Use `get`, `update`, `relate`, or `consolidate` based on the results.",
     annotations: {
         readOnlyHint: true,
+        destructiveHint: false,
         idempotentHint: true,
         openWorldHint: true,
     },
@@ -1674,6 +1762,7 @@ server.registerTool("recall", {
     }),
     outputSchema: RecallResultSchema,
 }, async ({ query, cwd, limit, minSimilarity, mode, verbose, tags, scope }) => {
+    const t0Recall = performance.now();
     await ensureBranchSynced(cwd);
     const project = await resolveProject(cwd);
     const queryVec = await embed(query);
@@ -1681,6 +1770,12 @@ server.registerTool("recall", {
     const noteCache = new Map();
     const noteCacheKey = (vault, id) => `${vault.storage.vaultPath}::${id}`;
     const readCachedNote = async (vault, id) => {
+        // Check session cache first (populated when getOrBuildVaultEmbeddings was called)
+        if (project) {
+            const sessionNote = getSessionCachedNote(project.id, vault.storage.vaultPath, id);
+            if (sessionNote !== undefined)
+                return sessionNote;
+        }
         const key = noteCacheKey(vault, id);
         const cached = noteCache.get(key);
         if (cached) {
@@ -1697,7 +1792,9 @@ server.registerTool("recall", {
     }
     const scored = [];
     for (const vault of vaults) {
-        const embeddings = await vault.storage.listEmbeddings();
+        const embeddings = project
+            ? (await getOrBuildVaultEmbeddings(project.id, vault)) ?? await vault.storage.listEmbeddings()
+            : await vault.storage.listEmbeddings();
         for (const rec of embeddings) {
             const rawScore = cosineSimilarity(queryVec, rec.embedding);
             if (rawScore < minSimilarity)
@@ -1792,6 +1889,7 @@ server.registerTool("recall", {
         scope: scope || "all",
         results: structuredResults,
     };
+    console.error(`[recall:timing] ${(performance.now() - t0Recall).toFixed(1)}ms`);
     return {
         content: [{ type: "text", text: textContent }],
         structuredContent,
@@ -1942,6 +2040,7 @@ server.registerTool("update", {
         lifecycle: updated.lifecycle,
         persistence,
     };
+    invalidateActiveProjectCache();
     return { content: [{ type: "text", text: `Updated memory '${id}'\n${formatPersistenceSummary(persistence)}` }], structuredContent };
 });
 // ── forget ────────────────────────────────────────────────────────────────────
@@ -2048,6 +2147,7 @@ server.registerTool("forget", {
         retry,
     };
     const retrySummary = formatRetrySummary(retry);
+    invalidateActiveProjectCache();
     return {
         content: [{
                 type: "text",
@@ -2075,6 +2175,7 @@ server.registerTool("get", {
         "- Use `update`, `forget`, `move_memory`, or `relate` after inspection.",
     annotations: {
         readOnlyHint: true,
+        destructiveHint: false,
         idempotentHint: true,
         openWorldHint: false,
     },
@@ -2085,12 +2186,26 @@ server.registerTool("get", {
     }),
     outputSchema: GetResultSchema,
 }, async ({ ids, cwd, includeRelationships }) => {
+    const t0Get = performance.now();
     await ensureBranchSynced(cwd);
     const project = await resolveProject(cwd);
     const found = [];
     const notFound = [];
     for (const id of ids) {
-        const result = await vaultManager.findNote(id, cwd);
+        // Check session cache before hitting storage
+        let result = null;
+        if (project) {
+            for (const vault of vaultManager.allKnownVaults()) {
+                const cached = getSessionCachedNote(project.id, vault.storage.vaultPath, id);
+                if (cached !== undefined) {
+                    result = { note: cached, vault };
+                    break;
+                }
+            }
+        }
+        if (!result) {
+            result = await vaultManager.findNote(id, cwd);
+        }
         if (!result) {
             notFound.push(id);
             continue;
@@ -2138,6 +2253,7 @@ server.registerTool("get", {
         notes: found,
         notFound,
     };
+    console.error(`[get:timing] ${(performance.now() - t0Get).toFixed(1)}ms`);
     return { content: [{ type: "text", text: lines.join("\n").trim() }], structuredContent };
 });
 // ── where_is_memory ───────────────────────────────────────────────────────────
@@ -2157,6 +2273,7 @@ server.registerTool("where_is_memory", {
         "- Use `move_memory` if the storage location is wrong, or `get` for full inspection.",
     annotations: {
         readOnlyHint: true,
+        destructiveHint: false,
         idempotentHint: true,
         openWorldHint: false,
     },
@@ -2213,6 +2330,7 @@ server.registerTool("list", {
         "- Use `get` for exact inspection or `update` / `consolidate` for cleanup.",
     annotations: {
         readOnlyHint: true,
+        destructiveHint: false,
         idempotentHint: true,
         openWorldHint: false,
     },
@@ -2323,6 +2441,7 @@ server.registerTool("discover_tags", {
         "Read-only.",
     annotations: {
         readOnlyHint: true,
+        destructiveHint: false,
         idempotentHint: true,
         openWorldHint: false,
     },
@@ -2529,6 +2648,7 @@ server.registerTool("recent_memories", {
         "- Use `get` for exact inspection or `update` to continue refining a recent note.",
     annotations: {
         readOnlyHint: true,
+        destructiveHint: false,
         idempotentHint: true,
         openWorldHint: false,
     },
@@ -2598,6 +2718,7 @@ server.registerTool("memory_graph", {
         "- Use `get`, `relate`, `unrelate`, or `consolidate` based on what the graph reveals.",
     annotations: {
         readOnlyHint: true,
+        destructiveHint: false,
         idempotentHint: true,
         openWorldHint: false,
     },
@@ -2677,6 +2798,7 @@ server.registerTool("project_memory_summary", {
         "- Use `recall` or `list` to drill down into specific areas.",
     annotations: {
         readOnlyHint: true,
+        destructiveHint: false,
         idempotentHint: true,
         openWorldHint: false,
     },
@@ -2690,8 +2812,11 @@ server.registerTool("project_memory_summary", {
     }),
     outputSchema: ProjectSummaryResultSchema,
 }, async ({ cwd, maxPerTheme, recentLimit, anchorLimit, includeRelatedGlobal, relatedGlobalLimit }) => {
+    const t0Summary = performance.now();
     await ensureBranchSynced(cwd);
-    const { project, entries } = await collectVisibleNotes(cwd, "all");
+    // Pre-resolve project so we can pass its id to collectVisibleNotes for session caching
+    const preProject = await resolveProject(cwd);
+    const { project, entries } = await collectVisibleNotes(cwd, "all", undefined, "any", preProject?.id);
     if (!project) {
         return { content: [{ type: "text", text: `Could not detect a project for: ${cwd}` }], isError: true };
     }
@@ -2715,17 +2840,23 @@ server.registerTool("project_memory_summary", {
     }
     const policyLine = await formatProjectPolicyLine(project.id);
     // Build theme cache for connection diversity scoring (project-scoped only)
+    // This uses simple classifyTheme for consistent diversity calculations
     const themeCache = buildThemeCache(projectEntries.map(e => e.note));
-    // Categorize by theme (project-scoped only)
+    // Compute promoted themes from keywords (graduation system)
+    const graduationResult = computeThemesWithGraduation(projectEntries.map(e => e.note));
+    const promotedThemes = new Set(graduationResult.promotedThemes);
+    // Categorize by theme with graduation (project-scoped only)
     const themed = new Map();
     for (const entry of projectEntries) {
-        const theme = classifyTheme(entry.note);
+        const theme = classifyThemeWithGraduation(entry.note, promotedThemes);
         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"];
+    // Theme order: fixed themes first, then promoted themes alphabetically, then "other"
+    const fixedThemes = ["overview", "decisions", "tooling", "bugs", "architecture", "quality"];
+    const dynamicThemes = graduationResult.promotedThemes.filter(t => !fixedThemes.includes(t));
+    const themeOrder = [...fixedThemes, ...dynamicThemes.sort(), "other"];
     // Calculate notes distribution (project-scoped only)
     const projectVaultCount = projectEntries.filter(e => e.vault.isProject).length;
     const mainVaultProjectEntries = projectEntries.filter(e => !e.vault.isProject);
@@ -3001,12 +3132,13 @@ server.registerTool("project_memory_summary", {
             id: e.note.id,
             title: e.note.title,
             updatedAt: e.note.updatedAt,
-            theme: classifyTheme(e.note),
+            theme: classifyThemeWithGraduation(e.note, promotedThemes),
         })),
         anchors,
         orientation,
         relatedGlobal,
     };
+    console.error(`[summary:timing] ${(performance.now() - t0Summary).toFixed(1)}ms`);
     return { content: [{ type: "text", text: sections.join("\n") }], structuredContent };
 });
 // ── sync ──────────────────────────────────────────────────────────────────────
@@ -3093,6 +3225,8 @@ server.registerTool("sync", {
         action: "synced",
         vaults: vaultResults,
     };
+    // Vault contents may have changed via pull — discard session cache
+    invalidateActiveProjectCache();
     return { content: [{ type: "text", text: lines.join("\n") }], structuredContent };
 });
 // ── move_memory ───────────────────────────────────────────────────────────────
@@ -3244,6 +3378,7 @@ server.registerTool("move_memory", {
     const associationText = metadataRewritten
         ? `Project association is now ${associationValue}.`
         : `Project association remains ${associationValue}.`;
+    invalidateActiveProjectCache();
     return {
         content: [{
                 type: "text",
@@ -3349,6 +3484,7 @@ server.registerTool("relate", {
                     cwd,
                     vault,
                     mutationApplied: true,
+                    preferredRecovery: "rerun-tool-call-serial",
                 });
                 const structuredContent = {
                     action: "related",
@@ -3398,6 +3534,7 @@ server.registerTool("relate", {
                 cwd,
                 vault,
                 mutationApplied: true,
+                preferredRecovery: "rerun-tool-call-serial",
             });
         }
         if (commitStatus.status === "committed") {
@@ -3416,6 +3553,7 @@ server.registerTool("relate", {
         retry,
     };
     const retrySummary = formatRetrySummary(retry);
+    invalidateActiveProjectCache();
     return {
         content: [{
                 type: "text",
@@ -3519,6 +3657,7 @@ server.registerTool("unrelate", {
                     cwd,
                     vault,
                     mutationApplied: true,
+                    preferredRecovery: "rerun-tool-call-serial",
                 });
                 const structuredContent = {
                     action: "unrelated",
@@ -3562,6 +3701,7 @@ server.registerTool("unrelate", {
                 cwd,
                 vault,
                 mutationApplied: true,
+                preferredRecovery: "rerun-tool-call-serial",
             });
         }
         if (commitStatus.status === "committed") {
@@ -3582,6 +3722,7 @@ server.registerTool("unrelate", {
         retry,
     };
     const retrySummary = formatRetrySummary(retry);
+    invalidateActiveProjectCache();
     return {
         content: [{
                 type: "text",
@@ -3680,13 +3821,19 @@ server.registerTool("consolidate", {
             return findClusters(projectNotes, project);
         case "suggest-merges":
             return suggestMerges(projectNotes, threshold, defaultConsolidationMode, project, mode);
-        case "execute-merge":
+        case "execute-merge": {
             if (!mergePlan) {
                 return { content: [{ type: "text", text: "execute-merge strategy requires a mergePlan with sourceIds and targetTitle." }], isError: true };
             }
-            return executeMerge(entries, mergePlan, defaultConsolidationMode, project, cwd, mode, policy, allowProtectedBranch);
-        case "prune-superseded":
-            return pruneSuperseded(projectNotes, mode ?? defaultConsolidationMode, project, cwd, policy, allowProtectedBranch);
+            const mergeResult = await executeMerge(entries, mergePlan, defaultConsolidationMode, project, cwd, mode, policy, allowProtectedBranch);
+            invalidateActiveProjectCache();
+            return mergeResult;
+        }
+        case "prune-superseded": {
+            const pruneResult = await pruneSuperseded(projectNotes, mode ?? defaultConsolidationMode, project, cwd, policy, allowProtectedBranch);
+            invalidateActiveProjectCache();
+            return pruneResult;
+        }
         case "dry-run":
             return dryRunAll(projectNotes, threshold, defaultConsolidationMode, project, mode);
         default: