mcp-memory-bucket 0.1.0 → 0.2.1

package/dist/client/index.html

@@ -7,7 +7,7 @@
     :root { color-scheme: light dark; }
     body { font-family: system-ui, sans-serif; margin: 0; }
   </style>
-  <script type="module" crossorigin src="/assets/index-CxhInmjj.js"></script>
+  <script type="module" crossorigin src="/assets/index-CU-hoVvq.js"></script>
 </head>
 <body>
   <mem-bucket-app></mem-bucket-app>

package/dist/src/config.js

@@ -4,20 +4,87 @@ function memoryDirFlag(argv) {
     const idx = argv.indexOf('--memory-dir');
     return idx !== -1 ? argv[idx + 1] : undefined;
 }
+function readConfigFile(configPath) {
+    if (!fs.existsSync(configPath))
+        return {};
+    return JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+}
+function nameFromPath(p) {
+    return path.basename(p);
+}
+function resolveRoots(entries, baseDir) {
+    const roots = entries.map((entry) => {
+        if (typeof entry === 'string') {
+            return { name: nameFromPath(entry), path: path.resolve(baseDir, entry) };
+        }
+        return { name: entry.name, path: path.resolve(baseDir, entry.path) };
+    });
+    // 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)));
+}
 export function loadConfig(cwd = process.cwd(), argv = process.argv) {
-    const configPath = path.join(cwd, 'memory-bucket.config.json');
-    const hasConfigFile = fs.existsSync(configPath);
-    let overrides = {};
-    if (hasConfigFile) {
-        overrides = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
-    }
     const explicitDir = memoryDirFlag(argv) ?? process.env.MEMORY_BUCKET_DIR;
     const baseDir = explicitDir ? path.resolve(cwd, explicitDir) : cwd;
-    const skillSources = (overrides.skill_sources ?? ['./skills']).map((p) => path.resolve(baseDir, p));
-    const memorySources = (overrides.memory_sources ?? ['./docs']).map((p) => path.resolve(baseDir, p));
+    // 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.
+    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,
+    // 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);
     return {
-        skillSources,
-        memorySources,
+        skillRoots,
+        memoryRoots,
         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,
+ * 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) {
+    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
+    // ./skills or ./docs implicit default, since that default is applied at
+    // 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 next = {
+        ...current,
+        [key]: [...existing, { name: root.name, path: storedPath }],
+    };
+    fs.writeFileSync(config.configPath, JSON.stringify(next, null, 2) + '\n');
+}
+/**
+ * Removes a named root 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) {
+    const current = readConfigFile(config.configPath);
+    const key = kind === 'skill' ? 'skill_sources' : 'memory_sources';
+    const existing = current[key];
+    if (!existing)
+        return;
+    const filtered = existing.filter((entry) => {
+        const entryName = typeof entry === 'string' ? nameFromPath(entry) : entry.name;
+        return entryName !== name;
+    });
+    if (filtered.length === existing.length)
+        return; // nothing matched, don't rewrite the file
+    const next = { ...current, [key]: filtered };
+    fs.writeFileSync(config.configPath, JSON.stringify(next, null, 2) + '\n');
+}

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, memorySyncSpec } from '../store/sync.js';
+import { upsertFile, removeFile, scanSingleRoot, unregisterRoot, memorySyncSpec } from '../store/sync.js';
 import { normalizeKey } from '../types.js';
 function rowToDoc(row) {
     return {
@@ -17,17 +17,59 @@ function rowToDoc(row) {
         status: row.status,
         related_to: row.related_to,
         source_path: row.source_path,
+        root: row.root,
         body: row.body,
     };
 }
 export class MemoryRepository {
     db;
-    defaultSourceDir;
+    roots;
     syncSpec;
-    constructor(db, defaultSourceDir) {
+    watcher;
+    constructor(db, roots) {
         this.db = db;
-        this.defaultSourceDir = defaultSourceDir;
-        this.syncSpec = memorySyncSpec([defaultSourceDir]);
+        this.roots = roots;
+        this.syncSpec = memorySyncSpec(roots);
+    }
+    /** Attaches the live chokidar watcher so addRoot/removeRoot can mutate it without a restart. */
+    setWatcher(watcher) {
+        this.watcher = watcher;
+    }
+    listRoots() {
+        return [...this.roots];
+    }
+    resolveRoot(rootName) {
+        if (rootName) {
+            const found = this.roots.find((r) => r.name === rootName);
+            if (!found) {
+                throw new Error(`unknown memory root "${rootName}" — valid roots: ${this.roots.map((r) => r.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)');
+        }
+        throw new Error(`multiple memory roots configured — specify root: one of ${this.roots.map((r) => r.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`);
+        }
+        this.roots.push(root);
+        scanSingleRoot(this.db, this.syncSpec, root.path);
+        this.watcher?.add(root.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);
+        if (idx === -1)
+            throw new Error(`memory root "${name}" not found`);
+        const [removed] = this.roots.splice(idx, 1);
+        this.watcher?.unwatch(removed.path);
+        unregisterRoot(this.db, 'memory_docs', name);
     }
     /** Exact-match lookup by normalized key, per V0 (no fuzzy matching). */
     getByKey(key, docType) {
@@ -53,7 +95,8 @@ export class MemoryRepository {
     create(input) {
         const normalizedKey = normalizeKey(input.key);
         const id = `${slugify(normalizedKey)}-${slugify(input.description)}-${randomUUID().slice(0, 8)}`;
-        const filePath = resolveWithinBase(this.defaultSourceDir, input.folder, `${id}.md`);
+        const targetRoot = this.resolveRoot(input.root);
+        const filePath = resolveWithinBase(targetRoot.path, input.folder, `${id}.md`);
         fs.mkdirSync(path.dirname(filePath), { recursive: true });
         const fm = {
             id,
@@ -65,6 +108,7 @@ export class MemoryRepository {
             status: 'active',
             related_to: input.related_to ?? null,
             source_path: filePath,
+            root: targetRoot.name,
         };
         writeMarkdownFile(filePath, stripSourcePath(fm), input.body);
         upsertFile(this.db, this.syncSpec, filePath);
@@ -94,6 +138,6 @@ export class MemoryRepository {
     }
 }
 function stripSourcePath(fm) {
-    const { source_path: _sp, ...rest } = fm;
+    const { source_path: _sp, root: _root, ...rest } = fm;
     return rest;
 }

package/dist/src/memory/tools.js

@@ -4,6 +4,9 @@ const MEMORY_KEY_TYPES = ['ticket', 'freeform'];
 const MEMORY_STATUS = ['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(', ');
     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.', {
         key: z.string(),
         doc_type: z.enum(MEMORY_DOC_TYPES).optional(),
@@ -15,7 +18,7 @@ export function registerMemoryTools(mcp, repo) {
         const keys = repo.listKeys(key_prefix);
         return { content: [{ type: 'text', text: JSON.stringify(keys, null, 2) }] };
     });
-    mcp.tool('memory_create', `Writes a new memory doc (plan, spec, SQL, testing notes, discovery, etc.) into the memory source directory 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 root 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),
@@ -23,10 +26,11 @@ export function registerMemoryTools(mcp, repo) {
         body: z.string(),
         tags: z.array(z.string()).optional(),
         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 source dir'),
-    }, async ({ key, key_type, doc_type, description, body, tags, related_to, folder }) => {
+        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, related_to, folder, root }) => {
         try {
-            const doc = repo.create({ key, key_type, doc_type, description, body, tags, related_to, folder });
+            const doc = repo.create({ key, key_type, doc_type, description, body, tags, related_to, folder, root });
             return { content: [{ type: 'text', text: JSON.stringify(doc, null, 2) }] };
         }
         catch (err) {
@@ -66,7 +70,8 @@ export function registerMemoryTools(mcp, repo) {
         key: z.string().optional(),
         description: z.string().optional(),
         tags: z.array(z.string()).optional(),
-    }, async ({ summary, key, description, tags }) => {
+        ...(multiRoot ? { root: z.string().optional().describe(`which configured memory root to write into: ${rootNames}`) } : {}),
+    }, async ({ summary, key, description, tags, root }) => {
         if (!key || !description) {
             const missing = [!key && 'key', !description && 'description'].filter(Boolean).join(' and ');
             return {
@@ -87,6 +92,7 @@ export function registerMemoryTools(mcp, repo) {
                 description,
                 body: summary,
                 tags,
+                root,
             });
             return { content: [{ type: 'text', text: JSON.stringify(doc, null, 2) }] };
         }

package/dist/src/server.js

@@ -13,6 +13,9 @@ import { registerMemoryTools } from './memory/tools.js';
 import { registerRelocateTool } from './shared/relocate-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.
 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
@@ -26,14 +29,19 @@ 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([builtinSkillsDir, ...config.skillSources]);
-const memorySpec = memorySyncSpec(config.memorySources);
+const skillSpec = skillSyncSpec([{ name: 'builtin', path: builtinSkillsDir }, ...config.skillRoots]);
+const memorySpec = memorySyncSpec(config.memoryRoots);
 initialScan(db, skillSpec);
 initialScan(db, memorySpec);
-watchSources(db, skillSpec);
-watchSources(db, memorySpec);
-const skillRepo = new SkillRepository(db, config.skillSources[0]);
-const memoryRepo = new MemoryRepository(db, config.memorySources[0]);
+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);
+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 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
@@ -50,7 +58,7 @@ function buildMcpServer() {
 }
 const app = express();
 app.use(express.json());
-app.use(buildWebRouter(db));
+app.use(buildWebRouter(db, config, skillRepo, memoryRepo));
 app.use(express.static(path.join(packageRoot, 'dist', 'client')));
 app.post('/mcp', async (req, res) => {
     const server = buildMcpServer();
@@ -77,8 +85,8 @@ app.get('/mcp', methodNotAllowed);
 app.delete('/mcp', methodNotAllowed);
 app.listen(PORT, () => {
     console.error(`[memory-bucket] MCP server listening on http://localhost:${PORT}/mcp`);
-    console.error(`[memory-bucket] skill sources: ${config.skillSources.join(', ')}`);
-    console.error(`[memory-bucket] memory sources: ${config.memorySources.join(', ')}`);
+    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)'}`);
 });
 process.on('SIGINT', () => {
     db.close();

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

@@ -19,7 +19,8 @@ export function registerRelocateTool(mcp, skillRepo, memoryRepo) {
             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: z.enum(['stable', 'beta', 'unreviewed', 'active', 'shipped', 'abandoned']).optional(),
-            folder: z.string().optional().describe('optional subdirectory under the target source dir'),
+            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'),
         })
             .optional(),
     }, async (opts) => {

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);
+        }, body, opts.overrides?.folder, opts.overrides?.root);
         if (!opts.keep_original)
             fs.unlinkSync(opts.path);
         return { moved: true, id: doc.name, target: 'skill' };
@@ -92,6 +92,7 @@ export function relocate(opts, skillRepo, memoryRepo) {
         body,
         tags: opts.overrides?.tags,
         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

@@ -164,6 +164,30 @@ If the user asks to save the current conversation/session as memory, use
 **summary**, not a raw transcript. If `key` or `description` weren't
 given, ask for both before calling it; don't guess a key from context.
 
+## Multiple roots
+
+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
+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`,
+`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
+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.
+
+Roots (for both skills and memory) are managed through the web UI
+(`bucket_open_ui`) — add one via its "+ Add root" 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.
+
 ## relocate: pulling in an existing file
 
 If there's already a local markdown file that should become a skill or

package/dist/src/skills/repository.js

@@ -3,7 +3,7 @@ import path from 'node:path';
 import { writeMarkdownFile } from '../store/markdown-file.js';
 import { assertValidSkillName } from '../store/skill-name.js';
 import { resolveWithinBase } from '../store/safe-path.js';
-import { upsertFile, removeFile, skillSyncSpec } from '../store/sync.js';
+import { upsertFile, removeFile, scanSingleRoot, unregisterRoot, skillSyncSpec } from '../store/sync.js';
 function rowToDoc(row) {
     return {
         name: row.id,
@@ -12,22 +12,71 @@ function rowToDoc(row) {
         trigger_phrases: JSON.parse(row.trigger_phrases),
         metadata: { owner: row.owner, status: row.status, extends: row.extends },
         source_path: row.source_path,
+        root: row.root,
         body: row.body,
     };
 }
 export class SkillRepository {
     db;
-    sourceDir;
+    roots;
     syncSpec;
-    constructor(db, sourceDir) {
+    watcher;
+    /** `roots[0]` is always the builtin skills dir — never exposed for create()/removal. */
+    constructor(db, roots) {
         this.db = db;
-        this.sourceDir = sourceDir;
-        this.syncSpec = skillSyncSpec([sourceDir]);
+        this.roots = roots;
+        this.syncSpec = skillSyncSpec(roots);
     }
-    list(query) {
-        const rows = this.db
-            .prepare(`SELECT id, description, owner, status, tags, trigger_phrases FROM skills`)
-            .all();
+    /** Attaches the live chokidar watcher so addRoot/removeRoot can mutate it without a restart. */
+    setWatcher(watcher) {
+        this.watcher = watcher;
+    }
+    /** User-addable roots — excludes the always-present builtin skills dir at roots[0]. */
+    listRoots() {
+        return this.roots.slice(1);
+    }
+    resolveRoot(rootName) {
+        const userRoots = this.listRoots();
+        if (rootName) {
+            const found = userRoots.find((r) => r.name === rootName);
+            if (!found) {
+                throw new Error(`unknown skill root "${rootName}" — valid roots: ${userRoots.map((r) => r.name).join(', ') || '(none configured)'}`);
+            }
+            return found;
+        }
+        if (userRoots.length === 1)
+            return userRoots[0];
+        if (userRoots.length === 0) {
+            throw new Error('no skill root configured — add one first (see bucket_open_ui)');
+        }
+        throw new Error(`multiple skill roots configured — specify root: one of ${userRoots.map((r) => r.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 skill root named "${root.name}" already exists`);
+        }
+        this.roots.push(root);
+        scanSingleRoot(this.db, this.syncSpec, root.path);
+        this.watcher?.add(root.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);
+        if (idx <= 0)
+            throw new Error(`skill root "${name}" not found or is not removable`); // index 0 is builtin
+        const [removed] = this.roots.splice(idx, 1);
+        this.watcher?.unwatch(removed.path);
+        unregisterRoot(this.db, 'skills', name);
+    }
+    list(query, root) {
+        const rows = root
+            ? this.db
+                .prepare(`SELECT id, description, owner, status, tags, trigger_phrases, root FROM skills WHERE root = ?`)
+                .all(root)
+            : this.db
+                .prepare(`SELECT id, description, owner, status, tags, trigger_phrases, root FROM skills`)
+                .all();
         const needle = query?.trim().toLowerCase();
         const items = rows.map((r) => ({
             name: r.id,
@@ -36,6 +85,7 @@ export class SkillRepository {
             status: r.status,
             tags: JSON.parse(r.tags),
             triggerPhrases: JSON.parse(r.trigger_phrases),
+            root: r.root,
         }));
         const filtered = needle
             ? items.filter((item) => item.description.toLowerCase().includes(needle) ||
@@ -49,15 +99,18 @@ export class SkillRepository {
         return row ? rowToDoc(row) : null;
     }
     /**
-     * Creates <sourceDir>/[folder/]<name>/SKILL.md — folder-per-skill, per the
+     * Creates <root>/[folder/]<name>/SKILL.md — folder-per-skill, per the
      * agentskills.io spec (`name` must equal the containing folder's name).
+     * `root` selects which configured skill root to write into; required only
+     * when more than one user root is configured.
      */
-    create(frontmatter, body, folder) {
+    create(frontmatter, body, folder, root) {
         assertValidSkillName(frontmatter.name);
         if (this.get(frontmatter.name)) {
             throw new Error(`skill with name "${frontmatter.name}" already exists`);
         }
-        const skillDir = resolveWithinBase(this.sourceDir, folder, frontmatter.name);
+        const targetRoot = this.resolveRoot(root);
+        const skillDir = resolveWithinBase(targetRoot.path, folder, frontmatter.name);
         if (fs.existsSync(skillDir)) {
             throw new Error(`skill directory already exists at ${skillDir}`);
         }
@@ -76,6 +129,7 @@ export class SkillRepository {
                 extends: frontmatter.extends ?? null,
             },
             source_path: filePath,
+            root: targetRoot.name,
         };
         writeMarkdownFile(filePath, stripSourcePath(fm), body);
         upsertFile(this.db, this.syncSpec, filePath);
@@ -139,6 +193,6 @@ export class SkillRepository {
     }
 }
 function stripSourcePath(fm) {
-    const { source_path: _sp, ...rest } = fm;
+    const { source_path: _sp, root: _root, ...rest } = fm;
     return rest;
 }

package/dist/src/skills/tools.js

@@ -3,8 +3,13 @@ const SKILL_STATUS = ['stable', 'beta', 'unreviewed'];
 const SKILL_NAME_DESCRIPTION = 'stable id, must be 1-64 chars, lowercase letters/numbers/hyphens only, no leading/trailing/consecutive hyphens — this becomes the skill\'s folder name (agentskills.io spec requirement)';
 const AUTHORING_SKILL_HINT = "Before your first call in a session, run skill_get(\"memory-bucket-authoring\") to learn the exact frontmatter schema and conventions — don't guess the shape.";
 export function registerSkillTools(mcp, repo) {
-    mcp.tool('skill_list', 'Lists skills (reusable coding patterns, one SKILL.md per folder per the agentskills.io open standard), optionally filtered by a keyword matched against description/tags/trigger phrases.', { query: z.string().optional() }, async ({ query }) => {
-        const items = repo.list(query);
+    const roots = repo.listRoots();
+    const multiRoot = roots.length > 1;
+    const rootNames = roots.map((r) => r.name).join(', ');
+    mcp.tool('skill_list', 'Lists skills (reusable coding patterns, one SKILL.md per folder per the agentskills.io open standard), optionally filtered by a keyword matched against description/tags/trigger phrases.', multiRoot
+        ? { query: z.string().optional(), root: z.string().optional().describe(`filter to one root: ${rootNames}`) }
+        : { query: z.string().optional() }, async ({ query, root }) => {
+        const items = repo.list(query, root);
         return { content: [{ type: 'text', text: JSON.stringify(items, null, 2) }] };
     });
     mcp.tool('skill_get', 'Fetches a single skill by name, including its full markdown body.', { name: z.string() }, async ({ name }) => {
@@ -14,7 +19,7 @@ export function registerSkillTools(mcp, repo) {
         }
         return { content: [{ type: 'text', text: JSON.stringify(doc, null, 2) }] };
     });
-    mcp.tool('skill_create', `Creates a new skill as <sourceDir>/[folder/]<name>/SKILL.md, per the agentskills.io open standard — a folder containing SKILL.md, optionally alongside scripts/references/assets subfolders you create separately on disk. ${AUTHORING_SKILL_HINT}`, {
+    mcp.tool('skill_create', `Creates a new skill as <root>/[folder/]<name>/SKILL.md, per the agentskills.io open standard — a folder containing SKILL.md, optionally alongside scripts/references/assets subfolders you create separately on disk. ${AUTHORING_SKILL_HINT}`, {
         name: z.string().describe(SKILL_NAME_DESCRIPTION),
         description: z
             .string()
@@ -28,10 +33,11 @@ export function registerSkillTools(mcp, repo) {
         tags: z.array(z.string()).optional(),
         trigger_phrases: z.array(z.string()).optional(),
         extends: z.string().optional().describe('reserved for a future overlay mechanism — stored in frontmatter.metadata'),
-        folder: z.string().optional().describe('optional subdirectory under the skill source dir, e.g. "frontend"'),
-    }, async ({ name, description, body, license, compatibility, owner, status, tags, trigger_phrases, extends: extendsId, folder }) => {
+        folder: z.string().optional().describe('optional subdirectory under the skill root, e.g. "frontend"'),
+        ...(multiRoot ? { root: z.string().describe(`which configured skill root to write into: ${rootNames}`) } : {}),
+    }, async ({ name, description, body, license, compatibility, owner, status, tags, trigger_phrases, extends: extendsId, folder, root }) => {
         try {
-            const doc = repo.create({ name, description, license, compatibility, owner, status, tags, trigger_phrases, extends: extendsId }, body, folder);
+            const doc = repo.create({ name, description, license, compatibility, owner, status, tags, trigger_phrases, extends: extendsId }, body, folder, root);
             return { content: [{ type: 'text', text: JSON.stringify(doc, null, 2) }] };
         }
         catch (err) {

package/dist/src/store/db.js

@@ -12,6 +12,7 @@ export function openCache(dbPath) {
       trigger_phrases TEXT NOT NULL,  -- JSON array
       extends TEXT,
       source_path TEXT NOT NULL UNIQUE, -- path to SKILL.md
+      root TEXT NOT NULL DEFAULT '',  -- name of the configured root this file lives under
       body TEXT NOT NULL,
       mtime_ms INTEGER NOT NULL
     );
@@ -26,6 +27,7 @@ export function openCache(dbPath) {
       status TEXT NOT NULL,
       related_to TEXT,
       source_path TEXT NOT NULL UNIQUE,
+      root TEXT NOT NULL DEFAULT '',  -- name of the configured root this file lives under
       body TEXT NOT NULL,
       mtime_ms INTEGER NOT NULL
     );
@@ -41,9 +43,18 @@ export function openCache(dbPath) {
       tokenize = 'porter unicode61'
     );
   `);
+    addRootColumnIfMissing(db, 'skills');
+    addRootColumnIfMissing(db, 'memory_docs');
     backfillSearchIndex(db);
     return db;
 }
+/** Migration for cache files created before the `root` column existed. */
+function addRootColumnIfMissing(db, table) {
+    const columns = db.prepare(`PRAGMA table_info(${table})`).all();
+    if (columns.some((c) => c.name === 'root'))
+        return;
+    db.exec(`ALTER TABLE ${table} ADD COLUMN root TEXT NOT NULL DEFAULT ''`);
+}
 /** One-time backfill for existing rows the first time search_index is introduced into a cache file. */
 function backfillSearchIndex(db) {
     const { count: indexed } = db.prepare(`SELECT COUNT(*) as count FROM search_index`).get();