@danielmarbach/mnemonic-mcp 0.27.1 → 0.27.2

package/CHANGELOG.md

@@ -6,6 +6,19 @@ The format is loosely based on Keep a Changelog and uses semver-style version he
 
 ## [Unreleased]
 
+## [0.27.2] - 2026-05-01
+
+### Fixed
+
+- `remember` and `update(content)` now return structured error responses with actionable retry guidance when markdown lint fails, instead of propagating raw errors that LLMs sometimes ignore.
+- `remember` and `update` `content` parameter descriptions include proactive lint guidance (auto-fixable vs. unfixable issues, common MD040 fenced-code-language gotcha).
+
+### Changed
+
+- `semanticPatch` schema example and guidance now use `insertAfter` instead of the rejected `appendChild`/`replaceChildren` on `heading` selectors.
+- `semanticPatch` workflow hint corrected: recommends `insertAfter` for adding content under headings instead of `appendChild`, which the code rejects.
+- `semanticPatch` parameter now auto-parses string-wrapped JSON arrays, recovering gracefully when LLMs serialize the array as a string instead of a proper JSON array.
+
 ## [0.27.1] - 2026-04-28
 
 ### Changed

package/build/index.js

@@ -1461,7 +1461,9 @@ server.registerTool("remember", {
     },
     inputSchema: z.object({
         title: z.string().describe("Specific, retrieval-friendly title. Prefer the concrete topic or decision, not a vague label."),
-        content: z.string().describe("Markdown note body. Put the key fact, decision, or outcome in the opening lines, then supporting detail. Embeddings weight early content more heavily."),
+        content: z.string().describe("Markdown note body. Put the key fact, decision, or outcome in the opening lines, then supporting detail. Embeddings weight early content more heavily. " +
+            "Content must pass markdown lint. Auto-fixable issues are fixed automatically. Common unfixable issues: fenced code blocks need a language tag (e.g. use ```text not bare ```), and broken links are rejected. " +
+            "If lint fails, fix the specific issues listed in the error and retry the same call."),
         tags: z.array(z.string()).optional().default([]).describe("Optional tags for later filtering. Use a small number of stable, meaningful tags."),
         lifecycle: z
             .enum(NOTE_LIFECYCLES)
@@ -1504,7 +1506,21 @@ server.registerTool("remember", {
 }, async ({ title, content, tags, lifecycle, role, summary, alwaysLoad, cwd, scope, allowProtectedBranch = false }) => {
     await ensureBranchSynced(cwd);
     const project = await resolveProject(cwd);
-    const cleanedContent = await cleanMarkdown(content);
+    let cleanedContent;
+    try {
+        cleanedContent = await cleanMarkdown(content);
+    }
+    catch (err) {
+        if (err instanceof MarkdownLintError) {
+            const message = `Markdown lint issues prevented this note from being stored. Fix the specific lint errors listed below in your content and retry the remember call — the note was NOT stored.\n\n${err.message}`;
+            return {
+                content: [{ type: "text", text: message }],
+                structuredContent: { action: "lint_error", tool: "remember", issues: err.issues },
+                isError: true,
+            };
+        }
+        throw err;
+    }
     const policy = project ? await configStore.getProjectPolicy(project.id) : undefined;
     const policyScope = policy?.defaultScope;
     const projectVaultExists = cwd ? Boolean(await vaultManager.getProjectVaultIfExists(cwd)) : true;
@@ -2263,7 +2279,17 @@ server.registerTool("update", {
     inputSchema: z.object({
         id: z.string().describe("Exact memory id. Use an id returned by `recall`, `list`, `recent_memories`, or `where_is`."),
         semanticPatch: z
-            .array(z.object({
+            .preprocess((val) => {
+            if (typeof val === "string") {
+                try {
+                    return JSON.parse(val);
+                }
+                catch {
+                    return val;
+                }
+            }
+            return val;
+        }, z.array(z.object({
             selector: z.object({
                 heading: z.string().optional(),
                 headingStartsWith: z.string().optional(),
@@ -2282,20 +2308,20 @@ server.registerTool("update", {
                 z.object({ op: z.literal("insertBefore"), value: z.string() }),
                 z.object({ op: z.literal("remove") }),
             ]),
-        }))
+        })))
             .optional()
             .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" +
+            "Example — add a paragraph under ## Findings, replace body under ## Recommendation, 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\": \"Findings\" }, \"operation\": { \"op\": \"insertAfter\", \"value\": \"A new paragraph.\" } },\n" +
+            "  { \"selector\": { \"heading\": \"Recommendation\" }, \"operation\": { \"op\": \"replace\", \"value\": \"## Recommendation\\n\\nUpdated recommendation.\" } },\n" +
             "  { \"selector\": { \"heading\": \"Old Section\" }, \"operation\": { \"op\": \"remove\" } }\n" +
             "]\n\n" +
-            "`replaceChildren` on a `heading` selector targets the heading itself, not the body below it. Use `appendChild` or `replace` instead."),
-        content: z.string().optional().describe("Full note body replacement. Use only for complete rewrites or when the note is small. Mutually exclusive with semanticPatch."),
+            "IMPORTANT: `appendChild`, `prependChild`, and `replaceChildren` do NOT work with `heading` selectors (headings only contain inline text, not block content). To add or replace content under a heading, use `insertAfter`. To replace a heading entirely, use `replace`."),
+        content: z.string().optional().describe("Full note body replacement. Use only for complete rewrites or when the note is small. Mutually exclusive with semanticPatch. Content must pass markdown lint. Auto-fixable issues are fixed automatically. Common unfixable issues: fenced code blocks need a language tag (e.g. use ```text not bare ```), and broken links are rejected. If lint fails, fix the specific issues and retry — do NOT fall back to semanticPatch for this."),
         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."),
         lifecycle: z
@@ -2373,7 +2399,23 @@ server.registerTool("update", {
             return { content: [{ type: "text", text: `Semantic patch failed: ${message}` }], isError: true };
         }
     }
-    const cleanedContent = content === undefined ? undefined : await cleanMarkdown(content);
+    let cleanedContent;
+    if (content !== undefined) {
+        try {
+            cleanedContent = await cleanMarkdown(content);
+        }
+        catch (err) {
+            if (err instanceof MarkdownLintError) {
+                const message = `Markdown lint issues prevented the update. Fix the specific lint errors in your content and retry — do NOT fall back to semanticPatch for this.\n\n${err.message}`;
+                return {
+                    content: [{ type: "text", text: message }],
+                    structuredContent: { action: "lint_error", tool: "update", issues: err.issues },
+                    isError: true,
+                };
+            }
+            throw err;
+        }
+    }
     const resolvedTitle = title ?? note.title;
     const resolvedContent = patchedContent ?? cleanedContent ?? note.content;
     const resolvedTags = tags ?? note.tags;
@@ -5365,8 +5407,8 @@ server.registerPrompt("mnemonic-workflow-hint", {
                     "- `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\" } }`\n" +
-                    "- `replaceChildren` on a `heading` selector targets the heading itself, not the body below it. Use `appendChild` or `replace` instead.",
+                    "- Common mistake: writing `{ \"op\": \"appendChild\", \"value\": \"...\" }` at the top level instead of nesting inside `operation`. Correct shape: `{ \"selector\": { \"heading\": \"Findings\" }, \"operation\": { \"op\": \"insertAfter\", \"value\": \"text\" } }`\n" +
+                    "- `appendChild`, `prependChild`, and `replaceChildren` do NOT work with `heading` selectors. To add content under a heading, use `insertAfter`. To replace a heading, use `replace`.",
             },
         },
     ],