@danielmarbach/mnemonic-mcp 0.17.0 → 0.18.0

package/CHANGELOG.md

@@ -4,6 +4,23 @@ All notable changes to `mnemonic` will be documented in this file.
 
 The format is loosely based on Keep a Changelog and uses semver-style version headings.
 
+## [0.18.0] - 2026-03-27
+
+### Added
+
+- Theme graduation from "other": keywords appearing across multiple notes become named themes automatically.
+- Keyword extraction with synonym normalization for theme classification.
+- `analyzeThemeQuality()` utility for checking theme distribution metrics.
+
+### Changed
+
+- All 23 MCP tools now include complete SDK tool hints (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`). Previously, read-only tools were missing `destructiveHint: false`.
+- Mutating tool retry results now return explicit recovery guidance instead of vague `Retry: safe` text, including recovery kind and no-inference instructions for partial-persistence failures.
+- Recovery precedence is now encoded in retry metadata: deterministic tool reconciliation is preferred where available, and same-vault retries must be replayed serially.
+- Retry metadata now uses `attemptedCommit.subject` instead of `attemptedCommit.message`.
+- `classifyTheme` now uses keyword-based graduation in addition to tag matching.
+- `project_memory_summary` includes both fixed themes and dynamically promoted keywords.
+
 ## [0.17.0] - 2026-03-25
 
 ### Added

package/README.md

@@ -452,6 +452,18 @@ Imported notes are written to the main vault with `lifecycle: permanent` and `sc
 | `update`                    | Update note content/title/tags/lifecycle, re-embeds always               |
 | `where_is_memory`           | Show note's project association and storage location                     |
 
+### Theme emergence
+
+`project_memory_summary` categorizes notes by theme. Themes **emerge automatically** from your notes:
+
+- **Tag-based classification** — notes with matching tags (e.g., `["decisions"]`, `["bugs"]`) are grouped immediately
+- **Keyword graduation** — keywords that appear across multiple notes become named themes over time
+- **"other" bucket** — notes that don't match any theme are grouped here; this shrinks as themes emerge
+
+No predefined schema required. The system adapts to your project's vocabulary.
+
+**Language handling:** The system degrades gracefully for non-English notes. Stopwords and synonyms are optional English enhancements; keywords that don't match pass through unchanged, allowing non-English keywords to graduate if they meet frequency thresholds.
+
 ### Relationships
 
 Notes can be linked with typed edges stored in frontmatter:

package/build/index.js

@@ -17,7 +17,7 @@ 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";
@@ -693,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,
@@ -708,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 = [
@@ -731,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);
     }
@@ -969,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,
     },
@@ -1023,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,
     },
@@ -1179,6 +1244,7 @@ server.registerTool("list_migrations", {
         "- Run `execute_migration` with `dryRun: true` first.",
     annotations: {
         readOnlyHint: true,
+        destructiveHint: false,
         idempotentHint: true,
         openWorldHint: false,
     },
@@ -1600,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,
     },
@@ -1673,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,
     },
@@ -2107,6 +2175,7 @@ server.registerTool("get", {
         "- Use `update`, `forget`, `move_memory`, or `relate` after inspection.",
     annotations: {
         readOnlyHint: true,
+        destructiveHint: false,
         idempotentHint: true,
         openWorldHint: false,
     },
@@ -2204,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,
     },
@@ -2260,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,
     },
@@ -2370,6 +2441,7 @@ server.registerTool("discover_tags", {
         "Read-only.",
     annotations: {
         readOnlyHint: true,
+        destructiveHint: false,
         idempotentHint: true,
         openWorldHint: false,
     },
@@ -2576,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,
     },
@@ -2645,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,
     },
@@ -2724,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,
     },
@@ -2765,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);
@@ -3051,7 +3132,7 @@ 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,
@@ -3403,6 +3484,7 @@ server.registerTool("relate", {
                     cwd,
                     vault,
                     mutationApplied: true,
+                    preferredRecovery: "rerun-tool-call-serial",
                 });
                 const structuredContent = {
                     action: "related",
@@ -3452,6 +3534,7 @@ server.registerTool("relate", {
                 cwd,
                 vault,
                 mutationApplied: true,
+                preferredRecovery: "rerun-tool-call-serial",
             });
         }
         if (commitStatus.status === "committed") {
@@ -3574,6 +3657,7 @@ server.registerTool("unrelate", {
                     cwd,
                     vault,
                     mutationApplied: true,
+                    preferredRecovery: "rerun-tool-call-serial",
                 });
                 const structuredContent = {
                     action: "unrelated",
@@ -3617,6 +3701,7 @@ server.registerTool("unrelate", {
                 cwd,
                 vault,
                 mutationApplied: true,
+                preferredRecovery: "rerun-tool-call-serial",
             });
         }
         if (commitStatus.status === "committed") {