mcp-memory-bucket 0.7.4 → 0.8.0

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'];
@@ -19,7 +20,7 @@ export function registerMemoryTools(mcp, repo) {
         return { content: [{ type: 'text', text: JSON.stringify(docs, null, 2) }] };
     });
     mcp.tool('memory_bulk_get', 'Fetches many memory docs by id in one call, including full markdown bodies — e.g. hydrating a batch of memory_search hits (which return ids, not keys). Missing ids are simply omitted from the result, not errors.', { ids: z.array(z.string()).min(1) }, async ({ ids }) => {
-        const docs = repo.bulkGet(ids);
+        const docs = await repo.bulkGet(ids);
         return { content: [{ type: 'text', text: JSON.stringify(docs, null, 2) }] };
     });
     mcp.tool('memory_list', 'Browses available memory keys (optionally filtered by a prefix) without needing to know the exact key upfront. Returns each key with its doc count.', { key_prefix: z.string().optional() }, async ({ key_prefix }) => {
@@ -52,7 +53,7 @@ export function registerMemoryTools(mcp, repo) {
         related_to: z.string().nullable().optional(),
         deprecated: z.boolean().optional().describe('marks docs as deprecated (or un-deprecates when false) — independent of status'),
     }, async ({ ids, add_tags, remove_tags, status, related_to, deprecated }) => {
-        const results = repo.bulkUpdate(ids, { add_tags, remove_tags, status, related_to, deprecated });
+        const results = await repo.bulkUpdate(ids, { add_tags, remove_tags, status, related_to, deprecated });
         return { content: [{ type: 'text', text: JSON.stringify(results, null, 2) }] };
     });
     mcp.tool('memory_create', `Writes a new memory doc (plan, spec, SQL, testing notes, discovery, etc.) into the memory folder under the given key. ${AUTHORING_SKILL_HINT}`, {
@@ -73,7 +74,7 @@ export function registerMemoryTools(mcp, repo) {
             const nearDuplicate = repo
                 .suggestKeys(key, 3)
                 .find((m) => stripKey(m.key) === strippedNew && m.key !== normalized);
-            const doc = repo.create({ key, key_type, doc_type, description, body, tags, status, related_to, subfolder, folder });
+            const doc = await repo.create({ key, key_type, doc_type, description, body, tags, status, related_to, subfolder, folder });
             const result = { ...doc };
             if (nearDuplicate) {
                 result.key_warning = `A similarly-formatted key "${nearDuplicate.key}" already exists with ${nearDuplicate.docCount} doc(s) — did you mean to use that key instead of "${normalized}"? This doc was still created under "${normalized}".`;
@@ -97,24 +98,42 @@ export function registerMemoryTools(mcp, repo) {
         ...(multiFolder ? { folder: z.string().describe(`which configured memory folder to write into: ${folderNames}`) } : {}),
     });
     mcp.tool('memory_bulk_create', `Writes many memory docs in one call — each entry is the same shape as memory_create's args. Returns per-key success/failure (with the new id on success) so one bad entry doesn't abort the rest of the batch. ${AUTHORING_SKILL_HINT}`, { entries: z.array(memoryEntrySchema).min(1) }, async ({ entries }) => {
-        const results = repo.bulkCreate(entries);
+        const results = await 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 {
-            const doc = repo.update(id, frontmatterFields, body);
-            return { content: [{ type: 'text', text: JSON.stringify(doc, null, 2) }] };
+            let diff;
+            if (body_edits) {
+                const existing = await 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 = await repo.update(id, 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 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 };
@@ -124,12 +143,12 @@ export function registerMemoryTools(mcp, repo) {
         ids: z.array(z.string()).min(1),
         paused: z.boolean().describe('true to pause (hide from memory_get/memory_search), false to resume'),
     }, async ({ ids, paused }) => {
-        const results = repo.setPaused(ids, paused);
+        const results = await repo.setPaused(ids, paused);
         return { content: [{ type: 'text', text: JSON.stringify(results, null, 2) }] };
     });
     mcp.tool('memory_delete', 'Hard-deletes a memory doc by id — removes the markdown file, no tombstone.', { id: z.string() }, async ({ id }) => {
         try {
-            repo.delete(id);
+            await repo.delete(id);
             return { content: [{ type: 'text', text: `Deleted memory doc "${id}"` }] };
         }
         catch (err) {
@@ -137,7 +156,7 @@ export function registerMemoryTools(mcp, repo) {
         }
     });
     mcp.tool('memory_bulk_delete', 'Hard-deletes many memory docs by id in one call — e.g. cleaning up a batch of abandoned docs found via memory_search. No tombstone. Returns per-id success/failure so one bad id doesn\'t abort the rest of the batch.', { ids: z.array(z.string()).min(1) }, async ({ ids }) => {
-        const results = repo.bulkDelete(ids);
+        const results = await repo.bulkDelete(ids);
         return { content: [{ type: 'text', text: JSON.stringify(results, null, 2) }] };
     });
     mcp.tool('memory_save_session', `Saves a summary of the current chat session as a memory doc (doc_type "session-summary"). Pass a summary, not a raw transcript. If key or description are omitted, ask the user for them rather than guessing. ${AUTHORING_SKILL_HINT}`, {
@@ -160,7 +179,7 @@ export function registerMemoryTools(mcp, repo) {
             };
         }
         try {
-            const doc = repo.create({
+            const doc = await repo.create({
                 key,
                 key_type: /^[A-Z]+-\d+$/i.test(key) ? 'ticket' : 'freeform',
                 doc_type: 'session-summary',

package/dist/src/remote/credentials.js

@@ -0,0 +1,31 @@
+import fs from 'node:fs';
+import path from 'node:path';
+function credentialsPath(baseDir) {
+    return path.join(baseDir, '.memory-bucket-credentials.json');
+}
+function readStore(baseDir) {
+    const file = credentialsPath(baseDir);
+    if (!fs.existsSync(file))
+        return {};
+    return JSON.parse(fs.readFileSync(file, 'utf-8'));
+}
+function writeStore(baseDir, store) {
+    // 0600: this file holds a live JWT, so it shouldn't be group/world-
+    // readable the way a config file might reasonably be.
+    fs.writeFileSync(credentialsPath(baseDir), JSON.stringify(store, null, 2) + '\n', { mode: 0o600 });
+}
+export function getCredential(baseDir, server) {
+    return readStore(baseDir)[server];
+}
+export function setCredential(baseDir, server, jwt) {
+    const store = readStore(baseDir);
+    store[server] = { jwt };
+    writeStore(baseDir, store);
+}
+export function clearCredential(baseDir, server) {
+    const store = readStore(baseDir);
+    if (!(server in store))
+        return;
+    delete store[server];
+    writeStore(baseDir, store);
+}

package/dist/src/remote/folderfoo-client.js

@@ -0,0 +1,149 @@
+import { getCredential, setCredential, clearCredential } from './credentials.js';
+/** Thrown when a folderfoo call fails auth (expired/invalid token, refresh also failed). Callers should surface this as "reconnect via the web UI", not retry silently. */
+export class FolderfooAuthError extends Error {
+    constructor(server) {
+        super(`folderfoo session expired for ${server} - reconnect via the web UI`);
+        this.name = 'FolderfooAuthError';
+    }
+}
+export async function login(server, username, password) {
+    const res = await fetch(`${server}/login`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ username, password }),
+    });
+    if (!res.ok) {
+        const body = await res.json().catch(() => ({}));
+        throw new Error(`folderfoo login failed: ${body.error ?? res.statusText}`);
+    }
+    const { token } = (await res.json());
+    return { jwt: token };
+}
+/**
+ * Reissues a fresh token from the current one - folderfoo's POST /refresh
+ * accepts even an expired bearer token (verified server-side with
+ * ignoreExpiration: true) and reissues a new one as long as the original
+ * login is within its age window (origIat-based). There is no separate
+ * refresh-token concept to pass here - see credentials.ts's doc comment.
+ */
+async function refresh(server, jwt) {
+    const res = await fetch(`${server}/refresh`, {
+        method: 'POST',
+        headers: { authorization: `Bearer ${jwt}` },
+    });
+    if (!res.ok)
+        throw new FolderfooAuthError(server);
+    const { token } = (await res.json());
+    return token;
+}
+/**
+ * Resolves a usable, current JWT for `server`: returns the stored one, or
+ * throws FolderfooAuthError if none is stored (the caller must direct the
+ * user through the web UI's login flow - this module never prompts for
+ * credentials itself). Does NOT proactively refresh; callers hit this once
+ * per call and rely on withAuth's 401-retry-once instead, since a token
+ * that still works needs no refresh round trip.
+ */
+function requireCredential(server, baseDir) {
+    const credential = getCredential(baseDir, server);
+    if (!credential)
+        throw new FolderfooAuthError(server);
+    return credential.jwt;
+}
+/**
+ * Wraps one folderfoo call: on a 401, attempts exactly one refresh-and-
+ * retry (persisting the refreshed token so subsequent calls reuse it),
+ * and on a second 401 (or a refresh failure) clears the stored credential
+ * and throws FolderfooAuthError - per the settled design, a failure here
+ * must surface loudly, never fall back to stale cached data or queue
+ * silently.
+ */
+async function withAuth(server, baseDir, call, parse) {
+    const jwt = requireCredential(server, baseDir);
+    let res = await call(jwt);
+    if (res.status === 401) {
+        let refreshed;
+        try {
+            refreshed = await refresh(server, jwt);
+        }
+        catch {
+            clearCredential(baseDir, server);
+            throw new FolderfooAuthError(server);
+        }
+        setCredential(baseDir, server, refreshed);
+        res = await call(refreshed);
+        if (res.status === 401) {
+            clearCredential(baseDir, server);
+            throw new FolderfooAuthError(server);
+        }
+    }
+    if (!res.ok) {
+        const body = await res.json().catch(() => ({}));
+        throw new Error(`folderfoo request failed (${res.status}): ${body.error ?? res.statusText}`);
+    }
+    return parse(res);
+}
+function folderQuery(tenantId, folderPath, extra) {
+    const params = new URLSearchParams({ folderPath, ...extra });
+    return params.toString();
+}
+export async function getLastChanged(server, baseDir, tenantId, folderPath) {
+    return withAuth(server, baseDir, (jwt) => fetch(`${server}/folders/last-changed?${folderQuery(tenantId, folderPath)}`, {
+        headers: { authorization: `Bearer ${jwt}`, 'x-tenant-id': tenantId },
+    }), async (res) => (await res.json()).lastChanged);
+}
+/**
+ * Lists the caller's own folderfoo folders (flat list of full paths, each
+ * with a createdAt timestamp - folderfoo's own GET /folders response
+ * shape) via folderfoo's existing GET /folders — used by the "connect a
+ * folderfoo folder" UI to offer a picker instead of requiring the user to
+ * type a raw folder path. Own folders only (no owner param) - browsing
+ * INTO a shared folder someone else owns is a separate, not-yet-exposed
+ * flow.
+ */
+export async function listFolders(server, baseDir, tenantId) {
+    return withAuth(server, baseDir, (jwt) => fetch(`${server}/folders`, { headers: { authorization: `Bearer ${jwt}`, 'x-tenant-id': tenantId } }), (res) => res.json());
+}
+export async function getChangedSince(server, baseDir, tenantId, folderPath, since) {
+    return withAuth(server, baseDir, (jwt) => fetch(`${server}/folders/changed-since?${folderQuery(tenantId, folderPath, { since: String(since) })}`, {
+        headers: { authorization: `Bearer ${jwt}`, 'x-tenant-id': tenantId },
+    }), async (res) => (await res.json()).files);
+}
+// folders.js's parseFolderFilenameParam (folderfoo's server) is ambiguous
+// for a bare single-segment own-folder path: "work:name" parses as
+// owner="work", not folderPath="work" (a folder path is only
+// unambiguously recognized when it contains "/"). The always-safe form is
+// the explicit-empty-owner 3-part grammar, ":folder/path:name" - folderfoo
+// itself uses this same form in its own sharing tests for exactly this
+// reason. Always use it here rather than only for the single-segment case,
+// so this client doesn't need to special-case folder depth.
+function filenameParam(folderPath, name) {
+    return folderPath ? `:${encodeURIComponent(folderPath)}:${name}` : name;
+}
+/**
+ * Joins a RemoteFolder's own folderPath (its actual location on folderfoo,
+ * e.g. "memz") with a path relative to the LOCAL mirror directory (e.g. a
+ * subfolder the user created inside that mirror, or "." for the mirror's
+ * own root). Repository call sites must always route through this rather
+ * than passing the mirror-relative path alone - a bug where every remote
+ * write dropped the RemoteFolder's own folderPath entirely (writing to the
+ * user's folderfoo ROOT instead of the connected folder) shipped once
+ * already because each of 4 call sites recomputed this by hand.
+ */
+export function joinRemoteFolderPath(remoteFolderPath, mirrorRelativeDir) {
+    if (mirrorRelativeDir === '.' || mirrorRelativeDir === '')
+        return remoteFolderPath;
+    return remoteFolderPath ? `${remoteFolderPath}/${mirrorRelativeDir}` : mirrorRelativeDir;
+}
+/** Reads one file's raw content via GET /data/:filename. */
+export async function readFile(server, baseDir, tenantId, folderPath, name) {
+    return withAuth(server, baseDir, (jwt) => fetch(`${server}/data/${filenameParam(folderPath, name)}`, { headers: { authorization: `Bearer ${jwt}`, 'x-tenant-id': tenantId } }), (res) => res.text());
+}
+/** Writes one file's raw content via POST /save/:filename. */
+export async function writeFile(server, baseDir, tenantId, folderPath, name, content) {
+    await withAuth(server, baseDir, (jwt) => fetch(`${server}/save/${filenameParam(folderPath, name)}`, {
+        method: 'POST',
+        headers: { authorization: `Bearer ${jwt}`, 'x-tenant-id': tenantId, 'content-type': 'text/markdown' },
+        body: content,
+    }), async () => undefined);
+}

package/dist/src/remote/remote-sync.js

@@ -0,0 +1,176 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { upsertFile, removeFile, walkMarkdownFiles } from '../store/sync.js';
+import { getLastChanged, getChangedSince, readFile, FolderfooAuthError } from './folderfoo-client.js';
+// Fixed for every remote source in v1 - no per-source tuning knob, per the
+// settled design (Q15 in the grilling session).
+const POLL_INTERVAL_MS = 60_000;
+/**
+ * Local, per-source last-synced watermark - NOT the sqlite cache itself
+ * (that's a completely separate concept, mtime_ms per cached row). This is
+ * a small sidecar file recording "the last folderfoo last-changed value
+ * this poller has successfully synced up through", so a restart doesn't
+ * re-pull everything from since=0.
+ */
+function watermarkPath(mirrorDir) {
+    return path.join(mirrorDir, '.last-synced');
+}
+function readLocalWatermark(mirrorDir) {
+    try {
+        return Number(fs.readFileSync(watermarkPath(mirrorDir), 'utf-8')) || 0;
+    }
+    catch {
+        return 0;
+    }
+}
+function writeLocalWatermark(mirrorDir, value) {
+    fs.mkdirSync(mirrorDir, { recursive: true });
+    fs.writeFileSync(watermarkPath(mirrorDir), String(value));
+}
+/**
+ * folderfoo's GET /folders/changed-since (and GET /folders in general)
+ * report folderPath ABSOLUTE FROM THE TENANT ROOT (server.js's walk()
+ * seeds its relPath accumulator with the queried folderPath itself) - e.g.
+ * querying folderPath=memz for a root-level file returns folderPath:
+ * "memz", not "". That's a DIFFERENT coordinate system than mirror-
+ * relative (where the mirror root already IS memz, so a root-level file's
+ * mirror-relative dir is ""). Joining a tenant-root-absolute folderPath
+ * directly onto folder.mirrorDir double-nests it (mirrorDir/memz/...
+ * instead of mirrorDir/...) - this strips remote.folderPath back off to
+ * recover the true mirror-relative subpath. Every caller that turns a
+ * changed-since response entry into a local mirror path must go through
+ * this, not path.join the raw folderPath directly.
+ */
+function toMirrorRelativeDir(remoteFolderPath, absoluteFolderPath) {
+    if (!absoluteFolderPath)
+        return '';
+    if (absoluteFolderPath === remoteFolderPath)
+        return '';
+    if (remoteFolderPath && absoluteFolderPath.startsWith(`${remoteFolderPath}/`)) {
+        return absoluteFolderPath.slice(remoteFolderPath.length + 1);
+    }
+    // Shouldn't happen (changed-since was queried with remoteFolderPath, so
+    // every entry should be that path or nested under it) - fall back to the
+    // raw value rather than silently losing the file, but this indicates a
+    // mismatch worth knowing about.
+    console.error(`[memory-bucket] unexpected folderPath "${absoluteFolderPath}" from folderfoo outside queried folder "${remoteFolderPath}" - using it as-is`);
+    return absoluteFolderPath;
+}
+/**
+ * Reconciles deletions: getChangedSince only reports additions/
+ * modifications (files with mtime > since), never "this file no longer
+ * exists" - there's no tombstone protocol on the folderfoo side (see the
+ * implementation plan's flagged gap). Resolved here via a full-listing
+ * comparison instead: ask folderfoo for every file under the folder
+ * (changed-since?since=0, which is exactly "everything"), diff that
+ * against what's currently mirrored on disk, and remove any mirror file
+ * that's no longer in the remote listing. Run once per poll tick
+ * alongside the incremental pull, not in place of it - the incremental
+ * pull still avoids re-fetching unchanged file CONTENT, this only avoids
+ * missing deletions.
+ */
+async function reconcileDeletions(db, spec, folder, credentialsBaseDir) {
+    const remoteFiles = await getChangedSince(folder.server, credentialsBaseDir, folder.tenantId, folder.folderPath, 0);
+    const remoteRelPaths = new Set(remoteFiles.map((f) => {
+        const mirrorRelativeDir = toMirrorRelativeDir(folder.folderPath, f.folderPath);
+        return mirrorRelativeDir ? path.join(mirrorRelativeDir, f.name) : f.name;
+    }));
+    if (!fs.existsSync(folder.mirrorDir))
+        return;
+    for (const mirrorFilePath of walkMarkdownFiles(folder.mirrorDir)) {
+        const relPath = path.relative(folder.mirrorDir, mirrorFilePath);
+        // remoteFiles' entries are keyed by folderfoo's own filename grammar
+        // (no .md suffix - folderfoo doesn't know about markdown, it stores
+        // opaque names), while the mirror stores real .md files so upsertFile/
+        // matchesFile work unchanged - strip the extension before comparing.
+        const relPathNoExt = relPath.endsWith('.md') ? relPath.slice(0, -3) : relPath;
+        if (!remoteRelPaths.has(relPathNoExt)) {
+            fs.unlinkSync(mirrorFilePath);
+            removeFile(db, spec.table, mirrorFilePath);
+        }
+    }
+}
+async function pullFile(db, spec, folder, credentialsBaseDir, changedFile) {
+    // changedFile.folderPath is tenant-root-absolute (folderfoo's own
+    // convention - see toMirrorRelativeDir's doc comment), so it's the
+    // correct value to pass straight through to readFile (folderfoo expects
+    // that same absolute form for GET /data/:filename), but it must be
+    // converted to mirror-relative before joining onto folder.mirrorDir.
+    const content = await readFile(folder.server, credentialsBaseDir, folder.tenantId, changedFile.folderPath, changedFile.name);
+    const mirrorRelativeDir = toMirrorRelativeDir(folder.folderPath, changedFile.folderPath);
+    const relPath = mirrorRelativeDir ? path.join(mirrorRelativeDir, changedFile.name) : changedFile.name;
+    const mirrorPath = path.join(folder.mirrorDir, `${relPath}.md`);
+    fs.mkdirSync(path.dirname(mirrorPath), { recursive: true });
+    fs.writeFileSync(mirrorPath, content);
+    // Preserves the remote mtime on the mirror file so upsertFile's own
+    // mtime-based skip check (existing.mtime_ms === parsed.mtimeMs) stays
+    // meaningful on a later poll tick, rather than every mirrored file
+    // always reporting "just now" and getting needlessly reprocessed.
+    const mtimeDate = new Date(changedFile.mtime);
+    fs.utimesSync(mirrorPath, mtimeDate, mtimeDate);
+    if (spec.matchesFile(mirrorPath))
+        upsertFile(db, spec, mirrorPath);
+}
+/**
+ * credentialsBaseDir is the memory-bucket PROCESS's own base directory
+ * (where memory-bucket.config.json and .memory-bucket-credentials.json
+ * live) - deliberately NOT folder.mirrorDir, which is just this one
+ * source's local content cache. All remote sources share one credentials
+ * file at credentialsBaseDir, keyed by server URL (see credentials.ts).
+ */
+export async function pollOne(db, spec, folder, credentialsBaseDir, options = {}) {
+    try {
+        const lastChanged = await getLastChanged(folder.server, credentialsBaseDir, folder.tenantId, folder.folderPath);
+        const localWatermark = readLocalWatermark(folder.mirrorDir);
+        // force (manual resync, or rebuild-cache) always does real work,
+        // including reconcileDeletions - a user explicitly asking to resync
+        // shouldn't silently no-op just because folderfoo's watermark happens
+        // to equal what we last saw; the whole point of a manual resync is to
+        // re-verify against the live state, not trust the cheap check alone.
+        if (!options.force && lastChanged <= localWatermark)
+            return; // cheap path: nothing changed since our last sync, no listing call
+        const changed = await getChangedSince(folder.server, credentialsBaseDir, folder.tenantId, folder.folderPath, localWatermark);
+        for (const file of changed) {
+            await pullFile(db, spec, folder, credentialsBaseDir, file);
+        }
+        await reconcileDeletions(db, spec, folder, credentialsBaseDir);
+        writeLocalWatermark(folder.mirrorDir, lastChanged);
+    }
+    catch (err) {
+        if (err instanceof FolderfooAuthError) {
+            // Per the settled design: fail loudly per-call, but a poll tick
+            // failing auth shouldn't crash the whole poller loop - the next
+            // tick tries again (and any live skill_get/memory_get call against
+            // this source will surface its own FolderfooAuthError directly to
+            // the caller regardless of poller state).
+            console.error(`[memory-bucket] ${err.message}`);
+            return;
+        }
+        throw err;
+    }
+}
+export function startRemotePolling(db, spec, remoteFolders, credentialsBaseDir) {
+    const byName = new Map(remoteFolders.map((f) => [f.name, f]));
+    const interval = setInterval(() => {
+        for (const folder of remoteFolders) {
+            pollOne(db, spec, folder, credentialsBaseDir).catch((err) => console.error(`[memory-bucket] remote poll failed for ${folder.name}:`, err));
+        }
+    }, POLL_INTERVAL_MS);
+    // Node's default keep-alive behavior would hold the process open just for
+    // this interval - unref so remote polling never blocks a clean process exit.
+    interval.unref();
+    return {
+        stop: () => clearInterval(interval),
+        resyncNow: async (folderName) => {
+            const folder = byName.get(folderName);
+            if (!folder)
+                throw new Error(`no remote source configured with name "${folderName}"`);
+            await pollOne(db, spec, folder, credentialsBaseDir, { force: true });
+        },
+        resyncAll: async () => {
+            for (const folder of remoteFolders) {
+                await pollOne(db, spec, folder, credentialsBaseDir, { force: true });
+            }
+        },
+    };
+}

package/dist/src/server.js

@@ -19,6 +19,7 @@ import { buildWebRouter } from './web/routes.js';
 import { registerUiTool } from './web/ui-tool.js';
 import { registerMemoryChannelTools } from './channels/tools.js';
 import { startChannelSweep } from './channels/store.js';
+import { startRemotePolling } from './remote/remote-sync.js';
 // server.ts is rebuilt from `buildMcpServer()` on every /mcp request (see below),
 // so tool schemas (which conditionally include `folder` based on folder count) always
 // reflect the current folders — no restart needed after an add/remove-folder call.
@@ -41,11 +42,17 @@ initialScan(db, skillSpec);
 initialScan(db, memorySpec);
 const skillWatcher = watchSources(db, skillSpec);
 const memoryWatcher = watchSources(db, memorySpec);
-const skillRepo = new SkillRepository(db, [{ name: 'builtin', path: builtinSkillsDir }, ...config.skillFolders]);
-const memoryRepo = new MemoryRepository(db, config.memoryFolders);
+const skillRepo = new SkillRepository(db, [{ name: 'builtin', path: builtinSkillsDir }, ...config.skillFolders], config.remoteSkillFolders, config.baseDir);
+const memoryRepo = new MemoryRepository(db, config.memoryFolders, config.remoteMemoryFolders, config.baseDir);
 skillRepo.setWatcher(skillWatcher);
 memoryRepo.setWatcher(memoryWatcher);
 const attachmentRepo = new AttachmentRepository(memoryRepo, skillRepo);
+// Remote sources have no filesystem to watch (chokidar doesn't apply) - a
+// fixed-interval poller stands in for watchSources above, pulling changes
+// into each remote source's local mirror directory and reusing the exact
+// same upsertFile/removeFile path a local file-watch event would.
+const remoteSkillPoller = config.remoteSkillFolders.length > 0 ? startRemotePolling(db, skillSpec, config.remoteSkillFolders, config.baseDir) : undefined;
+const remoteMemoryPoller = config.remoteMemoryFolders.length > 0 ? startRemotePolling(db, memorySpec, config.remoteMemoryFolders, config.baseDir) : undefined;
 if (config.skillFolders.length === 0 && config.memoryFolders.length === 0) {
     console.error(`[memory-bucket] no folders configured — open http://localhost:${PORT} to add one`);
 }
@@ -70,7 +77,7 @@ function buildMcpServer() {
 startChannelSweep((name) => console.error(`[memory-bucket] sweeping idle memory channel: ${name}`));
 const app = express();
 app.use(express.json());
-app.use(buildWebRouter(db, config, skillRepo, memoryRepo, skillSpec, memorySpec));
+app.use(buildWebRouter(db, config, skillRepo, memoryRepo, skillSpec, memorySpec, { skill: remoteSkillPoller, memory: remoteMemoryPoller }));
 app.use(express.static(path.join(packageRoot, 'dist', 'client')));
 app.post('/mcp', async (req, res) => {
     const server = buildMcpServer();
@@ -98,10 +105,18 @@ app.delete('/mcp', methodNotAllowed);
 app.listen(PORT, () => {
     console.error(`[memory-bucket] MCP server listening on http://localhost:${PORT}/mcp`);
     console.error(`[memory-bucket] UI available at http://localhost:${PORT}`);
+    console.error(`[memory-bucket] folderfoo integration: ${config.folderfooMode}${config.folderfooHost ? ` (${config.folderfooHost})` : ''}` +
+        (config.folderfooMode === 'off' ? ' — pass --folderfoo-mode dev|cloud (or set FOLDERFOO_MODE) to enable' : ''));
     console.error(`[memory-bucket] skill folders: ${config.skillFolders.map((f) => `${f.name}=${f.path}`).join(', ') || '(none)'}`);
     console.error(`[memory-bucket] memory folders: ${config.memoryFolders.map((f) => `${f.name}=${f.path}`).join(', ') || '(none)'}`);
+    if (config.remoteSkillFolders.length > 0 || config.remoteMemoryFolders.length > 0) {
+        console.error(`[memory-bucket] remote (folderfoo) skill folders: ${config.remoteSkillFolders.map((f) => `${f.name}@${f.server}`).join(', ') || '(none)'}`);
+        console.error(`[memory-bucket] remote (folderfoo) memory folders: ${config.remoteMemoryFolders.map((f) => `${f.name}@${f.server}`).join(', ') || '(none)'}`);
+    }
 });
 process.on('SIGINT', () => {
+    remoteSkillPoller?.stop();
+    remoteMemoryPoller?.stop();
     db.close();
     process.exit(0);
 });

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/shared/relocate-tool.js

@@ -26,7 +26,7 @@ export function registerRelocateTool(mcp, skillRepo, memoryRepo) {
         keep_original: z.boolean().optional().describe('if true, copies instead of moving (default: move)'),
         overrides: overridesSchema,
     }, async (opts) => {
-        const result = relocate(opts, skillRepo, memoryRepo);
+        const result = await relocate(opts, skillRepo, memoryRepo);
         return {
             content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
             isError: !result.moved,
@@ -42,7 +42,7 @@ export function registerRelocateTool(mcp, skillRepo, memoryRepo) {
         }))
             .min(1),
     }, async ({ entries }) => {
-        const results = relocateMany(entries, skillRepo, memoryRepo);
+        const results = await relocateMany(entries, skillRepo, memoryRepo);
         return { content: [{ type: 'text', text: JSON.stringify(results, null, 2) }] };
     });
 }