mcp-memory-bucket 0.7.4 → 0.7.5

package/dist/src/memory/repository.js

@@ -6,6 +6,7 @@ import { slugify } from '../store/slug.js';
 import { resolveWithinBase } from '../store/safe-path.js';
 import { upsertFile, removeFile, scanSingleFolder, unregisterFolder, memorySyncSpec } from '../store/sync.js';
 import { SearchQueryError, sanitizeFtsQuery } from '../store/search.js';
+import { applyBodyEdits } from '../shared/body-edits.js';
 import { attachmentsDirFor } from '../attachments/storage.js';
 import { normalizeKey } from '../types.js';
 /** Uppercases and strips everything but letters/digits — used to compare keys that differ only in
@@ -235,7 +236,7 @@ export class MemoryRepository {
             }
         });
     }
-    update(id, frontmatter, body) {
+    update(id, frontmatter, body, bodyEdits) {
         const existing = this.get(id);
         if (!existing)
             throw new Error(`memory doc with id "${id}" not found`);
@@ -248,7 +249,7 @@ export class MemoryRepository {
             id: existing.id,
             key: frontmatter?.key ? normalizeKey(frontmatter.key) : existing.key,
         };
-        const newBody = body ?? existing.body;
+        const newBody = bodyEdits ? applyBodyEdits(existing.body, bodyEdits).body : (body ?? existing.body);
         writeMarkdownFile(existing.source_path, stripSourcePath(merged), newBody);
         upsertFile(this.db, this.syncSpec, existing.source_path);
         return { ...merged, body: newBody, paused: existingPaused };

package/dist/src/memory/tools.js

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { stripKey } from './repository.js';
 import { statusSchema } from '../shared/status.js';
+import { bodyEditsSchema, applyBodyEdits, formatBodyEditsDiff } from '../shared/body-edits.js';
 import { normalizeKey } from '../types.js';
 const MEMORY_DOC_TYPES = ['plan', 'spec', 'sql', 'testing-todo', 'discovery', 'session-summary', 'other'];
 const MEMORY_KEY_TYPES = ['ticket', 'freeform'];
@@ -100,21 +101,39 @@ export function registerMemoryTools(mcp, repo) {
         const results = repo.bulkCreate(entries);
         return { content: [{ type: 'text', text: JSON.stringify(results, null, 2) }] };
     });
-    mcp.tool('memory_update', `Edits an existing memory doc in place — frontmatter fields and/or body. Only provided fields change. ${AUTHORING_SKILL_HINT}`, {
+    mcp.tool('memory_update', `Edits an existing memory doc in place — frontmatter fields and/or body. Only provided fields change. For a body change smaller than the whole document, prefer body_edits over body: it patches via find/replace instead of requiring you to reproduce the entire body, which saves tokens and avoids accidentally dropping untouched content on a large doc. When body_edits is used, the response includes a \`diff\` field (compact -/+ per-edit summary) — show it to the user so they can see what changed, similar to a code diff view. The response never includes the full body (even on a full-body replacement) to avoid echoing back a potentially large doc — call memory_get(id) if you need the fresh full body. ${AUTHORING_SKILL_HINT}`, {
         id: z.string(),
         key: z.string().optional(),
         key_type: z.enum(MEMORY_KEY_TYPES).optional(),
         doc_type: z.enum(MEMORY_DOC_TYPES).optional(),
         description: z.string().optional(),
-        body: z.string().optional(),
+        body: z.string().optional().describe('full body replacement — omit in favor of body_edits when only part of the doc is changing'),
+        body_edits: bodyEditsSchema.optional(),
         tags: z.array(z.string()).optional(),
         status: statusSchema(MEMORY_STATUS_DEFAULTS).optional(),
         related_to: z.string().optional(),
         deprecated: z.boolean().optional().describe('marks the doc as deprecated (or un-deprecates when false) — independent of status'),
-    }, async ({ id, body, ...frontmatterFields }) => {
+    }, async ({ id, body, body_edits, ...frontmatterFields }) => {
+        if (body !== undefined && body_edits !== undefined) {
+            return { content: [{ type: 'text', text: 'Pass either body or body_edits, not both.' }], isError: true };
+        }
         try {
+            let diff;
+            if (body_edits) {
+                const existing = repo.get(id);
+                if (!existing)
+                    throw new Error(`memory doc with id "${id}" not found`);
+                const { body: patchedBody, applied } = applyBodyEdits(existing.body, body_edits);
+                diff = formatBodyEditsDiff(applied);
+                body = patchedBody;
+            }
             const doc = repo.update(id, frontmatterFields, body);
-            return { content: [{ type: 'text', text: JSON.stringify(doc, null, 2) }] };
+            // Body is omitted from the response: the caller either just sent it (full replacement),
+            // already has it, or has `diff` — echoing a potentially large body back is pure waste.
+            // Fetch memory_get(id) if the fresh full body is actually needed.
+            const { body: _omitted, ...docWithoutBody } = doc;
+            const result = diff ? { ...docWithoutBody, diff } : docWithoutBody;
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
         }
         catch (err) {
             return { content: [{ type: 'text', text: err.message }], isError: true };

package/dist/src/shared/body-edits.js

@@ -0,0 +1,87 @@
+import { z } from 'zod';
+/**
+ * Search/replace patch format for editing a doc body without round-tripping the whole
+ * thing through the model — same shape as Claude Code's own Edit tool (old_string/new_string).
+ * Line-anchored diffs (unified diff, @@ hunk headers) are what this deliberately avoids:
+ * weaker models reliably botch line numbers and context-line counts, and a rejected hunk
+ * gives no partial credit. Exact-text search/replace has no offsets for the model to get
+ * wrong, and the host enforces uniqueness so a bad match fails loudly with context instead
+ * of silently patching the wrong spot.
+ */
+export const bodyEditSchema = z.object({
+    find: z.string().min(1).describe('exact existing text to locate in the body — must match exactly once unless replace_all is set'),
+    replace: z.string().describe('text to substitute in place of the match'),
+    replace_all: z.boolean().optional().describe('replace every occurrence instead of requiring exactly one match (default: false)'),
+});
+export const bodyEditsSchema = z
+    .array(bodyEditSchema)
+    .min(1)
+    .describe('Alternative to `body`: apply one or more find/replace patches to the existing body instead of rewriting it wholesale. ' +
+    'Applied in order against the current body. Each `find` must match exactly once unless `replace_all` is set. ' +
+    'Cannot be combined with `body` in the same call.');
+/**
+ * Applies find/replace edits to `body` in order, matching Claude Code's Edit tool semantics:
+ * each `find` must appear exactly once unless `replace_all` is set, and a zero/ambiguous match
+ * throws immediately (with surrounding context) rather than guessing — so the caller can retry
+ * with a more specific `find` in the same turn instead of silently corrupting the doc.
+ *
+ * Also returns the applied edits (with occurrence counts) so a caller can render a diff of what
+ * changed without having to re-fetch and diff the pre-edit body itself.
+ */
+export function applyBodyEdits(body, edits) {
+    let result = body;
+    const applied = [];
+    for (const [i, edit] of edits.entries()) {
+        const { find, replace, replace_all } = edit;
+        const occurrences = countOccurrences(result, find);
+        if (occurrences === 0) {
+            throw new Error(`body_edits[${i}]: find text not found in body: ${JSON.stringify(truncate(find))}`);
+        }
+        if (occurrences > 1 && !replace_all) {
+            throw new Error(`body_edits[${i}]: find text matches ${occurrences} times in body — narrow it to a unique match, or set replace_all: true. Text: ${JSON.stringify(truncate(find))}`);
+        }
+        result = replace_all ? result.split(find).join(replace) : replaceFirst(result, find, replace);
+        applied.push({ find, replace, replace_all: !!replace_all, occurrences });
+    }
+    return { body: result, applied };
+}
+/**
+ * Renders applied edits as a compact per-edit diff (`-`/`+` lines, aider/Claude-Code-Edit-tool
+ * style) so a calling agent can show the user what changed without re-fetching the old body.
+ * Not a true unified diff (no line numbers/hunk headers) — deliberately, since this is for
+ * human-readable display, not for feeding back into another patch tool.
+ */
+export function formatBodyEditsDiff(applied) {
+    return applied
+        .map((edit, i) => {
+        const suffix = edit.occurrences > 1 ? ` (${edit.occurrences} occurrences replaced)` : '';
+        const removed = edit.find
+            .split('\n')
+            .map((line) => `-${line}`)
+            .join('\n');
+        const added = edit.replace
+            .split('\n')
+            .map((line) => `+${line}`)
+            .join('\n');
+        return `--- edit ${i + 1}${suffix} ---\n${removed}\n${added}`;
+    })
+        .join('\n');
+}
+function countOccurrences(haystack, needle) {
+    if (needle.length === 0)
+        return 0;
+    let count = 0;
+    let idx = 0;
+    while ((idx = haystack.indexOf(needle, idx)) !== -1) {
+        count++;
+        idx += needle.length;
+    }
+    return count;
+}
+function replaceFirst(haystack, needle, replacement) {
+    const idx = haystack.indexOf(needle);
+    return idx === -1 ? haystack : haystack.slice(0, idx) + replacement + haystack.slice(idx + needle.length);
+}
+function truncate(s, max = 120) {
+    return s.length > max ? `${s.slice(0, max)}…` : s;
+}

package/dist/src/skills/repository.js

@@ -5,6 +5,7 @@ import { assertValidSkillName } from '../store/skill-name.js';
 import { resolveWithinBase } from '../store/safe-path.js';
 import { upsertFile, removeFile, scanSingleFolder, unregisterFolder, skillSyncSpec } from '../store/sync.js';
 import { SearchQueryError, sanitizeFtsQuery } from '../store/search.js';
+import { applyBodyEdits } from '../shared/body-edits.js';
 function rowToDoc(row) {
     return {
         name: row.id,
@@ -221,7 +222,7 @@ export class SkillRepository {
     isBuiltin(doc) {
         return doc.folder === this.folders[0]?.name;
     }
-    update(name, frontmatter, body) {
+    update(name, frontmatter, body, bodyEdits) {
         const existing = this.get(name);
         if (!existing)
             throw new Error(`skill with name "${name}" not found`);
@@ -243,7 +244,7 @@ export class SkillRepository {
                 extends: frontmatter?.extends !== undefined ? frontmatter.extends : existing.metadata.extends,
             },
         };
-        const newBody = body ?? existing.body;
+        const newBody = bodyEdits ? applyBodyEdits(existing.body, bodyEdits).body : (body ?? existing.body);
         writeMarkdownFile(existing.source_path, stripSourcePath(merged), newBody);
         upsertFile(this.db, this.syncSpec, existing.source_path);
         return { ...merged, body: newBody, paused: existingPaused };

package/dist/src/skills/tools.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { statusSchema } from '../shared/status.js';
+import { bodyEditsSchema, applyBodyEdits, formatBodyEditsDiff } from '../shared/body-edits.js';
 const SKILL_STATUS_DEFAULTS = ['stable', 'beta', 'unreviewed'];
 const SKILL_NAME_DESCRIPTION = 'stable id, must be 1-64 chars, lowercase letters/numbers/hyphens only, no leading/trailing/consecutive hyphens — this becomes the skill\'s folder name (agentskills.io spec requirement)';
 const AUTHORING_SKILL_HINT = "Before your first call in a session, run skill_get(\"memory-bucket-authoring\") to learn the exact frontmatter schema and conventions — don't guess the shape.";
@@ -119,10 +120,11 @@ export function registerSkillTools(mcp, repo) {
         })));
         return { content: [{ type: 'text', text: JSON.stringify(results, null, 2) }] };
     });
-    mcp.tool('skill_update', `Edits an existing skill in place — frontmatter fields and/or body. Only provided fields change. Use skill_rename to change the name/folder. ${AUTHORING_SKILL_HINT}`, {
+    mcp.tool('skill_update', `Edits an existing skill in place — frontmatter fields and/or body. Only provided fields change. Use skill_rename to change the name/folder. For a body change smaller than the whole document, prefer body_edits over body: it patches via find/replace instead of requiring you to reproduce the entire body, which saves tokens and avoids accidentally dropping untouched content on a large skill. When body_edits is used, the response includes a \`diff\` field (compact -/+ per-edit summary) — show it to the user so they can see what changed, similar to a code diff view. The response never includes the full body (even on a full-body replacement) to avoid echoing back a potentially large doc — call skill_get(name) if you need the fresh full body. ${AUTHORING_SKILL_HINT}`, {
         name: z.string(),
         description: z.string().max(1024).optional(),
-        body: z.string().optional(),
+        body: z.string().optional().describe('full body replacement — omit in favor of body_edits when only part of the doc is changing'),
+        body_edits: bodyEditsSchema.optional(),
         license: z.string().optional(),
         compatibility: z.string().max(500).optional(),
         owner: z.string().optional(),
@@ -131,10 +133,27 @@ export function registerSkillTools(mcp, repo) {
         trigger_phrases: z.array(z.string()).optional(),
         extends: z.string().optional(),
         deprecated: z.boolean().optional().describe('marks the skill as deprecated (or un-deprecates when false) — independent of status'),
-    }, async ({ name, body, ...frontmatterFields }) => {
+    }, async ({ name, body, body_edits, ...frontmatterFields }) => {
+        if (body !== undefined && body_edits !== undefined) {
+            return { content: [{ type: 'text', text: 'Pass either body or body_edits, not both.' }], isError: true };
+        }
         try {
+            let diff;
+            if (body_edits) {
+                const existing = repo.get(name);
+                if (!existing)
+                    throw new Error(`skill with name "${name}" not found`);
+                const { body: patchedBody, applied } = applyBodyEdits(existing.body, body_edits);
+                diff = formatBodyEditsDiff(applied);
+                body = patchedBody;
+            }
             const doc = repo.update(name, frontmatterFields, body);
-            return { content: [{ type: 'text', text: JSON.stringify(doc, null, 2) }] };
+            // Body is omitted from the response: the caller either just sent it (full replacement),
+            // already has it, or has `diff` — echoing a potentially large body back is pure waste.
+            // Fetch skill_get(name) if the fresh full body is actually needed.
+            const { body: _omitted, ...docWithoutBody } = doc;
+            const result = diff ? { ...docWithoutBody, diff } : docWithoutBody;
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
         }
         catch (err) {
             return { content: [{ type: 'text', text: err.message }], isError: true };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-memory-bucket",
-  "version": "0.7.4",
+  "version": "0.7.5",
   "type": "module",
   "description": "MCP server exposing skill_* (reusable coding patterns) and memory_* (point-in-time working context) tools over a markdown+frontmatter source, cached into SQLite at runtime.",
   "repository": {