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

mcp-memory-bucket 0.2.2 → 0.3.0

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/README.md +47 -13
package/dist/client/assets/{index-BxAZ48QK.js → index-DIO48C0V.js} +212 -113
package/dist/client/index.html +1 -1
package/dist/src/memory/repository.js +117 -0
package/dist/src/memory/tools.js +52 -0
package/dist/src/server.js +3 -1
package/dist/src/shared/relocate-tool.js +32 -18
package/dist/src/shared/relocate.js +9 -0
package/dist/src/shared/search-tool.js +18 -0
package/dist/src/skills/builtin/memory-bucket-authoring/SKILL.md +423 -7
package/dist/src/skills/repository.js +129 -0
package/dist/src/skills/tools.js +71 -0
package/dist/src/store/db.js +21 -8
package/dist/src/store/search.js +60 -0
package/dist/src/store/sync.js +6 -2
package/dist/src/web/routes.js +98 -4
package/dist/src/web/ui-tool.js +1 -1
package/package.json +1 -1

package/dist/client/index.html CHANGED Viewed

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

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

@@ -5,6 +5,7 @@ import { writeMarkdownFile } from '../store/markdown-file.js';
 import { slugify } from '../store/slug.js';
 import { resolveWithinBase } from '../store/safe-path.js';
 import { upsertFile, removeFile, scanSingleRoot, unregisterRoot, memorySyncSpec } from '../store/sync.js';
+import { SearchQueryError } from '../store/search.js';
 import { normalizeKey } from '../types.js';
 function rowToDoc(row) {
     return {
@@ -16,6 +17,8 @@ function rowToDoc(row) {
         tags: JSON.parse(row.tags),
         status: row.status,
         related_to: row.related_to,
+        deprecated: !!row.deprecated,
+        created_at: row.created_at ?? undefined,
         source_path: row.source_path,
         root: row.root,
         body: row.body,
@@ -79,10 +82,58 @@ export class MemoryRepository {
             : this.db.prepare(`SELECT * FROM memory_docs WHERE key = ?`).all(normalized);
         return rows.map(rowToDoc);
     }
+    /**
+     * Full-text search over memory description/body/tags via FTS5 — `query` is
+     * raw FTS5 MATCH syntax (AND/OR/NOT, "phrases", prefix*). Ranked by bm25.
+     * Optional metadata filters (doc_type/status/root/tag) apply before limit/offset,
+     * 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 conditions = [];
+        const params = [query];
+        if (docType) {
+            conditions.push('m.doc_type = ?');
+            params.push(docType);
+        }
+        if (status) {
+            conditions.push('m.status = ?');
+            params.push(status);
+        }
+        if (root) {
+            conditions.push('m.root = ?');
+            params.push(root);
+        }
+        if (tag) {
+            conditions.push('EXISTS (SELECT 1 FROM json_each(m.tags) WHERE value = ?)');
+            params.push(tag);
+        }
+        params.push(limit, offset);
+        try {
+            const rows = this.db
+                .prepare(`SELECT m.id, m.key, m.description, m.doc_type, m.root,
+                  snippet(search_index, 3, '<<', '>>', '…', 20) AS snippet,
+                  -bm25(search_index) AS score
+           FROM search_index
+           JOIN memory_docs m ON m.id = search_index.ref_id
+           WHERE search_index.ref_table = 'memory_docs' AND search_index MATCH ? ${conditions.map((c) => `AND ${c}`).join(' ')}
+           ORDER BY bm25(search_index)
+           LIMIT ? OFFSET ?`)
+                .all(...params);
+            return rows;
+        }
+        catch (err) {
+            throw new SearchQueryError(query, err);
+        }
+    }
     get(id) {
         const row = this.db.prepare(`SELECT * FROM memory_docs WHERE id = ?`).get(id);
         return row ? rowToDoc(row) : null;
     }
+    /** Fetches many memory docs by id in one call — e.g. hydrating full bodies for a batch of search() hits. Missing ids are simply absent from the result, not errors. */
+    bulkGet(ids) {
+        return ids.map((id) => this.get(id)).filter((doc) => doc !== null);
+    }
     listKeys(keyPrefix) {
         const rows = this.db
             .prepare(`SELECT key, COUNT(*) as doc_count FROM memory_docs GROUP BY key ORDER BY key`)
@@ -107,6 +158,8 @@ export class MemoryRepository {
             tags: input.tags ?? [],
             status: 'active',
             related_to: input.related_to ?? null,
+            deprecated: false,
+            created_at: new Date().toISOString(),
             source_path: filePath,
             root: targetRoot.name,
         };
@@ -114,6 +167,22 @@ export class MemoryRepository {
         upsertFile(this.db, this.syncSpec, filePath);
         return { ...fm, body: input.body };
     }
+    /**
+     * Creates many memory docs in one call — each entry is the same shape as
+     * create()'s input. Returns per-key results (with the id filled in on
+     * success) so one bad entry doesn't abort the rest of the batch.
+     */
+    bulkCreate(entries) {
+        return entries.map((entry) => {
+            try {
+                const doc = this.create(entry);
+                return { key: entry.key, ok: true, id: doc.id };
+            }
+            catch (err) {
+                return { key: entry.key, ok: false, error: err.message };
+            }
+        });
+    }
     update(id, frontmatter, body) {
         const existing = this.get(id);
         if (!existing)
@@ -129,6 +198,38 @@ export class MemoryRepository {
         upsertFile(this.db, this.syncSpec, existing.source_path);
         return { ...merged, body: newBody };
     }
+    /**
+     * Applies the same frontmatter change to many memory docs at once — e.g.
+     * add/remove a tag across a batch found via search(), or flip status for a
+     * group (e.g. mark a set of docs "shipped"). Tags in `add_tags`/`remove_tags`
+     * are merged/subtracted per-doc; `status`/`related_to` overwrite uniformly
+     * when provided. Never touches body. Returns per-id results so partial
+     * failures (e.g. an unknown id) don't abort the rest of the batch.
+     */
+    bulkUpdate(ids, changes) {
+        return ids.map((id) => {
+            try {
+                const existing = this.get(id);
+                if (!existing)
+                    throw new Error(`memory doc with id "${id}" not found`);
+                let tags = existing.tags;
+                if (changes.add_tags?.length)
+                    tags = Array.from(new Set([...tags, ...changes.add_tags]));
+                if (changes.remove_tags?.length)
+                    tags = tags.filter((t) => !changes.remove_tags.includes(t));
+                this.update(id, {
+                    tags,
+                    ...(changes.status !== undefined ? { status: changes.status } : {}),
+                    ...(changes.related_to !== undefined ? { related_to: changes.related_to } : {}),
+                    ...(changes.deprecated !== undefined ? { deprecated: changes.deprecated } : {}),
+                });
+                return { id, ok: true };
+            }
+            catch (err) {
+                return { id, ok: false, error: err.message };
+            }
+        });
+    }
     delete(id) {
         const existing = this.get(id);
         if (!existing)
@@ -136,6 +237,22 @@ export class MemoryRepository {
         fs.unlinkSync(existing.source_path);
         removeFile(this.db, 'memory_docs', 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
+     * doesn't abort the rest of the batch.
+     */
+    bulkDelete(ids) {
+        return ids.map((id) => {
+            try {
+                this.delete(id);
+                return { id, ok: true };
+            }
+            catch (err) {
+                return { id, ok: false, error: err.message };
+            }
+        });
+    }
 }
 function stripSourcePath(fm) {
     const { source_path: _sp, root: _root, ...rest } = fm;

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

@@ -14,10 +14,42 @@ export function registerMemoryTools(mcp, repo) {
         const docs = repo.getByKey(key, doc_type);
         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 }) => {
+        const docs = repo.bulkGet(ids);
+        return { content: [{ type: 'text', text: JSON.stringify(docs, null, 2) }] };
+    });
     mcp.tool('memory_list', 'Browses available memory keys (optionally filtered by a prefix) without needing to know the exact key upfront. Returns each key with its doc count.', { key_prefix: z.string().optional() }, async ({ key_prefix }) => {
         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.', {
+        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(),
+        tag: z.string().optional(),
+        ...(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 }) => {
+        try {
+            const hits = repo.search(query, { docType: doc_type, status, tag, root, 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('memory_bulk_update', 'Applies the same frontmatter change to many memory docs at once by id — e.g. add/remove a tag across a batch found via memory_search, or mark a group of docs "shipped". add_tags/remove_tags merge or subtract per-doc; status/related_to overwrite uniformly when provided. Body is never touched. Returns per-id success/failure so one bad id doesn\'t abort the batch.', {
+        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(),
+        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 }) => {
+        const results = repo.bulkUpdate(ids, { add_tags, remove_tags, status, related_to, deprecated });
+        return { content: [{ type: 'text', text: JSON.stringify(results, null, 2) }] };
+    });
     mcp.tool('memory_create', `Writes a new memory doc (plan, spec, SQL, testing notes, discovery, etc.) into the memory root under the given key. ${AUTHORING_SKILL_HINT}`, {
         key: z.string().describe('lookup handle — ticket ID or free-form name; normalized on write'),
         key_type: z.enum(MEMORY_KEY_TYPES),
@@ -37,6 +69,21 @@ export function registerMemoryTools(mcp, repo) {
             return { content: [{ type: 'text', text: err.message }], isError: true };
         }
     });
+    const memoryEntrySchema = z.object({
+        key: z.string().describe('lookup handle — ticket ID or free-form name; normalized on write'),
+        key_type: z.enum(MEMORY_KEY_TYPES),
+        doc_type: z.enum(MEMORY_DOC_TYPES),
+        description: z.string().describe('distinguishes this doc from others sharing the same key'),
+        body: z.string(),
+        tags: z.array(z.string()).optional(),
+        related_to: z.string().optional(),
+        folder: z.string().optional(),
+        ...(multiRoot ? { root: z.string().describe(`which configured memory root to write into: ${rootNames}`) } : {}),
+    });
+    mcp.tool('memory_bulk_create', `Writes many memory docs in one call — each entry is the same shape as memory_create's args. Returns per-key success/failure (with the new id on success) so one bad entry doesn't abort the rest of the batch. ${AUTHORING_SKILL_HINT}`, { entries: z.array(memoryEntrySchema).min(1) }, async ({ entries }) => {
+        const results = repo.bulkCreate(entries);
+        return { content: [{ type: 'text', text: JSON.stringify(results, null, 2) }] };
+    });
     mcp.tool('memory_update', `Edits an existing memory doc in place — frontmatter fields and/or body. Only provided fields change. ${AUTHORING_SKILL_HINT}`, {
         id: z.string(),
         key: z.string().optional(),
@@ -47,6 +94,7 @@ export function registerMemoryTools(mcp, repo) {
         tags: z.array(z.string()).optional(),
         status: z.enum(MEMORY_STATUS).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 }) => {
         try {
             const doc = repo.update(id, frontmatterFields, body);
@@ -65,6 +113,10 @@ export function registerMemoryTools(mcp, repo) {
             return { content: [{ type: 'text', text: err.message }], isError: true };
         }
     });
+    mcp.tool('memory_bulk_delete', 'Hard-deletes many memory docs by id in one call — e.g. cleaning up a batch of abandoned docs found via memory_search. No tombstone. Returns per-id success/failure so one bad id doesn\'t abort the rest of the batch.', { ids: z.array(z.string()).min(1) }, async ({ ids }) => {
+        const results = repo.bulkDelete(ids);
+        return { content: [{ type: 'text', text: JSON.stringify(results, null, 2) }] };
+    });
     mcp.tool('memory_save_session', `Saves a summary of the current chat session as a memory doc (doc_type "session-summary"). Pass a summary, not a raw transcript. If key or description are omitted, ask the user for them rather than guessing. ${AUTHORING_SKILL_HINT}`, {
         summary: z.string().describe('a scannable summary of the session, not a raw transcript'),
         key: z.string().optional(),

package/dist/src/server.js CHANGED Viewed

@@ -11,6 +11,7 @@ import { MemoryRepository } from './memory/repository.js';
 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 { buildWebRouter } from './web/routes.js';
 import { registerUiTool } from './web/ui-tool.js';
 // server.ts is rebuilt from `buildMcpServer()` on every /mcp request (see below),
@@ -47,12 +48,13 @@ 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 a shared relocate tool. 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 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.`;
 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);
     registerUiTool(server, PORT);
     return server;
 }

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

@@ -1,28 +1,29 @@
 import { z } from 'zod';
-import { relocate } from './relocate.js';
+import { relocate, relocateMany } from './relocate.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({
+    name: z.string().optional().describe('skill target only: lowercase, hyphenated, <=64 chars — becomes the skill folder name'),
+    description: z
+        .string()
+        .max(1024)
+        .optional()
+        .describe('required for skill target (cannot be inferred from a filename — must state what the skill does and when to use it); optional for memory target where it distinguishes this doc from siblings under the same key'),
+    key: z.string().optional().describe('memory target only'),
+    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(),
+    folder: z.string().optional().describe('optional subdirectory under the target root'),
+    root: z.string().optional().describe('which configured root to write into; required if multiple roots exist for the target type'),
+})
+    .optional();
 export function registerRelocateTool(mcp, skillRepo, memoryRepo) {
     mcp.tool('relocate', `Moves an existing local markdown file into the skill or memory source directory, converting it into a properly frontmattered doc. Default is a move (original deleted); pass keep_original to copy instead. On a weak/ambiguous filename match for memory docs, does nothing — no guess, no partial write; ask the user for an explicit key/description and retry with overrides. ${AUTHORING_SKILL_HINT}`, {
         path: z.string().describe('absolute or relative path to the local file to relocate'),
         target: z.enum(['skill', 'memory']),
         keep_original: z.boolean().optional().describe('if true, copies instead of moving (default: move)'),
-        overrides: z
-            .object({
-            name: z.string().optional().describe('skill target only: lowercase, hyphenated, <=64 chars — becomes the skill folder name'),
-            description: z
-                .string()
-                .max(1024)
-                .optional()
-                .describe('required for skill target (cannot be inferred from a filename — must state what the skill does and when to use it); optional for memory target where it distinguishes this doc from siblings under the same key'),
-            key: z.string().optional().describe('memory target only'),
-            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(),
-            folder: z.string().optional().describe('optional subdirectory under the target root'),
-            root: z.string().optional().describe('which configured root to write into; required if multiple roots exist for the target type'),
-        })
-            .optional(),
+        overrides: overridesSchema,
     }, async (opts) => {
         const result = relocate(opts, skillRepo, memoryRepo);
         return {
@@ -30,4 +31,17 @@ export function registerRelocateTool(mcp, skillRepo, memoryRepo) {
             isError: !result.moved,
         };
     });
+    mcp.tool('relocate_bulk', `Relocates many local files in one call — each entry is the same shape as relocate's args. Returns one result per path (in order); a weak/ambiguous filename match for one file does not block the rest of the batch. ${AUTHORING_SKILL_HINT}`, {
+        entries: z
+            .array(z.object({
+            path: z.string().describe('absolute or relative path to the local file to relocate'),
+            target: z.enum(['skill', 'memory']),
+            keep_original: z.boolean().optional(),
+            overrides: overridesSchema,
+        }))
+            .min(1),
+    }, async ({ entries }) => {
+        const results = relocateMany(entries, skillRepo, memoryRepo);
+        return { content: [{ type: 'text', text: JSON.stringify(results, null, 2) }] };
+    });
 }

package/dist/src/shared/relocate.js CHANGED Viewed

@@ -98,6 +98,15 @@ export function relocate(opts, skillRepo, memoryRepo) {
         fs.unlinkSync(opts.path);
     return { moved: true, id: doc.id, target: 'memory' };
 }
+/**
+ * Relocates many files in one call — each entry is the same shape as
+ * relocate()'s options, minus `path` which is supplied per-entry. Returns one
+ * RelocateResult per path (in order) so one bad/ambiguous file doesn't abort
+ * the rest of the batch — same "no guess, no partial write" behavior per file.
+ */
+export function relocateMany(entries, skillRepo, memoryRepo) {
+    return entries.map((entry) => ({ path: entry.path, ...relocate(entry, skillRepo, memoryRepo) }));
+}
 function slugFromFilename(filePath) {
     return path
         .basename(filePath, path.extname(filePath))

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

@@ -0,0 +1,18 @@
+import { z } from 'zod';
+import { searchCombined, 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"`'),
+        limit: z.number().int().positive().max(100).optional(),
+        offset: z.number().int().nonnegative().optional(),
+    }, async ({ query, limit, offset }) => {
+        try {
+            const hits = searchCombined(db, query, limit, offset);
+            return { content: [{ type: 'text', text: JSON.stringify(hits, null, 2) }] };
+        }
+        catch (err) {
+            const message = err instanceof SearchQueryError ? err.message : err.message;
+            return { content: [{ type: 'text', text: message }], isError: true };
+        }
+    });
+}