npm - mcp-memory-bucket - Versions diffs - 0.3.0 → 0.4.2 - Mend

mcp-memory-bucket 0.3.0 → 0.4.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (18) hide show

package/dist/client/assets/index-BXCTjiGA.js +894 -0
package/dist/client/index.html +23 -3
package/dist/src/config.js +9 -0
package/dist/src/memory/repository.js +50 -9
package/dist/src/memory/tools.js +15 -6
package/dist/src/server.js +4 -1
package/dist/src/shared/bucket-root-tool.js +66 -0
package/dist/src/shared/search-tool.js +16 -1
package/dist/src/skills/builtin/memory-bucket-authoring/SKILL.md +13 -0
package/dist/src/skills/repository.js +72 -14
package/dist/src/skills/tools.js +30 -7
package/dist/src/store/date-extract.js +49 -0
package/dist/src/store/db.js +13 -0
package/dist/src/store/search.js +58 -0
package/dist/src/store/sync.js +17 -0
package/dist/src/web/routes.js +87 -14
package/package.json +2 -2
package/dist/client/assets/index-DIO48C0V.js +0 -744

package/dist/client/index.html CHANGED Viewed

@@ -4,10 +4,30 @@
   <meta charset="utf-8" />
   <title>mem-bucket viewer</title>
   <style>
-    :root { color-scheme: light dark; }
-    body { font-family: system-ui, sans-serif; margin: 0; }
+    :root {
+      color-scheme: light dark;
+      --border: light-dark(#0000001f, #ffffff2e);
+      --border-strong: light-dark(#00000038, #ffffff4a);
+      --hover: light-dark(#00000010, #ffffff14);
+      --hover-strong: light-dark(#00000018, #ffffff20);
+      --bg: light-dark(#ffffff, #1a1a1a);
+      --bg-subtle: light-dark(#00000008, #ffffff0d);
+      --fg: light-dark(#111111, #f0f0f0);
+      --accent: light-dark(#2563eb, #3b82f6);
+      --accent-fg: #ffffff;
+      --accent-tint: light-dark(#2563eb11, #3b82f622);
+      --danger: light-dark(#dc2626, #fca5a5);
+      --purple: light-dark(#7c3aed, #a78bfa);
+      --purple-fg: light-dark(#6d28d9, #d8caff);
+      --purple-tint: #a78bfa33;
+      --shadow: light-dark(#00000026, #00000080);
+      --overlay: light-dark(#00000059, #000000b3);
+    }
+    :root[data-theme='light'] { color-scheme: light; }
+    :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-DIO48C0V.js"></script>
+  <script type="module" crossorigin src="/assets/index-BXCTjiGA.js"></script>
 </head>
 <body>
   <mem-bucket-app></mem-bucket-app>

package/dist/src/config.js CHANGED Viewed

@@ -68,6 +68,15 @@ export function saveRoot(config, kind, root) {
     };
     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) {
+    return raw
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 64);
+}
 /**
  * Removes a named root from the config file by name. Matches both explicit
  * {name, path} entries and bare-string entries (via their derived name).

package/dist/src/memory/repository.js CHANGED Viewed

@@ -18,6 +18,7 @@ function rowToDoc(row) {
         status: row.status,
         related_to: row.related_to,
         deprecated: !!row.deprecated,
+        paused: !!row.paused,
         created_at: row.created_at ?? undefined,
         source_path: row.source_path,
         root: row.root,
@@ -74,12 +75,24 @@ export class MemoryRepository {
         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) {
+    /**
+     * Exact-match lookup by normalized key, per V0 (no fuzzy matching).
+     * `includePaused` defaults to false: paused docs are hidden from discovery (see setPaused).
+     */
+    getByKey(key, docType, opts = {}) {
         const normalized = normalizeKey(key);
-        const rows = docType
-            ? this.db.prepare(`SELECT * FROM memory_docs WHERE key = ? AND doc_type = ?`).all(normalized, docType)
-            : this.db.prepare(`SELECT * FROM memory_docs WHERE key = ?`).all(normalized);
+        const conditions = ['key = ?'];
+        const params = [normalized];
+        if (docType) {
+            conditions.push('doc_type = ?');
+            params.push(docType);
+        }
+        if (!opts.includePaused) {
+            conditions.push('paused = 0');
+        }
+        const rows = this.db
+            .prepare(`SELECT * FROM memory_docs WHERE ${conditions.join(' AND ')}`)
+            .all(...params);
         return rows.map(rowToDoc);
     }
     /**
@@ -89,7 +102,7 @@ export class MemoryRepository {
      * so pagination stays correct even when filtering narrows the FTS hit set.
      */
     search(query, opts = {}) {
-        const { docType, status, root, tag, limit = 20, offset = 0 } = opts;
+        const { docType, status, root, tag, limit = 20, offset = 0, includePaused = false } = opts;
         const conditions = [];
         const params = [query];
         if (docType) {
@@ -108,6 +121,9 @@ export class MemoryRepository {
             conditions.push('EXISTS (SELECT 1 FROM json_each(m.tags) WHERE value = ?)');
             params.push(tag);
         }
+        if (!includePaused) {
+            conditions.push('m.paused = 0');
+        }
         params.push(limit, offset);
         try {
             const rows = this.db
@@ -165,7 +181,7 @@ export class MemoryRepository {
         };
         writeMarkdownFile(filePath, stripSourcePath(fm), input.body);
         upsertFile(this.db, this.syncSpec, filePath);
-        return { ...fm, body: input.body };
+        return { ...fm, body: input.body, paused: false };
     }
     /**
      * Creates many memory docs in one call — each entry is the same shape as
@@ -187,8 +203,11 @@ export class MemoryRepository {
         const existing = this.get(id);
         if (!existing)
             throw new Error(`memory doc with id "${id}" not found`);
+        // `paused` is local-cache-only and must never reach writeMarkdownFile — split it off of
+        // `existing` before spreading the rest into the frontmatter that gets written to disk.
+        const { paused: existingPaused, ...existingForFile } = existing;
         const merged = {
-            ...existing,
+            ...existingForFile,
             ...frontmatter,
             id: existing.id,
             key: frontmatter?.key ? normalizeKey(frontmatter.key) : existing.key,
@@ -196,7 +215,7 @@ export class MemoryRepository {
         const newBody = body ?? existing.body;
         writeMarkdownFile(existing.source_path, stripSourcePath(merged), newBody);
         upsertFile(this.db, this.syncSpec, existing.source_path);
-        return { ...merged, body: newBody };
+        return { ...merged, body: newBody, paused: existingPaused };
     }
     /**
      * Applies the same frontmatter change to many memory docs at once — e.g.
@@ -230,6 +249,28 @@ export class MemoryRepository {
             }
         });
     }
+    /**
+     * Pauses/resumes memory docs by id — a local-only toggle stored directly in this cache file's
+     * `paused` column, never written to the doc's markdown file and never synced by the file
+     * watcher (see the comment on memoryColumns in store/sync.ts). Paused docs are hidden from
+     * getByKey()/search() by default but remain fetchable via get()/bulkGet(). Because it's
+     * local-only, the flag does not follow the doc to another machine's cache or survive the cache
+     * file being deleted. Returns per-id results so one bad id doesn't abort the rest of the batch.
+     */
+    setPaused(ids, paused) {
+        return ids.map((id) => {
+            try {
+                const existing = this.get(id);
+                if (!existing)
+                    throw new Error(`memory doc with id "${id}" not found`);
+                this.db.prepare(`UPDATE memory_docs SET paused = ? WHERE id = ?`).run(paused ? 1 : 0, id);
+                return { id, ok: true };
+            }
+            catch (err) {
+                return { id, ok: false, error: err.message };
+            }
+        });
+    }
     delete(id) {
         const existing = this.get(id);
         if (!existing)

package/dist/src/memory/tools.js CHANGED Viewed

@@ -7,11 +7,12 @@ 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.', {
+    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(),
-    }, async ({ key, doc_type }) => {
-        const docs = repo.getByKey(key, doc_type);
+        include_paused: z.boolean().optional().describe('include paused docs, which are hidden by default (see memory_set_paused)'),
+    }, async ({ key, doc_type, include_paused }) => {
+        const docs = repo.getByKey(key, doc_type, { includePaused: include_paused });
         return { content: [{ type: 'text', text: JSON.stringify(docs, null, 2) }] };
     });
     mcp.tool('memory_bulk_get', 'Fetches many memory docs by id in one call, including full markdown bodies — e.g. hydrating a batch of memory_search hits (which return ids, not keys). Missing ids are simply omitted from the result, not errors.', { ids: z.array(z.string()).min(1) }, async ({ ids }) => {
@@ -22,7 +23,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_search', 'Full-text search over memory doc description/body/tags (grep/find-like, ranked by relevance) — unlike memory_get\'s exact-key lookup, this searches by content across all keys. `query` is raw SQLite FTS5 MATCH syntax: bare words, "exact phrases", prefix* wildcards, AND/OR/NOT boolean operators; hyphenated/punctuated terms must be quoted, e.g. "blue-green". Can be combined with doc_type/status/tag filters. Returns ranked hits with a highlighted snippet, not the full body — call memory_get(key) or fetch by id for that.', {
+    mcp.tool('memory_search', 'Full-text search over memory doc description/body/tags (grep/find-like, ranked by relevance) — unlike memory_get\'s exact-key lookup, this searches by content across all keys. `query` is raw SQLite FTS5 MATCH syntax: bare words, "exact phrases", prefix* wildcards, AND/OR/NOT boolean operators; hyphenated/punctuated terms must be quoted, e.g. "blue-green". Can be combined with doc_type/status/tag filters. Returns ranked hits with a highlighted snippet, not the full body — call memory_get(key) or fetch by id for that. Paused docs are hidden by default — pass include_paused to see them.', {
         query: z.string().describe('FTS5 match expression, e.g. `migration AND rollback` or `"blue green"`'),
         doc_type: z.enum(MEMORY_DOC_TYPES).optional(),
         status: z.enum(MEMORY_STATUS).optional(),
@@ -30,9 +31,10 @@ export function registerMemoryTools(mcp, repo) {
         ...(multiRoot ? { root: z.string().optional().describe(`filter to one root: ${rootNames}`) } : {}),
         limit: z.number().int().positive().max(100).optional(),
         offset: z.number().int().nonnegative().optional(),
-    }, async ({ query, doc_type, status, tag, root, limit, offset }) => {
+        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 }) => {
         try {
-            const hits = repo.search(query, { docType: doc_type, status, tag, root, limit, offset });
+            const hits = repo.search(query, { docType: doc_type, status, tag, root, limit, offset, includePaused: include_paused });
             return { content: [{ type: 'text', text: JSON.stringify(hits, null, 2) }] };
         }
         catch (err) {
@@ -104,6 +106,13 @@ export function registerMemoryTools(mcp, repo) {
             return { content: [{ type: 'text', text: err.message }], isError: true };
         }
     });
+    mcp.tool('memory_set_paused', 'Pauses or resumes memory docs by id — a local-only toggle stored in this machine\'s SQLite cache, never written to the doc\'s markdown file, so it never touches the file on disk and never follows the doc to another machine\'s cache. Paused docs are hidden from memory_get/memory_search by default but stay fully intact and are still fetchable directly via memory_bulk_get — use this to temporarily stop a doc from surfacing during discovery without deprecating it. Returns per-id success/failure so one bad id doesn\'t abort the batch.', {
+        ids: z.array(z.string()).min(1),
+        paused: z.boolean().describe('true to pause (hide from memory_get/memory_search), false to resume'),
+    }, async ({ ids, paused }) => {
+        const results = repo.setPaused(ids, paused);
+        return { content: [{ type: 'text', text: JSON.stringify(results, null, 2) }] };
+    });
     mcp.tool('memory_delete', 'Hard-deletes a memory doc by id — removes the markdown file, no tombstone.', { id: z.string() }, async ({ id }) => {
         try {
             repo.delete(id);

package/dist/src/server.js CHANGED Viewed

@@ -12,6 +12,7 @@ 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 { buildWebRouter } from './web/routes.js';
 import { registerUiTool } from './web/ui-tool.js';
 // server.ts is rebuilt from `buildMcpServer()` on every /mcp request (see below),
@@ -48,13 +49,14 @@ if (config.skillRoots.length === 0 && config.memoryRoots.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 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. Most operations have a _bulk_ variant (bulk_get/bulk_create/bulk_update/bulk_delete, 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. 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_*_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.`;
 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);
     registerUiTool(server, PORT);
     return server;
 }
@@ -87,6 +89,7 @@ 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] 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)'}`);
 });

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

@@ -0,0 +1,66 @@
+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 };
+        }
+    });
+}

package/dist/src/shared/search-tool.js CHANGED Viewed

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { searchCombined, SearchQueryError } from '../store/search.js';
+import { searchCombined, searchByDate, SearchQueryError } from '../store/search.js';
 export function registerSearchTool(mcp, db) {
     mcp.tool('bucket_search', 'Full-text search across BOTH skills and memory docs in one ranked list — use this when you don\'t know (or don\'t care) which bucket something landed in. `query` is raw SQLite FTS5 MATCH syntax: bare words, "exact phrases", prefix* wildcards, AND/OR/NOT boolean operators; hyphenated/punctuated terms must be quoted, e.g. "blue-green". For filtering by doc_type/status/tag, use skill_search or memory_search instead. Returns ranked hits with a highlighted snippet, not full body — call skill_get/memory_get on a hit for that.', {
         query: z.string().describe('FTS5 match expression, e.g. `deploy AND rollback` or `"blue green"`'),
@@ -15,4 +15,19 @@ export function registerSearchTool(mcp, db) {
             return { content: [{ type: 'text', text: message }], isError: true };
         }
     });
+    mcp.tool('search_by_date', 'Finds skills and memory docs whose body text mentions a date, OR whose created_at falls, within [start, end] (inclusive, ISO YYYY-MM-DD). Matches any date extracted from the document body plus its created_at — ANY-match, no priority between them. created_at is stored converted to the server\'s local calendar date, so "today"/"this week" ranges built from local time line up correctly without any timezone adjustment. Useful for period-based recall, e.g. "what did I work on this week": the caller computes the date range itself, this tool does not parse natural language. Returns ranked hits (earliest matched date first) with a highlighted snippet showing the matched date in context (or a note that it matched via created_at, when the date isn\'t literally in the body), not the full body — call skill_get/memory_get on a hit for that.', {
+        start: z.string().describe('ISO date YYYY-MM-DD, inclusive'),
+        end: z.string().describe('ISO date YYYY-MM-DD, inclusive'),
+        table: z.enum(['skills', 'memory_docs']).optional().describe('restrict to one bucket; omit to search both'),
+        limit: z.number().int().positive().max(100).optional(),
+        offset: z.number().int().nonnegative().optional(),
+    }, async ({ start, end, table, limit, offset }) => {
+        try {
+            const hits = searchByDate(db, start, end, { table, limit, offset });
+            return { content: [{ type: 'text', text: JSON.stringify(hits, null, 2) }] };
+        }
+        catch (err) {
+            return { content: [{ type: 'text', text: err.message }], isError: true };
+        }
+    });
 }

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

@@ -557,6 +557,19 @@ given, ask for both before calling it; don't guess a key from context.
   tools when you don't know (or don't care) which bucket something
   landed in. All three return snippets, not full bodies — follow up with
   `skill_get`/`memory_get` (or the bulk variants below) for the rest.
+- **`search_by_date(start, end)`** — finds skills and memory docs whose
+  **body text mentions a date, or whose `created_at` falls,** within an
+  inclusive ISO `YYYY-MM-DD` range, e.g. "what did I work on this week"
+  once you've resolved "this week" into concrete start/end dates
+  yourself (it does not parse natural language). Both a date written
+  inside the content and the doc's `created_at` count as candidate
+  matches — whichever is earliest wins, no priority between them. Like
+  `bucket_search`, it covers both skills and memory docs at once (pass
+  `table` to restrict to one). Returns a highlighted snippet around the
+  matched date (or a note that it matched via `created_at`, when the
+  date isn't literally in the body), not the full body. `created_at` is
+  indexed as the server's local calendar date, so "today"/"this week"
+  ranges built from local time just work — no timezone conversion needed.
 - **`skill_get`/`memory_get`** — exact-key lookup when you already know
   the name/key.

package/dist/src/skills/repository.js CHANGED Viewed

@@ -13,6 +13,7 @@ function rowToDoc(row) {
         trigger_phrases: JSON.parse(row.trigger_phrases),
         metadata: { owner: row.owner, status: row.status, extends: row.extends },
         deprecated: !!row.deprecated,
+        paused: !!row.paused,
         created_at: row.created_at ?? undefined,
         source_path: row.source_path,
         root: row.root,
@@ -72,14 +73,21 @@ export class SkillRepository {
         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();
+    /** `includePaused` defaults to false: paused skills are hidden from discovery (see setPaused). */
+    list(query, root, opts = {}) {
+        const conditions = [];
+        const params = [];
+        if (root) {
+            conditions.push('root = ?');
+            params.push(root);
+        }
+        if (!opts.includePaused) {
+            conditions.push('paused = 0');
+        }
+        const where = conditions.length ? ` WHERE ${conditions.join(' AND ')}` : '';
+        const rows = this.db
+            .prepare(`SELECT id, description, owner, status, tags, trigger_phrases, root, paused FROM skills${where}`)
+            .all(...params);
         const needle = query?.trim().toLowerCase();
         const items = rows.map((r) => ({
             name: r.id,
@@ -89,6 +97,7 @@ export class SkillRepository {
             tags: JSON.parse(r.tags),
             triggerPhrases: JSON.parse(r.trigger_phrases),
             root: r.root,
+            paused: !!r.paused,
         }));
         const filtered = needle
             ? items.filter((item) => item.description.toLowerCase().includes(needle) ||
@@ -104,7 +113,7 @@ export class SkillRepository {
      * so pagination stays correct even when filtering narrows the FTS hit set.
      */
     search(query, opts = {}) {
-        const { root, status, owner, tag, limit = 20, offset = 0 } = opts;
+        const { root, status, owner, tag, limit = 20, offset = 0, includePaused = false } = opts;
         const conditions = [];
         const params = [query];
         if (root) {
@@ -123,6 +132,9 @@ export class SkillRepository {
             conditions.push('EXISTS (SELECT 1 FROM json_each(s.tags) WHERE value = ?)');
             params.push(tag);
         }
+        if (!includePaused) {
+            conditions.push('s.paused = 0');
+        }
         params.push(limit, offset);
         try {
             const rows = this.db
@@ -186,7 +198,7 @@ export class SkillRepository {
         };
         writeMarkdownFile(filePath, stripSourcePath(fm), body);
         upsertFile(this.db, this.syncSpec, filePath);
-        return { ...fm, body };
+        return { ...fm, body, paused: false };
     }
     /**
      * Creates many skills in one call — each entry is the same shape as create()'s
@@ -212,11 +224,14 @@ export class SkillRepository {
         const existing = this.get(name);
         if (!existing)
             throw new Error(`skill with name "${name}" not found`);
+        // `paused` is local-cache-only and must never reach writeMarkdownFile — split it off of
+        // `existing` before spreading the rest into the frontmatter that gets written to disk.
+        const { paused: existingPaused, ...existingForFile } = existing;
         // Builtin skills (e.g. memory-bucket-authoring) are the server's own always-present
         // documentation, not user content — deprecating them would hide guidance every session needs.
         const deprecated = this.isBuiltin(existing) ? existing.deprecated : frontmatter?.deprecated;
         const merged = {
-            ...existing,
+            ...existingForFile,
             ...frontmatter,
             deprecated,
             name: existing.name, // name is immutable post-creation (it's also the folder name)
@@ -230,7 +245,7 @@ export class SkillRepository {
         const newBody = body ?? existing.body;
         writeMarkdownFile(existing.source_path, stripSourcePath(merged), newBody);
         upsertFile(this.db, this.syncSpec, existing.source_path);
-        return { ...merged, body: newBody };
+        return { ...merged, body: newBody, paused: existingPaused };
     }
     /**
      * Renames a skill: moves <sourceDir>/[folder/]<oldName>/ to .../<newName>/ (keeping any
@@ -253,11 +268,14 @@ export class SkillRepository {
         }
         fs.renameSync(oldDir, newDir);
         const newFilePath = path.join(newDir, 'SKILL.md');
-        const merged = { ...existing, name: newName };
+        // Rename changes the skill's id, so it becomes a fresh cache row — paused (local-only,
+        // keyed by id) does not carry over, same as it wouldn't survive deleting the cache file.
+        const { paused: _existingPaused, ...existingForFile } = existing;
+        const merged = { ...existingForFile, name: newName };
         writeMarkdownFile(newFilePath, stripSourcePath(merged), existing.body);
         removeFile(this.db, 'skills', existing.source_path);
         upsertFile(this.db, this.syncSpec, newFilePath);
-        return { ...merged, body: existing.body };
+        return { ...merged, body: existing.body, paused: false };
     }
     /**
      * Applies the same frontmatter change to many skills at once — e.g. add/remove
@@ -293,6 +311,46 @@ export class SkillRepository {
             }
         });
     }
+    /**
+     * Pauses/resumes skills by name — a local-only toggle stored directly in this cache file's
+     * `paused` column, never written to SKILL.md and never synced by the file watcher (see the
+     * comment on skillColumns in store/sync.ts). Paused skills are hidden from list()/search() by
+     * default but remain fetchable via get()/bulkGet(). Because it's local-only, the flag does not
+     * follow the skill to another machine's cache, survive a rename, or survive the cache file
+     * being deleted. Returns per-name results so one bad name doesn't abort the rest of the batch.
+     */
+    setPaused(names, paused) {
+        return names.map((name) => {
+            try {
+                const existing = this.get(name);
+                if (!existing)
+                    throw new Error(`skill with name "${name}" not found`);
+                if (this.isBuiltin(existing))
+                    throw new Error(`skill "${name}" is builtin and cannot be paused`);
+                this.db.prepare(`UPDATE skills SET paused = ? WHERE id = ?`).run(paused ? 1 : 0, name);
+                return { name, ok: true };
+            }
+            catch (err) {
+                return { name, ok: false, error: err.message };
+            }
+        });
+    }
+    /**
+     * Renames many skills at once — each entry is a {name, new_name} pair, same
+     * semantics as rename(). Returns per-entry results so one bad pair (unknown
+     * name, name collision) doesn't abort the rest of the batch.
+     */
+    bulkRename(entries) {
+        return entries.map(({ name, new_name }) => {
+            try {
+                this.rename(name, new_name);
+                return { name, new_name, ok: true };
+            }
+            catch (err) {
+                return { name, new_name, ok: false, error: err.message };
+            }
+        });
+    }
     /** Removes the whole skill directory, including any scripts/references/assets alongside SKILL.md. */
     delete(name) {
         const existing = this.get(name);

package/dist/src/skills/tools.js CHANGED Viewed

@@ -6,23 +6,31 @@ export function registerSkillTools(mcp, repo) {
     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);
+    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. Paused skills are hidden by default — pass include_paused to see them.', multiRoot
+        ? {
+            query: z.string().optional(),
+            root: z.string().optional().describe(`filter to one root: ${rootNames}`),
+            include_paused: z.boolean().optional().describe('include paused skills, which are hidden by default (see skill_set_paused)'),
+        }
+        : {
+            query: z.string().optional(),
+            include_paused: z.boolean().optional().describe('include paused skills, which are hidden by default (see skill_set_paused)'),
+        }, async ({ query, root, include_paused }) => {
+        const items = repo.list(query, root, { includePaused: include_paused });
         return { content: [{ type: 'text', text: JSON.stringify(items, null, 2) }] };
     });
-    mcp.tool('skill_search', 'Full-text search over skill description/body/tags (grep/find-like, ranked by relevance) — unlike skill_list\'s substring metadata filter, this searches the full markdown body. `query` is raw SQLite FTS5 MATCH syntax: bare words, "exact phrases", prefix* wildcards, AND/OR/NOT boolean operators; hyphenated/punctuated terms must be quoted, e.g. "blue-green". Can be combined with status/owner/tag filters. Returns ranked hits with a highlighted snippet, not the full body — call skill_get on a hit\'s name for that.', {
+    mcp.tool('skill_search', 'Full-text search over skill description/body/tags (grep/find-like, ranked by relevance) — unlike skill_list\'s substring metadata filter, this searches the full markdown body. `query` is raw SQLite FTS5 MATCH syntax: bare words, "exact phrases", prefix* wildcards, AND/OR/NOT boolean operators; hyphenated/punctuated terms must be quoted, e.g. "blue-green". Can be combined with status/owner/tag filters. Returns ranked hits with a highlighted snippet, not the full body — call skill_get on a hit\'s name for that. Paused skills are hidden by default — pass include_paused to see them.', {
         query: z.string().describe('FTS5 match expression, e.g. `deploy AND rollback` or `"blue green"`'),
         status: z.enum(SKILL_STATUS).optional(),
         owner: z.string().optional(),
         tag: z.string().optional(),
         limit: z.number().int().positive().max(100).optional(),
         offset: z.number().int().nonnegative().optional(),
+        include_paused: z.boolean().optional().describe('include paused skills, which are hidden by default (see skill_set_paused)'),
         ...(multiRoot ? { root: z.string().optional().describe(`filter to one root: ${rootNames}`) } : {}),
-    }, async ({ query, status, owner, tag, limit, offset, root }) => {
+    }, async ({ query, status, owner, tag, limit, offset, root, include_paused }) => {
         try {
-            const hits = repo.search(query, { root, status, owner, tag, limit, offset });
+            const hits = repo.search(query, { root, status, owner, tag, limit, offset, includePaused: include_paused });
             return { content: [{ type: 'text', text: JSON.stringify(hits, null, 2) }] };
         }
         catch (err) {
@@ -143,6 +151,21 @@ export function registerSkillTools(mcp, repo) {
             return { content: [{ type: 'text', text: err.message }], isError: true };
         }
     });
+    mcp.tool('skill_bulk_rename', 'Renames many skills at once — each entry is a {name, new_name} pair, same semantics as skill_rename (moves the folder, updates frontmatter `name`). Returns per-entry success/failure so one bad pair (unknown name, name collision) doesn\'t abort the rest of the batch.', {
+        entries: z
+            .array(z.object({ name: z.string().describe('current skill name'), new_name: z.string().describe(SKILL_NAME_DESCRIPTION) }))
+            .min(1),
+    }, async ({ entries }) => {
+        const results = repo.bulkRename(entries);
+        return { content: [{ type: 'text', text: JSON.stringify(results, null, 2) }] };
+    });
+    mcp.tool('skill_set_paused', 'Pauses or resumes skills by name — a local-only toggle stored in this machine\'s SQLite cache, never written to SKILL.md, so it never touches the file on disk and never follows the skill to another machine\'s cache. Paused skills are hidden from skill_list/skill_search by default but stay fully intact and are still fetchable directly via skill_get/skill_bulk_get — use this to temporarily stop a skill from being surfaced during discovery without deprecating (retiring) it. Returns per-name success/failure so one bad name doesn\'t abort the batch.', {
+        names: z.array(z.string()).min(1),
+        paused: z.boolean().describe('true to pause (hide from skill_list/skill_search), false to resume'),
+    }, async ({ names, paused }) => {
+        const results = repo.setPaused(names, paused);
+        return { content: [{ type: 'text', text: JSON.stringify(results, null, 2) }] };
+    });
     mcp.tool('skill_delete', 'Hard-deletes a skill by name — removes the whole skill folder (SKILL.md plus any scripts/references/assets), no tombstone.', { name: z.string() }, async ({ name }) => {
         try {
             repo.delete(name);