mcp-memory-bucket 0.4.3 → 0.5.1

package/dist/client/index.html

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

package/dist/src/memory/repository.js

@@ -172,7 +172,7 @@ export class MemoryRepository {
             description: input.description,
             doc_type: input.doc_type,
             tags: input.tags ?? [],
-            status: 'active',
+            status: input.status ?? 'active',
             related_to: input.related_to ?? null,
             deprecated: false,
             created_at: new Date().toISOString(),
@@ -278,6 +278,21 @@ export class MemoryRepository {
         fs.unlinkSync(existing.source_path);
         removeFile(this.db, 'memory_docs', existing.source_path);
     }
+    /**
+     * Strips the doc's frontmatter entirely, leaving a bare markdown file with just the body — the
+     * inverse of memory_create, for turning a managed memory doc back into a plain dropped-in file.
+     * The file stays at the same path, but loses its `key` (so it drops out of key-based lookup) and
+     * its `id` — the upsertFile call below immediately re-derives a fresh one from the filename via
+     * deriveFrontmatter's fallback, so the caller should treat this doc as gone under its old id
+     * once this returns (look it up by the new filename-derived id/key instead).
+     */
+    stripFrontmatter(id) {
+        const existing = this.get(id);
+        if (!existing)
+            throw new Error(`memory doc with id "${id}" not found`);
+        writeMarkdownFile(existing.source_path, {}, existing.body);
+        upsertFile(this.db, this.syncSpec, existing.source_path);
+    }
     /**
      * Deletes many memory docs by id in one call — e.g. cleaning up a batch of
      * abandoned docs found via search(). Returns per-id results so one bad id

package/dist/src/memory/tools.js

@@ -1,7 +1,8 @@
 import { z } from 'zod';
+import { statusSchema } from '../shared/status.js';
 const MEMORY_DOC_TYPES = ['plan', 'spec', 'sql', 'testing-todo', 'discovery', 'session-summary', 'other'];
 const MEMORY_KEY_TYPES = ['ticket', 'freeform'];
-const MEMORY_STATUS = ['active', 'shipped', 'abandoned'];
+const MEMORY_STATUS_DEFAULTS = ['active', 'shipped', 'abandoned'];
 const AUTHORING_SKILL_HINT = "Before your first call in a session, run skill_get(\"memory-bucket-authoring\") to learn the exact frontmatter schema and conventions — don't guess the shape.";
 export function registerMemoryTools(mcp, repo) {
     const roots = repo.listRoots();
@@ -26,7 +27,7 @@ export function registerMemoryTools(mcp, repo) {
     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(),
+        status: statusSchema(MEMORY_STATUS_DEFAULTS).optional(),
         tag: z.string().optional(),
         ...(multiRoot ? { root: z.string().optional().describe(`filter to one root: ${rootNames}`) } : {}),
         limit: z.number().int().positive().max(100).optional(),
@@ -45,7 +46,7 @@ export function registerMemoryTools(mcp, repo) {
         ids: z.array(z.string()).min(1),
         add_tags: z.array(z.string()).optional(),
         remove_tags: z.array(z.string()).optional(),
-        status: z.enum(MEMORY_STATUS).optional(),
+        status: statusSchema(MEMORY_STATUS_DEFAULTS).optional(),
         related_to: z.string().nullable().optional(),
         deprecated: z.boolean().optional().describe('marks docs as deprecated (or un-deprecates when false) — independent of status'),
     }, async ({ ids, add_tags, remove_tags, status, related_to, deprecated }) => {
@@ -59,12 +60,13 @@ export function registerMemoryTools(mcp, repo) {
         description: z.string().describe('distinguishes this doc from others sharing the same key'),
         body: z.string(),
         tags: z.array(z.string()).optional(),
+        status: statusSchema(MEMORY_STATUS_DEFAULTS).optional().describe('defaults to "active"'),
         related_to: z.string().optional().describe('id of a related doc, e.g. a spec linking to its plan'),
         folder: z.string().optional().describe('optional subdirectory under the memory root'),
         ...(multiRoot ? { root: z.string().describe(`which configured memory root to write into: ${rootNames}`) } : {}),
-    }, async ({ key, key_type, doc_type, description, body, tags, related_to, folder, root }) => {
+    }, async ({ key, key_type, doc_type, description, body, tags, status, related_to, folder, root }) => {
         try {
-            const doc = repo.create({ key, key_type, doc_type, description, body, tags, related_to, folder, root });
+            const doc = repo.create({ key, key_type, doc_type, description, body, tags, status, related_to, folder, root });
             return { content: [{ type: 'text', text: JSON.stringify(doc, null, 2) }] };
         }
         catch (err) {
@@ -78,6 +80,7 @@ export function registerMemoryTools(mcp, repo) {
         description: z.string().describe('distinguishes this doc from others sharing the same key'),
         body: z.string(),
         tags: z.array(z.string()).optional(),
+        status: statusSchema(MEMORY_STATUS_DEFAULTS).optional().describe('defaults to "active"'),
         related_to: z.string().optional(),
         folder: z.string().optional(),
         ...(multiRoot ? { root: z.string().describe(`which configured memory root to write into: ${rootNames}`) } : {}),
@@ -94,7 +97,7 @@ export function registerMemoryTools(mcp, repo) {
         description: z.string().optional(),
         body: z.string().optional(),
         tags: z.array(z.string()).optional(),
-        status: z.enum(MEMORY_STATUS).optional(),
+        status: statusSchema(MEMORY_STATUS_DEFAULTS).optional(),
         related_to: z.string().optional(),
         deprecated: z.boolean().optional().describe('marks the doc as deprecated (or un-deprecates when false) — independent of status'),
     }, async ({ id, body, ...frontmatterFields }) => {

package/dist/src/server.js

@@ -62,7 +62,7 @@ function buildMcpServer() {
 }
 const app = express();
 app.use(express.json());
-app.use(buildWebRouter(db, config, skillRepo, memoryRepo));
+app.use(buildWebRouter(db, config, skillRepo, memoryRepo, skillSpec, memorySpec));
 app.use(express.static(path.join(packageRoot, 'dist', 'client')));
 app.post('/mcp', async (req, res) => {
     const server = buildMcpServer();

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

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { relocate, relocateMany } from './relocate.js';
+import { statusSchema } from './status.js';
 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.";
 const overridesSchema = z
     .object({
@@ -13,7 +14,7 @@ const overridesSchema = z
     key_type: z.enum(['ticket', 'freeform']).optional().describe('memory target only'),
     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(),
+    status: statusSchema(['stable', 'beta', 'unreviewed', 'active', 'shipped', 'abandoned']).optional(),
     folder: z.string().optional().describe('optional subdirectory under the target root'),
     root: z.string().optional().describe('which configured root to write into; required if multiple roots exist for the target type'),
 })

package/dist/src/shared/status.js

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+/**
+ * Status is a free-form label, not a closed enum — the DB column has no CHECK
+ * constraint and the web UI's filter dropdown is populated from distinct values
+ * actually in use (see buildFacets in web/routes.ts), so any normalized string
+ * works end to end. This schema only enforces a consistent shape (lowercase,
+ * hyphenated) so casing/typo variants don't silently fragment that dropdown.
+ */
+const STATUS_PATTERN = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+export function normalizeStatus(status) {
+    return status.trim().toLowerCase().replace(/\s+/g, '-');
+}
+export function statusSchema(defaults) {
+    return z
+        .string()
+        .min(1)
+        .max(40)
+        .transform(normalizeStatus)
+        .refine((s) => STATUS_PATTERN.test(s), {
+        message: 'status must be lowercase alphanumeric with hyphens, e.g. "active" or "needs-review"',
+    })
+        .describe(`free-form status label, normalized to lowercase-hyphenated; conventional values: ${defaults.join(', ')} — but any value is accepted`);
+}

package/dist/src/skills/tools.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
-const SKILL_STATUS = ['stable', 'beta', 'unreviewed'];
+import { statusSchema } from '../shared/status.js';
+const SKILL_STATUS_DEFAULTS = ['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) {
@@ -21,7 +22,7 @@ export function registerSkillTools(mcp, repo) {
     });
     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(),
+        status: statusSchema(SKILL_STATUS_DEFAULTS).optional(),
         owner: z.string().optional(),
         tag: z.string().optional(),
         limit: z.number().int().positive().max(100).optional(),
@@ -42,7 +43,7 @@ export function registerSkillTools(mcp, repo) {
         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(),
+        status: statusSchema(SKILL_STATUS_DEFAULTS).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 }) => {
@@ -70,7 +71,7 @@ export function registerSkillTools(mcp, repo) {
         license: z.string().optional(),
         compatibility: z.string().max(500).optional().describe('only needed if the skill has specific environment requirements'),
         owner: z.string().optional().describe('squad or "company" — stored in frontmatter.metadata, unused for resolution in V0'),
-        status: z.enum(SKILL_STATUS).optional().describe('defaults to "unreviewed"; stored in frontmatter.metadata'),
+        status: statusSchema(SKILL_STATUS_DEFAULTS).optional().describe('defaults to "unreviewed"; stored in frontmatter.metadata'),
         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'),
@@ -92,7 +93,7 @@ export function registerSkillTools(mcp, repo) {
         license: z.string().optional(),
         compatibility: z.string().max(500).optional(),
         owner: z.string().optional(),
-        status: z.enum(SKILL_STATUS).optional(),
+        status: statusSchema(SKILL_STATUS_DEFAULTS).optional(),
         tags: z.array(z.string()).optional(),
         trigger_phrases: z.array(z.string()).optional(),
         extends: z.string().optional(),
@@ -125,7 +126,7 @@ export function registerSkillTools(mcp, repo) {
         license: z.string().optional(),
         compatibility: z.string().max(500).optional(),
         owner: z.string().optional(),
-        status: z.enum(SKILL_STATUS).optional(),
+        status: statusSchema(SKILL_STATUS_DEFAULTS).optional(),
         tags: z.array(z.string()).optional(),
         trigger_phrases: z.array(z.string()).optional(),
         extends: z.string().optional(),

package/dist/src/store/sync.js

@@ -18,7 +18,7 @@ export function skillSyncSpec(sources) {
         matchesFile: (filePath) => path.basename(filePath) === 'SKILL.md',
         columns: skillColumns,
         getId: (fm) => fm.name,
-        toRow: (fm) => ({
+        toRow: (fm, _sourcePath, mtimeMs) => ({
             id: fm.name,
             description: fm.description,
             owner: fm.metadata?.owner ?? null,
@@ -27,7 +27,7 @@ export function skillSyncSpec(sources) {
             trigger_phrases: JSON.stringify(fm.trigger_phrases ?? []),
             extends: fm.metadata?.extends ?? null,
             deprecated: fm.deprecated ? 1 : 0,
-            created_at: fm.created_at ?? null,
+            created_at: fm.created_at ?? new Date(mtimeMs).toISOString(),
         }),
     };
 }
@@ -38,7 +38,7 @@ export function memorySyncSpec(sources) {
         matchesFile: (filePath) => filePath.endsWith('.md'),
         columns: memoryColumns,
         getId: (fm) => fm.id,
-        deriveFrontmatter: (fm, filePath) => {
+        deriveFrontmatter: (fm, filePath, mtimeMs) => {
             const basename = path.basename(filePath, '.md');
             const fallbackId = slugify(basename) || 'untitled';
             return {
@@ -51,6 +51,7 @@ export function memorySyncSpec(sources) {
                 status: fm.status ?? 'active',
                 tags: fm.tags ?? [],
                 related_to: fm.related_to ?? null,
+                created_at: fm.created_at ?? new Date(mtimeMs).toISOString(),
             };
         },
         toRow: (fm) => ({
@@ -94,14 +95,14 @@ export function upsertFile(db, spec, filePath) {
     if (existing && existing.mtime_ms === parsed.mtimeMs)
         return; // unchanged, skip reprocessing
     const frontmatter = spec.deriveFrontmatter
-        ? spec.deriveFrontmatter(parsed.frontmatter, filePath)
+        ? spec.deriveFrontmatter(parsed.frontmatter, filePath, parsed.mtimeMs)
         : parsed.frontmatter;
     const id = spec.getId(frontmatter);
     if (!id) {
         console.error(`[memory-bucket] skipping ${filePath}: missing required id field in frontmatter`);
         return;
     }
-    const row = spec.toRow(frontmatter, filePath);
+    const row = spec.toRow(frontmatter, filePath, parsed.mtimeMs);
     const root = rootForFile(spec.sources, filePath);
     const cols = [...spec.columns, 'source_path', 'root', 'body', 'mtime_ms'];
     const values = [...spec.columns.map((c) => row[c]), filePath, root, parsed.body, parsed.mtimeMs];

package/dist/src/web/routes.js

@@ -2,7 +2,9 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import express from 'express';
+import matter from 'gray-matter';
 import { saveRoot, removeRoot as removeRootFromConfig, sanitizeRootName } from '../config.js';
+import { initialScan } from '../store/sync.js';
 function asArray(v) {
     if (v === undefined)
         return [];
@@ -253,8 +255,21 @@ function buildHealth(db) {
         .map((m) => m.id);
     return { danglingExtends, danglingRelatedTo, emptyTriggerPhrases, staleActiveMemoryDocs };
 }
-export function buildWebRouter(db, config, skillRepo, memoryRepo) {
+export function buildWebRouter(db, config, skillRepo, memoryRepo, skillSpec, memorySpec) {
     const router = express.Router();
+    router.post('/api/rebuild-cache', (_req, res) => {
+        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;
+            res.json({ skillCount, memoryCount });
+        }
+        catch (err) {
+            res.status(500).json({ error: err.message });
+        }
+    });
     router.get('/api/entries', (req, res) => {
         res.json(queryEntries(db, req));
     });
@@ -271,7 +286,26 @@ export function buildWebRouter(db, config, skillRepo, memoryRepo) {
         }
         const tags = JSON.parse(row.tags);
         const trigger_phrases = row.trigger_phrases ? JSON.parse(row.trigger_phrases) : undefined;
-        res.json({ ...row, tags, trigger_phrases });
+        // A memory doc's cache row always looks fully populated even for a bare file (deriveFrontmatter's
+        // fallback backfills id/key/etc — see sync.ts), so whether it actually has an authored
+        // frontmatter block has to be checked on disk. This drives "Add frontmatter" (memory only —
+        // write real values in for the first time) vs "Edit"/"Delete frontmatter". Skills have no such
+        // fallback, so a skills row reaching this route always has real frontmatter; this stays false
+        // only in the memory_docs case in practice.
+        //
+        // `raw_file` is the true on-disk content (frontmatter block + body) for the Raw view — distinct
+        // from the cache's `body` column, which is always frontmatter-stripped (see readMarkdownFile).
+        let has_frontmatter = true;
+        let raw_file;
+        try {
+            raw_file = fs.readFileSync(row.source_path, 'utf-8');
+            has_frontmatter = Object.keys(matter(raw_file).data).length > 0;
+        }
+        catch {
+            // file unreadable/missing — treat as having frontmatter so the UI doesn't offer to "add"
+            // one for a doc it can't actually reach; the existing edit/delete-doc paths will 404 instead.
+        }
+        res.json({ ...row, tags, trigger_phrases, has_frontmatter, raw_file });
     });
     router.patch('/api/entries/:table/:id/deprecated', (req, res) => {
         const { table, id } = req.params;
@@ -313,6 +347,73 @@ export function buildWebRouter(db, config, skillRepo, memoryRepo) {
         const results = table === 'skills' ? skillRepo.bulkUpdate(ids, { deprecated }) : memoryRepo.bulkUpdate(ids, { deprecated });
         res.json({ results });
     });
+    // General frontmatter edit — covers both "edit an existing doc's fields" and "add frontmatter
+    // to a bare file" (a bare memory doc already has a derived id/key from deriveFrontmatter, so
+    // "add" is just this same call supplying real values). Memory `key` is editable here (update()
+    // normalizes it). Skill `name` is not — SkillRepository.update() rejects it outright since
+    // renaming requires a real folder move (see the rename route below).
+    router.patch('/api/entries/:table/:id', (req, res) => {
+        const { table, id } = req.params;
+        const { frontmatter } = 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 (!frontmatter || typeof frontmatter !== 'object') {
+            res.status(400).json({ error: 'body must be { frontmatter: object }' });
+            return;
+        }
+        if (table === 'skills' && 'name' in frontmatter) {
+            res.status(400).json({ error: 'name cannot be changed via this route — use rename' });
+            return;
+        }
+        try {
+            const updated = table === 'skills' ? skillRepo.update(id, frontmatter) : memoryRepo.update(id, frontmatter);
+            res.json(updated);
+        }
+        catch (err) {
+            res.status(404).json({ error: err.message });
+        }
+    });
+    router.post('/api/entries/skills/:name/rename', (req, res) => {
+        const { name } = req.params;
+        const { new_name } = req.body;
+        if (!name) {
+            res.status(400).json({ error: 'name is required' });
+            return;
+        }
+        if (!new_name) {
+            res.status(400).json({ error: 'body must be { new_name: string }' });
+            return;
+        }
+        try {
+            const renamed = skillRepo.rename(name, new_name);
+            res.json(renamed);
+        }
+        catch (err) {
+            res.status(400).json({ error: err.message });
+        }
+    });
+    // Memory docs only — skill frontmatter (name/description) is required by the agentskills.io
+    // spec, so stripping it would produce a non-conformant SKILL.md no compliant agent can load.
+    router.delete('/api/entries/memory_docs/:id/frontmatter', (req, res) => {
+        const { id } = req.params;
+        if (!id) {
+            res.status(400).json({ error: 'id is required' });
+            return;
+        }
+        try {
+            memoryRepo.stripFrontmatter(id);
+            res.json({ id, frontmatterRemoved: true });
+        }
+        catch (err) {
+            res.status(404).json({ error: err.message });
+        }
+    });
     // `paused` is a local-only cache toggle (see SkillRepository/MemoryRepository#setPaused) — it
     // never touches the source file, so this goes through setPaused, not update()/bulkUpdate().
     router.patch('/api/entries/:table/:id/paused', (req, res) => {

package/package.json

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