gnosys 5.12.0 → 5.12.3

package/dist/cli.js

@@ -9,16 +9,16 @@ import fs from "fs/promises";
 import os from "os";
 import { fileURLToPath } from "url";
 import dotenv from "dotenv";
-import { readFileSync, existsSync } from "fs";
+import { readFileSync, existsSync, } from "fs";
 // v5.8.0 (#4): only the lightweight modules are imported at top-level.
 // Anything that pulls @huggingface/transformers, mammoth/pdf-parse/turndown,
 // large file-walking machinery, or otherwise costs >100ms to load gets
 // `await import(...)` inside its own action handler. This keeps
 // `gnosys --help` and other lightweight commands fast.
 import { GnosysResolver } from "./lib/resolver.js";
-import { loadConfig, generateConfigTemplate } from "./lib/config.js";
+import { loadConfig, generateConfigTemplate, } from "./lib/config.js";
 import { GnosysDB } from "./lib/db.js";
-import { createProjectIdentity, findProjectIdentity } from "./lib/projectIdentity.js";
+import { createProjectIdentity, findProjectIdentity, } from "./lib/projectIdentity.js";
 // Lazy-loaded inside action handlers (each ~200ms-2.5s on cold cache):
 //   - ./lib/embeddings.js       (@huggingface/transformers — 80MB)
 //   - ./lib/hybridSearch.js     (depends on embeddings)
@@ -468,9 +468,9 @@ setupCmd
     }
 });
 // v5.4.2 removal: `gnosys models` (top-level shortcut) was removed in favor
-// of the canonical `gnosys setup models` form. The implementation function
-// runModelsCommand() in setup.ts is no longer wired but kept for now in case
-// we need to revive a top-level shortcut later.
+// of the canonical `gnosys setup models` form. The unwired implementation
+// (runModelsCommand in setup.ts) was deleted in v5.12.1 after eight minor
+// versions without revival — recover from git history if ever needed.
 // ─── gnosys init ─────────────────────────────────────────────────────────
 program
     .command("init")
@@ -685,6 +685,24 @@ program
     const { runIngestCommand } = await import("./lib/ingestCommand.js");
     await runIngestCommand(getResolver, fileOrGlob, opts);
 });
+// ─── gnosys attach <file> --memory <id> ──────────────────────────────────
+program
+    .command("attach <file>")
+    .description("Attach a small binary file (logo, diagram, screenshot) inline to a memory. Travels machine-to-machine over normal sync. Limit ~10MB — use 'gnosys ingest' for large media.")
+    .requiredOption("--memory <id>", "Memory ID to attach the file to")
+    .action(async (file, opts) => {
+    const { runAttachCommand } = await import("./lib/attachCommand.js");
+    await runAttachCommand(file, opts);
+});
+// ─── gnosys get-attachment <id> ───────────────────────────────────────────
+program
+    .command("get-attachment <memoryId>")
+    .description("Retrieve the binary attachment stored on a memory. Writes to --out, or prints base64 to stdout.")
+    .option("--out <path>", "Write the attachment to this file path instead of printing base64")
+    .action(async (memoryId, opts) => {
+    const { runGetAttachmentCommand } = await import("./lib/attachCommand.js");
+    await runGetAttachmentCommand(memoryId, opts);
+});
 // ─── gnosys tags-add ────────────────────────────────────────────────────
 program
     .command("tags-add")
@@ -970,7 +988,22 @@ program
     .description("Remove dead and temp-dir entries from the project registry")
     .option("--yes", "Non-interactive, remove without prompting")
     .option("--dry-run", "Show what would be removed without writing")
+    .option("--rules [dir]", "Remove the GNOSYS block from agent rules files (CLAUDE.md, .cursor, .codex) in the given directory (default: cwd)")
     .action(async (opts) => {
+    // v5.12.1: uninstall counterpart of `gnosys setup ides` rules generation.
+    if (opts.rules !== undefined) {
+        const { removeRulesFromProject } = await import("./lib/rulesGen.js");
+        const dir = typeof opts.rules === "string" ? path.resolve(opts.rules) : process.cwd();
+        const cleaned = await removeRulesFromProject(dir);
+        if (cleaned.length === 0) {
+            console.log(`No GNOSYS rules blocks found in ${dir}`);
+        }
+        else {
+            for (const rel of cleaned)
+                console.log(`Removed GNOSYS block: ${rel}`);
+        }
+        return;
+    }
     const { cleanupRegistry } = await import("./lib/cleanup.js");
     const result = await cleanupRegistry({
         interactive: !opts.yes && !opts.dryRun,
@@ -1852,4 +1885,12 @@ if (!isTestEnv()) {
         // non-critical — don't block CLI startup
     }
 }
-program.parse();
+// v5.12.x observability: all 100+ command actions are async — with bare
+// program.parse() a thrown action error surfaced as a raw Node
+// UnhandledPromiseRejection (full engine stack, no gnosys framing).
+// parseAsync routes every action failure through one clean exit path.
+program.parseAsync().catch(async (err) => {
+    const { logError } = await import("./lib/log.js");
+    logError(err, { module: "cli" });
+    process.exitCode = 1;
+});

package/dist/index.js

@@ -10,6 +10,7 @@
 // MCP stdio JSON protocol. parse() is a pure function with no side effects.
 import dotenv from "dotenv";
 import path from "path";
+import { AsyncLocalStorage } from "async_hooks";
 import { readFileSync, realpathSync } from "fs";
 import { fileURLToPath } from "url";
 const home = process.env.HOME || process.env.USERPROFILE || "/tmp";
@@ -49,13 +50,14 @@ import { groupByPeriod, computeStats } from "./lib/timeline.js";
 import { buildLinkGraph, getBacklinks, getOutgoingLinks, formatGraphSummary } from "./lib/wikilinks.js";
 import { loadConfig, DEFAULT_CONFIG } from "./lib/config.js";
 import { getLLMProvider } from "./lib/llm.js";
-import { recall, formatRecall } from "./lib/recall.js";
+import { recall, formatRecall, } from "./lib/recall.js";
 import { initAudit, readAuditLog, formatAuditTimeline } from "./lib/audit.js";
+import { logError } from "./lib/log.js";
 import { GnosysDB } from "./lib/db.js";
 import { syncMemoryToDb, syncUpdateToDb, syncDearchiveToDb, syncReinforcementToDb, auditToDb } from "./lib/dbWrite.js";
-import { createProjectIdentity, readProjectIdentity } from "./lib/projectIdentity.js";
+import { createProjectIdentity, readProjectIdentity, } from "./lib/projectIdentity.js";
 import { setPreference, getPreference, getAllPreferences, deletePreference, KNOWN_PREFERENCE_KEYS, suggestPreferenceKey } from "./lib/preferences.js";
-import { syncRules, generateRulesBlock } from "./lib/rulesGen.js";
+import { syncRules, generateRulesBlock, } from "./lib/rulesGen.js";
 import { federatedSearch, detectAmbiguity, generateBriefing, generateAllBriefings, getWorkingSet, formatWorkingSet, detectCurrentProject } from "./lib/federated.js";
 import { generatePortfolio, formatPortfolioCompact, formatPortfolioMarkdown, generateStatusPrompt } from "./lib/portfolio.js";
 import { applyPendingOverlay, mergeOverlayDiscoverResults, mergeOverlaySearchResults, pendingAddToDbMemory, } from "./lib/clientReadOverlay.js";
@@ -71,9 +73,47 @@ const server = new McpServer({
     version: "2.0.0",
 });
 const _registrations = [];
+// v5.12.1 reliability: every tool handler resolves a ToolContext whose
+// clientRead (v13 sync) may own a DB handle. Historically only 8 of 52
+// handlers released it, leaking handles on every early return. Enforce
+// release centrally: resolveToolContext() registers each context in the
+// per-call AsyncLocalStorage store, and withContextRelease() (wrapped around
+// every tool handler at registration) releases them when the handler settles
+// — every return path, every throw, every future tool, no per-handler code.
+const activeToolContexts = new AsyncLocalStorage();
+function withContextRelease(handler, toolName) {
+    return (...hargs) => {
+        const opened = [];
+        return activeToolContexts.run(opened, async () => {
+            try {
+                return await handler(...hargs);
+            }
+            catch (err) {
+                // v5.12.x observability: last-resort error envelope. 19 of 52 tools
+                // had no catch at all — a throw reached the SDK as a raw JSON-RPC
+                // error with no corruption-recovery guidance. Per-tool catches with
+                // more specific messages still take precedence; this only sees what
+                // they let through. Logged to stderr (stdout is JSON-RPC).
+                logError(err, { module: "mcp", op: toolName });
+                return {
+                    content: [{ type: "text", text: formatMcpError(`in ${toolName}`, err) }],
+                    isError: true,
+                };
+            }
+            finally {
+                for (const c of opened)
+                    releaseClientReadFromContext(c);
+            }
+        });
+    };
+}
 // Typed to the McpServer methods so call-site generic inference (Zod schema →
 // handler arg types) is preserved; the body just collects a replay thunk.
 const regTool = ((...args) => {
+    const last = args.length - 1;
+    if (typeof args[last] === "function") {
+        args[last] = withContextRelease(args[last], typeof args[0] === "string" ? args[0] : "tool");
+    }
     _registrations.push((s) => s.tool(...args));
 });
 const regPrompt = ((...args) => {
@@ -160,9 +200,25 @@ function applyClientReadToCentralDb(localDb) {
     const clientRead = openClientReadContext(localDb, masterPath, mc.machineId);
     return { centralDb: clientRead.db, clientRead };
 }
+/** Idempotent: safe to call from both a handler's own finally and the central
+ *  withContextRelease wrapper. */
 function releaseClientReadFromContext(ctx) {
-    if (ctx.clientRead)
+    if (ctx.clientRead) {
         closeClientReadContext(ctx.clientRead);
+        ctx.clientRead = null;
+    }
+    // v5.12.x perf/leak: projectRoot-scoped contexts open their own
+    // GnosysSearch (SQLite handle to <store>/.config/search.db) per call.
+    if (ctx.ownsSearch && ctx.search) {
+        try {
+            ctx.search.close();
+        }
+        catch {
+            // already closed / never opened — fine
+        }
+        ctx.search = null;
+        ctx.ownsSearch = false;
+    }
 }
 async function resolveToolContext(projectRoot) {
     if (!projectRoot) {
@@ -176,7 +232,7 @@ async function resolveToolContext(projectRoot) {
             projectId = identity?.projectId || null;
         }
         const applied = applyClientReadToCentralDb(centralDb);
-        return {
+        const ctx = {
             resolver,
             store: writeTarget?.store || null,
             storePath: writeTarget?.store.getStorePath() || "",
@@ -187,6 +243,8 @@ async function resolveToolContext(projectRoot) {
             projectId,
             clientRead: applied.clientRead,
         };
+        activeToolContexts.getStore()?.push(ctx);
+        return ctx;
     }
     // Scoped context — resolve for this specific project
     const scopedResolver = await GnosysResolver.resolveForProject(projectRoot);
@@ -215,7 +273,7 @@ async function resolveToolContext(projectRoot) {
         // gnosys.db in the project's .gnosys/ directory.
     }
     const applied = applyClientReadToCentralDb(centralDb);
-    return {
+    const ctx = {
         resolver: scopedResolver,
         store: scopedWriteTarget?.store || null,
         storePath: scopedStorePath,
@@ -225,7 +283,10 @@ async function resolveToolContext(projectRoot) {
         centralDb: applied.centralDb,
         projectId,
         clientRead: applied.clientRead,
+        ownsSearch: scopedSearch !== null,
     };
+    activeToolContexts.getStore()?.push(ctx);
+    return ctx;
 }
 /**
  * v5.7.1 (#13): Resolve scope + projectId for a memory write.
@@ -1632,7 +1693,7 @@ regTool("gnosys_import", "Bulk import structured data (CSV, JSON, JSONL) into Gn
     const effectiveMode = mode || "structured";
     try {
         // v5.9.1 (#100): import.js pulls mammoth + pdf-parse + turndown.
-        const { performImport, formatImportSummary, estimateDuration } = await import("./lib/import.js");
+        const { performImport, formatImportSummary } = await import("./lib/import.js");
         const result = await performImport(writeTarget.store, ingestion, {
             format: format,
             data,
@@ -1657,7 +1718,6 @@ regTool("gnosys_import", "Bulk import structured data (CSV, JSON, JSONL) into Gn
         // Smart threshold guidance
         if (effectiveMode === "llm" &&
             result.totalProcessed > 100) {
-            const estimate = estimateDuration(result.totalProcessed, "llm", concurrency || 5);
             response += `\n\n💡 Tip: For large LLM imports, the CLI offers progress tracking and resume:\n  gnosys import ${data.length < 100 ? data : "<file>"} --format ${format} --mode llm --skip-existing`;
         }
         return { content: [{ type: "text", text: response }] };
@@ -1692,10 +1752,17 @@ regTool("gnosys_hybrid_search", "Search memories using hybrid keyword + semantic
         };
     }
     try {
-        const results = await hybridSearch.hybridSearch(query, limit || 15, mode || "hybrid");
+        const requestedMode = mode || "hybrid";
+        const results = await hybridSearch.hybridSearch(query, limit || 15, requestedMode);
+        // v5.12.3: hybrid used to degrade to keyword-only silently when the
+        // semantic leg can't run (embeddings are only built by gnosys_reindex,
+        // and DB mode also needs the store-local query embedder). Say so loudly.
+        const degradeWarning = requestedMode !== "keyword" && !hybridSearch.canRunSemantic()
+            ? `⚠️ Semantic embeddings unavailable — ${requestedMode} search ran keyword-only. Run gnosys_reindex to build embeddings and enable semantic recall.\n\n`
+            : "";
         if (results.length === 0) {
             return {
-                content: [{ type: "text", text: `No results for "${query}". Try gnosys_reindex to build embeddings, or different keywords.` }],
+                content: [{ type: "text", text: `${degradeWarning}No results for "${query}". Try different keywords.` }],
             };
         }
         const formatted = results
@@ -1714,7 +1781,7 @@ regTool("gnosys_hybrid_search", "Search memories using hybrid keyword + semantic
             content: [
                 {
                     type: "text",
-                    text: `Found ${results.length} results for "${query}" (${embCount} embeddings indexed):\n\n${formatted}`,
+                    text: `${degradeWarning}Found ${results.length} results for "${query}" (${embCount} embeddings indexed):\n\n${formatted}`,
                 },
             ],
         };
@@ -1742,10 +1809,19 @@ regTool("gnosys_semantic_search", "Search memories using semantic similarity onl
         };
     }
     try {
+        // v5.12.3: semantic search without a working semantic leg either
+        // returns nothing or (in DB mode) keyword hits mislabeled as semantic —
+        // refuse with the exact reason instead.
+        if (!hybridSearch.canRunSemantic()) {
+            return {
+                content: [{ type: "text", text: `⚠️ Semantic embeddings unavailable — semantic search cannot run. Run gnosys_reindex to build embeddings, then retry.` }],
+                isError: true,
+            };
+        }
         const results = await hybridSearch.hybridSearch(query, limit || 15, "semantic");
         if (results.length === 0) {
             return {
-                content: [{ type: "text", text: `No semantic results for "${query}". Run gnosys_reindex first to build embeddings.` }],
+                content: [{ type: "text", text: `No semantic results for "${query}". Try a broader query.` }],
             };
         }
         const formatted = results
@@ -1967,7 +2043,7 @@ regTool("gnosys_dream", "Run a Dream Mode cycle — idle-time consolidation that
 }, async (params) => {
     try {
         const ctx = await resolveToolContext(params.projectRoot);
-        if (!ctx.centralDb || !ctx.centralDb.isAvailable() || !ctx.centralDb.isMigrated()) {
+        if (!ctx.centralDb?.isAvailable() || !ctx.centralDb.isMigrated()) {
             return {
                 content: [
                     {
@@ -2047,7 +2123,7 @@ regTool("gnosys_export", "Export gnosys.db to Obsidian-compatible vault — atom
 }, async (params) => {
     try {
         const ctx = await resolveToolContext(params.projectRoot);
-        if (!ctx.centralDb || !ctx.centralDb.isAvailable() || !ctx.centralDb.isMigrated()) {
+        if (!ctx.centralDb?.isAvailable() || !ctx.centralDb.isMigrated()) {
             return {
                 content: [
                     {
@@ -2720,6 +2796,106 @@ regTool("gnosys_remote_resolve", "Resolve a sync conflict by choosing which vers
         localDb.close();
     }
 });
+// ─── Tool: gnosys_attach ────────────────────────────────────────────────
+regTool("gnosys_attach", "Attach a small binary file (logo, diagram, screenshot, small PDF) directly to a memory. The bytes are stored inline in the memory row, so the attachment travels machine-to-machine over the normal sync and works with a remote/dockerized server (no shared filesystem). Limit ~10MB — use gnosys_ingest_file for large media.", {
+    memoryId: z.string().describe("Memory ID to attach the file to (e.g., 'deci-052')"),
+    filePath: z.string().describe("Absolute path to the file to attach"),
+    projectRoot: projectRootParam,
+}, async ({ memoryId, filePath, projectRoot }) => {
+    const ctx = await resolveToolContext(projectRoot);
+    if (!ctx.centralDb?.isAvailable()) {
+        return {
+            content: [{ type: "text", text: "Database not available. Cannot attach file." }],
+            isError: true,
+        };
+    }
+    try {
+        const { attachFileToMemory } = await import("./lib/attachments.js");
+        const result = await attachFileToMemory(ctx.centralDb, memoryId, filePath);
+        auditToDb(ctx.centralDb, "write", memoryId, {
+            tool: "gnosys_attach",
+            name: result.name,
+            mime: result.mime,
+            sizeBytes: result.sizeBytes,
+            unchanged: result.unchanged,
+        });
+        const sizeKb = (result.sizeBytes / 1024).toFixed(1);
+        const verb = result.unchanged ? "already attached (no change)" : "attached";
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `File ${verb}: ${result.name} (${result.mime}, ${sizeKb} KB)\nMemory: ${memoryId}`,
+                },
+            ],
+        };
+    }
+    catch (err) {
+        return {
+            content: [{ type: "text", text: formatMcpError("attaching file", err) }],
+            isError: true,
+        };
+    }
+});
+// ─── Tool: gnosys_get_attachment ────────────────────────────────────────
+regTool("gnosys_get_attachment", "Retrieve the binary attachment stored on a memory. By default returns the bytes (base64, plus an inline image when the attachment is an image). Pass outputPath to write the file to disk instead.", {
+    memoryId: z.string().describe("Memory ID that holds the attachment"),
+    outputPath: z.string().optional().describe("If provided, write the attachment to this absolute path instead of returning bytes"),
+    projectRoot: projectRootParam,
+}, async ({ memoryId, outputPath, projectRoot }) => {
+    const ctx = await resolveToolContext(projectRoot);
+    if (!ctx.centralDb?.isAvailable()) {
+        return {
+            content: [{ type: "text", text: "Database not available." }],
+            isError: true,
+        };
+    }
+    try {
+        const { getMemoryAttachment } = await import("./lib/attachments.js");
+        const att = getMemoryAttachment(ctx.centralDb, memoryId);
+        if (!att) {
+            return {
+                content: [{ type: "text", text: `No attachment found on memory: ${memoryId}` }],
+                isError: true,
+            };
+        }
+        if (outputPath) {
+            const { writeFile } = await import("fs/promises");
+            await writeFile(outputPath, att.data);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Wrote ${att.name} (${att.mime}, ${att.data.length} bytes) to ${outputPath}`,
+                    },
+                ],
+            };
+        }
+        const base64 = att.data.toString("base64");
+        if (att.mime.startsWith("image/")) {
+            return {
+                content: [
+                    { type: "image", data: base64, mimeType: att.mime },
+                    { type: "text", text: `${att.name} (${att.mime}, ${att.data.length} bytes)` },
+                ],
+            };
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `${att.name} (${att.mime}, ${att.data.length} bytes)\n\nbase64:\n${base64}`,
+                },
+            ],
+        };
+    }
+    catch (err) {
+        return {
+            content: [{ type: "text", text: formatMcpError("reading attachment", err) }],
+            isError: true,
+        };
+    }
+});
 // ─── Tool: gnosys_update_status ─────────────────────────────────────────
 regTool("gnosys_update_status", "Get the prompt/template for writing a dashboard-compatible status memory for this project. Returns instructions for creating a landscape memory with the correct heading format so the portfolio dashboard can parse it. Run this, then follow the instructions to analyze and write the status.", {
     projectRoot: z.string().optional().describe("Project root for auto-detection"),
@@ -3080,6 +3256,15 @@ async function initHeavyDeps() {
 // ─── Start the server ────────────────────────────────────────────────────
 /** Start the MCP server (stdio or http). Called by `gnosys serve` and when invoked as `gnosys-mcp`. */
 export async function startMcpServer() {
+    // v5.12.1 reliability: an escaped async error must not kill the server.
+    // Log to stderr (stdout is JSON-RPC in stdio mode) and keep serving —
+    // all persistent state is transactional SQLite, so survivors are safe.
+    process.on("unhandledRejection", (reason) => {
+        console.error(`Gnosys MCP: unhandled rejection — ${reason instanceof Error ? reason.stack || reason.message : String(reason)}`);
+    });
+    process.on("uncaughtException", (err) => {
+        console.error(`Gnosys MCP: uncaught exception — ${err.stack || err.message}`);
+    });
     // v5.7.1 (#15): start the upgrade-marker watcher BEFORE anything else.
     // If `gnosys upgrade` was run on this machine while the MCP was idle,
     // pick that up immediately instead of serving stale tool handlers.

package/dist/lib/addCommand.js

@@ -54,7 +54,6 @@ export async function runAddCommand(getResolver, input, opts, resolveProjectId)
         centralDb = GnosysDB.openCentral();
         const projectId = await resolveProjectId();
         const id = centralDb.getNextId(result.category, projectId || undefined);
-        const today = new Date().toISOString().split("T")[0];
         const now = new Date().toISOString();
         const content = `# ${result.title}\n\n${result.content}`;
         const tags = result.tags;

package/dist/lib/archive.js

@@ -10,7 +10,6 @@
  *                then dearchives used memories back to active
  */
 // Dynamic import — gracefully handles missing native module
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
 let Database = null;
 try {
     Database = (await import("better-sqlite3")).default;
@@ -24,9 +23,9 @@ import { statSync } from "fs";
 import { syncMemoryToDb, syncDearchiveToDb } from "./dbWrite.js";
 import { enableWAL } from "./lock.js";
 import { auditLog } from "./audit.js";
+import { ftsTerms, ftsAndQuery, ftsOrQuery } from "./ftsQuery.js";
 // ─── Archive Manager ────────────────────────────────────────────────────
 export class GnosysArchive {
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     db = null;
     storePath;
     available = false;
@@ -219,8 +218,8 @@ export class GnosysArchive {
     searchArchive(query, limit = 20) {
         if (!this.db)
             return [];
-        const safeQuery = query.replace(/['"]/g, "").trim();
-        if (!safeQuery)
+        const terms = ftsTerms(query);
+        if (terms.length === 0)
             return [];
         const stmt = this.db.prepare(`
       SELECT
@@ -237,7 +236,12 @@ export class GnosysArchive {
       LIMIT ?
     `);
         try {
-            return stmt.all(safeQuery, limit);
+            // v5.12.3: AND first (precision), OR retry when AND finds nothing —
+            // multi-word queries previously required every term to match.
+            const results = stmt.all(ftsAndQuery(terms), limit);
+            if (results.length > 0 || terms.length === 1)
+                return results;
+            return stmt.all(ftsOrQuery(terms), limit);
         }
         catch {
             // FTS5 query syntax failed — try LIKE fallback
@@ -253,7 +257,7 @@ export class GnosysArchive {
         WHERE content LIKE ? OR title LIKE ? OR tags LIKE ?
         LIMIT ?
       `);
-            const pattern = `%${safeQuery}%`;
+            const pattern = `%${terms.join(" ")}%`;
             return likeStmt.all(pattern, pattern, pattern, limit);
         }
     }

package/dist/lib/askCommand.js

@@ -90,7 +90,7 @@ export async function runAskCommand(getResolver, question, opts) {
     const useStream = opts.stream !== false && !opts.json;
     try {
         const result = await ask.ask(question, {
-            limit: parseInt(opts.limit),
+            limit: parseInt(opts.limit, 10),
             mode,
             stream: useStream,
             additionalContext: federatedContext,

package/dist/lib/attachCommand.d.ts

@@ -0,0 +1,17 @@
+/**
+ * CLI handlers for inline DB-blob attachments (v5.12).
+ *
+ *   gnosys attach <file> --memory <id>      store bytes inline on a memory
+ *   gnosys get-attachment <id> [--out path] retrieve the stored bytes
+ *
+ * Inline attachments live in the memory row, so they ride the normal sync
+ * rail to other machines and a remote/dockerized server.
+ */
+export interface AttachCommandOptions {
+    memory: string;
+}
+export declare function runAttachCommand(filePath: string, opts: AttachCommandOptions): Promise<void>;
+export interface GetAttachmentCommandOptions {
+    out?: string;
+}
+export declare function runGetAttachmentCommand(memoryId: string, opts: GetAttachmentCommandOptions): Promise<void>;

package/dist/lib/attachCommand.js

@@ -0,0 +1,66 @@
+/**
+ * CLI handlers for inline DB-blob attachments (v5.12).
+ *
+ *   gnosys attach <file> --memory <id>      store bytes inline on a memory
+ *   gnosys get-attachment <id> [--out path] retrieve the stored bytes
+ *
+ * Inline attachments live in the memory row, so they ride the normal sync
+ * rail to other machines and a remote/dockerized server.
+ */
+import { GnosysDB } from "./db.js";
+export async function runAttachCommand(filePath, opts) {
+    const db = GnosysDB.openCentral();
+    try {
+        if (!db.isAvailable()) {
+            console.error("Database not available.");
+            process.exitCode = 1;
+            return;
+        }
+        const { attachFileToMemory } = await import("./attachments.js");
+        const result = await attachFileToMemory(db, opts.memory, filePath);
+        const sizeKb = (result.sizeBytes / 1024).toFixed(1);
+        const verb = result.unchanged ? "Already attached (no change)" : "Attached";
+        console.log(`${verb}: ${result.name} (${result.mime}, ${sizeKb} KB) → ${opts.memory}`);
+    }
+    catch (err) {
+        console.error(`Error: ${err instanceof Error ? err.message : err}`);
+        process.exitCode = 1;
+    }
+    finally {
+        db.close();
+    }
+}
+export async function runGetAttachmentCommand(memoryId, opts) {
+    const db = GnosysDB.openCentral();
+    try {
+        if (!db.isAvailable()) {
+            console.error("Database not available.");
+            process.exitCode = 1;
+            return;
+        }
+        const { getMemoryAttachment } = await import("./attachments.js");
+        const att = getMemoryAttachment(db, memoryId);
+        if (!att) {
+            console.error(`No attachment found on memory: ${memoryId}`);
+            process.exitCode = 1;
+            return;
+        }
+        if (opts.out) {
+            const { writeFile } = await import("fs/promises");
+            await writeFile(opts.out, att.data);
+            console.log(`Wrote ${att.name} (${att.mime}, ${att.data.length} bytes) to ${opts.out}`);
+        }
+        else {
+            // No output path: print metadata + base64 so it can be piped/redirected.
+            console.error(`${att.name} (${att.mime}, ${att.data.length} bytes)`);
+            console.log(att.data.toString("base64"));
+        }
+    }
+    catch (err) {
+        console.error(`Error: ${err instanceof Error ? err.message : err}`);
+        process.exitCode = 1;
+    }
+    finally {
+        db.close();
+    }
+}

package/dist/lib/attachments.d.ts

@@ -1,9 +1,15 @@
 /**
  * Gnosys Attachments — File attachment management for multimodal ingestion.
  *
- * Stores binary files in .gnosys/attachments/<uuid>.<ext> with a JSON manifest
- * at .gnosys/attachments/attachments.json for tracking metadata and memory links.
+ * Two storage modes:
+ *  - Filesystem (legacy, large media): bytes copied to .gnosys/attachments/<uuid>.<ext>
+ *    with a JSON manifest. Does NOT travel between machines.
+ *  - Inline DB blob (v5.12, small assets): bytes stored in the memory row's
+ *    attachment_data column. Travels over the same row-copy sync rail as
+ *    embeddings, so it works single-machine, multi-machine, and with a future
+ *    dockerized MCP without any shared volume.
  */
+import type { GnosysDB } from "./db.js";
 export interface AttachmentRecord {
     uuid: string;
     originalName: string;
@@ -14,6 +20,8 @@ export interface AttachmentRecord {
     createdAt: string;
     memoryIds: string[];
 }
+/** Infer a MIME type from a file path's extension. */
+export declare function inferMimeType(filePath: string): string;
 /**
  * Initialize the attachments directory and manifest in a store.
  * Safe to call multiple times — creates only if missing.
@@ -40,3 +48,36 @@ export declare function getAttachmentPath(storePath: string, uuid: string, ext:
  * tracks which memories reference it.
  */
 export declare function linkMemoryToAttachment(storePath: string, uuid: string, memoryId: string): Promise<void>;
+/**
+ * Maximum size for an inline DB-blob attachment. Larger files should use the
+ * filesystem path (`gnosys ingest`) so the synced central DB stays lean.
+ */
+export declare const MAX_INLINE_ATTACHMENT_BYTES: number;
+export interface InlineAttachment {
+    /** Raw file bytes. */
+    data: Buffer;
+    /** MIME type, e.g. "image/svg+xml". */
+    mime: string;
+    /** Original filename, e.g. "prospero-logo.svg". */
+    name: string;
+    /** Size in bytes. */
+    sizeBytes: number;
+}
+export interface AttachToMemoryResult {
+    memoryId: string;
+    name: string;
+    mime: string;
+    sizeBytes: number;
+    /** True when the file was identical to what was already attached (no write). */
+    unchanged: boolean;
+}
+/**
+ * Read a file and store its bytes inline on a memory row (attachment_data).
+ * Enforces the size cap and skips the write if the same bytes are already
+ * attached (content-hash dedup). Bumps `modified` so remote sync picks it up.
+ */
+export declare function attachFileToMemory(db: GnosysDB, memoryId: string, filePath: string): Promise<AttachToMemoryResult>;
+/** Return the inline attachment stored on a memory row, or null if none. */
+export declare function getMemoryAttachment(db: GnosysDB, memoryId: string): InlineAttachment | null;
+/** Remove an inline attachment from a memory row (keeps the memory itself). */
+export declare function detachFromMemory(db: GnosysDB, memoryId: string): boolean;