@danielmarbach/mnemonic-mcp 0.25.0 → 0.25.2

package/CHANGELOG.md

@@ -6,6 +6,21 @@ The format is loosely based on Keep a Changelog and uses semver-style version he
 
 ## [Unreleased]
 
+## [0.25.2] - 2026-04-24
+
+### Changed
+
+- `semanticPatch` parameter description now includes the full selector/operation type union and a 3-patch working example, so LLMs can construct correct JSON shapes without guessing at the nesting structure.
+- `mnemonic-workflow-hint` prompt now includes a `semanticPatch format` section with explicit nesting examples and a callout for the common `{op, value}` flattening mistake.
+- Selector-not-found errors now include a format reminder showing the correct selector shape using the first available heading.
+
+## [0.25.1] - 2026-04-24
+
+### Changed
+
+- `semanticPatch` no longer rejects content with markdown lint issues — the patch succeeds and warnings are surfaced in the response instead, so the LLM can continue without retrying from scratch. Previously any lint issue forced a hard failure.
+- Structural errors (bad selector, invalid operation) and content lint errors are now distinguished from patch lint warnings with separate guidance, so the LLM gets the right fix direction for each failure mode.
+
 ## [0.25.0] - 2026-04-24
 
 ### Added

package/build/index.js

@@ -17,7 +17,7 @@ import { suggestAutoRelationships } from "./auto-relate.js";
 import { computeRecallMetadataBoost, computeHybridScore, selectRecallResults, selectWorkflowResults, applyLexicalReranking, applyCanonicalExplanationPromotion, } from "./recall.js";
 import { shouldTriggerLexicalRescue, rankDocumentsByTfIdf, LEXICAL_RESCUE_CANDIDATE_LIMIT, LEXICAL_RESCUE_THRESHOLD, LEXICAL_RESCUE_RESULT_LIMIT, } from "./lexical.js";
 import { getRelationshipPreview } from "./relationships.js";
-import { cleanMarkdown } from "./markdown.js";
+import { MarkdownLintError, cleanMarkdown } from "./markdown.js";
 import { applySemanticPatches } from "./semantic-patch.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";
@@ -2158,8 +2158,16 @@ server.registerTool("update", {
             ]),
         }))
             .optional()
-            .describe("Use for targeted edits when you know the structure. More token-efficient than passing full content. " +
-            "Mutually exclusive with content."),
+            .describe("Targeted edits to note sections. Array of {selector, operation} objects. Mutually exclusive with content. " +
+            "If this fails, fix the issue in your patch values and retry — do NOT fall back to full content rewrite.\n\n" +
+            "selector: exactly one of { heading: \"exact heading text\" } | { headingStartsWith: \"prefix\" } | { lastChild: true } | { nthChild: 0-based-index }\n" +
+            "operation: { op: \"appendChild\", value: \"content\" } | { op: \"prependChild\", value: \"content\" } | { op: \"replace\", value: \"new content\" } | { op: \"replaceChildren\", value: \"new children\" } | { op: \"insertAfter\", value: \"content\" } | { op: \"insertBefore\", value: \"content\" } | { op: \"remove\" }\n\n" +
+            "Example — append a paragraph under ## Findings, replace ## Recommendation body, remove ## Old Section:\n" +
+            "[\n" +
+            "  { \"selector\": { \"heading\": \"Findings\" }, \"operation\": { \"op\": \"appendChild\", \"value\": \"A new paragraph.\" } },\n" +
+            "  { \"selector\": { \"heading\": \"Recommendation\" }, \"operation\": { \"op\": \"replaceChildren\", \"value\": \"Updated recommendation.\" } },\n" +
+            "  { \"selector\": { \"heading\": \"Old Section\" }, \"operation\": { \"op\": \"remove\" } }\n" +
+            "]"),
         content: z.string().optional().describe("Full note body replacement. Use only for complete rewrites or when the note is small. Mutually exclusive with semanticPatch."),
         title: z.string().optional().describe("Specific, retrieval-friendly title. Prefer the concrete topic or decision, not a vague label."),
         tags: z.array(z.string()).optional().describe("Optional tags for later filtering. Use a small number of stable, meaningful tags."),
@@ -2222,11 +2230,18 @@ server.registerTool("update", {
     }
     const now = new Date().toISOString();
     let patchedContent;
+    let lintWarnings;
     if (semanticPatch && semanticPatch.length > 0) {
         try {
-            patchedContent = await applySemanticPatches(note.content, semanticPatch);
+            const result = await applySemanticPatches(note.content, semanticPatch);
+            patchedContent = result.content;
+            lintWarnings = result.lintWarnings;
         }
         catch (err) {
+            if (err instanceof MarkdownLintError) {
+                const message = `Semantic patch produced content with markdown lint issues. Fix the lint issues in your patch values and retry — do NOT fall back to full content rewrite.\n\n${err.message}`;
+                return { content: [{ type: "text", text: message }], isError: true };
+            }
             const message = err instanceof Error ? err.message : String(err);
             return { content: [{ type: "text", text: `Semantic patch failed: ${message}` }], isError: true };
         }
@@ -2333,11 +2348,15 @@ server.registerTool("update", {
         project: noteProjectRef(updated),
         lifecycle: updated.lifecycle,
         role: updated.role,
+        lintWarnings: lintWarnings && lintWarnings.length > 0 ? lintWarnings : undefined,
         persistence,
     };
     invalidateActiveProjectCache();
     const fieldText = changes.length > 0 ? `\nfields modified: ${changes.join(", ")}` : "";
-    return { content: [{ type: "text", text: `Updated memory '${id}'${fieldText}\n${formatPersistenceSummary(persistence)}` }], structuredContent };
+    const warningsText = lintWarnings && lintWarnings.length > 0
+        ? `\nmarkdown lint warnings (not auto-fixable):\n- ${lintWarnings.join("\n- ")}`
+        : "";
+    return { content: [{ type: "text", text: `Updated memory '${id}'${fieldText}${warningsText}\n${formatPersistenceSummary(persistence)}` }], structuredContent };
 });
 // ── forget ────────────────────────────────────────────────────────────────────
 server.registerTool("forget", {
@@ -5056,7 +5075,15 @@ 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" +
-                    "- Resume work: `project_memory_summary` -> `recall` (lifecycle: temporary) -> continue from temporary notes.",
+                    "- Resume work: `project_memory_summary` -> `recall` (lifecycle: temporary) -> continue from temporary notes.\n\n" +
+                    "### semanticPatch format\n\n" +
+                    "When using `update` with `semanticPatch`:\n" +
+                    "- Each patch is an object with two keys: `selector` and `operation` (not flat `{op, value}` at top level).\n" +
+                    "- `selector` has exactly one key: `heading`, `headingStartsWith`, `nthChild`, or `lastChild`.\n" +
+                    "- `operation` has an `op` key plus `value` (except `remove` which has no value).\n" +
+                    "- The parameter must be a JSON array, NOT a string.\n" +
+                    "- Use `get` first to read exact heading text, then use those headings (without `##` prefix) as selector values.\n" +
+                    "- Common mistake: writing `{ \"op\": \"appendChild\", \"value\": \"...\" }` at the top level instead of nesting inside `operation`. Correct shape: `{ \"selector\": { \"heading\": \"Findings\" }, \"operation\": { \"op\": \"appendChild\", \"value\": \"text\" } }`",
             },
         },
     ],