mcp-memory-bucket 0.5.3 → 0.5.4

package/dist/client/index.html

@@ -27,7 +27,7 @@
     :root[data-theme='dark'] { color-scheme: dark; }
     body { font-family: system-ui, sans-serif; margin: 0; background: var(--bg); color: var(--fg); }
   </style>
-  <script type="module" crossorigin src="/assets/index-CqgDoHFV.js"></script>
+  <script type="module" crossorigin src="/assets/index-6BCcM6pL.js"></script>
 </head>
 <body>
   <mem-bucket-app></mem-bucket-app>

package/dist/src/config.js

@@ -12,8 +12,8 @@ function readConfigFile(configPath) {
 function nameFromPath(p) {
     return path.basename(p);
 }
-function resolveRoots(entries, baseDir) {
-    const roots = entries.map((entry) => {
+function resolveFolders(entries, baseDir) {
+    const folders = entries.map((entry) => {
         if (typeof entry === 'string') {
             return { name: nameFromPath(entry), path: path.resolve(baseDir, entry) };
         }
@@ -21,39 +21,39 @@ function resolveRoots(entries, baseDir) {
     });
     // de-dupe by resolved path (e.g. default + explicit config both pointing at ./skills)
     const seen = new Set();
-    return roots.filter((r) => (seen.has(r.path) ? false : (seen.add(r.path), true)));
+    return folders.filter((f) => (seen.has(f.path) ? false : (seen.add(f.path), true)));
 }
 export function loadConfig(cwd = process.cwd(), argv = process.argv) {
     const explicitDir = memoryDirFlag(argv) ?? process.env.MEMORY_BUCKET_DIR;
     const baseDir = explicitDir ? path.resolve(cwd, explicitDir) : cwd;
     // The config file lives alongside the cache DB in baseDir (which is cwd
     // itself unless --memory-dir/MEMORY_BUCKET_DIR points elsewhere) — this
-    // must match where saveRoot/removeRoot write back to.
+    // must match where saveFolder/removeFolder write back to.
     const configPath = path.join(baseDir, 'memory-bucket.config.json');
     const overrides = readConfigFile(configPath);
     // Without an explicit config, only default to ./skills or ./docs when that
     // directory already exists on disk — otherwise a genuinely fresh directory
-    // should report zero roots and trigger the first-run "add a root" UI,
+    // should report zero folders and trigger the first-run "add a folder" UI,
     // rather than silently registering a directory that was never created.
     const defaultSkillSources = overrides.skill_sources ?? (fs.existsSync(path.resolve(baseDir, './skills')) ? ['./skills'] : []);
     const defaultMemorySources = overrides.memory_sources ?? (fs.existsSync(path.resolve(baseDir, './docs')) ? ['./docs'] : []);
-    const skillRoots = resolveRoots(defaultSkillSources, baseDir);
-    const memoryRoots = resolveRoots(defaultMemorySources, baseDir);
+    const skillFolders = resolveFolders(defaultSkillSources, baseDir);
+    const memoryFolders = resolveFolders(defaultMemorySources, baseDir);
     return {
-        skillRoots,
-        memoryRoots,
+        skillFolders,
+        memoryFolders,
         cacheDbPath: path.join(baseDir, '.memory-bucket-cache.sqlite'),
         configPath,
         baseDir,
     };
 }
 /**
- * Appends a new named root to the config file's skill_sources/memory_sources array,
+ * Appends a new named folder to the config file's skill_sources/memory_sources array,
  * creating the file if absent. Existing entries (bare strings or objects) are left
  * untouched — this only ever appends, never rewrites/normalizes prior entries.
  * Path is stored relative to baseDir when possible, for a portable config file.
  */
-export function saveRoot(config, kind, root) {
+export function saveFolder(config, kind, folder) {
     const current = readConfigFile(config.configPath);
     const key = kind === 'skill' ? 'skill_sources' : 'memory_sources';
     // Only append to whatever's already in the file — never inject the
@@ -61,15 +61,15 @@ export function saveRoot(config, kind, root) {
     // load time (loadConfig), not stored; writing it here would silently turn
     // an implicit default into an explicit, possibly-unwanted config entry.
     const existing = current[key] ?? [];
-    const storedPath = path.isAbsolute(root.path) ? path.relative(config.baseDir, root.path) || '.' : root.path;
+    const storedPath = path.isAbsolute(folder.path) ? path.relative(config.baseDir, folder.path) || '.' : folder.path;
     const next = {
         ...current,
-        [key]: [...existing, { name: root.name, path: storedPath }],
+        [key]: [...existing, { name: folder.name, path: storedPath }],
     };
     fs.writeFileSync(config.configPath, JSON.stringify(next, null, 2) + '\n');
 }
-/** Lowercase-hyphenate a folder-derived root name, same shape as skill names. */
-export function sanitizeRootName(raw) {
+/** Lowercase-hyphenate a folder-derived name, same shape as skill names. */
+export function sanitizeFolderName(raw) {
     return raw
         .trim()
         .toLowerCase()
@@ -78,11 +78,11 @@ export function sanitizeRootName(raw) {
         .slice(0, 64);
 }
 /**
- * Removes a named root from the config file by name. Matches both explicit
+ * Removes a named folder from the config file by name. Matches both explicit
  * {name, path} entries and bare-string entries (via their derived name).
  * No-op if the name isn't found (e.g. it only ever existed in-memory).
  */
-export function removeRoot(config, kind, name) {
+export function removeFolder(config, kind, name) {
     const current = readConfigFile(config.configPath);
     const key = kind === 'skill' ? 'skill_sources' : 'memory_sources';
     const existing = current[key];

package/dist/src/memory/repository.js

@@ -4,7 +4,7 @@ import { randomUUID } from 'node:crypto';
 import { writeMarkdownFile } from '../store/markdown-file.js';
 import { slugify } from '../store/slug.js';
 import { resolveWithinBase } from '../store/safe-path.js';
-import { upsertFile, removeFile, scanSingleRoot, unregisterRoot, memorySyncSpec } from '../store/sync.js';
+import { upsertFile, removeFile, scanSingleFolder, unregisterFolder, memorySyncSpec } from '../store/sync.js';
 import { SearchQueryError } from '../store/search.js';
 import { normalizeKey } from '../types.js';
 function rowToDoc(row) {
@@ -21,59 +21,59 @@ function rowToDoc(row) {
         paused: !!row.paused,
         created_at: row.created_at ?? undefined,
         source_path: row.source_path,
-        root: row.root,
+        folder: row.folder,
         body: row.body,
     };
 }
 export class MemoryRepository {
     db;
-    roots;
+    folders;
     syncSpec;
     watcher;
-    constructor(db, roots) {
+    constructor(db, folders) {
         this.db = db;
-        this.roots = roots;
-        this.syncSpec = memorySyncSpec(roots);
+        this.folders = folders;
+        this.syncSpec = memorySyncSpec(folders);
     }
-    /** Attaches the live chokidar watcher so addRoot/removeRoot can mutate it without a restart. */
+    /** Attaches the live chokidar watcher so addFolder/removeFolder can mutate it without a restart. */
     setWatcher(watcher) {
         this.watcher = watcher;
     }
-    listRoots() {
-        return [...this.roots];
+    listFolders() {
+        return [...this.folders];
     }
-    resolveRoot(rootName) {
-        if (rootName) {
-            const found = this.roots.find((r) => r.name === rootName);
+    resolveFolder(folderName) {
+        if (folderName) {
+            const found = this.folders.find((f) => f.name === folderName);
             if (!found) {
-                throw new Error(`unknown memory root "${rootName}" — valid roots: ${this.roots.map((r) => r.name).join(', ') || '(none configured)'}`);
+                throw new Error(`unknown memory folder "${folderName}" — valid folders: ${this.folders.map((f) => f.name).join(', ') || '(none configured)'}`);
             }
             return found;
         }
-        if (this.roots.length === 1)
-            return this.roots[0];
-        if (this.roots.length === 0) {
-            throw new Error('no memory root configured — add one first (see bucket_open_ui)');
+        if (this.folders.length === 1)
+            return this.folders[0];
+        if (this.folders.length === 0) {
+            throw new Error('no memory folder configured — add one first (see bucket_open_ui)');
         }
-        throw new Error(`multiple memory roots configured — specify root: one of ${this.roots.map((r) => r.name).join(', ')}`);
+        throw new Error(`multiple memory folders configured — specify folder: one of ${this.folders.map((f) => f.name).join(', ')}`);
     }
-    /** Registers a new root: appends it, scans it once, and starts watching it live. */
-    addRoot(root) {
-        if (this.roots.some((r) => r.name === root.name)) {
-            throw new Error(`a memory root named "${root.name}" already exists`);
+    /** 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)) {
+            throw new Error(`a memory folder named "${folder.name}" already exists`);
         }
-        this.roots.push(root);
-        scanSingleRoot(this.db, this.syncSpec, root.path);
-        this.watcher?.add(root.path);
+        this.folders.push(folder);
+        scanSingleFolder(this.db, this.syncSpec, folder.path);
+        this.watcher?.add(folder.path);
     }
-    /** Unregisters a root: stops watching it and drops its cached rows. Never touches files on disk. */
-    removeRoot(name) {
-        const idx = this.roots.findIndex((r) => r.name === name);
+    /** Unregisters a folder: stops watching it and drops its cached rows. Never touches files on disk. */
+    removeFolder(name) {
+        const idx = this.folders.findIndex((f) => f.name === name);
         if (idx === -1)
-            throw new Error(`memory root "${name}" not found`);
-        const [removed] = this.roots.splice(idx, 1);
+            throw new Error(`memory folder "${name}" not found`);
+        const [removed] = this.folders.splice(idx, 1);
         this.watcher?.unwatch(removed.path);
-        unregisterRoot(this.db, 'memory_docs', name);
+        unregisterFolder(this.db, 'memory_docs', name);
     }
     /**
      * Exact-match lookup by normalized key, per V0 (no fuzzy matching).
@@ -98,11 +98,11 @@ export class MemoryRepository {
     /**
      * Full-text search over memory description/body/tags via FTS5 — `query` is
      * raw FTS5 MATCH syntax (AND/OR/NOT, "phrases", prefix*). Ranked by bm25.
-     * Optional metadata filters (doc_type/status/root/tag) apply before limit/offset,
+     * Optional metadata filters (doc_type/status/folder/tag) apply before limit/offset,
      * so pagination stays correct even when filtering narrows the FTS hit set.
      */
     search(query, opts = {}) {
-        const { docType, status, root, tag, limit = 20, offset = 0, includePaused = false } = opts;
+        const { docType, status, folder, tag, limit = 20, offset = 0, includePaused = false } = opts;
         const conditions = [];
         const params = [query];
         if (docType) {
@@ -113,9 +113,9 @@ export class MemoryRepository {
             conditions.push('m.status = ?');
             params.push(status);
         }
-        if (root) {
-            conditions.push('m.root = ?');
-            params.push(root);
+        if (folder) {
+            conditions.push('m.folder = ?');
+            params.push(folder);
         }
         if (tag) {
             conditions.push('EXISTS (SELECT 1 FROM json_each(m.tags) WHERE value = ?)');
@@ -127,7 +127,7 @@ export class MemoryRepository {
         params.push(limit, offset);
         try {
             const rows = this.db
-                .prepare(`SELECT m.id, m.key, m.description, m.doc_type, m.root,
+                .prepare(`SELECT m.id, m.key, m.description, m.doc_type, m.folder,
                   snippet(search_index, 3, '<<', '>>', '…', 20) AS snippet,
                   -bm25(search_index) AS score
            FROM search_index
@@ -162,8 +162,8 @@ export class MemoryRepository {
     create(input) {
         const normalizedKey = normalizeKey(input.key);
         const id = `${slugify(normalizedKey)}-${slugify(input.description)}-${randomUUID().slice(0, 8)}`;
-        const targetRoot = this.resolveRoot(input.root);
-        const filePath = resolveWithinBase(targetRoot.path, input.folder, `${id}.md`);
+        const targetFolder = this.resolveFolder(input.folder);
+        const filePath = resolveWithinBase(targetFolder.path, input.subfolder, `${id}.md`);
         fs.mkdirSync(path.dirname(filePath), { recursive: true });
         const fm = {
             id,
@@ -177,7 +177,7 @@ export class MemoryRepository {
             deprecated: false,
             created_at: new Date().toISOString(),
             source_path: filePath,
-            root: targetRoot.name,
+            folder: targetFolder.name,
         };
         writeMarkdownFile(filePath, stripSourcePath(fm), input.body);
         upsertFile(this.db, this.syncSpec, filePath);
@@ -311,6 +311,6 @@ export class MemoryRepository {
     }
 }
 function stripSourcePath(fm) {
-    const { source_path: _sp, root: _root, ...rest } = fm;
+    const { source_path: _sp, folder: _folder, ...rest } = fm;
     return rest;
 }

package/dist/src/memory/tools.js

@@ -5,9 +5,9 @@ const MEMORY_KEY_TYPES = ['ticket', 'freeform'];
 const MEMORY_STATUS_DEFAULTS = ['active', 'shipped', 'abandoned'];
 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.";
 export function registerMemoryTools(mcp, repo) {
-    const roots = repo.listRoots();
-    const multiRoot = roots.length > 1;
-    const rootNames = roots.map((r) => r.name).join(', ');
+    const folders = repo.listFolders();
+    const multiFolder = folders.length > 1;
+    const folderNames = folders.map((f) => f.name).join(', ');
     mcp.tool('memory_get', 'Exact-match lookup of memory docs (plan/spec/sql/etc.) by normalized key — a ticket ID or a free-form name like "Spot Chart Design". Returns every doc under that key, or only the matching doc_type if provided. Paused docs are hidden by default — pass include_paused to see them.', {
         key: z.string(),
         doc_type: z.enum(MEMORY_DOC_TYPES).optional(),
@@ -29,13 +29,13 @@ export function registerMemoryTools(mcp, repo) {
         doc_type: z.enum(MEMORY_DOC_TYPES).optional(),
         status: statusSchema(MEMORY_STATUS_DEFAULTS).optional(),
         tag: z.string().optional(),
-        ...(multiRoot ? { root: z.string().optional().describe(`filter to one root: ${rootNames}`) } : {}),
+        ...(multiFolder ? { folder: z.string().optional().describe(`filter to one folder: ${folderNames}`) } : {}),
         limit: z.number().int().positive().max(100).optional(),
         offset: z.number().int().nonnegative().optional(),
         include_paused: z.boolean().optional().describe('include paused docs, which are hidden by default (see memory_set_paused)'),
-    }, async ({ query, doc_type, status, tag, root, limit, offset, include_paused }) => {
+    }, async ({ query, doc_type, status, tag, folder, limit, offset, include_paused }) => {
         try {
-            const hits = repo.search(query, { docType: doc_type, status, tag, root, limit, offset, includePaused: include_paused });
+            const hits = repo.search(query, { docType: doc_type, status, tag, folder, limit, offset, includePaused: include_paused });
             return { content: [{ type: 'text', text: JSON.stringify(hits, null, 2) }] };
         }
         catch (err) {
@@ -53,7 +53,7 @@ export function registerMemoryTools(mcp, repo) {
         const results = 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 root under the given key. ${AUTHORING_SKILL_HINT}`, {
+    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}`, {
         key: z.string().describe('lookup handle — ticket ID or free-form name; normalized on write'),
         key_type: z.enum(MEMORY_KEY_TYPES),
         doc_type: z.enum(MEMORY_DOC_TYPES),
@@ -62,11 +62,11 @@ export function registerMemoryTools(mcp, repo) {
         tags: z.array(z.string()).optional(),
         status: statusSchema(MEMORY_STATUS_DEFAULTS).optional().describe('defaults to "active"'),
         related_to: z.string().optional().describe('id of a related doc, e.g. a spec linking to its plan'),
-        folder: z.string().optional().describe('optional subdirectory under the memory root'),
-        ...(multiRoot ? { root: z.string().describe(`which configured memory root to write into: ${rootNames}`) } : {}),
-    }, async ({ key, key_type, doc_type, description, body, tags, status, related_to, folder, root }) => {
+        subfolder: z.string().optional().describe('optional subdirectory under the memory folder'),
+        ...(multiFolder ? { folder: z.string().describe(`which configured memory folder to write into: ${folderNames}`) } : {}),
+    }, async ({ key, key_type, doc_type, description, body, tags, status, related_to, subfolder, folder }) => {
         try {
-            const doc = repo.create({ key, key_type, doc_type, description, body, tags, status, related_to, folder, root });
+            const doc = repo.create({ key, key_type, doc_type, description, body, tags, status, related_to, subfolder, folder });
             return { content: [{ type: 'text', text: JSON.stringify(doc, null, 2) }] };
         }
         catch (err) {
@@ -82,8 +82,8 @@ export function registerMemoryTools(mcp, repo) {
         tags: z.array(z.string()).optional(),
         status: statusSchema(MEMORY_STATUS_DEFAULTS).optional().describe('defaults to "active"'),
         related_to: z.string().optional(),
-        folder: z.string().optional(),
-        ...(multiRoot ? { root: z.string().describe(`which configured memory root to write into: ${rootNames}`) } : {}),
+        subfolder: z.string().optional(),
+        ...(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);
@@ -134,8 +134,8 @@ export function registerMemoryTools(mcp, repo) {
         key: z.string().optional(),
         description: z.string().optional(),
         tags: z.array(z.string()).optional(),
-        ...(multiRoot ? { root: z.string().optional().describe(`which configured memory root to write into: ${rootNames}`) } : {}),
-    }, async ({ summary, key, description, tags, root }) => {
+        ...(multiFolder ? { folder: z.string().optional().describe(`which configured memory folder to write into: ${folderNames}`) } : {}),
+    }, async ({ summary, key, description, tags, folder }) => {
         if (!key || !description) {
             const missing = [!key && 'key', !description && 'description'].filter(Boolean).join(' and ');
             return {
@@ -156,7 +156,7 @@ export function registerMemoryTools(mcp, repo) {
                 description,
                 body: summary,
                 tags,
-                root,
+                folder,
             });
             return { content: [{ type: 'text', text: JSON.stringify(doc, null, 2) }] };
         }

package/dist/src/server.js

@@ -12,12 +12,12 @@ import { registerSkillTools } from './skills/tools.js';
 import { registerMemoryTools } from './memory/tools.js';
 import { registerRelocateTool } from './shared/relocate-tool.js';
 import { registerSearchTool } from './shared/search-tool.js';
-import { registerBucketRootTools } from './shared/bucket-root-tool.js';
+import { registerBucketFolderTools } from './shared/bucket-folder-tool.js';
 import { buildWebRouter } from './web/routes.js';
 import { registerUiTool } from './web/ui-tool.js';
 // server.ts is rebuilt from `buildMcpServer()` on every /mcp request (see below),
-// so tool schemas (which conditionally include `root` based on root count) always
-// reflect the current roots — no restart needed after an add/remove-root call.
+// 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.
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 // __dirname is <pkg>/src when run via tsx (dev/test) and <pkg>/dist/src once
 // built — either way dist/client (the Vite output) sits one level above the
@@ -31,32 +31,32 @@ const builtinSkillsDir = path.join(__dirname, 'skills', 'builtin');
 const PORT = process.env.PORT ? Number(process.env.PORT) : 8767;
 const config = loadConfig();
 const db = openCache(config.cacheDbPath);
-const skillSpec = skillSyncSpec([{ name: 'builtin', path: builtinSkillsDir }, ...config.skillRoots]);
-const memorySpec = memorySyncSpec(config.memoryRoots);
+const skillSpec = skillSyncSpec([{ name: 'builtin', path: builtinSkillsDir }, ...config.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.skillRoots]);
-const memoryRepo = new MemoryRepository(db, config.memoryRoots);
+const skillRepo = new SkillRepository(db, [{ name: 'builtin', path: builtinSkillsDir }, ...config.skillFolders]);
+const memoryRepo = new MemoryRepository(db, config.memoryFolders);
 skillRepo.setWatcher(skillWatcher);
 memoryRepo.setWatcher(memoryWatcher);
-if (config.skillRoots.length === 0 && config.memoryRoots.length === 0) {
-    console.error(`[memory-bucket] no roots configured — open http://localhost:${PORT} to add one`);
+if (config.skillFolders.length === 0 && config.memoryFolders.length === 0) {
+    console.error(`[memory-bucket] no folders configured — open http://localhost:${PORT} to add one`);
 }
 // If the user refers to "mem bucket", "mem bucket mcp", "memory bucket", or
 // "skill bucket" (its working-title predecessor) in conversation, they mean
 // 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_*_root 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_roots to see what named source directories (roots) are configured before passing a root argument elsewhere, and bucket_create_root/bucket_delete_root 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.`;
+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.`;
 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);
-    registerBucketRootTools(server, config, skillRepo, memoryRepo, db, skillSpec, memorySpec);
+    registerBucketFolderTools(server, config, skillRepo, memoryRepo, db, skillSpec, memorySpec);
     registerUiTool(server, PORT);
     return server;
 }
@@ -90,8 +90,8 @@ 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] skill roots: ${config.skillRoots.map((r) => `${r.name}=${r.path}`).join(', ') || '(none)'}`);
-    console.error(`[memory-bucket] memory roots: ${config.memoryRoots.map((r) => `${r.name}=${r.path}`).join(', ') || '(none)'}`);
+    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)'}`);
 });
 process.on('SIGINT', () => {
     db.close();

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

@@ -0,0 +1,66 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod';
+import { saveFolder, removeFolder as removeFolderFromConfig, sanitizeFolderName } from '../config.js';
+import { initialScan } from '../store/sync.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' }));
+        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.', {
+        kind: KIND,
+        path: z.string().describe('absolute path to an existing directory'),
+        name: z.string().optional().describe('name for the folder; 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 folderName = sanitizeFolderName(name || path.basename(dirPath));
+            if (!folderName) {
+                return { content: [{ type: 'text', text: 'could not derive a valid folder name — provide one explicitly' }], isError: true };
+            }
+            const repo = kind === 'skill' ? skillRepo : memoryRepo;
+            repo.addFolder({ name: folderName, path: dirPath });
+            saveFolder(config, kind, { name: folderName, path: dirPath });
+            return { content: [{ type: 'text', text: JSON.stringify({ name: folderName, path: dirPath, 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: 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.removeFolder(name);
+            removeFolderFromConfig(config, kind, name);
+            return { content: [{ type: 'text', text: `Removed ${kind} folder "${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 folder 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 folder; 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 };
+        }
+    });
+}

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

@@ -15,8 +15,8 @@ const overridesSchema = z
     doc_type: z.enum(['plan', 'spec', 'sql', 'testing-todo', 'discovery', 'session-summary', 'other']).optional().describe('memory target only'),
     tags: z.array(z.string()).optional(),
     status: statusSchema(['stable', 'beta', 'unreviewed', 'active', 'shipped', 'abandoned']).optional(),
-    folder: z.string().optional().describe('optional subdirectory under the target root'),
-    root: z.string().optional().describe('which configured root to write into; required if multiple roots exist for the target type'),
+    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'),
 })
     .optional();
 export function registerRelocateTool(mcp, skillRepo, memoryRepo) {

package/dist/src/shared/relocate.js

@@ -63,7 +63,7 @@ export function relocate(opts, skillRepo, memoryRepo) {
             tags: opts.overrides?.tags ?? [],
             trigger_phrases: [],
             extends: null,
-        }, body, opts.overrides?.folder, opts.overrides?.root);
+        }, body, opts.overrides?.subfolder, opts.overrides?.folder);
         if (!opts.keep_original)
             fs.unlinkSync(opts.path);
         return { moved: true, id: doc.name, target: 'skill' };
@@ -91,8 +91,8 @@ export function relocate(opts, skillRepo, memoryRepo) {
         description,
         body,
         tags: opts.overrides?.tags,
+        subfolder: opts.overrides?.subfolder,
         folder: opts.overrides?.folder,
-        root: opts.overrides?.root,
     });
     if (!opts.keep_original)
         fs.unlinkSync(opts.path);

package/dist/src/skills/builtin/memory-bucket-authoring/SKILL.md

@@ -311,48 +311,48 @@ body: >-
   - `relocate_bulk` — same idea for `relocate`, one entry per file.
 
 
-  ## Multiple roots
+  ## Multiple folders
 
 
-  A server can be configured with more than one skill root and/or memory
+  A server can be configured with more than one skill folder and/or memory
 
-  root at once — e.g. a personal skills folder plus a shared company repo.
+  folder at once — e.g. a personal skills folder plus a shared company repo.
 
-  When exactly one root of a given kind is configured, everything above
+  When exactly one folder of a given kind is configured, everything above
 
   works unchanged: `skill_create`/`memory_create`/`relocate` write into it
 
   with no extra parameter needed.
 
 
-  Once **two or more** roots of a kind are configured, `skill_create`,
+  Once **two or more** folders of a kind are configured, `skill_create`,
 
   `memory_create`, `memory_save_session`, and `relocate`'s `overrides` gain
 
-  a required (or, for `memory_save_session`, optional) `root` parameter —
+  a required (or, for `memory_save_session`, optional) `folder` parameter —
 
-  its tool description lists the valid root names. Match a root by name
+  its tool description lists the valid folder names. Match a folder by name
 
   from what the user said ("save this to my personal skills", "put this in
 
-  the company repo") rather than guessing; if it's unclear which root they
+  the company repo") rather than guessing; if it's unclear which folder they
 
-  mean, ask. `skill_list`/`memory_list` also gain an optional `root` filter
+  mean, ask. `skill_list`/`memory_list` also gain an optional `folder` filter
 
-  to narrow results to one root once multiple exist.
+  to narrow results to one folder once multiple exist.
 
 
-  Roots (for both skills and memory) are managed through the web UI
+  Folders (for both skills and memory) are managed through the web UI
 
-  (`bucket_open_ui`) — add one via its "+ Add root" folder browser, or
+  (`bucket_open_ui`) — add one via its "+ Add folder" folder browser, or
 
   remove one via the ✕ on its chip (this only unregisters it and drops its
 
   cached rows; it never deletes files on disk). If the server has zero
 
-  roots configured, the UI opens straight into a first-run "add your first
+  folders configured, the UI opens straight into a first-run "add your first
 
-  root" screen instead of the normal search view.
+  folder" screen instead of the normal search view.
 
 
   ## relocate: pulling in an existing file
@@ -593,29 +593,29 @@ calls whenever acting on more than one item, e.g. after a search:
   name/id in one call.
 - `relocate_bulk` — same idea for `relocate`, one entry per file.
 
-## Multiple roots
+## Multiple folders
 
-A server can be configured with more than one skill root and/or memory
-root at once — e.g. a personal skills folder plus a shared company repo.
-When exactly one root of a given kind is configured, everything above
+A server can be configured with more than one skill folder and/or memory
+folder at once — e.g. a personal skills folder plus a shared company repo.
+When exactly one folder of a given kind is configured, everything above
 works unchanged: `skill_create`/`memory_create`/`relocate` write into it
 with no extra parameter needed.
 
-Once **two or more** roots of a kind are configured, `skill_create`,
+Once **two or more** folders of a kind are configured, `skill_create`,
 `memory_create`, `memory_save_session`, and `relocate`'s `overrides` gain
-a required (or, for `memory_save_session`, optional) `root` parameter —
-its tool description lists the valid root names. Match a root by name
+a required (or, for `memory_save_session`, optional) `folder` parameter —
+its tool description lists the valid folder names. Match a folder by name
 from what the user said ("save this to my personal skills", "put this in
-the company repo") rather than guessing; if it's unclear which root they
-mean, ask. `skill_list`/`memory_list` also gain an optional `root` filter
-to narrow results to one root once multiple exist.
+the company repo") rather than guessing; if it's unclear which folder they
+mean, ask. `skill_list`/`memory_list` also gain an optional `folder` filter
+to narrow results to one folder once multiple exist.
 
-Roots (for both skills and memory) are managed through the web UI
-(`bucket_open_ui`) — add one via its "+ Add root" folder browser, or
+Folders (for both skills and memory) are managed through the web UI
+(`bucket_open_ui`) — add one via its "+ Add folder" folder browser, or
 remove one via the ✕ on its chip (this only unregisters it and drops its
 cached rows; it never deletes files on disk). If the server has zero
-roots configured, the UI opens straight into a first-run "add your first
-root" screen instead of the normal search view.
+folders configured, the UI opens straight into a first-run "add your first
+folder" screen instead of the normal search view.
 
 ## relocate: pulling in an existing file