mcp-memory-bucket 0.7.4 → 0.8.0

package/dist/src/shared/relocate.js

@@ -37,7 +37,7 @@ export function inferMemoryFrontmatter(filePath) {
         return null; // nothing left to distinguish this doc — ambiguous
     return { key, key_type: 'ticket', doc_type: docType, description };
 }
-export function relocate(opts, skillRepo, memoryRepo) {
+export async function relocate(opts, skillRepo, memoryRepo) {
     if (!fs.existsSync(opts.path) || !fs.statSync(opts.path).isFile()) {
         return { moved: false, reason: `file not found or not readable: ${opts.path}` };
     }
@@ -55,7 +55,7 @@ export function relocate(opts, skillRepo, memoryRepo) {
         if (!description) {
             return { moved: false, reason: 'skill description cannot be inferred from a filename — provide overrides.description (what it does and when to use it)' };
         }
-        const doc = skillRepo.create({
+        const doc = await skillRepo.create({
             name,
             description,
             owner: null,
@@ -84,7 +84,7 @@ export function relocate(opts, skillRepo, memoryRepo) {
     if (already) {
         return { moved: false, reason: `already relocated as memory doc "${already.id}"`, id: already.id, target: 'memory' };
     }
-    const doc = memoryRepo.create({
+    const doc = await memoryRepo.create({
         key,
         key_type: keyType,
         doc_type: docType,
@@ -104,8 +104,12 @@ export function relocate(opts, skillRepo, memoryRepo) {
  * RelocateResult per path (in order) so one bad/ambiguous file doesn't abort
  * the rest of the batch — same "no guess, no partial write" behavior per file.
  */
-export function relocateMany(entries, skillRepo, memoryRepo) {
-    return entries.map((entry) => ({ path: entry.path, ...relocate(entry, skillRepo, memoryRepo) }));
+export async function relocateMany(entries, skillRepo, memoryRepo) {
+    const results = [];
+    for (const entry of entries) {
+        results.push({ path: entry.path, ...(await relocate(entry, skillRepo, memoryRepo)) });
+    }
+    return results;
 }
 function slugFromFilename(filePath) {
     return path

package/dist/src/skills/repository.js

@@ -1,10 +1,13 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import matter from 'gray-matter';
 import { writeMarkdownFile } from '../store/markdown-file.js';
 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';
+import { readFile as readRemoteFile, writeFile as writeRemoteFile, joinRemoteFolderPath } from '../remote/folderfoo-client.js';
 function rowToDoc(row) {
     return {
         name: row.id,
@@ -24,14 +27,31 @@ function rowToDoc(row) {
 export class SkillRepository {
     db;
     folders;
+    remoteFolders;
+    credentialsBaseDir;
     syncSpec;
     watcher;
     /** `folders[0]` is always the builtin skills dir — never exposed for create()/removal. */
-    constructor(db, folders) {
+    constructor(db, folders, remoteFolders = [], credentialsBaseDir) {
         this.db = db;
         this.folders = folders;
+        this.remoteFolders = remoteFolders;
+        this.credentialsBaseDir = credentialsBaseDir;
         this.syncSpec = skillSyncSpec(folders);
     }
+    /** The RemoteFolder a NamedFolder name resolves to, or undefined for a local (non-remote) folder. */
+    remoteFor(folderName) {
+        return this.remoteFolders.find((f) => f.name === folderName);
+    }
+    /** Pushes the just-written SKILL.md at filePath to folderfoo, if targetFolderName resolves to a remote source. No-op for a local folder. See get()'s comment on the folderPath/name split for a skill's directory-per-skill layout. */
+    async pushToRemoteIfNeeded(targetFolderName, filePath) {
+        const remote = this.remoteFor(targetFolderName);
+        if (!remote || !this.credentialsBaseDir)
+            return;
+        const skillDirRelPath = joinRemoteFolderPath(remote.folderPath, path.relative(remote.mirrorDir, path.dirname(filePath)));
+        const fileContents = fs.readFileSync(filePath, 'utf-8');
+        await writeRemoteFile(remote.server, this.credentialsBaseDir, remote.tenantId, skillDirRelPath, 'SKILL', fileContents);
+    }
     /** Attaches the live chokidar watcher so addFolder/removeFolder can mutate it without a restart. */
     setWatcher(watcher) {
         this.watcher = watcher;
@@ -40,6 +60,14 @@ export class SkillRepository {
     listFolders() {
         return this.folders.slice(1);
     }
+    /** Full RemoteFolder records (server/tenantId/folderPath/mirrorDir) for every connected remote source — for matching an incoming folderfoo-file-open address back to a configured source. */
+    listRemoteFolders() {
+        return [...this.remoteFolders];
+    }
+    /** Same as listFolders(), but tags each entry with whether it's a remote (folderfoo) source — for the web UI's folder list, e.g. to render remote folders in a distinct color. */
+    listFoldersWithRemoteInfo() {
+        return this.listFolders().map((f) => ({ ...f, remote: !!this.remoteFor(f.name) }));
+    }
     resolveFolder(folderName) {
         const userFolders = this.listFolders();
         if (folderName) {
@@ -56,6 +84,24 @@ export class SkillRepository {
         }
         throw new Error(`multiple skill folders configured — specify folder: one of ${userFolders.map((f) => f.name).join(', ')}`);
     }
+    /**
+     * Registers a new REMOTE (folderfoo) folder: creates its local mirror
+     * directory, registers it exactly like a local addFolder (so it starts
+     * watching/scanning immediately — empty at first, since nothing's been
+     * pulled from folderfoo yet), and records the folderfoo coordinates so
+     * get()/create()/update() know to treat this folder as remote. Does NOT
+     * perform the initial pull itself — the caller (the web route) does one
+     * immediate poll right after this returns, so content shows up without
+     * waiting for the first interval tick.
+     */
+    registerRemoteFolder(remote) {
+        if (this.folders.some((f) => f.name === remote.name)) {
+            throw new Error(`a skill folder named "${remote.name}" already exists`);
+        }
+        fs.mkdirSync(remote.mirrorDir, { recursive: true });
+        this.remoteFolders.push(remote);
+        this.addFolder({ name: remote.name, path: remote.mirrorDir });
+    }
     /** Registers a new folder: appends it, scans it once, and starts watching it live. */
     addFolder(folder) {
         if (this.folders.some((f) => f.name === folder.name)) {
@@ -154,13 +200,39 @@ export class SkillRepository {
             throw new SearchQueryError(query, err);
         }
     }
-    get(name) {
+    /**
+     * For a skill in a LOCAL folder, returns the cached row unchanged (identical behavior to before
+     * remote sources existed). For a skill in a REMOTE folder, the cached `body` is only ever a
+     * poll-interval-stale mirror snapshot — per the settled design, `get` always fetches the current
+     * body live from folderfoo instead of trusting it.
+     */
+    async get(name) {
         const row = this.db.prepare(`SELECT * FROM skills WHERE id = ?`).get(name);
-        return row ? rowToDoc(row) : null;
+        if (!row)
+            return null;
+        const doc = rowToDoc(row);
+        const remote = this.remoteFor(doc.folder);
+        if (!remote || !this.credentialsBaseDir)
+            return doc;
+        // A skill's SKILL.md sits INSIDE a directory named after the skill
+        // (<mirrorDir>/[subfolder/]<name>/SKILL.md, per agentskills.io), unlike
+        // a memory doc's flat <id>.md - so the skill's own directory is part of
+        // the folderPath sent to folderfoo, and "SKILL" (no extension - the
+        // server stores opaque names) is the file name within it.
+        const skillDirRelPath = joinRemoteFolderPath(remote.folderPath, path.relative(remote.mirrorDir, path.dirname(doc.source_path)));
+        // readRemoteFile returns the RAW file bytes folderfoo stored (whole
+        // SKILL.md, frontmatter included) - must parse it the same way a local
+        // file read would, or the next update() nests a fresh frontmatter
+        // block around this already-frontmattered blob (see memory/
+        // repository.ts's get() for the confirmed real-world corruption this
+        // caused).
+        const liveBody = matter(await readRemoteFile(remote.server, this.credentialsBaseDir, remote.tenantId, skillDirRelPath, 'SKILL')).content.trim();
+        return { ...doc, body: liveBody };
     }
     /** Fetches many skills by name in one call — e.g. hydrating full bodies for a batch of search() hits. Missing names are simply absent from the result, not errors. */
-    bulkGet(names) {
-        return names.map((name) => this.get(name)).filter((doc) => doc !== null);
+    async bulkGet(names) {
+        const docs = await Promise.all(names.map((name) => this.get(name)));
+        return docs.filter((doc) => doc !== null);
     }
     /**
      * Creates <folder>/[subfolder/]<name>/SKILL.md — folder-per-skill, per the
@@ -168,9 +240,9 @@ export class SkillRepository {
      * `folder` selects which configured skill folder to write into; required only
      * when more than one user folder is configured.
      */
-    create(frontmatter, body, subfolder, folder) {
+    async create(frontmatter, body, subfolder, folder) {
         assertValidSkillName(frontmatter.name);
-        if (this.get(frontmatter.name)) {
+        if (await this.get(frontmatter.name)) {
             throw new Error(`skill with name "${frontmatter.name}" already exists`);
         }
         const targetFolder = this.resolveFolder(folder);
@@ -198,6 +270,9 @@ export class SkillRepository {
             folder: targetFolder.name,
         };
         writeMarkdownFile(filePath, stripSourcePath(fm), body);
+        // Live/synchronous per the settled design — a folderfoo rejection here throws before upsertFile
+        // indexes the mirror as if the skill were successfully saved remotely.
+        await this.pushToRemoteIfNeeded(targetFolder.name, filePath);
         upsertFile(this.db, this.syncSpec, filePath);
         return { ...fm, body, paused: false };
     }
@@ -206,23 +281,25 @@ export class SkillRepository {
      * args. Returns per-name results so one bad entry (duplicate name, invalid
      * name, existing directory) doesn't abort the rest of the batch.
      */
-    bulkCreate(entries) {
-        return entries.map((entry) => {
+    async bulkCreate(entries) {
+        const results = [];
+        for (const entry of entries) {
             try {
-                this.create(entry.frontmatter, entry.body, entry.subfolder, entry.folder);
-                return { name: entry.frontmatter.name, ok: true };
+                await this.create(entry.frontmatter, entry.body, entry.subfolder, entry.folder);
+                results.push({ name: entry.frontmatter.name, ok: true });
             }
             catch (err) {
-                return { name: entry.frontmatter.name, ok: false, error: err.message };
+                results.push({ name: entry.frontmatter.name, ok: false, error: err.message });
             }
-        });
+        }
+        return results;
     }
     /** Name of the always-present, non-removable builtin folder (folders[0]) — never user content, never deprecatable. */
     isBuiltin(doc) {
         return doc.folder === this.folders[0]?.name;
     }
-    update(name, frontmatter, body) {
-        const existing = this.get(name);
+    async update(name, frontmatter, body, bodyEdits) {
+        const existing = await this.get(name);
         if (!existing)
             throw new Error(`skill with name "${name}" not found`);
         // `paused` is local-cache-only and must never reach writeMarkdownFile — split it off of
@@ -243,23 +320,31 @@ 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);
+        await this.pushToRemoteIfNeeded(existing.folder, existing.source_path);
         upsertFile(this.db, this.syncSpec, existing.source_path);
         return { ...merged, body: newBody, paused: existingPaused };
     }
     /**
      * Renames a skill: moves <sourceDir>/[subfolder/]<oldName>/ to .../<newName>/ (keeping any
      * scripts/references/assets alongside SKILL.md) and updates the `name` frontmatter field to match.
+     *
+     * Remote-folder note: pushes the renamed skill's content to folderfoo at its NEW path (a plain
+     * write, via pushToRemoteIfNeeded), but does not delete the OLD path on folderfoo — a true
+     * remote rename would need a folderfoo folder-rename call scoped to one skill's directory, which
+     * is out of scope for this pass (the settled design's write scope covers create/update/
+     * attachment writes, not rename). Renaming a remote-sourced skill currently leaves a stale copy
+     * under the old name on folderfoo; flagged here rather than silently incomplete.
      */
-    rename(name, newName) {
+    async rename(name, newName) {
         assertValidSkillName(newName);
-        const existing = this.get(name);
+        const existing = await this.get(name);
         if (!existing)
             throw new Error(`skill with name "${name}" not found`);
         if (newName === name)
             return existing;
-        if (this.get(newName)) {
+        if (await this.get(newName)) {
             throw new Error(`skill with name "${newName}" already exists`);
         }
         const oldDir = path.dirname(existing.source_path);
@@ -274,6 +359,7 @@ export class SkillRepository {
         const { paused: _existingPaused, ...existingForFile } = existing;
         const merged = { ...existingForFile, name: newName };
         writeMarkdownFile(newFilePath, stripSourcePath(merged), existing.body);
+        await this.pushToRemoteIfNeeded(existing.folder, newFilePath);
         removeFile(this.db, 'skills', existing.source_path);
         upsertFile(this.db, this.syncSpec, newFilePath);
         return { ...merged, body: existing.body, paused: false };
@@ -286,10 +372,11 @@ export class SkillRepository {
      * Returns per-name results so partial failures (e.g. an unknown name) don't
      * abort the rest of the batch.
      */
-    bulkUpdate(names, changes) {
-        return names.map((name) => {
+    async bulkUpdate(names, changes) {
+        const results = [];
+        for (const name of names) {
             try {
-                const existing = this.get(name);
+                const existing = await this.get(name);
                 if (!existing)
                     throw new Error(`skill with name "${name}" not found`);
                 const builtin = this.isBuiltin(existing);
@@ -298,19 +385,20 @@ export class SkillRepository {
                     tags = Array.from(new Set([...tags, ...changes.add_tags]));
                 if (changes.remove_tags?.length)
                     tags = tags.filter((t) => !changes.remove_tags.includes(t));
-                this.update(name, {
+                await this.update(name, {
                     tags,
                     owner: changes.owner,
                     status: changes.status,
                     extends: changes.extends,
                     ...(changes.deprecated !== undefined && !builtin ? { deprecated: changes.deprecated } : {}),
                 });
-                return { name, ok: true };
+                results.push({ name, ok: true });
             }
             catch (err) {
-                return { name, ok: false, error: err.message };
+                results.push({ name, ok: false, error: err.message });
             }
-        });
+        }
+        return results;
     }
     /**
      * Pauses/resumes skills by name — a local-only toggle stored directly in this cache file's
@@ -320,41 +408,45 @@ export class SkillRepository {
      * follow the skill to another machine's cache, survive a rename, or survive the cache file
      * being deleted. Returns per-name results so one bad name doesn't abort the rest of the batch.
      */
-    setPaused(names, paused) {
-        return names.map((name) => {
+    async setPaused(names, paused) {
+        const results = [];
+        for (const name of names) {
             try {
-                const existing = this.get(name);
+                const existing = await this.get(name);
                 if (!existing)
                     throw new Error(`skill with name "${name}" not found`);
                 if (this.isBuiltin(existing))
                     throw new Error(`skill "${name}" is builtin and cannot be paused`);
                 this.db.prepare(`UPDATE skills SET paused = ? WHERE id = ?`).run(paused ? 1 : 0, name);
-                return { name, ok: true };
+                results.push({ name, ok: true });
             }
             catch (err) {
-                return { name, ok: false, error: err.message };
+                results.push({ name, ok: false, error: err.message });
             }
-        });
+        }
+        return results;
     }
     /**
      * Renames many skills at once — each entry is a {name, new_name} pair, same
      * semantics as rename(). Returns per-entry results so one bad pair (unknown
      * name, name collision) doesn't abort the rest of the batch.
      */
-    bulkRename(entries) {
-        return entries.map(({ name, new_name }) => {
+    async bulkRename(entries) {
+        const results = [];
+        for (const { name, new_name } of entries) {
             try {
-                this.rename(name, new_name);
-                return { name, new_name, ok: true };
+                await this.rename(name, new_name);
+                results.push({ name, new_name, ok: true });
             }
             catch (err) {
-                return { name, new_name, ok: false, error: err.message };
+                results.push({ name, new_name, ok: false, error: err.message });
             }
-        });
+        }
+        return results;
     }
-    /** Removes the whole skill directory, including any scripts/references/assets alongside SKILL.md. */
-    delete(name) {
-        const existing = this.get(name);
+    /** Removes the whole skill directory, including any scripts/references/assets alongside SKILL.md. Remote-folder note: does not delete the corresponding content on folderfoo — deletion isn't in the settled design's remote write scope (create/update/attachment writes only), same gap flagged on rename(). */
+    async delete(name) {
+        const existing = await this.get(name);
         if (!existing)
             throw new Error(`skill with name "${name}" not found`);
         if (this.isBuiltin(existing))
@@ -368,16 +460,18 @@ export class SkillRepository {
      * via search()/list(). Returns per-name results so one bad name doesn't
      * abort the rest of the batch.
      */
-    bulkDelete(names) {
-        return names.map((name) => {
+    async bulkDelete(names) {
+        const results = [];
+        for (const name of names) {
             try {
-                this.delete(name);
-                return { name, ok: true };
+                await this.delete(name);
+                results.push({ name, ok: true });
             }
             catch (err) {
-                return { name, ok: false, error: err.message };
+                results.push({ name, ok: false, error: err.message });
             }
-        });
+        }
+        return results;
     }
 }
 function stripSourcePath(fm) {

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.";
@@ -47,18 +48,18 @@ export function registerSkillTools(mcp, repo) {
         extends: z.string().nullable().optional(),
         deprecated: z.boolean().optional().describe('marks skills as deprecated (or un-deprecates when false) — independent of status'),
     }, async ({ names, add_tags, remove_tags, owner, status, extends: extendsId, deprecated }) => {
-        const results = repo.bulkUpdate(names, { add_tags, remove_tags, owner, status, extends: extendsId, deprecated });
+        const results = await repo.bulkUpdate(names, { add_tags, remove_tags, owner, status, extends: extendsId, deprecated });
         return { content: [{ type: 'text', text: JSON.stringify(results, null, 2) }] };
     });
     mcp.tool('skill_get', 'Fetches a single skill by name, including its full markdown body.', { name: z.string() }, async ({ name }) => {
-        const doc = repo.get(name);
+        const doc = await repo.get(name);
         if (!doc) {
             return { content: [{ type: 'text', text: `No skill found with name "${name}"` }], isError: true };
         }
         return { content: [{ type: 'text', text: JSON.stringify(doc, null, 2) }] };
     });
     mcp.tool('skill_bulk_get', 'Fetches many skills by name in one call, including full markdown bodies — e.g. hydrating a batch of skill_search hits. Missing names are simply omitted from the result, not errors.', { names: z.array(z.string()).min(1) }, async ({ names }) => {
-        const docs = repo.bulkGet(names);
+        const docs = await repo.bulkGet(names);
         return { content: [{ type: 'text', text: JSON.stringify(docs, null, 2) }] };
     });
     mcp.tool('skill_create', `Creates a new skill as <folder>/[subfolder/]<name>/SKILL.md, per the agentskills.io open standard — a folder containing SKILL.md, optionally alongside scripts/references/assets subfolders you create separately on disk. ${AUTHORING_SKILL_HINT}`, {
@@ -79,7 +80,7 @@ export function registerSkillTools(mcp, repo) {
         ...(multiFolder ? { folder: z.string().describe(`which configured skill folder to write into: ${folderNames}`) } : {}),
     }, async ({ name, description, body, license, compatibility, owner, status, tags, trigger_phrases, extends: extendsId, subfolder, folder }) => {
         try {
-            const doc = repo.create({ name, description, license, compatibility, owner, status, tags, trigger_phrases, extends: extendsId }, body, subfolder, folder);
+            const doc = await repo.create({ name, description, license, compatibility, owner, status, tags, trigger_phrases, extends: extendsId }, body, subfolder, folder);
             return { content: [{ type: 'text', text: JSON.stringify(doc, null, 2) }] };
         }
         catch (err) {
@@ -101,7 +102,7 @@ export function registerSkillTools(mcp, repo) {
         ...(multiFolder ? { folder: z.string().describe(`which configured skill folder to write into: ${folderNames}`) } : {}),
     });
     mcp.tool('skill_bulk_create', `Creates many skills in one call — each entry is the same shape as skill_create's args. Returns per-name success/failure so one bad entry (duplicate name, invalid name, existing directory) doesn't abort the rest of the batch. ${AUTHORING_SKILL_HINT}`, { entries: z.array(skillEntrySchema).min(1) }, async ({ entries }) => {
-        const results = repo.bulkCreate(entries.map((e) => ({
+        const results = await repo.bulkCreate(entries.map((e) => ({
             frontmatter: {
                 name: e.name,
                 description: e.description,
@@ -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 {
-            const doc = repo.update(name, frontmatterFields, body);
-            return { content: [{ type: 'text', text: JSON.stringify(doc, null, 2) }] };
+            let diff;
+            if (body_edits) {
+                const existing = await 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 = await repo.update(name, frontmatterFields, body);
+            // 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 };
@@ -145,7 +164,7 @@ export function registerSkillTools(mcp, repo) {
         new_name: z.string().describe(SKILL_NAME_DESCRIPTION),
     }, async ({ name, new_name }) => {
         try {
-            const doc = repo.rename(name, new_name);
+            const doc = await repo.rename(name, new_name);
             return { content: [{ type: 'text', text: JSON.stringify(doc, null, 2) }] };
         }
         catch (err) {
@@ -157,19 +176,19 @@ export function registerSkillTools(mcp, repo) {
             .array(z.object({ name: z.string().describe('current skill name'), new_name: z.string().describe(SKILL_NAME_DESCRIPTION) }))
             .min(1),
     }, async ({ entries }) => {
-        const results = repo.bulkRename(entries);
+        const results = await repo.bulkRename(entries);
         return { content: [{ type: 'text', text: JSON.stringify(results, null, 2) }] };
     });
     mcp.tool('skill_set_paused', 'Pauses or resumes skills by name — a local-only toggle stored in this machine\'s SQLite cache, never written to SKILL.md, so it never touches the file on disk and never follows the skill to another machine\'s cache. Paused skills are hidden from skill_list/skill_search by default but stay fully intact and are still fetchable directly via skill_get/skill_bulk_get — use this to temporarily stop a skill from being surfaced during discovery without deprecating (retiring) it. Returns per-name success/failure so one bad name doesn\'t abort the batch.', {
         names: z.array(z.string()).min(1),
         paused: z.boolean().describe('true to pause (hide from skill_list/skill_search), false to resume'),
     }, async ({ names, paused }) => {
-        const results = repo.setPaused(names, paused);
+        const results = await repo.setPaused(names, paused);
         return { content: [{ type: 'text', text: JSON.stringify(results, null, 2) }] };
     });
     mcp.tool('skill_delete', 'Hard-deletes a skill by name — removes the whole skill folder (SKILL.md plus any scripts/references/assets), no tombstone.', { name: z.string() }, async ({ name }) => {
         try {
-            repo.delete(name);
+            await repo.delete(name);
             return { content: [{ type: 'text', text: `Deleted skill "${name}"` }] };
         }
         catch (err) {
@@ -177,7 +196,7 @@ export function registerSkillTools(mcp, repo) {
         }
     });
     mcp.tool('skill_bulk_delete', 'Hard-deletes many skills by name in one call — e.g. cleaning up a batch found via skill_search/skill_list. No tombstone. Returns per-name success/failure so one bad name doesn\'t abort the rest of the batch.', { names: z.array(z.string()).min(1) }, async ({ names }) => {
-        const results = repo.bulkDelete(names);
+        const results = await repo.bulkDelete(names);
         return { content: [{ type: 'text', text: JSON.stringify(results, null, 2) }] };
     });
 }

package/dist/src/store/sync.js

@@ -90,11 +90,11 @@ function folderForFile(sources, filePath) {
     return best?.name ?? '';
 }
 export function upsertFile(db, spec, filePath) {
-    const existing = db
+    const existingBySourcePath = db
         .prepare(`SELECT mtime_ms FROM ${spec.table} WHERE source_path = ?`)
         .get(filePath);
     const parsed = readMarkdownFile(filePath);
-    if (existing && existing.mtime_ms === parsed.mtimeMs)
+    if (existingBySourcePath && existingBySourcePath.mtime_ms === parsed.mtimeMs)
         return; // unchanged, skip reprocessing
     const frontmatter = spec.deriveFrontmatter
         ? spec.deriveFrontmatter(parsed.frontmatter, filePath, parsed.mtimeMs)
@@ -104,6 +104,23 @@ export function upsertFile(db, spec, filePath) {
         console.error(`[memory-bucket] skipping ${filePath}: missing required id field in frontmatter`);
         return;
     }
+    // id/name is the table's real PRIMARY KEY (used as the sole addressing
+    // handle across the whole public API - skill_get(name), memory_get(id),
+    // etc.), so a DIFFERENT file claiming the same id is a genuine name
+    // collision across configured folders/sources, not a re-scan of the same
+    // file. The ON CONFLICT(id) below would otherwise silently overwrite
+    // whichever row synced first - the first-synced item's row (and its
+    // full content) simply vanishes from the cache with no error and no way
+    // to address it, since id is the only lookup key this schema has.
+    // Refuse the overwrite and warn loudly instead: the first-synced item
+    // keeps working, the colliding one is visibly excluded rather than
+    // invisibly clobbering it.
+    const existingById = db.prepare(`SELECT source_path FROM ${spec.table} WHERE id = ?`).get(id);
+    if (existingById && existingById.source_path !== filePath) {
+        console.error(`[memory-bucket] SKIPPED indexing ${filePath}: id "${id}" already used by ${existingById.source_path} — ` +
+            `names must be unique across every configured folder. Rename one of these two files (or its frontmatter id/name) to resolve the collision.`);
+        return;
+    }
     const row = spec.toRow(frontmatter, filePath, parsed.mtimeMs);
     const folder = folderForFile(spec.sources, filePath);
     const cols = [...spec.columns, 'source_path', 'folder', 'body', 'mtime_ms'];