mcp-memory-bucket 0.5.4 → 0.6.0

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-6BCcM6pL.js"></script>
+  <script type="module" crossorigin src="/assets/index-PIigsGBG.js"></script>
 </head>
 <body>
   <mem-bucket-app></mem-bucket-app>

package/dist/src/attachments/repository.js

@@ -0,0 +1,78 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { attachmentsDirFor, writeAttachmentFile, listAttachmentFiles } from './storage.js';
+import { resolveWithinBase } from '../store/safe-path.js';
+export class AttachmentRepository {
+    memoryRepo;
+    skillRepo;
+    constructor(memoryRepo, skillRepo) {
+        this.memoryRepo = memoryRepo;
+        this.skillRepo = skillRepo;
+    }
+    getDoc(kind, docIdOrName) {
+        const doc = kind === 'memory' ? this.memoryRepo.get(docIdOrName) : this.skillRepo.get(docIdOrName);
+        if (!doc)
+            throw new Error(`${kind} doc "${docIdOrName}" not found`);
+        return doc;
+    }
+    saveAttachmentsList(kind, docIdOrName, attachments) {
+        if (kind === 'memory') {
+            this.memoryRepo.update(docIdOrName, { attachments });
+        }
+        else {
+            this.skillRepo.update(docIdOrName, { attachments });
+        }
+    }
+    add(kind, docIdOrName, filename, data) {
+        const doc = this.getDoc(kind, docIdOrName);
+        const dir = attachmentsDirFor(doc.source_path, kind);
+        const entry = writeAttachmentFile(dir, filename, data);
+        const existing = doc.attachments ?? [];
+        this.saveAttachmentsList(kind, docIdOrName, [...existing, entry]);
+        return entry;
+    }
+    get(kind, docIdOrName, filename) {
+        const doc = this.getDoc(kind, docIdOrName);
+        return (doc.attachments ?? []).find((a) => a.filename === filename);
+    }
+    update(kind, docIdOrName, filename, data) {
+        const doc = this.getDoc(kind, docIdOrName);
+        const dir = attachmentsDirFor(doc.source_path, kind);
+        const existingEntry = (doc.attachments ?? []).find((a) => a.filename === filename);
+        if (!existingEntry)
+            throw new Error(`attachment "${filename}" not found on ${kind} doc "${docIdOrName}"`);
+        const safePath = resolveWithinBase(dir, undefined, filename);
+        fs.rmSync(safePath, { force: true });
+        const written = writeAttachmentFile(dir, filename, data);
+        // Full replace: preserve position, overwrite metadata for this filename entry.
+        const next = (doc.attachments ?? []).map((a) => (a.filename === filename ? written : a));
+        this.saveAttachmentsList(kind, docIdOrName, next);
+        return written;
+    }
+    remove(kind, docIdOrName, filename) {
+        const doc = this.getDoc(kind, docIdOrName);
+        const dir = attachmentsDirFor(doc.source_path, kind);
+        const safePath = resolveWithinBase(dir, undefined, filename);
+        fs.rmSync(safePath, { force: true });
+        const next = (doc.attachments ?? []).filter((a) => a.filename !== filename);
+        this.saveAttachmentsList(kind, docIdOrName, next);
+    }
+    list(kind, docIdOrName) {
+        return this.getDoc(kind, docIdOrName).attachments ?? [];
+    }
+    /** Absolute filesystem path for an attachment's file, for callers (e.g. MCP tools) that need to Read it. */
+    absolutePathFor(kind, docIdOrName, filename) {
+        const doc = this.getDoc(kind, docIdOrName);
+        return path.join(attachmentsDirFor(doc.source_path, kind), filename);
+    }
+    reconcile(kind, docIdOrName) {
+        const doc = this.getDoc(kind, docIdOrName);
+        const dir = attachmentsDirFor(doc.source_path, kind);
+        const declared = new Set((doc.attachments ?? []).map((a) => a.filename));
+        const onDisk = new Set(listAttachmentFiles(dir));
+        const orphans = [...declared].filter((f) => !onDisk.has(f));
+        const unlisted = [...onDisk].filter((f) => !declared.has(f));
+        return { orphans, unlisted };
+    }
+}
+export { attachmentsDirFor };

package/dist/src/attachments/storage.js

@@ -0,0 +1,67 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { resolveWithinBase } from '../store/safe-path.js';
+import { ATTACHMENT_MAX_BYTES } from '../config.js';
+export { ATTACHMENT_MAX_BYTES };
+/**
+ * Skills already live one-per-directory (<skillDir>/SKILL.md), so attachments
+ * sit directly in that directory. Memory docs are flat files (<id>.md) with no
+ * per-doc directory, so attachments get a new sibling directory named after
+ * the doc's id, alongside the existing file.
+ */
+export function attachmentsDirFor(docSourcePath, kind) {
+    if (kind === 'skill') {
+        return path.join(path.dirname(docSourcePath), 'attachments');
+    }
+    const dir = path.dirname(docSourcePath);
+    const id = path.basename(docSourcePath, '.md');
+    return path.join(dir, id, 'attachments');
+}
+const MIME_BY_EXT = {
+    '.json': 'application/json',
+    '.xml': 'application/xml',
+    '.txt': 'text/plain',
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.pdf': 'application/pdf',
+    '.csv': 'text/csv',
+};
+function guessMimeType(filename) {
+    return MIME_BY_EXT[path.extname(filename).toLowerCase()] ?? 'application/octet-stream';
+}
+function uniqueFilename(dir, filename) {
+    // Validate that the filename doesn't escape the directory
+    resolveWithinBase(dir, undefined, filename);
+    if (!fs.existsSync(path.join(dir, filename)))
+        return filename;
+    const ext = path.extname(filename);
+    const base = path.basename(filename, ext);
+    let n = 2;
+    while (fs.existsSync(path.join(dir, `${base}-${n}${ext}`)))
+        n++;
+    return `${base}-${n}${ext}`;
+}
+/** `dir` is the attachments directory itself, as returned by attachmentsDirFor. */
+export function writeAttachmentFile(dir, filename, data) {
+    if (data.byteLength > ATTACHMENT_MAX_BYTES) {
+        throw new Error(`attachment "${filename}" (${data.byteLength} bytes) exceeds the ${ATTACHMENT_MAX_BYTES}-byte limit`);
+    }
+    fs.mkdirSync(dir, { recursive: true });
+    const finalName = uniqueFilename(dir, filename);
+    const safePath = resolveWithinBase(dir, undefined, finalName);
+    fs.writeFileSync(safePath, data);
+    return {
+        filename: finalName,
+        path: path.join('attachments', finalName),
+        mime_type: guessMimeType(finalName),
+        size: data.byteLength,
+        added_at: new Date().toISOString(),
+    };
+}
+export function listAttachmentFiles(dir) {
+    if (!fs.existsSync(dir))
+        return [];
+    return fs.readdirSync(dir).filter((name) => fs.statSync(path.join(dir, name)).isFile());
+}

package/dist/src/attachments/tools.js

@@ -0,0 +1,85 @@
+import { z } from 'zod';
+import fs from 'node:fs';
+import { ATTACHMENT_MAX_BYTES } from './storage.js';
+const kindSchema = z.enum(['memory', 'skill']);
+/** Cheap pre-check so we never read a too-large file's bytes into memory before rejecting it. */
+function assertFileSizeOk(file_path) {
+    const { size } = fs.statSync(file_path);
+    if (size > ATTACHMENT_MAX_BYTES) {
+        throw new Error(`file "${file_path}" (${size} bytes) exceeds the ${ATTACHMENT_MAX_BYTES}-byte limit`);
+    }
+}
+export function registerAttachmentTools(mcp, attachRepo) {
+    mcp.tool('attachment_add', 'Attaches a raw file (JSON, image, XML, etc.) to a memory doc or skill. Auto-renames on filename collision.', {
+        kind: kindSchema,
+        doc: z.string().describe('memory doc id or skill name'),
+        filename: z.string(),
+        file_path: z.string().describe('local filesystem path to the file to attach'),
+    }, async ({ kind, doc, filename, file_path }) => {
+        try {
+            assertFileSizeOk(file_path);
+            const data = fs.readFileSync(file_path);
+            const entry = attachRepo.add(kind, doc, filename, data);
+            const absolute_path = attachRepo.absolutePathFor(kind, doc, entry.filename);
+            return { content: [{ type: 'text', text: JSON.stringify({ ...entry, absolute_path }, null, 2) }] };
+        }
+        catch (err) {
+            return { content: [{ type: 'text', text: err.message }], isError: true };
+        }
+    });
+    mcp.tool('attachment_get', 'Returns the on-disk path (not content) of an attachment, plus its metadata. Use Read on the returned absolute_path for the content.', { kind: kindSchema, doc: z.string(), filename: z.string() }, async ({ kind, doc, filename }) => {
+        try {
+            const entry = attachRepo.get(kind, doc, filename);
+            if (!entry)
+                throw new Error(`attachment "${filename}" not found`);
+            const absolute_path = attachRepo.absolutePathFor(kind, doc, entry.filename);
+            return { content: [{ type: 'text', text: JSON.stringify({ ...entry, absolute_path }, null, 2) }] };
+        }
+        catch (err) {
+            return { content: [{ type: 'text', text: err.message }], isError: true };
+        }
+    });
+    mcp.tool('attachment_update', "Replaces an attachment's content in place.", { kind: kindSchema, doc: z.string(), filename: z.string(), file_path: z.string() }, async ({ kind, doc, filename, file_path }) => {
+        try {
+            assertFileSizeOk(file_path);
+            const data = fs.readFileSync(file_path);
+            const entry = attachRepo.update(kind, doc, filename, data);
+            const absolute_path = attachRepo.absolutePathFor(kind, doc, entry.filename);
+            return { content: [{ type: 'text', text: JSON.stringify({ ...entry, absolute_path }, null, 2) }] };
+        }
+        catch (err) {
+            return { content: [{ type: 'text', text: err.message }], isError: true };
+        }
+    });
+    mcp.tool('attachment_remove', 'Deletes an attachment from a memory doc or skill.', { kind: kindSchema, doc: z.string(), filename: z.string() }, async ({ kind, doc, filename }) => {
+        try {
+            attachRepo.remove(kind, doc, filename);
+            return { content: [{ type: 'text', text: `removed "${filename}"` }] };
+        }
+        catch (err) {
+            return { content: [{ type: 'text', text: err.message }], isError: true };
+        }
+    });
+    mcp.tool('attachment_list', 'Lists all attachments on a memory doc or skill, each with its absolute on-disk path.', { kind: kindSchema, doc: z.string() }, async ({ kind, doc }) => {
+        try {
+            const entries = attachRepo.list(kind, doc);
+            const withPaths = entries.map((entry) => ({
+                ...entry,
+                absolute_path: attachRepo.absolutePathFor(kind, doc, entry.filename),
+            }));
+            return { content: [{ type: 'text', text: JSON.stringify(withPaths, null, 2) }] };
+        }
+        catch (err) {
+            return { content: [{ type: 'text', text: err.message }], isError: true };
+        }
+    });
+    mcp.tool('attachment_reconcile', "Compares a doc's declared attachments against what is actually on disk; reports orphans (declared but missing) and unlisted files (present but not declared). Report-only, does not repair.", { kind: kindSchema, doc: z.string() }, async ({ kind, doc }) => {
+        try {
+            const result = attachRepo.reconcile(kind, doc);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            return { content: [{ type: 'text', text: err.message }], isError: true };
+        }
+    });
+}

package/dist/src/attachments/types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/config.js

@@ -97,3 +97,6 @@ export function removeFolder(config, kind, name) {
     const next = { ...current, [key]: filtered };
     fs.writeFileSync(config.configPath, JSON.stringify(next, null, 2) + '\n');
 }
+export const ATTACHMENT_MAX_BYTES = process.env.ATTACHMENT_MAX_BYTES
+    ? Number(process.env.ATTACHMENT_MAX_BYTES)
+    : 20 * 1024 * 1024; // 20MB default

package/dist/src/memory/repository.js

@@ -5,8 +5,14 @@ import { writeMarkdownFile } from '../store/markdown-file.js';
 import { slugify } from '../store/slug.js';
 import { resolveWithinBase } from '../store/safe-path.js';
 import { upsertFile, removeFile, scanSingleFolder, unregisterFolder, memorySyncSpec } from '../store/sync.js';
-import { SearchQueryError } from '../store/search.js';
+import { SearchQueryError, sanitizeFtsQuery } from '../store/search.js';
+import { attachmentsDirFor } from '../attachments/storage.js';
 import { normalizeKey } from '../types.js';
+/** Uppercases and strips everything but letters/digits — used to compare keys that differ only in
+ * punctuation/whitespace formatting (e.g. `RMXS-15` and `RMXS15` strip to the same `RMXS15`). */
+export function stripKey(s) {
+    return s.toUpperCase().replace(/[^A-Z0-9]/g, '');
+}
 function rowToDoc(row) {
     return {
         id: row.id,
@@ -20,6 +26,7 @@ function rowToDoc(row) {
         deprecated: !!row.deprecated,
         paused: !!row.paused,
         created_at: row.created_at ?? undefined,
+        attachments: row.attachments ? JSON.parse(row.attachments) : undefined,
         source_path: row.source_path,
         folder: row.folder,
         body: row.body,
@@ -104,7 +111,7 @@ export class MemoryRepository {
     search(query, opts = {}) {
         const { docType, status, folder, tag, limit = 20, offset = 0, includePaused = false } = opts;
         const conditions = [];
-        const params = [query];
+        const params = [sanitizeFtsQuery(query)];
         if (docType) {
             conditions.push('m.doc_type = ?');
             params.push(docType);
@@ -159,6 +166,35 @@ export class MemoryRepository {
             .filter((r) => !prefix || r.key.startsWith(prefix))
             .map((r) => ({ key: r.key, docCount: r.doc_count }));
     }
+    /**
+     * Fuzzy key lookup for a partial/drifted key, comparing keys with all punctuation stripped so
+     * `RMXS15` and `RMXS-15` are treated as the same candidate. Ranked: exact stripped match first,
+     * then stripped-prefix, then stripped-substring; alphabetical tiebreak within each tier.
+     */
+    suggestKeys(partial, limit = 5) {
+        const strippedPartial = stripKey(partial);
+        if (!strippedPartial)
+            return [];
+        const rows = this.db
+            .prepare(`SELECT key, COUNT(*) as doc_count FROM memory_docs GROUP BY key`)
+            .all();
+        return rows
+            .map((r) => ({ key: r.key, docCount: r.doc_count, stripped: stripKey(r.key) }))
+            .filter((r) => r.stripped.includes(strippedPartial))
+            .sort((a, b) => {
+            const aExact = a.stripped === strippedPartial ? 0 : 1;
+            const bExact = b.stripped === strippedPartial ? 0 : 1;
+            if (aExact !== bExact)
+                return aExact - bExact;
+            const aPrefix = a.stripped.startsWith(strippedPartial) ? 0 : 1;
+            const bPrefix = b.stripped.startsWith(strippedPartial) ? 0 : 1;
+            if (aPrefix !== bPrefix)
+                return aPrefix - bPrefix;
+            return a.key.localeCompare(b.key);
+        })
+            .slice(0, limit)
+            .map(({ key, docCount }) => ({ key, docCount }));
+    }
     create(input) {
         const normalizedKey = normalizeKey(input.key);
         const id = `${slugify(normalizedKey)}-${slugify(input.description)}-${randomUUID().slice(0, 8)}`;
@@ -275,6 +311,10 @@ export class MemoryRepository {
         const existing = this.get(id);
         if (!existing)
             throw new Error(`memory doc with id "${id}" not found`);
+        // The <id>/ wrapper directory exists solely to hold attachments/ for this doc (memory docs
+        // are otherwise flat <id>.md files), so remove the whole wrapper — not just attachments/ —
+        // to avoid leaving an orphaned empty <id>/ directory behind. No-op if it never existed.
+        fs.rmSync(path.dirname(attachmentsDirFor(existing.source_path, 'memory')), { recursive: true, force: true });
         fs.unlinkSync(existing.source_path);
         removeFile(this.db, 'memory_docs', existing.source_path);
     }

package/dist/src/memory/tools.js

@@ -1,5 +1,7 @@
 import { z } from 'zod';
+import { stripKey } from './repository.js';
 import { statusSchema } from '../shared/status.js';
+import { normalizeKey } from '../types.js';
 const MEMORY_DOC_TYPES = ['plan', 'spec', 'sql', 'testing-todo', 'discovery', 'session-summary', 'other'];
 const MEMORY_KEY_TYPES = ['ticket', 'freeform'];
 const MEMORY_STATUS_DEFAULTS = ['active', 'shipped', 'abandoned'];
@@ -66,8 +68,17 @@ export function registerMemoryTools(mcp, repo) {
         ...(multiFolder ? { folder: z.string().describe(`which configured memory folder to write into: ${folderNames}`) } : {}),
     }, async ({ key, key_type, doc_type, description, body, tags, status, related_to, subfolder, folder }) => {
         try {
+            const normalized = normalizeKey(key);
+            const strippedNew = stripKey(normalized);
+            const nearDuplicate = repo
+                .suggestKeys(key, 3)
+                .find((m) => stripKey(m.key) === strippedNew && m.key !== normalized);
             const doc = repo.create({ key, key_type, doc_type, description, body, tags, status, related_to, subfolder, folder });
-            return { content: [{ type: 'text', text: JSON.stringify(doc, null, 2) }] };
+            const result = { ...doc };
+            if (nearDuplicate) {
+                result.key_warning = `A similarly-formatted key "${nearDuplicate.key}" already exists with ${nearDuplicate.docCount} doc(s) — did you mean to use that key instead of "${normalized}"? This doc was still created under "${normalized}".`;
+            }
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
         }
         catch (err) {
             return { content: [{ type: 'text', text: err.message }], isError: true };

package/dist/src/server.js

@@ -13,6 +13,8 @@ import { registerMemoryTools } from './memory/tools.js';
 import { registerRelocateTool } from './shared/relocate-tool.js';
 import { registerSearchTool } from './shared/search-tool.js';
 import { registerBucketFolderTools } from './shared/bucket-folder-tool.js';
+import { registerAttachmentTools } from './attachments/tools.js';
+import { AttachmentRepository } from './attachments/repository.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),
@@ -41,6 +43,7 @@ const skillRepo = new SkillRepository(db, [{ name: 'builtin', path: builtinSkill
 const memoryRepo = new MemoryRepository(db, config.memoryFolders);
 skillRepo.setWatcher(skillWatcher);
 memoryRepo.setWatcher(memoryWatcher);
+const attachmentRepo = new AttachmentRepository(memoryRepo, skillRepo);
 if (config.skillFolders.length === 0 && config.memoryFolders.length === 0) {
     console.error(`[memory-bucket] no folders configured — open http://localhost:${PORT} to add one`);
 }
@@ -57,6 +60,7 @@ function buildMcpServer() {
     registerRelocateTool(server, skillRepo, memoryRepo);
     registerSearchTool(server, db);
     registerBucketFolderTools(server, config, skillRepo, memoryRepo, db, skillSpec, memorySpec);
+    registerAttachmentTools(server, attachmentRepo);
     registerUiTool(server, PORT);
     return server;
 }

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

@@ -251,6 +251,36 @@ body: >-
   conversation, or ask if it's genuinely unclear.
 
 
+  **Tags are for cross-cutting labels, not grouping.** `key` is the one and
+
+  only grouping concept for memory docs — never add a doc's own key (or a
+
+  related doc's key) as a tag to link things together; that's what `key`
+
+  already does. Use `tags` for labels that cut across many keys (e.g.
+
+  `viz-team`, `datalab`), not as a second grouping axis.
+
+
+  **Before creating a doc under a `ticket`-type key, check for an existing
+
+  near-match first** — e.g. `memory_list("RMXS-15")` or `memory_search` —
+
+  rather than writing a fresh key that only differs in punctuation or
+
+  casing (`RMXS15` vs `RMXS-15` vs `Rmxs 15` are three different keys to
+
+  this system, even though they're clearly meant to be the same ticket).
+
+  Reuse the existing key's exact casing/format if one is found.
+
+  `memory_create`'s response includes a `key_warning` field if it detects a
+
+  likely near-duplicate after the fact — treat that as a signal to double
+
+  check, not to ignore.
+
+
   ### Saving a session
 
 

package/dist/src/skills/repository.js

@@ -4,7 +4,7 @@ import { writeMarkdownFile } from '../store/markdown-file.js';
 import { assertValidSkillName } from '../store/skill-name.js';
 import { resolveWithinBase } from '../store/safe-path.js';
 import { upsertFile, removeFile, scanSingleFolder, unregisterFolder, skillSyncSpec } from '../store/sync.js';
-import { SearchQueryError } from '../store/search.js';
+import { SearchQueryError, sanitizeFtsQuery } from '../store/search.js';
 function rowToDoc(row) {
     return {
         name: row.id,
@@ -15,6 +15,7 @@ function rowToDoc(row) {
         deprecated: !!row.deprecated,
         paused: !!row.paused,
         created_at: row.created_at ?? undefined,
+        attachments: row.attachments ? JSON.parse(row.attachments) : undefined,
         source_path: row.source_path,
         folder: row.folder,
         body: row.body,
@@ -115,7 +116,7 @@ export class SkillRepository {
     search(query, opts = {}) {
         const { folder, status, owner, tag, limit = 20, offset = 0, includePaused = false } = opts;
         const conditions = [];
-        const params = [query];
+        const params = [sanitizeFtsQuery(query)];
         if (folder) {
             conditions.push('s.folder = ?');
             params.push(folder);

package/dist/src/store/db.js

@@ -16,6 +16,7 @@ export function openCache(dbPath) {
       deprecated INTEGER NOT NULL DEFAULT 0,
       paused INTEGER NOT NULL DEFAULT 0, -- local-only: never synced from/to SKILL.md, cache-file scoped
       created_at TEXT,
+      attachments TEXT,               -- JSON array of AttachmentEntry, mirrors frontmatter
       body TEXT NOT NULL,
       mtime_ms INTEGER NOT NULL
     );
@@ -34,6 +35,7 @@ export function openCache(dbPath) {
       deprecated INTEGER NOT NULL DEFAULT 0,
       paused INTEGER NOT NULL DEFAULT 0, -- local-only: never synced from/to the doc's markdown file, cache-file scoped
       created_at TEXT,
+      attachments TEXT,               -- JSON array of AttachmentEntry, mirrors frontmatter
       body TEXT NOT NULL,
       mtime_ms INTEGER NOT NULL
     );
@@ -46,6 +48,7 @@ export function openCache(dbPath) {
       description,
       body,
       tags,
+      key,
       tokenize = 'porter unicode61'
     );
 
@@ -63,16 +66,43 @@ export function openCache(dbPath) {
         ['deprecated', 'INTEGER NOT NULL DEFAULT 0'],
         ['paused', 'INTEGER NOT NULL DEFAULT 0'],
         ['created_at', 'TEXT'],
+        ['attachments', 'TEXT'],
     ]);
     ensureColumns(db, 'memory_docs', [
         ['folder', "TEXT NOT NULL DEFAULT ''"],
         ['deprecated', 'INTEGER NOT NULL DEFAULT 0'],
         ['paused', 'INTEGER NOT NULL DEFAULT 0'],
         ['created_at', 'TEXT'],
+        ['attachments', 'TEXT'],
     ]);
+    ensureSearchIndexHasKeyColumn(db);
     backfillSearchIndex(db);
     return db;
 }
+/**
+ * search_index is an FTS5 virtual table — existing cache files created before the `key` column
+ * existed need it added. FTS5 doesn't support ALTER TABLE ADD COLUMN reliably across versions, and
+ * search_index is a disposable cache (rebuilt from skills/memory_docs, not the source of truth), so
+ * the simplest safe migration is: drop and recreate with the new schema, then let backfillSearchIndex
+ * repopulate everything.
+ */
+function ensureSearchIndexHasKeyColumn(db) {
+    const cols = db.prepare(`PRAGMA table_info(search_index)`).all();
+    if (cols.length === 0 || cols.some((c) => c.name === 'key'))
+        return; // fresh table, or already migrated
+    db.exec(`DROP TABLE search_index`);
+    db.exec(`
+    CREATE VIRTUAL TABLE search_index USING fts5(
+      ref_table UNINDEXED,
+      ref_id UNINDEXED,
+      description,
+      body,
+      tags,
+      key,
+      tokenize = 'porter unicode61'
+    );
+  `);
+}
 /** 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));
@@ -87,16 +117,16 @@ function backfillSearchIndex(db) {
     if (indexed > 0)
         return;
     const skillRows = db.prepare(`SELECT id, description, body, tags FROM skills`).all();
-    const memoryRows = db.prepare(`SELECT id, description, body, tags FROM memory_docs`).all();
+    const memoryRows = db.prepare(`SELECT id, key, description, body, tags FROM memory_docs`).all();
     if (skillRows.length === 0 && memoryRows.length === 0)
         return;
-    const insert = db.prepare(`INSERT INTO search_index (ref_table, ref_id, description, body, tags) VALUES (?, ?, ?, ?, ?)`);
+    const insert = db.prepare(`INSERT INTO search_index (ref_table, ref_id, description, body, tags, key) VALUES (?, ?, ?, ?, ?, ?)`);
     const insertAll = db.transaction(() => {
         for (const row of skillRows) {
-            insert.run('skills', row.id, row.description, row.body, flattenTags(row.tags));
+            insert.run('skills', row.id, row.description, row.body, flattenTags(row.tags), '');
         }
         for (const row of memoryRows) {
-            insert.run('memory_docs', row.id, row.description, row.body, flattenTags(row.tags));
+            insert.run('memory_docs', row.id, row.description, row.body, flattenTags(row.tags), row.key);
         }
     });
     insertAll();

package/dist/src/store/search.js

@@ -7,6 +7,27 @@ export class SearchQueryError extends Error {
         this.name = 'SearchQueryError';
     }
 }
+const FTS_BOOLEAN_KEYWORDS = new Set(['AND', 'OR', 'NOT']);
+/**
+ * Auto-quotes bareword tokens that contain punctuation (e.g. a bare hyphenated ticket key like
+ * `RMXS-15`) so FTS5 doesn't interpret a bare `-` as its NOT/column-filter operator and silently
+ * return zero rows. Already-quoted phrases, `AND`/`OR`/`NOT` operators, and `prefix*` wildcards are
+ * left untouched so existing power-user query syntax keeps working exactly as before.
+ */
+export function sanitizeFtsQuery(query) {
+    const tokens = query.match(/"[^"]*"|\S+/g) ?? [];
+    return tokens
+        .map((token) => {
+        if (token.startsWith('"'))
+            return token; // already an explicit phrase
+        if (FTS_BOOLEAN_KEYWORDS.has(token.toUpperCase()))
+            return token; // boolean operator
+        if (/^[A-Za-z0-9_*]+$/.test(token))
+            return token; // plain word or prefix* wildcard — no punctuation
+        return `"${token.replace(/"/g, '""')}"`; // punctuation present (hyphen, colon, etc.) — quote it literally
+    })
+        .join(' ');
+}
 /**
  * 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`,
@@ -16,6 +37,7 @@ export class SearchQueryError extends Error {
  */
 export function searchIndex(db, query, opts = {}) {
     const { table, limit = 20, offset = 0 } = opts;
+    const sanitized = sanitizeFtsQuery(query);
     try {
         const rows = db
             .prepare(`SELECT ref_table, ref_id,
@@ -25,7 +47,7 @@ export function searchIndex(db, query, opts = {}) {
          WHERE search_index MATCH ? ${table ? 'AND ref_table = ?' : ''}
          ORDER BY bm25(search_index)
          LIMIT ? OFFSET ?`)
-            .all(...(table ? [query, table, limit, offset] : [query, limit, offset]));
+            .all(...(table ? [sanitized, table, limit, offset] : [sanitized, limit, offset]));
         return rows;
     }
     catch (err) {
@@ -97,6 +119,7 @@ export function searchByDate(db, start, end, opts = {}) {
  * per table); use skill_search/memory_search directly when filtering by those.
  */
 export function searchCombined(db, query, limit = 20, offset = 0) {
+    const sanitized = sanitizeFtsQuery(query);
     try {
         return db
             .prepare(`SELECT ref_table, ref_id AS id,
@@ -110,7 +133,7 @@ export function searchCombined(db, query, limit = 20, offset = 0) {
          WHERE search_index MATCH ?
          ORDER BY bm25(search_index)
          LIMIT ? OFFSET ?`)
-            .all(query, limit, offset);
+            .all(sanitized, limit, offset);
     }
     catch (err) {
         throw new SearchQueryError(query, err);

package/dist/src/store/sync.js

@@ -9,8 +9,8 @@ import { normalizeKey } from '../types.js';
 // `paused` is deliberately absent from both lists: it's a local-only cache column (see
 // SkillRepository/MemoryRepository#setPaused) that never round-trips through frontmatter, so a
 // file add/change/rescan must never overwrite it via the INSERT/ON CONFLICT UPDATE below.
-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'];
+const skillColumns = ['id', 'description', 'owner', 'status', 'tags', 'trigger_phrases', 'extends', 'deprecated', 'created_at', 'attachments'];
+const memoryColumns = ['id', 'key', 'key_type', 'description', 'doc_type', 'tags', 'status', 'related_to', 'deprecated', 'created_at', 'attachments'];
 export function skillSyncSpec(sources) {
     return {
         table: 'skills',
@@ -28,6 +28,7 @@ export function skillSyncSpec(sources) {
             extends: fm.metadata?.extends ?? null,
             deprecated: fm.deprecated ? 1 : 0,
             created_at: fm.created_at ?? new Date(mtimeMs).toISOString(),
+            attachments: fm.attachments ? JSON.stringify(fm.attachments) : null,
         }),
     };
 }
@@ -65,6 +66,7 @@ export function memorySyncSpec(sources) {
             related_to: fm.related_to ?? null,
             deprecated: fm.deprecated ? 1 : 0,
             created_at: fm.created_at ?? null,
+            attachments: fm.attachments ? JSON.stringify(fm.attachments) : null,
         }),
     };
 }
@@ -114,7 +116,7 @@ export function upsertFile(db, spec, filePath) {
     db.prepare(`INSERT INTO ${spec.table} (${cols.join(', ')}) VALUES (${placeholders})
      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(`INSERT INTO search_index (ref_table, ref_id, description, body, tags, key) VALUES (?, ?, ?, ?, ?, ?)`).run(spec.table, id, String(row.description ?? ''), parsed.body, flattenTags(String(row.tags ?? '[]')), String(row.key ?? ''));
     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
@@ -176,10 +178,12 @@ export function unregisterFolder(db, table, folderName) {
         db.prepare(`DELETE FROM search_index WHERE ref_table = ? AND ref_id = ?`).run(table, row.id);
     }
 }
-function* walkMarkdownFiles(dir) {
+export function* walkMarkdownFiles(dir) {
     for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
         const full = path.join(dir, entry.name);
         if (entry.isDirectory()) {
+            if (entry.name === 'attachments')
+                continue;
             yield* walkMarkdownFiles(full);
         }
         else if (entry.isFile() && entry.name.endsWith('.md')) {
@@ -188,7 +192,7 @@ function* walkMarkdownFiles(dir) {
     }
 }
 export function watchSources(db, spec) {
-    const watcher = chokidar.watch(spec.sources.map((f) => f.path), { ignoreInitial: true, persistent: true, depth: 10 });
+    const watcher = chokidar.watch(spec.sources.map((f) => f.path), { ignoreInitial: true, persistent: true, depth: 10, ignored: /(^|[/\\])attachments([/\\]|$)/ });
     watcher
         .on('add', (filePath) => {
         if (!spec.matchesFile(filePath))