@danielmarbach/mnemonic-mcp 0.23.0 → 0.24.0

package/CHANGELOG.md

@@ -4,6 +4,12 @@ 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.24.0] - 2026-04-24
+
+### Added
+
+- `update` now supports `semanticPatch` for token-efficient targeted edits (insert, replace, append, remove content under specific headings) without round-tripping the full note body.
+
 ## [0.23.0] - 2026-04-17
 
 ### Added

package/build/index.js

@@ -18,6 +18,7 @@ import { computeRecallMetadataBoost, computeHybridScore, selectRecallResults, ap
 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 { 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";
 import { classifyTheme, classifyThemeWithGraduation, computeThemesWithGraduation, summarizePreview, titleCaseTheme, daysSinceUpdate, withinThemeScore, anchorScore, computeConnectionDiversity, workingStateScore, extractNextAction, } from "./project-introspection.js";
@@ -2103,7 +2104,8 @@ server.registerTool("update", {
         "- The updated memory id, changed fields, and persistence status\n\n" +
         "Side effects: rewrites the note, refreshes embeddings, git commits, and may push.\n\n" +
         "Typical next step:\n" +
-        "- Use `relate` or `consolidate` if the update changes how this note connects to others.",
+        "- Use `relate` or `consolidate` if the update changes how this note connects to others.\n\n" +
+        "Use `semanticPatch` for targeted edits (more token-efficient). Use `content` only for complete rewrites.",
     annotations: {
         readOnlyHint: false,
         destructiveHint: false,
@@ -2112,7 +2114,31 @@ 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`."),
-        content: z.string().optional().describe("Markdown note body. Put the key fact, decision, or outcome in the opening lines, then supporting detail."),
+        semanticPatch: z
+            .array(z.object({
+            selector: z.object({
+                heading: z.string().optional(),
+                headingStartsWith: z.string().optional(),
+                nthChild: z.number().int().optional(),
+                lastChild: z.literal(true).optional(),
+            }).refine((sel) => {
+                const keys = [sel.heading, sel.headingStartsWith, sel.nthChild, sel.lastChild].filter((v) => v !== undefined);
+                return keys.length === 1;
+            }, { message: "Selector must have exactly one of: heading, headingStartsWith, nthChild, lastChild" }),
+            operation: z.discriminatedUnion("op", [
+                z.object({ op: z.literal("appendChild"), value: z.string() }),
+                z.object({ op: z.literal("prependChild"), value: z.string() }),
+                z.object({ op: z.literal("replace"), value: z.string() }),
+                z.object({ op: z.literal("replaceChildren"), value: z.string() }),
+                z.object({ op: z.literal("insertAfter"), value: z.string() }),
+                z.object({ op: z.literal("insertBefore"), value: z.string() }),
+                z.object({ op: z.literal("remove") }),
+            ]),
+        }))
+            .optional()
+            .describe("Use for targeted edits when you know the structure. More token-efficient than passing full content. " +
+            "Mutually exclusive with content."),
+        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."),
         lifecycle: z
@@ -2133,12 +2159,18 @@ server.registerTool("update", {
             "When true, update can commit on a protected branch without changing project policy."),
     }),
     outputSchema: UpdateResultSchema,
-}, async ({ id, content, title, tags, lifecycle, summary, alwaysLoad, cwd, allowProtectedBranch = false }) => {
+}, async ({ id, content, semanticPatch, title, tags, lifecycle, summary, alwaysLoad, cwd, allowProtectedBranch = false }) => {
     await ensureBranchSynced(cwd);
     const found = await vaultManager.findNote(id, cwd);
     if (!found) {
         return { content: [{ type: "text", text: `No memory found with id '${id}'` }], isError: true };
     }
+    // Validate: content and semanticPatch are mutually exclusive
+    const hasContent = content !== undefined;
+    const hasSemanticPatch = semanticPatch !== undefined && semanticPatch.length > 0;
+    if (hasContent && hasSemanticPatch) {
+        return { content: [{ type: "text", text: "Exactly one of content or semanticPatch must be provided, not both." }], isError: true };
+    }
     const { note, vault } = found;
     if (vault.isProject) {
         const resolvedProject = await resolveProject(cwd);
@@ -2163,11 +2195,21 @@ server.registerTool("update", {
         }
     }
     const now = new Date().toISOString();
+    let patchedContent;
+    if (semanticPatch && semanticPatch.length > 0) {
+        try {
+            patchedContent = await applySemanticPatches(note.content, semanticPatch);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return { content: [{ type: "text", text: `Semantic patch failed: ${message}` }], isError: true };
+        }
+    }
     const cleanedContent = content === undefined ? undefined : await cleanMarkdown(content);
     const updated = {
         ...note,
         title: title ?? note.title,
-        content: cleanedContent ?? note.content,
+        content: patchedContent ?? cleanedContent ?? note.content,
         tags: tags ?? note.tags,
         lifecycle: lifecycle ?? note.lifecycle,
         alwaysLoad: alwaysLoad !== undefined ? alwaysLoad : note.alwaysLoad,
@@ -2211,6 +2253,8 @@ server.registerTool("update", {
         changes.push("title");
     if (content !== undefined)
         changes.push("content");
+    if (semanticPatch !== undefined)
+        changes.push("semanticPatch");
     if (tags !== undefined)
         changes.push("tags");
     if (lifecycle !== undefined && lifecycle !== note.lifecycle)