context-vault 3.0.3 → 3.1.1

package/bin/cli.js

@@ -2,9 +2,9 @@
 
 // Node.js version guard — must run before any ESM imports
 const nodeVersion = parseInt(process.versions.node.split(".")[0], 10);
-if (nodeVersion < 20) {
+if (nodeVersion < 22) {
   process.stderr.write(
-    `\ncontext-vault requires Node.js >= 20 (you have ${process.versions.node}).\n` +
+    `\ncontext-vault requires Node.js >= 22 (you have ${process.versions.node}).\n` +
       `Install a newer version: https://nodejs.org/\n\n`,
   );
   process.exit(1);
@@ -303,6 +303,7 @@ ${bold("Commands:")}
   ${cyan("health")}                     Quick health check — vault, DB, entry count
   ${cyan("status")}                     Show vault diagnostics
   ${cyan("doctor")}                     Diagnose and repair common issues
+  ${cyan("debug")}                      Generate AI-pasteable debug report
   ${cyan("restart")}                    Stop running MCP server processes (client auto-restarts)
   ${cyan("search")}                     Search vault entries from CLI
   ${cyan("save")}                       Save an entry to the vault from CLI
@@ -374,26 +375,6 @@ async function runSetup() {
     } catch {}
 
     if (latestVersion === VERSION) {
-      // Even when "up to date", ensure the launcher points to a valid server
-      const dataDir = join(HOME, ".context-mcp");
-      const launcherPath = join(dataDir, "server.mjs");
-      let launcherOk = false;
-      if (existsSync(launcherPath)) {
-        const content = readFileSync(launcherPath, "utf-8");
-        const m = content.match(/import "(.+?)"/);
-        if (m && existsSync(m[1])) launcherOk = true;
-      }
-      if (!launcherOk && !isNpx()) {
-        mkdirSync(dataDir, { recursive: true });
-        writeFileSync(launcherPath, `import "${SERVER_PATH}";\n`);
-        console.log(
-          green(`  ✓ context-vault v${VERSION} is up to date`) +
-            dim(`  (vault: ${existingVault})`),
-        );
-        console.log(dim(`  ↳ Repaired server launcher → ${SERVER_PATH}`));
-        console.log();
-        return;
-      }
       console.log(
         green(`  ✓ context-vault v${VERSION} is up to date`) +
           dim(`  (vault: ${existingVault})`),
@@ -512,12 +493,12 @@ async function runSetup() {
   if (detected.length === 0) {
     console.log(yellow("  No supported tools detected.\n"));
     console.log("  To manually configure, add to your tool's MCP config:\n");
-    if (isInstalledPackage()) {
+    if (isInstalledPackage() || isNpx()) {
       console.log(`  ${dim("{")}
     ${dim('"mcpServers": {')}
       ${dim('"context-vault": {')}
-        ${dim('"command": "npx",')}
-        ${dim(`"args": ["-y", "context-vault", "serve", "--vault-dir", "/path/to/vault"]`)}
+        ${dim('"command": "context-vault",')}
+        ${dim(`"args": ["serve", "--vault-dir", "/path/to/vault"]`)}
       ${dim("}")}
     ${dim("}")}
   ${dim("}")}\n`);
@@ -664,11 +645,6 @@ async function runSetup() {
   const dataDir = join(HOME, ".context-mcp");
   mkdirSync(dataDir, { recursive: true });
 
-  // Keep server.mjs launcher up to date so it always resolves to the current installation
-  if (isInstalledPackage()) {
-    writeFileSync(join(dataDir, "server.mjs"), `import "${SERVER_PATH}";\n`);
-  }
-
   // Write config.json to data dir (persistent, survives reinstalls)
   const configPath = join(dataDir, "config.json");
   const vaultConfig = {};
@@ -1136,11 +1112,25 @@ async function configureClaude(tool, vaultDir) {
         ],
         { stdio: "pipe", env },
       );
+    } else if (isInstalledPackage()) {
+      const serverArgs = ["serve"];
+      if (vaultDir) serverArgs.push("--vault-dir", vaultDir);
+      execFileSync(
+        "claude",
+        [
+          "mcp",
+          "add",
+          "-s",
+          "user",
+          "context-vault",
+          "--",
+          "context-vault",
+          ...serverArgs,
+        ],
+        { stdio: "pipe", env },
+      );
     } else {
-      const serverPath = isInstalledPackage()
-        ? join(HOME, ".context-mcp", "server.mjs")
-        : SERVER_PATH;
-      const nodeArgs = [serverPath];
+      const nodeArgs = [SERVER_PATH];
       if (vaultDir) nodeArgs.push("--vault-dir", vaultDir);
       execFileSync(
         "claude",
@@ -1182,11 +1172,16 @@ async function configureCodex(tool, vaultDir) {
         ["mcp", "add", "context-vault", "--", "npx", ...serverArgs],
         { stdio: "pipe" },
       );
+    } else if (isInstalledPackage()) {
+      const serverArgs = ["serve"];
+      if (vaultDir) serverArgs.push("--vault-dir", vaultDir);
+      execFileSync(
+        "codex",
+        ["mcp", "add", "context-vault", "--", "context-vault", ...serverArgs],
+        { stdio: "pipe" },
+      );
     } else {
-      const serverPath = isInstalledPackage()
-        ? join(HOME, ".context-mcp", "server.mjs")
-        : SERVER_PATH;
-      const nodeArgs = [serverPath];
+      const nodeArgs = [SERVER_PATH];
       if (vaultDir) nodeArgs.push("--vault-dir", vaultDir);
       execFileSync(
         "codex",
@@ -1236,13 +1231,11 @@ function configureJsonTool(tool, vaultDir) {
       env: { NODE_OPTIONS: "--no-warnings=ExperimentalWarning" },
     };
   } else if (isInstalledPackage()) {
-    const launcherPath = join(HOME, ".context-mcp", "server.mjs");
-    const serverArgs = [];
+    const serverArgs = ["serve"];
     if (vaultDir) serverArgs.push("--vault-dir", vaultDir);
     config[tool.configKey]["context-vault"] = {
-      command: process.execPath,
-      args: [launcherPath, ...serverArgs],
-      env: { NODE_OPTIONS: "--no-warnings=ExperimentalWarning" },
+      command: "context-vault",
+      args: serverArgs,
     };
   } else {
     const serverArgs = [SERVER_PATH];
@@ -1597,13 +1590,6 @@ async function runSwitch() {
   const { detected } = await detectAllTools();
 
   if (target === "local") {
-    const launcherPath = join(dataDir, "server.mjs");
-    if (!existsSync(launcherPath)) {
-      const serverAbs = resolve(ROOT, "src", "server.js");
-      mkdirSync(dataDir, { recursive: true });
-      writeFileSync(launcherPath, `import "${serverAbs}";\n`);
-    }
-
     vaultConfig.mode = "local";
     mkdirSync(dataDir, { recursive: true });
     writeFileSync(configPath, JSON.stringify(vaultConfig, null, 2) + "\n");
@@ -1635,7 +1621,7 @@ async function runSwitch() {
     }
     console.log();
     console.log(green("  ✓ Switched to local mode."));
-    console.log(dim(`  Server: node ${launcherPath}`));
+    console.log(dim(`  Server: context-vault serve`));
     console.log();
   } else {
     const hostedUrl = getFlag("--url") || vaultConfig.hostedUrl || API_URL;
@@ -2043,8 +2029,7 @@ async function runStatus() {
         const email = raw.email ? ` · ${raw.email}` : "";
         modeDetail = ` (${raw.hostedUrl}${email})`;
       } else {
-        const launcherPath = join(HOME, ".context-mcp", "server.mjs");
-        modeDetail = ` (node ${launcherPath})`;
+        modeDetail = ` (context-vault serve)`;
       }
     } catch {}
   }
@@ -4686,35 +4671,34 @@ async function runDoctor() {
       db?.close();
     } catch {}
 
-    // ── Launcher (server.mjs) ─────────────────────────────────────────────
-    const launcherPath = join(HOME, ".context-mcp", "server.mjs");
-    if (existsSync(launcherPath)) {
-      const launcherContent = readFileSync(launcherPath, "utf-8");
-      const match = launcherContent.match(/import "(.+?)"/);
-      if (match) {
-        const serverEntryPath = match[1];
-        if (existsSync(serverEntryPath)) {
-          console.log(
-            `  ${green("✓")} Launcher ${dim(`→ ${serverEntryPath}`)}`,
-          );
-        } else {
-          console.log(
-            `  ${red("✘")} Launcher points to missing server: ${serverEntryPath}`,
-          );
-          console.log(
-            `    ${dim("Fix: run context-vault setup to reinstall")}`,
-          );
-          allOk = false;
-        }
-      } else {
-        console.log(`  ${green("✓")} Launcher exists ${dim(launcherPath)}`);
-      }
-    } else {
-      console.log(`  ${yellow("!")} Launcher not found at ${launcherPath}`);
-      console.log(`    ${dim("Fix: run context-vault setup")}`);
+    // ── CLI binary ──────────────────────────────────────────────────────
+    try {
+      const binVersion = execSync("context-vault --version", {
+        encoding: "utf-8",
+        timeout: 5000,
+      }).trim();
+      console.log(
+        `  ${green("✓")} CLI binary ${dim(`(${binVersion})`)}`,
+      );
+    } catch {
+      console.log(
+        `  ${red("✘")} CLI binary not found in PATH`,
+      );
+      console.log(
+        `    ${dim("Fix: npm install -g context-vault")}`,
+      );
       allOk = false;
     }
 
+    // Clean up legacy launcher if it exists
+    const legacyLauncher = join(HOME, ".context-mcp", "server.mjs");
+    if (existsSync(legacyLauncher)) {
+      try {
+        unlinkSync(legacyLauncher);
+        console.log(`  ${green("✓")} Removed legacy launcher ${dim(legacyLauncher)}`);
+      } catch {}
+    }
+
     // ── Error log ─────────────────────────────────────────────────────────
     const logPath = errorLogPath(config.dataDir);
     const logCount = errorLogCount(config.dataDir);
@@ -5279,6 +5263,86 @@ async function runConsolidate() {
   console.log();
 }
 
+async function runDebug() {
+  const { resolveConfig } = await import("@context-vault/core/config");
+  const { errorLogPath, errorLogCount } = await import("../src/error-log.js");
+
+  let config;
+  try {
+    config = resolveConfig();
+  } catch {
+    config = null;
+  }
+
+  const dataDir = config?.dataDir || join(HOME, ".context-mcp");
+  const vaultDir = config?.vaultDir || join(HOME, "vault");
+  const dbPath = config?.dbPath || join(dataDir, "vault.db");
+  const configPath = config?.configPath || join(dataDir, "config.json");
+
+  const vaultExists = existsSync(vaultDir);
+  let vaultWritable = false;
+  if (vaultExists) {
+    try {
+      const probe = join(vaultDir, ".write-probe");
+      writeFileSync(probe, "");
+      unlinkSync(probe);
+      vaultWritable = true;
+    } catch {}
+  }
+
+  let dbAccessible = false;
+  let dbEntryCount = "n/a";
+  try {
+    const { initDatabase } = await import("@context-vault/core/db");
+    const db = await initDatabase(dbPath);
+    dbEntryCount = db.prepare("SELECT COUNT(*) as c FROM vault").get().c;
+    db.close();
+    dbAccessible = true;
+  } catch {}
+
+  const logCount = errorLogCount(dataDir);
+  const logPath = errorLogPath(dataDir);
+  let lastLogLines = [];
+  if (logCount > 0) {
+    try {
+      const lines = readFileSync(logPath, "utf-8")
+        .split("\n")
+        .filter((l) => l.trim());
+      lastLogLines = lines.slice(-5);
+    } catch {}
+  }
+
+  const lines = [
+    "```",
+    `context-vault debug report`,
+    `Generated: ${new Date().toISOString()}`,
+    ``,
+    `Node.js:    ${process.versions.node} (${process.execPath})`,
+    `Platform:   ${process.platform} ${process.arch}`,
+    `cv version: ${VERSION}`,
+    ``,
+    `Config:     ${configPath} (${existsSync(configPath) ? "found" : "missing"})`,
+    `Vault dir:  ${vaultDir} (${vaultExists ? "exists" : "missing"}${vaultExists ? `, writable: ${vaultWritable}` : ""})`,
+    `DB path:    ${dbPath} (${existsSync(dbPath) ? "exists" : "missing"})`,
+    `DB access:  ${dbAccessible ? `ok (${dbEntryCount} entries)` : "failed"}`,
+    ``,
+    `Error log:  ${logPath} (${logCount} entries)`,
+  ];
+
+  if (lastLogLines.length) {
+    lines.push(``, `Last 5 error log entries:`);
+    for (const l of lastLogLines) lines.push(`  ${l}`);
+  }
+
+  lines.push("```");
+  lines.push(
+    ``,
+    `Paste the above into Claude Code or your AI assistant to diagnose issues.`,
+  );
+
+  console.log(lines.join("\n"));
+}
+
 async function runServe() {
   await import("../src/server.js");
 }
@@ -5398,6 +5462,9 @@ async function main() {
     case "consolidate":
       await runConsolidate();
       break;
+    case "debug":
+      await runDebug();
+      break;
     default:
       console.error(red(`Unknown command: ${command}`));
       console.error(`Run ${cyan("context-vault --help")} for usage.`);
@@ -5406,6 +5473,15 @@ async function main() {
 }
 
 main().catch((e) => {
-  console.error(red(e.message));
+  const dataDir = join(HOME, ".context-mcp");
+  const logPath = join(dataDir, "error.log");
+  console.error(red(`Error: ${e.message}`));
+  console.error(dim(`Error log: ${logPath}`));
+  console.error(dim(`Run: context-vault doctor`));
+  console.error(
+    dim(
+      `Debug with AI: "context-vault exited with: ${e.message} — how do I fix this?"`,
+    ),
+  );
   process.exit(1);
 });

package/node_modules/@context-vault/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@context-vault/core",
-  "version": "3.0.3",
+  "version": "3.1.1",
   "type": "module",
   "description": "Pure local engine: capture, index, search, and utilities for context-vault",
   "main": "dist/main.js",

package/node_modules/@context-vault/core/src/db.ts

@@ -107,6 +107,7 @@ export async function initDatabase(dbPath: string): Promise<DatabaseSync> {
     const db = new DatabaseSync(path, { allowExtension: true });
     db.exec("PRAGMA journal_mode = WAL");
     db.exec("PRAGMA foreign_keys = ON");
+    db.exec("PRAGMA busy_timeout = 3000");
     try {
       sqliteVec.load(db);
     } catch (e) {
@@ -124,6 +125,7 @@ export async function initDatabase(dbPath: string): Promise<DatabaseSync> {
     );
 
     const backupPath = `${dbPath}.v${version}.backup`;
+    let backupSucceeded = false;
     try {
       db.close();
       if (existsSync(dbPath)) {
@@ -131,6 +133,9 @@ export async function initDatabase(dbPath: string): Promise<DatabaseSync> {
         console.error(
           `[context-vault] Backed up old database to: ${backupPath}`,
         );
+        backupSucceeded = true;
+      } else {
+        backupSucceeded = true;
       }
     } catch (backupErr) {
       console.error(
@@ -138,6 +143,13 @@ export async function initDatabase(dbPath: string): Promise<DatabaseSync> {
       );
     }
 
+    if (!backupSucceeded) {
+      throw new Error(
+        `[context-vault] Aborting schema migration: backup failed for ${dbPath}. ` +
+        `Fix the backup issue or manually back up the file before upgrading.`,
+      );
+    }
+
     unlinkSync(dbPath);
     try { unlinkSync(dbPath + "-wal"); } catch {}
     try { unlinkSync(dbPath + "-shm"); } catch {}

package/node_modules/@context-vault/core/src/index.ts

@@ -93,9 +93,16 @@ export async function indexEntry(
   }
 
   if (cat !== "event") {
-    const embedding = precomputedEmbedding !== undefined
-      ? precomputedEmbedding
-      : await ctx.embed([title, body].filter(Boolean).join(" "));
+    let embedding: Float32Array | null = null;
+    if (precomputedEmbedding !== undefined) {
+      embedding = precomputedEmbedding;
+    } else {
+      try {
+        embedding = await ctx.embed([title, body].filter(Boolean).join(" "));
+      } catch (embedErr) {
+        console.warn(`[context-vault] embed() failed for entry ${id} — skipping vec insert: ${(embedErr as Error).message}`);
+      }
+    }
 
     if (embedding) {
       try { ctx.deleteVec(rowid); } catch { /* no-op */ }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "context-vault",
-  "version": "3.0.3",
+  "version": "3.1.1",
   "type": "module",
   "description": "Persistent memory for AI agents — saves and searches knowledge across sessions",
   "bin": {
@@ -57,7 +57,7 @@
     "@context-vault/core"
   ],
   "dependencies": {
-    "@context-vault/core": "^3.0.3",
+    "@context-vault/core": "^3.1.1",
     "@modelcontextprotocol/sdk": "^1.26.0",
     "adm-zip": "^0.5.16",
     "sqlite-vec": "^0.1.0"

package/scripts/postinstall.js

@@ -6,11 +6,11 @@
  * 1. Installs @huggingface/transformers with --ignore-scripts to avoid sharp's
  *    broken install lifecycle in global contexts.  Semantic search degrades
  *    gracefully if this step fails.
- * 2. Writes local server launcher (global installs only).
+ * 2. Ensures data directory exists.
  */
 
 import { execSync } from "node:child_process";
-import { existsSync, writeFileSync, mkdirSync } from "node:fs";
+import { existsSync, mkdirSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { homedir } from "node:os";
@@ -51,18 +51,9 @@ async function main() {
     }
   }
 
-  // ── 2. Write local server launcher (global installs only) ────────────
-  // Under npx the path would be stale after cache eviction — configs use
-  // `npx context-vault serve` instead, so skip writing the launcher.
-  const isNpx = PKG_ROOT.includes("/_npx/") || PKG_ROOT.includes("\\_npx\\");
-  if (!isNpx) {
-    const SERVER_ABS = join(PKG_ROOT, "src", "server.js");
-    const DATA_DIR = join(homedir(), ".context-mcp");
-    const LAUNCHER = join(DATA_DIR, "server.mjs");
-    mkdirSync(DATA_DIR, { recursive: true });
-    writeFileSync(LAUNCHER, `import "${SERVER_ABS}";\n`);
-    console.log("[context-vault] Local server launcher written to " + LAUNCHER);
-  }
+  // ── 2. Ensure data dir exists ────────────────────────────────────────
+  const DATA_DIR = join(homedir(), ".context-mcp");
+  mkdirSync(DATA_DIR, { recursive: true });
 }
 
 main().catch(() => {});

package/src/helpers.js

@@ -4,7 +4,7 @@ import { fileURLToPath } from "node:url";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(
-  readFileSync(join(__dirname, "..", "..", "package.json"), "utf-8"),
+  readFileSync(join(__dirname, "..", "package.json"), "utf-8"),
 );
 
 export function ok(text) {
@@ -26,11 +26,19 @@ export function err(text, code = "UNKNOWN", meta = {}) {
   };
 }
 
+export function errWithHint(text, code, hint) {
+  const prompt = hint
+    ? `\n\n**Debug with AI:** Paste this into Claude Code or your AI assistant:\n> "${hint}"`
+    : "";
+  return err(text + prompt, code);
+}
+
 export function ensureVaultExists(config) {
   if (!config.vaultDirExists) {
-    return err(
+    return errWithHint(
       `Vault directory not found: ${config.vaultDir}. Run context-status for diagnostics.`,
       "VAULT_NOT_FOUND",
+      "My context-vault can't find the vault directory. Run `context-vault doctor` and help me fix it.",
     );
   }
   return null;

package/src/register-tools.js

@@ -109,7 +109,7 @@ export function registerTools(server, ctx) {
             },
           });
         } catch {}
-        throw e;
+        return err(e.message, "INTERNAL_ERROR");
       } finally {
         clearTimeout(timer);
         if (ctx.activeOps) ctx.activeOps.count--;

package/src/server.js

@@ -221,6 +221,13 @@ async function main() {
       phase,
     };
     appendErrorLog(dataDir, logEntry);
+    try {
+      mkdirSync(dataDir, { recursive: true });
+      writeFileSync(
+        join(dataDir, ".last-error"),
+        `${logEntry.timestamp} [${phase}] ${err.message}`,
+      );
+    } catch {}
 
     sendTelemetryEvent(config, {
       event: "startup_error",

package/src/tools/context-status.js

@@ -1,6 +1,8 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
 import { gatherVaultStatus, computeGrowthWarnings } from "../status.js";
 import { errorLogPath, errorLogCount } from "../error-log.js";
-import { ok } from "../helpers.js";
+import { ok, err } from "../helpers.js";
 
 function relativeTime(ts) {
   const secs = Math.floor((Date.now() - ts) / 1000);
@@ -23,6 +25,7 @@ export const inputSchema = {};
  * @param {import('../types.js').BaseCtx & Partial<import('../types.js').HostedCtxExtensions>} ctx
  */
 export function handler(_args, ctx) {
+  try {
   const { config } = ctx;
 
   const status = gatherVaultStatus(ctx);
@@ -120,6 +123,18 @@ export function handler(_args, ctx) {
     lines.push(`- Entries: ${logCount} (share this file for support)`);
   }
 
+  // Last startup error
+  const lastErrorPath = join(config.dataDir, ".last-error");
+  if (existsSync(lastErrorPath)) {
+    try {
+      const lastError = readFileSync(lastErrorPath, "utf-8").trim();
+      lines.push(``, `### Last Startup Error`);
+      lines.push(`\`\`\``);
+      lines.push(lastError);
+      lines.push(`\`\`\``);
+    } catch {}
+  }
+
   // Health: session-level tool call stats
   const ts = ctx.toolStats;
   if (ts) {
@@ -178,4 +193,7 @@ export function handler(_args, ctx) {
   }
 
   return ok(lines.join("\n"));
+  } catch (e) {
+    return err(e.message, "STATUS_FAILED");
+  }
 }

package/src/tools/create-snapshot.js

@@ -105,28 +105,32 @@ export async function handler(
 
   let candidates = [];
 
-  if (normalizedKinds.length > 0) {
-    for (const kindFilter of normalizedKinds) {
-      const rows = await hybridSearch(ctx, topic, {
-        kindFilter,
-        limit: Math.ceil(MAX_ENTRIES_FOR_GATHER / normalizedKinds.length),
-        
+  try {
+    if (normalizedKinds.length > 0) {
+      for (const kindFilter of normalizedKinds) {
+        const rows = await hybridSearch(ctx, topic, {
+          kindFilter,
+          limit: Math.ceil(MAX_ENTRIES_FOR_GATHER / normalizedKinds.length),
+
+          includeSuperseeded: false,
+        });
+        candidates.push(...rows);
+      }
+      const seen = new Set();
+      candidates = candidates.filter((r) => {
+        if (seen.has(r.id)) return false;
+        seen.add(r.id);
+        return true;
+      });
+    } else {
+      candidates = await hybridSearch(ctx, topic, {
+        limit: MAX_ENTRIES_FOR_GATHER,
+
         includeSuperseeded: false,
       });
-      candidates.push(...rows);
     }
-    const seen = new Set();
-    candidates = candidates.filter((r) => {
-      if (seen.has(r.id)) return false;
-      seen.add(r.id);
-      return true;
-    });
-  } else {
-    candidates = await hybridSearch(ctx, topic, {
-      limit: MAX_ENTRIES_FOR_GATHER,
-      
-      includeSuperseeded: false,
-    });
+  } catch (e) {
+    return err(e.message, "SEARCH_FAILED");
   }
 
   if (effectiveTags.length) {
@@ -162,22 +166,27 @@ export async function handler(
 
   const supersedes = noiseIds.length > 0 ? noiseIds : undefined;
 
-  const entry = await captureAndIndex(ctx, {
-    kind: "brief",
-    title: `${topic} — Context Brief`,
-    body: briefBody,
-    tags: briefTags,
-    source: "create_snapshot",
-    identity_key: effectiveIdentityKey,
-    supersedes,
-    
-    meta: {
-      topic,
-      entry_count: gatherEntries.length,
-      noise_superseded: noiseIds.length,
-      synthesized_from: gatherEntries.map((e) => e.id),
-    },
-  });
+  let entry;
+  try {
+    entry = await captureAndIndex(ctx, {
+      kind: "brief",
+      title: `${topic} — Context Brief`,
+      body: briefBody,
+      tags: briefTags,
+      source: "create_snapshot",
+      identity_key: effectiveIdentityKey,
+      supersedes,
+
+      meta: {
+        topic,
+        entry_count: gatherEntries.length,
+        noise_superseded: noiseIds.length,
+        synthesized_from: gatherEntries.map((e) => e.id),
+      },
+    });
+  } catch (e) {
+    return err(e.message, "SAVE_FAILED");
+  }
 
   const parts = [
     `✓ Snapshot created → id: ${entry.id}`,

package/src/tools/delete-context.js

@@ -17,7 +17,6 @@ export const inputSchema = {
  * @param {import('../types.js').ToolShared} shared
  */
 export async function handler({ id }, ctx, { ensureIndexed }) {
-
   if (!id?.trim())
     return err("Required: id (non-empty string)", "INVALID_INPUT");
   await ensureIndexed();
@@ -25,34 +24,31 @@ export async function handler({ id }, ctx, { ensureIndexed }) {
   const entry = ctx.stmts.getEntryById.get(id);
   if (!entry) return err(`Entry not found: ${id}`, "NOT_FOUND");
 
-  // Ownership check: don't leak existence across users
-    return err(`Entry not found: ${id}`, "NOT_FOUND");
-  }
-
-  // Delete file from disk first (source of truth)
-  let fileWarning = null;
-  if (entry.file_path) {
-    try {
-      unlinkSync(entry.file_path);
-    } catch (e) {
-      // ENOENT = already gone — not an error worth surfacing
-      if (e.code !== "ENOENT") {
-        fileWarning = `file could not be removed from disk (${e.code}): ${entry.file_path}`;
+  try {
+    // Delete DB record first — if this fails, the file stays and no orphan is created
+    const rowidResult = ctx.stmts.getRowid.get(id);
+    if (rowidResult?.rowid) {
+      try {
+        ctx.deleteVec(Number(rowidResult.rowid));
+      } catch {}
+    }
+    ctx.stmts.deleteEntry.run(id);
+
+    // Delete file from disk after successful DB delete
+    let fileWarning = null;
+    if (entry.file_path) {
+      try {
+        unlinkSync(entry.file_path);
+      } catch (e) {
+        if (e.code !== "ENOENT") {
+          fileWarning = `file could not be removed from disk (${e.code}): ${entry.file_path}`;
+        }
       }
     }
-  }
 
-  // Delete vector embedding
-  const rowidResult = ctx.stmts.getRowid.get(id);
-  if (rowidResult?.rowid) {
-    try {
-      ctx.deleteVec(Number(rowidResult.rowid));
-    } catch {}
+    const msg = `Deleted ${entry.kind}: ${entry.title || "(untitled)"} [${id}]`;
+    return ok(fileWarning ? `${msg}\nWarning: ${fileWarning}` : msg);
+  } catch (e) {
+    return err(e.message, "DELETE_FAILED");
   }
-
-  // Delete DB row (FTS trigger handles FTS cleanup)
-  ctx.stmts.deleteEntry.run(id);
-
-  const msg = `Deleted ${entry.kind}: ${entry.title || "(untitled)"} [${id}]`;
-  return ok(fileWarning ? `${msg}\nWarning: ${fileWarning}` : msg);
 }

package/src/tools/get-context.js

@@ -7,7 +7,7 @@ import { categoryFor } from "@context-vault/core/categories";
 import { normalizeKind } from "@context-vault/core/files";
 import { resolveTemporalParams } from "../temporal.js";
 import { collectLinkedEntries } from "../linking.js";
-import { ok, err } from "../helpers.js";
+import { ok, err, errWithHint } from "../helpers.js";
 import { isEmbedAvailable } from "@context-vault/core/embed";
 
 const STALE_DUPLICATE_DAYS = 7;
@@ -290,7 +290,7 @@ export const inputSchema = {
     .describe(
       "Return entries created before this date. Accepts ISO date strings or the same natural shortcuts as `since`. When `since` is 'yesterday' and `until` is omitted, `until` is automatically set to the end of yesterday.",
     ),
-  limit: z.number().optional().describe("Max results to return (default 10)"),
+  limit: z.number().max(500).optional().describe("Max results to return (default 10)"),
   include_superseded: z
     .boolean()
     .optional()
@@ -305,6 +305,7 @@ export const inputSchema = {
     ),
   max_tokens: z
     .number()
+    .max(100000)
     .optional()
     .describe(
       "Limit output to entries that fit within this token budget (rough estimate: 1 token ≈ 4 chars). Entries are packed greedily by relevance rank. At least 1 result is always returned. Response metadata includes tokens_used and tokens_budget.",
@@ -415,16 +416,7 @@ export async function handler(
   if (identity_key) {
     if (!kindFilter)
       return err("identity_key requires kind to be specified", "INVALID_INPUT");
-    // Local mode: getByIdentityKey takes 2 params (no user_id).
-    // Hosted mode: 3 params — (kind, identity_key).
-    const match =
-      ctx.stmts._mode === "local"
-        ? ctx.stmts.getByIdentityKey.get(kindFilter, identity_key)
-        : ctx.stmts.getByIdentityKey.get(
-            kindFilter,
-            identity_key,
-            null,
-          );
+    const match = ctx.stmts.getByIdentityKey.get(kindFilter, identity_key);
     if (match) {
       const entryTags = match.tags ? JSON.parse(match.tags) : [];
       const tagStr = entryTags.length ? entryTags.join(", ") : "none";
@@ -514,9 +506,18 @@ export async function handler(
     }
     const where = clauses.length ? `WHERE ${clauses.join(" AND ")}` : "";
     params.push(fetchLimit);
-    const rows = ctx.db
-      .prepare(`SELECT * FROM vault ${where} ORDER BY created_at DESC LIMIT ?`)
-      .all(...params);
+    let rows;
+    try {
+      rows = ctx.db
+        .prepare(`SELECT * FROM vault ${where} ORDER BY created_at DESC LIMIT ?`)
+        .all(...params);
+    } catch (e) {
+      return errWithHint(
+        e.message,
+        "DB_ERROR",
+        "context-vault get_context DB_ERROR. Check `cat ~/.context-mcp/error.log | tail -5` and help me debug.",
+      );
+    }
 
     // Post-filter by tags if provided, then apply requested limit
     filtered = effectiveTags.length

package/src/tools/list-context.js

@@ -1,7 +1,8 @@
 import { z } from "zod";
 import { normalizeKind } from "@context-vault/core/files";
 import { categoryFor } from "@context-vault/core/categories";
-import { ok } from "../helpers.js";
+import { ok, err, errWithHint } from "../helpers.js";
+import { resolveTemporalParams } from "../temporal.js";
 
 export const name = "list_context";
 
@@ -50,6 +51,10 @@ export async function handler(
 
   await ensureIndexed();
 
+  const resolved = resolveTemporalParams({ since, until });
+  since = resolved.since;
+  until = resolved.until;
+
   const kindFilter = kind ? normalizeKind(kind) : null;
   const effectiveCategory =
     category || (kindFilter ? categoryFor(kindFilter) : null);
@@ -64,8 +69,6 @@ export async function handler(
   const clauses = [];
   const params = [];
 
-  if (false) {
-  }
   if (kindFilter) {
     clauses.push("kind = ?");
     params.push(kindFilter);
@@ -91,16 +94,26 @@ export async function handler(
   const fetchLimit = tags?.length ? effectiveLimit * 10 : effectiveLimit;
 
   const countParams = [...params];
-  const total = ctx.db
-    .prepare(`SELECT COUNT(*) as c FROM vault ${where}`)
-    .get(...countParams).c;
-
-  params.push(fetchLimit, effectiveOffset);
-  const rows = ctx.db
-    .prepare(
-      `SELECT id, title, kind, category, tags, created_at, updated_at, SUBSTR(body, 1, 120) as preview FROM vault ${where} ORDER BY created_at DESC LIMIT ? OFFSET ?`,
-    )
-    .all(...params);
+  let total;
+  let rows;
+  try {
+    total = ctx.db
+      .prepare(`SELECT COUNT(*) as c FROM vault ${where}`)
+      .get(...countParams).c;
+
+    params.push(fetchLimit, effectiveOffset);
+    rows = ctx.db
+      .prepare(
+        `SELECT id, title, kind, category, tags, created_at, updated_at, SUBSTR(body, 1, 120) as preview FROM vault ${where} ORDER BY created_at DESC LIMIT ? OFFSET ?`,
+      )
+      .all(...params);
+  } catch (e) {
+    return errWithHint(
+      e.message,
+      "DB_ERROR",
+      "context-vault list_context DB_ERROR. Check `cat ~/.context-mcp/error.log | tail -5` and help me debug.",
+    );
+  }
 
   // Post-filter by tags if provided, then apply requested limit
   const filtered = tags?.length

package/src/tools/save-context.js

@@ -3,7 +3,7 @@ import { captureAndIndex, updateEntryFile } from "@context-vault/core/capture";
 import { indexEntry } from "@context-vault/core/index";
 import { categoryFor, defaultTierFor } from "@context-vault/core/categories";
 import { normalizeKind } from "@context-vault/core/files";
-import { ok, err, ensureVaultExists, ensureValidKind } from "../helpers.js";
+import { ok, err, errWithHint, ensureVaultExists, ensureValidKind } from "../helpers.js";
 import { maybeShowFeedbackPrompt } from "../telemetry.js";
 import { validateRelatedTo } from "../linking.js";
 import {
@@ -319,12 +319,6 @@ export const inputSchema = {
     .describe(
       "Source code files this entry is derived from. When these files change (hash mismatch), the entry will be flagged as stale in get_context results.",
     ),
-  tier: z
-    .enum(["ephemeral", "working", "durable"])
-    .optional()
-    .describe(
-      "Memory tier for lifecycle management. 'ephemeral': short-lived session data. 'working': active context (default). 'durable': long-term reference material. Defaults based on kind when not specified.",
-    ),
   dry_run: z
     .boolean()
     .optional()
@@ -409,10 +403,6 @@ export async function handler(
     const existing = ctx.stmts.getEntryById.get(id);
     if (!existing) return err(`Entry not found: ${id}`, "NOT_FOUND");
 
-    // Ownership check: don't leak existence across users
-      return err(`Entry not found: ${id}`, "NOT_FOUND");
-    }
-
     if (kind && normalizeKind(kind) !== existing.kind) {
       return err(
         `Cannot change kind (current: "${existing.kind}"). Delete and re-create instead.`,
@@ -434,18 +424,27 @@ export async function handler(
       if (decrypted.meta) existing.meta = JSON.stringify(decrypted.meta);
     }
 
-    const entry = updateEntryFile(ctx, existing, {
-      title,
-      body,
-      tags,
-      meta,
-      source,
-      expires_at,
-      supersedes,
-      related_to,
-      source_files,
-    });
-    await indexEntry(ctx, entry);
+    let entry;
+    try {
+      entry = updateEntryFile(ctx, existing, {
+        title,
+        body,
+        tags,
+        meta,
+        source,
+        expires_at,
+        supersedes,
+        related_to,
+        source_files,
+      });
+      await indexEntry(ctx, entry);
+    } catch (e) {
+      return errWithHint(
+        e.message,
+        "UPDATE_FAILED",
+        "context-vault save_context update is failing. Check `cat ~/.context-mcp/error.log | tail -5` and help me debug.",
+      );
+    }
     if (entry.related_to?.length && ctx.stmts.updateRelatedTo) {
       ctx.stmts.updateRelatedTo.run(JSON.stringify(entry.related_to), entry.id);
     } else if (entry.related_to === null && ctx.stmts.updateRelatedTo) {
@@ -489,7 +488,11 @@ export async function handler(
   if (category === "knowledge" || category === "event") {
     const threshold = similarity_threshold ?? DEFAULT_SIMILARITY_THRESHOLD;
     const embeddingText = [title, body].filter(Boolean).join(" ");
-    queryEmbedding = await ctx.embed(embeddingText);
+    try {
+      queryEmbedding = await ctx.embed(embeddingText);
+    } catch {
+      queryEmbedding = null;
+    }
     if (queryEmbedding) {
       similarEntries = await findSimilar(
         ctx,
@@ -543,22 +546,27 @@ export async function handler(
 
   const embeddingToReuse = category === "knowledge" ? queryEmbedding : null;
 
-  const entry = await captureAndIndex(ctx, {
-    kind: normalizedKind,
-    title,
-    body,
-    meta: finalMeta,
-    tags,
-    source,
-    folder,
-    identity_key,
-    expires_at,
-    supersedes,
-    related_to,
-    source_files,
+  let entry;
+  try {
+    entry = await captureAndIndex(ctx, {
+      kind: normalizedKind,
+      title,
+      body,
+      meta: finalMeta,
+      tags,
+      source,
+      folder,
+      identity_key,
+      expires_at,
+      supersedes,
+      related_to,
+      source_files,
 
-    tier: effectiveTier,
-  }, embeddingToReuse);
+      tier: effectiveTier,
+    }, embeddingToReuse);
+  } catch (e) {
+    return errWithHint(e.message, "SAVE_FAILED", "context-vault save_context is failing. Check `cat ~/.context-mcp/error.log | tail -5` and help me debug.");
+  }
 
   if (ctx.config?.dataDir) {
     maybeShowFeedbackPrompt(ctx.config.dataDir);
@@ -613,12 +621,8 @@ export async function handler(
   if (criticalLimit != null) {
     try {
       const countRow = ctx.db
-        .prepare(
-          false
-            
-            : "SELECT COUNT(*) as c FROM vault",
-        )
-        .get(...([]));
+        .prepare("SELECT COUNT(*) as c FROM vault")
+        .get();
       if (countRow.c >= criticalLimit) {
         parts.push(
           ``,