mcp-memory-bucket 0.8.2 → 0.8.4

package/dist/src/memory/repository.js

@@ -129,7 +129,13 @@ export class MemoryRepository {
         scanSingleFolder(this.db, this.syncSpec, folder.path);
         this.watcher?.add(folder.path);
     }
-    /** Unregisters a folder: stops watching it and drops its cached rows. Never touches files on disk. */
+    /**
+     * Unregisters a folder: stops watching it and drops its cached rows. Never touches the user's
+     * own files on disk. If `name` was a remote (folderfoo) source, also drops its RemoteFolder
+     * entry (so a same-named folder added afterwards, local or remote, isn't mistaken for the old
+     * connection by remoteFor()) and deletes its local mirror cache directory — that mirror is
+     * bucket-owned derived state, not user content, and gets recreated fresh on reconnect.
+     */
     removeFolder(name) {
         const idx = this.folders.findIndex((f) => f.name === name);
         if (idx === -1)
@@ -137,6 +143,11 @@ export class MemoryRepository {
         const [removed] = this.folders.splice(idx, 1);
         this.watcher?.unwatch(removed.path);
         unregisterFolder(this.db, 'memory_docs', name);
+        const remoteIdx = this.remoteFolders.findIndex((f) => f.name === name);
+        if (remoteIdx !== -1) {
+            const [removedRemote] = this.remoteFolders.splice(remoteIdx, 1);
+            fs.rmSync(removedRemote.mirrorDir, { recursive: true, force: true });
+        }
     }
     /**
      * Exact-match lookup by normalized key, per V0 (no fuzzy matching).

package/dist/src/server.js

@@ -38,13 +38,22 @@ const PORT = process.env.PORT ? Number(process.env.PORT) : 8767;
 const config = loadConfig();
 const db = openCache(config.cacheDbPath);
 const identity = new IdentityTracker(config.folderfooMode);
-const skillSpec = skillSyncSpec([{ name: 'builtin', path: builtinSkillsDir }, ...config.skillFolders]);
+// Built ONCE and shared by reference with SkillRepository below — registerRemoteFolder/addFolder
+// push into this same array in place, so skillSpec.sources (used by initialScan/watchSources/
+// startRemotePolling/pollOne's upsertFile) sees a folder added live, without a restart. Evaluating
+// this array literal separately for skillSpec and for `new SkillRepository(...)` (as before) creates
+// two distinct arrays that fall out of sync the moment a folder is added live: upsertFile's
+// folderForFile lookup against the stale skillSpec.sources then finds no match and stamps folder=""
+// on every doc from that folder — permanently, since upsertFile's mtime-based skip check means the
+// row is never reprocessed to pick up the correct value once the array is finally in sync.
+const skillFolders = [{ name: 'builtin', path: builtinSkillsDir }, ...config.skillFolders];
+const skillSpec = skillSyncSpec(skillFolders);
 const memorySpec = memorySyncSpec(config.memoryFolders);
 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], config.remoteSkillFolders, config.baseDir, identity);
+const skillRepo = new SkillRepository(db, skillFolders, config.remoteSkillFolders, config.baseDir, identity);
 const memoryRepo = new MemoryRepository(db, config.memoryFolders, config.remoteMemoryFolders, config.baseDir, identity);
 skillRepo.setWatcher(skillWatcher);
 memoryRepo.setWatcher(memoryWatcher);
@@ -63,14 +72,14 @@ if (config.skillFolders.length === 0 && config.memoryFolders.length === 0) {
 // this server — surfaced both in serverInfo.description and instructions so
 // clients that expose either to the model can make that association.
 const SERVER_DESCRIPTION = 'Also known as "memory bucket", "mem bucket", or "skill bucket" — if the user refers to this server by any of those names, they mean this one.';
-const SERVER_INSTRUCTIONS = `${SERVER_DESCRIPTION} Exposes skill_* (reusable coding patterns, stored as agentskills.io-standard SKILL.md folders) and memory_* (point-in-time working context — plans, specs, SQL, session summaries — looked up by key) tools, plus shared relocate/bucket_search/bucket_*_folder tools. Use skill_search/memory_search/bucket_search for full-text search over body content (not just metadata) — bucket_search when you don't know which bucket something landed in. Use bucket_list_folders to see what named source directories (folders) are configured before passing a folder argument elsewhere, and bucket_create_folder/bucket_delete_folder to register or unregister one. Most operations have a _bulk_ variant (bulk_get/bulk_create/bulk_update/bulk_delete/bulk_rename, relocate_bulk) that take a list and return per-item success/failure — prefer these over looping single calls when acting on more than one item. A memory doc's key can be changed in place via memory_update(id, key: ...) — no separate rename tool needed. Before calling any *_create/*_update/relocate tool, call skill_get("memory-bucket-authoring") first to learn the exact frontmatter schema — don't guess the shape. Also exposes memory_channel_read/memory_channel_post/list_memory_channels — a SEPARATE, ephemeral in-memory layer for live cross-agent coordination (a shared scratchpad/discussion channel by name), never written to disk and never indexed by memory_search/bucket_search; do not confuse these with the persisted memory_* docs above.`;
+const SERVER_INSTRUCTIONS = `${SERVER_DESCRIPTION} Exposes skill_* (reusable coding patterns, stored as agentskills.io-standard SKILL.md folders) and memory_* (point-in-time working context — plans, specs, SQL, session summaries — looked up by key) tools, plus shared relocate/bucket_search/bucket_*_folder tools. Use skill_search/memory_search/bucket_search for full-text search over body content (not just metadata) — bucket_search when you don't know which bucket something landed in. Use bucket_list_folders to see what named source directories (folders) are configured before passing a folder argument elsewhere, and bucket_create_folder/bucket_delete_folder to register or unregister one (bucket_delete_folder works for both local and remote folders). bucket_list_remote_folders/bucket_connect_remote_folder connect a folderfoo folder as a new source, once the user is logged in via the web UI. Most operations have a _bulk_ variant (bulk_get/bulk_create/bulk_update/bulk_delete/bulk_rename, relocate_bulk) that take a list and return per-item success/failure — prefer these over looping single calls when acting on more than one item. A memory doc's key can be changed in place via memory_update(id, key: ...) — no separate rename tool needed. Before calling any *_create/*_update/relocate tool, call skill_get("memory-bucket-authoring") first to learn the exact frontmatter schema — don't guess the shape. Also exposes memory_channel_read/memory_channel_post/list_memory_channels — a SEPARATE, ephemeral in-memory layer for live cross-agent coordination (a shared scratchpad/discussion channel by name), never written to disk and never indexed by memory_search/bucket_search; do not confuse these with the persisted memory_* docs above.`;
 function buildMcpServer() {
     const server = new McpServer({ name: 'memory-bucket', version: '0.1.0', description: SERVER_DESCRIPTION }, { capabilities: {}, instructions: SERVER_INSTRUCTIONS });
     registerSkillTools(server, skillRepo);
     registerMemoryTools(server, memoryRepo);
     registerRelocateTool(server, skillRepo, memoryRepo);
     registerSearchTool(server, db);
-    registerBucketFolderTools(server, config, skillRepo, memoryRepo, db, skillSpec, memorySpec);
+    registerBucketFolderTools(server, config, skillRepo, memoryRepo, db, skillSpec, memorySpec, identity);
     registerAttachmentTools(server, attachmentRepo);
     registerUiTool(server, PORT);
     registerMemoryChannelTools(server);

package/dist/src/shared/bucket-folder-tool.js

@@ -1,13 +1,18 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { z } from 'zod';
-import { saveFolder, removeFolder as removeFolderFromConfig, sanitizeFolderName } from '../config.js';
+import { saveFolder, saveRemoteFolder, removeFolder as removeFolderFromConfig, sanitizeFolderName, mirrorDirFor, } from '../config.js';
 import { initialScan } from '../store/sync.js';
+import { listFolders as listFolderfooFolders } from '../remote/folderfoo-client.js';
+import { pollOne } from '../remote/remote-sync.js';
+import { TENANT_ID } from './folderfoo-tenant.js';
 const KIND = z.enum(['skill', 'memory']);
-export function registerBucketFolderTools(mcp, config, skillRepo, memoryRepo, db, skillSpec, memorySpec) {
-    mcp.tool('bucket_list_folders', 'Lists the configured skill and memory folders (the named source directories skills/memory docs live under, e.g. "super-skills", "demo-skills", "builtin") — use this to see what folders exist before passing a `folder` argument to a create/list/search tool, or before adding/removing one.', {}, async () => {
-        const skill = skillRepo.listFolders().map((f) => ({ ...f, kind: 'skill' }));
-        const memory = memoryRepo.listFolders().map((f) => ({ ...f, kind: 'memory' }));
+export function registerBucketFolderTools(mcp, config, skillRepo, memoryRepo, db, skillSpec, memorySpec, identity) {
+    const repoFor = (kind) => (kind === 'skill' ? skillRepo : memoryRepo);
+    const specFor = (kind) => (kind === 'skill' ? skillSpec : memorySpec);
+    mcp.tool('bucket_list_folders', 'Lists the configured skill and memory folders (the named source directories skills/memory docs live under, e.g. "super-skills", "demo-skills", "builtin"), each tagged `remote: true/false` for whether it syncs with folderfoo — use this to see what folders exist before passing a `folder` argument to a create/list/search tool, or before adding/removing one. To see UNconnected folderfoo folders available to connect, use bucket_list_remote_folders instead.', {}, async () => {
+        const skill = skillRepo.listFoldersWithRemoteInfo().map((f) => ({ ...f, kind: 'skill' }));
+        const memory = memoryRepo.listFoldersWithRemoteInfo().map((f) => ({ ...f, kind: 'memory' }));
         return { content: [{ type: 'text', text: JSON.stringify({ skill, memory }, null, 2) }] };
     });
     mcp.tool('bucket_create_folder', 'Registers a new skill or memory folder: an existing absolute directory path becomes a new named source that skill_create/memory_create can target via `folder`. Scans it once and starts watching it live — never creates the directory itself, it must already exist.', {
@@ -35,7 +40,78 @@ export function registerBucketFolderTools(mcp, config, skillRepo, memoryRepo, db
             return { content: [{ type: 'text', text: err.message }], isError: true };
         }
     });
-    mcp.tool('bucket_delete_folder', 'Unregisters a skill or memory folder by name: stops watching it and drops its cached entries from the index. Never touches files on disk — the directory and its contents are left in place.', { kind: KIND, name: z.string() }, async ({ kind, name }) => {
+    mcp.tool('bucket_list_remote_folders', "Lists the current user's own folders on the connected folderfoo deployment, including ones not yet connected to this bucket — use this to pick a `folderPath` for bucket_connect_remote_folder. Each entry is tagged `connected` (the name it's already registered under, per kind, or null) so you don't connect the same remote folder twice. Errors with a clear message if folderfoo integration is off (needs --folderfoo-mode/FOLDERFOO_MODE) or nobody is logged in yet (log in via the web UI, bucket_open_ui, first — this tool cannot itself perform a folderfoo login).", {}, async () => {
+        if (config.folderfooMode === 'off' || !config.folderfooHost) {
+            return {
+                content: [{ type: 'text', text: 'folderfoo integration is off — restart with --folderfoo-mode dev|cloud (or set FOLDERFOO_MODE) to enable it' }],
+                isError: true,
+            };
+        }
+        const current = identity.current();
+        if (!current.username) {
+            return { content: [{ type: 'text', text: 'not logged in to folderfoo — open the web UI (bucket_open_ui) and log in first' }], isError: true };
+        }
+        try {
+            const server = config.folderfooHost;
+            const folders = await listFolderfooFolders(server, config.baseDir, TENANT_ID);
+            const connectedFor = (kind) => new Map(repoFor(kind)
+                .listRemoteFolders()
+                .filter((f) => f.server === server && f.tenantId === TENANT_ID)
+                .map((f) => [f.folderPath, f.name]));
+            const skillConnected = connectedFor('skill');
+            const memoryConnected = connectedFor('memory');
+            const annotated = folders.map((f) => ({
+                ...f,
+                connected: { skill: skillConnected.get(f.path) ?? null, memory: memoryConnected.get(f.path) ?? null },
+            }));
+            return { content: [{ type: 'text', text: JSON.stringify(annotated, null, 2) }] };
+        }
+        catch (err) {
+            return { content: [{ type: 'text', text: err.message }], isError: true };
+        }
+    });
+    mcp.tool('bucket_connect_remote_folder', "Connects one of the user's own folderfoo folders (see bucket_list_remote_folders for `folderPath` values) as a new skill or memory source — syncs like a folder added via bucket_create_folder, so skill_create/memory_create can target it via `folder` and edits push back to folderfoo automatically. Idempotent: if this exact folderPath is already connected under this kind, returns that existing folder instead of creating a duplicate. Same login requirement as bucket_list_remote_folders.", {
+        kind: KIND,
+        folderPath: z.string().describe("a `path` value from bucket_list_remote_folders ('' for the folderfoo root)"),
+        name: z.string().optional().describe("name for the folder; defaults to a sanitized version of folderPath's last segment"),
+    }, async ({ kind, folderPath, name }) => {
+        if (config.folderfooMode === 'off' || !config.folderfooHost) {
+            return {
+                content: [{ type: 'text', text: 'folderfoo integration is off — restart with --folderfoo-mode dev|cloud (or set FOLDERFOO_MODE) to enable it' }],
+                isError: true,
+            };
+        }
+        const current = identity.current();
+        if (!current.username) {
+            return { content: [{ type: 'text', text: 'not logged in to folderfoo — open the web UI (bucket_open_ui) and log in first' }], isError: true };
+        }
+        const server = config.folderfooHost;
+        const repo = repoFor(kind);
+        const already = repo.listRemoteFolders().find((f) => f.server === server && f.tenantId === TENANT_ID && f.folderPath === folderPath);
+        if (already) {
+            return {
+                content: [
+                    { type: 'text', text: JSON.stringify({ name: already.name, server, tenantId: TENANT_ID, folderPath, kind, alreadyConnected: true }, null, 2) },
+                ],
+            };
+        }
+        const folderName = sanitizeFolderName(name || folderPath.split('/').filter(Boolean).pop() || TENANT_ID);
+        if (!folderName) {
+            return { content: [{ type: 'text', text: 'could not derive a valid folder name — provide one explicitly' }], isError: true };
+        }
+        const mirrorDir = mirrorDirFor(config.baseDir, current.mode, current.username, folderName);
+        const remote = { name: folderName, server, tenantId: TENANT_ID, folderPath, mirrorDir, mode: current.mode, username: current.username };
+        try {
+            repo.registerRemoteFolder(remote);
+            saveRemoteFolder(config, kind, { name: folderName, server, tenantId: TENANT_ID, folderPath, mode: current.mode, username: current.username });
+            await pollOne(db, specFor(kind), remote, config.baseDir);
+            return { content: [{ type: 'text', text: JSON.stringify({ name: folderName, server, tenantId: TENANT_ID, folderPath, kind }, null, 2) }] };
+        }
+        catch (err) {
+            return { content: [{ type: 'text', text: err.message }], isError: true };
+        }
+    });
+    mcp.tool('bucket_delete_folder', 'Unregisters a skill or memory folder by name — works for both local and folderfoo-connected (remote) folders. Stops watching it and drops its cached entries from the index; never touches the user\'s own files, on disk or on folderfoo — for a remote folder, only its local mirror cache is deleted, which is rebuilt fresh if reconnected.', { kind: KIND, name: z.string() }, async ({ kind, name }) => {
         try {
             const repo = kind === 'skill' ? skillRepo : memoryRepo;
             repo.removeFolder(name);

package/dist/src/shared/folderfoo-tenant.js

@@ -0,0 +1,7 @@
+// memory-bucket's own fixed identity (X-Tenant-Id) as a folderfoo-consuming app — distinct from
+// which folderfoo TENANT'S DATA a given remote skill/memory folder pulls from (could be this same
+// tenant, or a different app's, e.g. mindfoo/bulletino). Has no node built-ins so it's safe to
+// import from both the server (registering a remote folder) and the client bundle (the connect-a-
+// folder modal) — the single source of truth for both, replacing what used to be two copies of the
+// same string.
+export const TENANT_ID = 'membkt';

package/dist/src/shared/relocate-tool.js

@@ -16,7 +16,10 @@ const overridesSchema = z
     tags: z.array(z.string()).optional(),
     status: statusSchema(['stable', 'beta', 'unreviewed', 'active', 'shipped', 'abandoned']).optional(),
     subfolder: z.string().optional().describe('optional subdirectory under the target folder'),
-    folder: z.string().optional().describe('which configured folder to write into; required if multiple folders exist for the target type'),
+    folder: z
+        .string()
+        .optional()
+        .describe('which configured folder to write into (a remote/folderfoo-connected folder works too — the file is pushed to folderfoo automatically); required if multiple folders exist for the target type'),
 })
     .optional();
 export function registerRelocateTool(mcp, skillRepo, memoryRepo) {

package/dist/src/skills/repository.js

@@ -132,7 +132,13 @@ export class SkillRepository {
         scanSingleFolder(this.db, this.syncSpec, folder.path);
         this.watcher?.add(folder.path);
     }
-    /** Unregisters a folder: stops watching it and drops its cached rows. Never touches files on disk. */
+    /**
+     * Unregisters a folder: stops watching it and drops its cached rows. Never touches the user's
+     * own files on disk. If `name` was a remote (folderfoo) source, also drops its RemoteFolder
+     * entry (so a same-named folder added afterwards, local or remote, isn't mistaken for the old
+     * connection by remoteFor()) and deletes its local mirror cache directory — that mirror is
+     * bucket-owned derived state, not user content, and gets recreated fresh on reconnect.
+     */
     removeFolder(name) {
         const idx = this.folders.findIndex((f) => f.name === name);
         if (idx <= 0)
@@ -140,6 +146,11 @@ export class SkillRepository {
         const [removed] = this.folders.splice(idx, 1);
         this.watcher?.unwatch(removed.path);
         unregisterFolder(this.db, 'skills', name);
+        const remoteIdx = this.remoteFolders.findIndex((f) => f.name === name);
+        if (remoteIdx !== -1) {
+            const [removedRemote] = this.remoteFolders.splice(remoteIdx, 1);
+            fs.rmSync(removedRemote.mirrorDir, { recursive: true, force: true });
+        }
     }
     /** `includePaused` defaults to false: paused skills are hidden from discovery (see setPaused). */
     list(query, folder, opts = {}) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-memory-bucket",
-  "version": "0.8.2",
+  "version": "0.8.4",
   "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": {

package/dist/src/shared/bucket-root-tool.js

@@ -1,66 +0,0 @@
-import fs from 'node:fs';
-import path from 'node:path';
-import { z } from 'zod';
-import { saveRoot, removeRoot as removeRootFromConfig, sanitizeRootName } from '../config.js';
-import { initialScan } from '../store/sync.js';
-const KIND = z.enum(['skill', 'memory']);
-export function registerBucketRootTools(mcp, config, skillRepo, memoryRepo, db, skillSpec, memorySpec) {
-    mcp.tool('bucket_list_roots', 'Lists the configured skill and memory roots (the named source directories skills/memory docs live under, e.g. "super-skills", "demo-skills", "builtin") — use this to see what roots exist before passing a `root` argument to a create/list/search tool, or before adding/removing one.', {}, async () => {
-        const skill = skillRepo.listRoots().map((r) => ({ ...r, kind: 'skill' }));
-        const memory = memoryRepo.listRoots().map((r) => ({ ...r, kind: 'memory' }));
-        return { content: [{ type: 'text', text: JSON.stringify({ skill, memory }, null, 2) }] };
-    });
-    mcp.tool('bucket_create_root', 'Registers a new skill or memory root: an existing absolute directory path becomes a new named source that skill_create/memory_create can target via `root`. Scans it once and starts watching it live — never creates the directory itself, it must already exist.', {
-        kind: KIND,
-        path: z.string().describe('absolute path to an existing directory'),
-        name: z.string().optional().describe('name for the root; defaults to a sanitized version of the directory\'s basename'),
-    }, async ({ kind, path: dirPath, name }) => {
-        try {
-            if (!path.isAbsolute(dirPath)) {
-                return { content: [{ type: 'text', text: 'path must be an absolute directory path' }], isError: true };
-            }
-            if (!fs.existsSync(dirPath) || !fs.statSync(dirPath).isDirectory()) {
-                return { content: [{ type: 'text', text: `not a directory: ${dirPath}` }], isError: true };
-            }
-            const rootName = sanitizeRootName(name || path.basename(dirPath));
-            if (!rootName) {
-                return { content: [{ type: 'text', text: 'could not derive a valid root name — provide one explicitly' }], isError: true };
-            }
-            const repo = kind === 'skill' ? skillRepo : memoryRepo;
-            repo.addRoot({ name: rootName, path: dirPath });
-            saveRoot(config, kind, { name: rootName, path: dirPath });
-            return { content: [{ type: 'text', text: JSON.stringify({ name: rootName, path: dirPath, kind }, null, 2) }] };
-        }
-        catch (err) {
-            return { content: [{ type: 'text', text: err.message }], isError: true };
-        }
-    });
-    mcp.tool('bucket_delete_root', 'Unregisters a skill or memory root by name: stops watching it and drops its cached entries from the index. Never touches files on disk — the directory and its contents are left in place.', { kind: KIND, name: z.string() }, async ({ kind, name }) => {
-        try {
-            const repo = kind === 'skill' ? skillRepo : memoryRepo;
-            repo.removeRoot(name);
-            removeRootFromConfig(config, kind, name);
-            return { content: [{ type: 'text', text: `Removed ${kind} root "${name}"` }] };
-        }
-        catch (err) {
-            return { content: [{ type: 'text', text: err.message }], isError: true };
-        }
-    });
-    mcp.tool('bucket_rebuild_cache', 'EMERGENCY USE ONLY. Wipes the entire SQLite cache (all skills, memory docs, the full-text search index, and the date index) and rebuilds it from scratch by rescanning every configured root from disk. Source markdown files on disk are never touched — this only affects the derived cache, which is always safe to discard and regenerate. Use this only when other tools return results that contradict what you can see in the actual files (e.g. stale search hits, a doc that clearly exists on disk but skill_get/memory_get can\'t find, or search_by_date returning wrong dates) and a normal create/update/relocate call hasn\'t resolved it — this is a last resort, not a routine maintenance step. Takes a moment to complete on a large root; nothing else should be called until it returns.', {}, async () => {
-        try {
-            db.exec(`DELETE FROM skills; DELETE FROM memory_docs; DELETE FROM search_index; DELETE FROM doc_dates;`);
-            initialScan(db, skillSpec);
-            initialScan(db, memorySpec);
-            const skillCount = db.prepare(`SELECT COUNT(*) AS n FROM skills`).get().n;
-            const memoryCount = db.prepare(`SELECT COUNT(*) AS n FROM memory_docs`).get().n;
-            return {
-                content: [
-                    { type: 'text', text: `Cache rebuilt from disk: ${skillCount} skill(s), ${memoryCount} memory doc(s) reindexed.` },
-                ],
-            };
-        }
-        catch (err) {
-            return { content: [{ type: 'text', text: err.message }], isError: true };
-        }
-    });
-}