mcp-memory-bucket 0.2.2 → 0.4.0

package/dist/src/skills/tools.js

@@ -12,6 +12,35 @@ export function registerSkillTools(mcp, repo) {
         const items = repo.list(query, root);
         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.', {
+        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(),
+        ...(multiRoot ? { root: z.string().optional().describe(`filter to one root: ${rootNames}`) } : {}),
+    }, async ({ query, status, owner, tag, limit, offset, root }) => {
+        try {
+            const hits = repo.search(query, { root, status, owner, tag, limit, offset });
+            return { content: [{ type: 'text', text: JSON.stringify(hits, null, 2) }] };
+        }
+        catch (err) {
+            return { content: [{ type: 'text', text: err.message }], isError: true };
+        }
+    });
+    mcp.tool('skill_bulk_update', 'Applies the same frontmatter change to many skills at once by name — e.g. add/remove a tag across a batch found via skill_search, or flip status for a group. add_tags/remove_tags merge or subtract per-skill; owner/status/extends overwrite uniformly when provided. Body is never touched. Returns per-name success/failure so one bad name doesn\'t abort the batch.', {
+        names: z.array(z.string()).min(1),
+        add_tags: z.array(z.string()).optional(),
+        remove_tags: z.array(z.string()).optional(),
+        owner: z.string().nullable().optional(),
+        status: z.enum(SKILL_STATUS).optional(),
+        extends: z.string().nullable().optional(),
+        deprecated: z.boolean().optional().describe('marks skills as deprecated (or un-deprecates when false) — independent of status'),
+    }, async ({ names, add_tags, remove_tags, owner, status, extends: extendsId, deprecated }) => {
+        const results = repo.bulkUpdate(names, { add_tags, remove_tags, owner, status, extends: extendsId, deprecated });
+        return { content: [{ type: 'text', text: JSON.stringify(results, null, 2) }] };
+    });
     mcp.tool('skill_get', 'Fetches a single skill by name, including its full markdown body.', { name: z.string() }, async ({ name }) => {
         const doc = repo.get(name);
         if (!doc) {
@@ -19,6 +48,10 @@ export function registerSkillTools(mcp, repo) {
         }
         return { content: [{ type: 'text', text: JSON.stringify(doc, null, 2) }] };
     });
+    mcp.tool('skill_bulk_get', 'Fetches many skills by name in one call, including full markdown bodies — e.g. hydrating a batch of skill_search hits. Missing names are simply omitted from the result, not errors.', { names: z.array(z.string()).min(1) }, async ({ names }) => {
+        const docs = repo.bulkGet(names);
+        return { content: [{ type: 'text', text: JSON.stringify(docs, null, 2) }] };
+    });
     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
@@ -44,6 +77,39 @@ export function registerSkillTools(mcp, repo) {
             return { content: [{ type: 'text', text: err.message }], isError: true };
         }
     });
+    const skillEntrySchema = z.object({
+        name: z.string().describe(SKILL_NAME_DESCRIPTION),
+        description: z.string().max(1024).describe('required by spec: what the skill does AND when to use it'),
+        body: z.string().describe('markdown body of SKILL.md'),
+        license: z.string().optional(),
+        compatibility: z.string().max(500).optional(),
+        owner: z.string().optional(),
+        status: z.enum(SKILL_STATUS).optional(),
+        tags: z.array(z.string()).optional(),
+        trigger_phrases: z.array(z.string()).optional(),
+        extends: z.string().optional(),
+        folder: z.string().optional(),
+        ...(multiRoot ? { root: z.string().describe(`which configured skill root to write into: ${rootNames}`) } : {}),
+    });
+    mcp.tool('skill_bulk_create', `Creates many skills in one call — each entry is the same shape as skill_create's args. Returns per-name success/failure so one bad entry (duplicate name, invalid name, existing directory) doesn't abort the rest of the batch. ${AUTHORING_SKILL_HINT}`, { entries: z.array(skillEntrySchema).min(1) }, async ({ entries }) => {
+        const results = repo.bulkCreate(entries.map((e) => ({
+            frontmatter: {
+                name: e.name,
+                description: e.description,
+                license: e.license,
+                compatibility: e.compatibility,
+                owner: e.owner,
+                status: e.status,
+                tags: e.tags,
+                trigger_phrases: e.trigger_phrases,
+                extends: e.extends,
+            },
+            body: e.body,
+            folder: e.folder,
+            root: e.root,
+        })));
+        return { content: [{ type: 'text', text: JSON.stringify(results, null, 2) }] };
+    });
     mcp.tool('skill_update', `Edits an existing skill in place — frontmatter fields and/or body. Only provided fields change. Use skill_rename to change the name/folder. ${AUTHORING_SKILL_HINT}`, {
         name: z.string(),
         description: z.string().max(1024).optional(),
@@ -55,6 +121,7 @@ export function registerSkillTools(mcp, repo) {
         tags: z.array(z.string()).optional(),
         trigger_phrases: z.array(z.string()).optional(),
         extends: z.string().optional(),
+        deprecated: z.boolean().optional().describe('marks the skill as deprecated (or un-deprecates when false) — independent of status'),
     }, async ({ name, body, ...frontmatterFields }) => {
         try {
             const doc = repo.update(name, frontmatterFields, body);
@@ -76,6 +143,14 @@ 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_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);
@@ -85,4 +160,8 @@ export function registerSkillTools(mcp, repo) {
             return { content: [{ type: 'text', text: err.message }], isError: true };
         }
     });
+    mcp.tool('skill_bulk_delete', 'Hard-deletes many skills by name in one call — e.g. cleaning up a batch found via skill_search/skill_list. No tombstone. Returns per-name success/failure so one bad name doesn\'t abort the rest of the batch.', { names: z.array(z.string()).min(1) }, async ({ names }) => {
+        const results = repo.bulkDelete(names);
+        return { content: [{ type: 'text', text: JSON.stringify(results, null, 2) }] };
+    });
 }

package/dist/src/store/date-extract.js

@@ -0,0 +1,49 @@
+const MONTHS = {
+    jan: '01', feb: '02', mar: '03', apr: '04', may: '05', jun: '06',
+    jul: '07', aug: '08', sep: '09', oct: '10', nov: '11', dec: '12',
+};
+const ISO_DATE_RE = /\b(\d{4})-(\d{2})-(\d{2})\b/g;
+const WRITTEN_MONTH_RE = /\b(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)[a-z]*\.?\s+(\d{1,2}),?\s+(\d{4})\b/gi;
+function isValidDate(year, month, day) {
+    if (month < 1 || month > 12 || day < 1 || day > 31)
+        return false;
+    const d = new Date(Date.UTC(year, month - 1, day));
+    return d.getUTCFullYear() === year && d.getUTCMonth() === month - 1 && d.getUTCDate() === day;
+}
+function stripCodeBlocks(body) {
+    return body.replace(/```[\s\S]*?```/g, '');
+}
+/** Extracts unique ISO (YYYY-MM-DD) dates mentioned in free text — conservative by design: only unambiguous formats (ISO, written-month-with-year) are matched, code blocks and slash-dates are skipped entirely. */
+export function extractDates(body) {
+    const text = stripCodeBlocks(body);
+    const dates = new Set();
+    for (const match of text.matchAll(ISO_DATE_RE)) {
+        const [, y, m, d] = match;
+        const year = Number(y);
+        const month = Number(m);
+        const day = Number(d);
+        if (isValidDate(year, month, day))
+            dates.add(`${y}-${m}-${d}`);
+    }
+    for (const match of text.matchAll(WRITTEN_MONTH_RE)) {
+        const [, monthName, dayStr, yearStr] = match;
+        const month = MONTHS[monthName.toLowerCase()];
+        const day = Number(dayStr);
+        const year = Number(yearStr);
+        if (month && isValidDate(year, Number(month), day)) {
+            dates.add(`${yearStr}-${month}-${String(day).padStart(2, '0')}`);
+        }
+    }
+    return Array.from(dates).sort();
+}
+/**
+ * Converts a UTC ISO timestamp (e.g. created_at) to the calendar date it
+ * falls on in the given IANA timezone (default: the OS timezone this
+ * process is running in). Distinct from extractDates()'s output, which is
+ * already timezone-naive text — this exists specifically so a UTC instant
+ * lands on the same calendar date a user in that timezone would call "today".
+ */
+export function toLocalDate(isoTimestamp, timeZone = Intl.DateTimeFormat().resolvedOptions().timeZone) {
+    const formatter = new Intl.DateTimeFormat('en-CA', { timeZone, year: 'numeric', month: '2-digit', day: '2-digit' });
+    return formatter.format(new Date(isoTimestamp));
+}

package/dist/src/store/db.js

@@ -13,6 +13,8 @@ export function openCache(dbPath) {
       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
+      deprecated INTEGER NOT NULL DEFAULT 0,
+      created_at TEXT,
       body TEXT NOT NULL,
       mtime_ms INTEGER NOT NULL
     );
@@ -28,6 +30,8 @@ export function openCache(dbPath) {
       related_to TEXT,
       source_path TEXT NOT NULL UNIQUE,
       root TEXT NOT NULL DEFAULT '',  -- name of the configured root this file lives under
+      deprecated INTEGER NOT NULL DEFAULT 0,
+      created_at TEXT,
       body TEXT NOT NULL,
       mtime_ms INTEGER NOT NULL
     );
@@ -42,18 +46,36 @@ export function openCache(dbPath) {
       tags,
       tokenize = 'porter unicode61'
     );
+
+    CREATE TABLE IF NOT EXISTS doc_dates (
+      ref_table TEXT NOT NULL,
+      ref_id TEXT NOT NULL,
+      date TEXT NOT NULL
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_doc_dates_date ON doc_dates(date);
+    CREATE INDEX IF NOT EXISTS idx_doc_dates_ref ON doc_dates(ref_table, ref_id);
   `);
-    addRootColumnIfMissing(db, 'skills');
-    addRootColumnIfMissing(db, 'memory_docs');
+    ensureColumns(db, 'skills', [
+        ['root', "TEXT NOT NULL DEFAULT ''"],
+        ['deprecated', 'INTEGER NOT NULL DEFAULT 0'],
+        ['created_at', 'TEXT'],
+    ]);
+    ensureColumns(db, 'memory_docs', [
+        ['root', "TEXT NOT NULL DEFAULT ''"],
+        ['deprecated', 'INTEGER NOT NULL DEFAULT 0'],
+        ['created_at', 'TEXT'],
+    ]);
     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 ''`);
+/** Migration for cache files created before a given column existed. Safe to call every startup. */
+function ensureColumns(db, table, columns) {
+    const existing = new Set(db.prepare(`PRAGMA table_info(${table})`).all().map((c) => c.name));
+    for (const [name, ddlType] of columns) {
+        if (!existing.has(name))
+            db.exec(`ALTER TABLE ${table} ADD COLUMN ${name} ${ddlType}`);
+    }
 }
 /** One-time backfill for existing rows the first time search_index is introduced into a cache file. */
 function backfillSearchIndex(db) {

package/dist/src/store/search.js

@@ -0,0 +1,118 @@
+/** A quoted FTS5 syntax error, translated into something an agent can act on without seeing raw SQLite internals. */
+export class SearchQueryError extends Error {
+    constructor(query, cause) {
+        super(`invalid search query "${query}": ${cause.message}. ` +
+            `FTS5 syntax notes: hyphenated/punctuated words must be quoted (e.g. "blue-green"), ` +
+            `bare words are AND'd by default, use OR/NOT for other logic, "exact phrase" for phrases, and prefix* for prefix matching.`);
+        this.name = 'SearchQueryError';
+    }
+}
+/**
+ * Full-text search over the shared FTS5 index, optionally scoped to one ref_table.
+ * `query` is passed through as raw FTS5 MATCH syntax — supports `AND`/`OR`/`NOT`,
+ * `"exact phrases"`, and `prefix*` — so callers get grep-like power for free.
+ * Ranked by bm25() (lower is better, so we negate for a "higher is better" score).
+ * Throws SearchQueryError on malformed FTS5 syntax instead of a raw SQLite error.
+ */
+export function searchIndex(db, query, opts = {}) {
+    const { table, limit = 20, offset = 0 } = opts;
+    try {
+        const rows = db
+            .prepare(`SELECT ref_table, ref_id,
+                snippet(search_index, 3, '<<', '>>', '…', 20) AS snippet,
+                -bm25(search_index) AS score
+         FROM search_index
+         WHERE search_index MATCH ? ${table ? 'AND ref_table = ?' : ''}
+         ORDER BY bm25(search_index)
+         LIMIT ? OFFSET ?`)
+            .all(...(table ? [query, table, limit, offset] : [query, limit, offset]));
+        return rows;
+    }
+    catch (err) {
+        throw new SearchQueryError(query, err);
+    }
+}
+const SNIPPET_CONTEXT_WORDS = 20;
+/**
+ * Builds a `<<...>>`-marked excerpt around the first occurrence of `date` in
+ * `body`, mirroring FTS5's snippet() style for visual consistency with the
+ * other search tools. `date` doesn't always appear literally in the body —
+ * it may have matched via created_at instead — in which case there's no
+ * position to excerpt around, so the marker stands alone with no context.
+ */
+function buildDateSnippet(body, date) {
+    const idx = body.indexOf(date);
+    if (idx === -1)
+        return `<<${date}>> (matched via created_at, not mentioned in body)`;
+    const before = body.slice(0, idx).split(/\s+/).filter(Boolean).slice(-SNIPPET_CONTEXT_WORDS).join(' ');
+    const after = body
+        .slice(idx + date.length)
+        .split(/\s+/)
+        .filter(Boolean)
+        .slice(0, SNIPPET_CONTEXT_WORDS)
+        .join(' ');
+    return `${before ? '…' + before + ' ' : ''}<<${date}>>${after ? ' ' + after + '…' : ''}`;
+}
+/**
+ * Finds skills/memory docs whose body mentions a date, OR whose created_at
+ * falls, within [start, end] (inclusive, ISO YYYY-MM-DD) — driven by the
+ * `doc_dates` side table, populated at index time from both extractDates()
+ * on the body and the doc's created_at, not FTS5. ANY-match: a doc with
+ * multiple candidate dates matches if any falls in range; `matched_date` is
+ * the earliest match, with no priority between body-extracted and created_at.
+ */
+export function searchByDate(db, start, end, opts = {}) {
+    if (start > end) {
+        throw new Error(`invalid date range: start "${start}" is after end "${end}"`);
+    }
+    const { table, limit = 20, offset = 0 } = opts;
+    const params = [start, end];
+    if (table)
+        params.push(table);
+    params.push(limit, offset);
+    const rows = db
+        .prepare(`SELECT ref_table, ref_id, MIN(date) AS matched_date
+       FROM doc_dates
+       WHERE date BETWEEN ? AND ? ${table ? 'AND ref_table = ?' : ''}
+       GROUP BY ref_table, ref_id
+       ORDER BY matched_date
+       LIMIT ? OFFSET ?`)
+        .all(...params);
+    return rows.map((row) => {
+        const bodyRow = db
+            .prepare(`SELECT body FROM ${row.ref_table} WHERE id = ?`)
+            .get(row.ref_id);
+        return {
+            ref_table: row.ref_table,
+            ref_id: row.ref_id,
+            matched_date: row.matched_date,
+            snippet: bodyRow ? buildDateSnippet(bodyRow.body, row.matched_date) : '',
+        };
+    });
+}
+/**
+ * Full-text search across BOTH skills and memory docs in one ranked list —
+ * for the common case of "find where I put X" when the caller doesn't know
+ * which bucket it landed in. No metadata filters (doc_type/status/tag differ
+ * per table); use skill_search/memory_search directly when filtering by those.
+ */
+export function searchCombined(db, query, limit = 20, offset = 0) {
+    try {
+        return db
+            .prepare(`SELECT ref_table, ref_id AS id,
+                COALESCE(s.description, m.description) AS description,
+                COALESCE(s.root, m.root) AS root,
+                snippet(search_index, 3, '<<', '>>', '…', 20) AS snippet,
+                -bm25(search_index) AS score
+         FROM search_index
+         LEFT JOIN skills s ON search_index.ref_table = 'skills' AND s.id = search_index.ref_id
+         LEFT JOIN memory_docs m ON search_index.ref_table = 'memory_docs' AND m.id = search_index.ref_id
+         WHERE search_index MATCH ?
+         ORDER BY bm25(search_index)
+         LIMIT ? OFFSET ?`)
+            .all(query, limit, offset);
+    }
+    catch (err) {
+        throw new SearchQueryError(query, err);
+    }
+}

package/dist/src/store/sync.js

@@ -3,8 +3,9 @@ import path from 'node:path';
 import chokidar, {} from 'chokidar';
 import { readMarkdownFile } from './markdown-file.js';
 import { flattenTags } from './db.js';
-const skillColumns = ['id', 'description', 'owner', 'status', 'tags', 'trigger_phrases', 'extends'];
-const memoryColumns = ['id', 'key', 'key_type', 'description', 'doc_type', 'tags', 'status', 'related_to'];
+import { extractDates, toLocalDate } from './date-extract.js';
+const skillColumns = ['id', 'description', 'owner', 'status', 'tags', 'trigger_phrases', 'extends', 'deprecated', 'created_at'];
+const memoryColumns = ['id', 'key', 'key_type', 'description', 'doc_type', 'tags', 'status', 'related_to', 'deprecated', 'created_at'];
 export function skillSyncSpec(sources) {
     return {
         table: 'skills',
@@ -20,6 +21,8 @@ export function skillSyncSpec(sources) {
             tags: JSON.stringify(fm.tags ?? []),
             trigger_phrases: JSON.stringify(fm.trigger_phrases ?? []),
             extends: fm.metadata?.extends ?? null,
+            deprecated: fm.deprecated ? 1 : 0,
+            created_at: fm.created_at ?? null,
         }),
     };
 }
@@ -39,6 +42,8 @@ export function memorySyncSpec(sources) {
             tags: JSON.stringify(fm.tags ?? []),
             status: fm.status ?? 'active',
             related_to: fm.related_to ?? null,
+            deprecated: fm.deprecated ? 1 : 0,
+            created_at: fm.created_at ?? null,
         }),
     };
 }
@@ -86,12 +91,25 @@ export function upsertFile(db, spec, filePath) {
      ON CONFLICT(id) DO UPDATE SET ${updateClause}`).run(...values);
     db.prepare(`DELETE FROM search_index WHERE ref_table = ? AND ref_id = ?`).run(spec.table, id);
     db.prepare(`INSERT INTO search_index (ref_table, ref_id, description, body, tags) VALUES (?, ?, ?, ?, ?)`).run(spec.table, id, String(row.description ?? ''), parsed.body, flattenTags(String(row.tags ?? '[]')));
+    db.prepare(`DELETE FROM doc_dates WHERE ref_table = ? AND ref_id = ?`).run(spec.table, id);
+    const dates = new Set(extractDates(parsed.body));
+    // created_at is a UTC instant; convert to the OS-local calendar date so it
+    // lines up with what a user in this timezone would call "today", matching
+    // extractDates()'s output, which is already timezone-naive local text.
+    if (row.created_at)
+        dates.add(toLocalDate(String(row.created_at)));
+    if (dates.size > 0) {
+        const insertDate = db.prepare(`INSERT INTO doc_dates (ref_table, ref_id, date) VALUES (?, ?, ?)`);
+        for (const date of dates)
+            insertDate.run(spec.table, id, date);
+    }
 }
 export function removeFile(db, table, filePath) {
     const existing = db.prepare(`SELECT id FROM ${table} WHERE source_path = ?`).get(filePath);
     db.prepare(`DELETE FROM ${table} WHERE source_path = ?`).run(filePath);
     if (existing) {
         db.prepare(`DELETE FROM search_index WHERE ref_table = ? AND ref_id = ?`).run(table, existing.id);
+        db.prepare(`DELETE FROM doc_dates WHERE ref_table = ? AND ref_id = ?`).run(table, existing.id);
     }
 }
 /** Full scan of all configured source dirs — used once at startup before the watcher takes over. */

package/dist/src/web/routes.js

@@ -2,7 +2,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import express from 'express';
-import { saveRoot, removeRoot as removeRootFromConfig } from '../config.js';
+import { saveRoot, removeRoot as removeRootFromConfig, sanitizeRootName } from '../config.js';
 function asArray(v) {
     if (v === undefined)
         return [];
@@ -23,18 +23,26 @@ function queryEntries(db, req) {
     const keyTypes = asArray(req.query.key_type);
     const roots = asArray(req.query.root);
     const q = req.query.q?.trim();
+    const deprecatedParam = req.query.deprecated;
+    const deprecated = deprecatedParam === '0' || deprecatedParam === '1' ? deprecatedParam : undefined;
+    const dateFrom = req.query.date_from?.trim() || undefined;
+    const dateTo = req.query.date_to?.trim() || undefined;
     const matchedIds = q
         ? matchSearch(db, q)
         : null;
     if (q && matchedIds && matchedIds.skills.size === 0 && matchedIds.memory_docs.size === 0) {
         return [];
     }
+    const dateIds = dateFrom || dateTo ? matchDateRange(db, dateFrom, dateTo) : null;
+    if (dateIds && dateIds.skills.size === 0 && dateIds.memory_docs.size === 0) {
+        return [];
+    }
     const results = [];
     if (type === 'skill' || type === 'all') {
-        results.push(...queryTable(db, 'skills', { tags, statuses, owners, docTypes: [], keyTypes: [], roots }, matchedIds?.skills));
+        results.push(...queryTable(db, 'skills', { tags, statuses, owners, docTypes: [], keyTypes: [], roots, deprecated }, intersectIds(matchedIds?.skills, dateIds?.skills)));
     }
     if (type === 'memory' || type === 'all') {
-        results.push(...queryTable(db, 'memory_docs', { tags, statuses, owners: [], docTypes, keyTypes, roots }, matchedIds?.memory_docs));
+        results.push(...queryTable(db, 'memory_docs', { tags, statuses, owners: [], docTypes, keyTypes, roots, deprecated }, intersectIds(matchedIds?.memory_docs, dateIds?.memory_docs)));
     }
     const sort = req.query.sort ?? 'mtime_desc';
     results.sort((a, b) => {
@@ -42,6 +50,15 @@ function queryEntries(db, req) {
             return a.mtime_ms - b.mtime_ms;
         if (sort === 'name_asc')
             return a.name.localeCompare(b.name);
+        if (sort === 'created_at_asc') {
+            if (!a.created_at && !b.created_at)
+                return 0;
+            if (!a.created_at)
+                return 1; // missing created_at sorts last
+            if (!b.created_at)
+                return -1;
+            return a.created_at.localeCompare(b.created_at);
+        }
         return b.mtime_ms - a.mtime_ms; // mtime_desc, default
     });
     return results;
@@ -74,13 +91,17 @@ function queryTable(db, table, filters, restrictToIds) {
         where += ` AND root IN (${filters.roots.map(() => '?').join(', ')})`;
         params.push(...filters.roots);
     }
+    if (filters.deprecated !== undefined) {
+        where += ` AND deprecated = ?`;
+        params.push(filters.deprecated === '1' ? 1 : 0);
+    }
     if (restrictToIds) {
         where += ` AND id IN (${[...restrictToIds].map(() => '?').join(', ')})`;
         params.push(...restrictToIds);
     }
     if (table === 'skills') {
         const rows = db
-            .prepare(`SELECT id, description, owner, status, tags, root, mtime_ms FROM skills WHERE ${where}`)
+            .prepare(`SELECT id, description, owner, status, tags, root, mtime_ms, deprecated, created_at FROM skills WHERE ${where}`)
             .all(...params);
         return rows.map((r) => ({
             _table: 'skills',
@@ -94,10 +115,12 @@ function queryTable(db, table, filters, restrictToIds) {
             key_type: null,
             root: r.root,
             mtime_ms: r.mtime_ms,
+            deprecated: !!r.deprecated,
+            created_at: r.created_at,
         }));
     }
     const rows = db
-        .prepare(`SELECT id, key, description, doc_type, key_type, status, tags, root, mtime_ms FROM memory_docs WHERE ${where}`)
+        .prepare(`SELECT id, key, description, doc_type, key_type, status, tags, root, mtime_ms, deprecated, created_at FROM memory_docs WHERE ${where}`)
         .all(...params);
     return rows.map((r) => ({
         _table: 'memory_docs',
@@ -111,8 +134,40 @@ function queryTable(db, table, filters, restrictToIds) {
         key_type: r.key_type,
         root: r.root,
         mtime_ms: r.mtime_ms,
+        deprecated: !!r.deprecated,
+        created_at: r.created_at,
     }));
 }
+/** Combines two optional id-restriction sets (e.g. from `q` and a date range) into one, when both are present. */
+function intersectIds(a, b) {
+    if (!a)
+        return b;
+    if (!b)
+        return a;
+    return new Set([...a].filter((id) => b.has(id)));
+}
+/** Queries the `doc_dates` side table for ids whose body-extracted or created_at date falls in [from, to], bucketed by source table. */
+function matchDateRange(db, from, to) {
+    const skills = new Set();
+    const memory_docs = new Set();
+    const params = [];
+    let where = '1 = 1';
+    if (from) {
+        where += ' AND date >= ?';
+        params.push(from);
+    }
+    if (to) {
+        where += ' AND date <= ?';
+        params.push(to);
+    }
+    const rows = db
+        .prepare(`SELECT DISTINCT ref_table, ref_id FROM doc_dates WHERE ${where}`)
+        .all(...params);
+    for (const row of rows) {
+        (row.ref_table === 'skills' ? skills : memory_docs).add(row.ref_id);
+    }
+    return { skills, memory_docs };
+}
 /** Runs the FTS5 query once and buckets matching ids by source table. */
 function matchSearch(db, q) {
     const skills = new Set();
@@ -190,15 +245,6 @@ function buildHealth(db) {
         .map((m) => m.id);
     return { danglingExtends, danglingRelatedTo, emptyTriggerPhrases, staleActiveMemoryDocs };
 }
-/** Lowercase-hyphenate a folder-derived root name, same shape as skill names. */
-function sanitizeRootName(raw) {
-    return raw
-        .trim()
-        .toLowerCase()
-        .replace(/[^a-z0-9]+/g, '-')
-        .replace(/^-+|-+$/g, '')
-        .slice(0, 64);
-}
 export function buildWebRouter(db, config, skillRepo, memoryRepo) {
     const router = express.Router();
     router.get('/api/entries', (req, res) => {
@@ -219,6 +265,81 @@ export function buildWebRouter(db, config, skillRepo, memoryRepo) {
         const trigger_phrases = row.trigger_phrases ? JSON.parse(row.trigger_phrases) : undefined;
         res.json({ ...row, tags, trigger_phrases });
     });
+    router.patch('/api/entries/:table/:id/deprecated', (req, res) => {
+        const { table, id } = req.params;
+        const { deprecated } = req.body;
+        if (table !== 'skills' && table !== 'memory_docs') {
+            res.status(400).json({ error: 'table must be "skills" or "memory_docs"' });
+            return;
+        }
+        if (!id) {
+            res.status(400).json({ error: 'id is required' });
+            return;
+        }
+        if (typeof deprecated !== 'boolean') {
+            res.status(400).json({ error: 'body must be { deprecated: boolean }' });
+            return;
+        }
+        try {
+            if (table === 'skills')
+                skillRepo.update(id, { deprecated });
+            else
+                memoryRepo.update(id, { deprecated });
+            res.json({ id, deprecated });
+        }
+        catch (err) {
+            res.status(404).json({ error: err.message });
+        }
+    });
+    router.post('/api/entries/:table/bulk/deprecated', (req, res) => {
+        const { table } = req.params;
+        const { ids, deprecated } = req.body;
+        if (table !== 'skills' && table !== 'memory_docs') {
+            res.status(400).json({ error: 'table must be "skills" or "memory_docs"' });
+            return;
+        }
+        if (!Array.isArray(ids) || ids.length === 0 || typeof deprecated !== 'boolean') {
+            res.status(400).json({ error: 'body must be { ids: string[], deprecated: boolean }' });
+            return;
+        }
+        const results = table === 'skills' ? skillRepo.bulkUpdate(ids, { deprecated }) : memoryRepo.bulkUpdate(ids, { deprecated });
+        res.json({ results });
+    });
+    router.delete('/api/entries/:table/:id', (req, res) => {
+        const { table, id } = req.params;
+        if (table !== 'skills' && table !== 'memory_docs') {
+            res.status(400).json({ error: 'table must be "skills" or "memory_docs"' });
+            return;
+        }
+        if (!id) {
+            res.status(400).json({ error: 'id is required' });
+            return;
+        }
+        try {
+            if (table === 'skills')
+                skillRepo.delete(id);
+            else
+                memoryRepo.delete(id);
+            res.json({ deleted: id });
+        }
+        catch (err) {
+            res.status(404).json({ error: err.message });
+        }
+    });
+    router.post('/api/entries/:table/bulk/delete', (req, res) => {
+        const { table } = req.params;
+        const { ids } = req.body;
+        if (table !== 'skills' && table !== 'memory_docs') {
+            res.status(400).json({ error: 'table must be "skills" or "memory_docs"' });
+            return;
+        }
+        if (!Array.isArray(ids) || ids.length === 0) {
+            res.status(400).json({ error: 'body must be { ids: string[] }' });
+            return;
+        }
+        const results = table === 'skills' ? skillRepo.bulkDelete(ids) : memoryRepo.bulkDelete(ids);
+        res.json({ results });
+    });
     router.get('/api/facets', (req, res) => {
         const type = req.query.type ?? 'all';
         res.json(buildFacets(db, type));

package/dist/src/web/ui-tool.js

@@ -1,5 +1,5 @@
 export function registerUiTool(mcp, port) {
-    mcp.tool('bucket_open_ui', 'Returns the URL for the mem-bucket web viewer — a read-only browser UI for searching/filtering skills and memory docs by tag, status, owner, and fulltext. Not for editing; use the skill_*/memory_* tools for that.', {}, async () => {
+    mcp.tool('bucket_open_ui', 'Returns the URL for the mem-bucket web viewer — a browser UI for searching/filtering skills and memory docs by tag, status, owner, deprecated flag, and fulltext, sorting by creation date, and marking items deprecated or deleting them (single or bulk). For anything beyond that, use the skill_*/memory_* tools instead.', {}, async () => {
         const url = `http://localhost:${port}/`;
         return { content: [{ type: 'text', text: url }] };
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-memory-bucket",
-  "version": "0.2.2",
+  "version": "0.4.0",
   "type": "module",
   "description": "MCP server exposing skill_* (reusable coding patterns) and memory_* (point-in-time working context) tools over a markdown+frontmatter source, cached into SQLite at runtime.",
   "repository": {