@context-vault/core 2.10.3 → 2.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@context-vault/core",
-  "version": "2.10.3",
+  "version": "2.11.0",
   "type": "module",
   "description": "Shared core: capture, index, retrieve, tools, and utilities for context-vault",
   "main": "src/index.js",

package/src/capture/file-ops.js

@@ -32,10 +32,12 @@ export function writeEntryFile(
     tags,
     source,
     createdAt,
+    updatedAt,
     folder,
     category,
     identity_key,
     expires_at,
+    supersedes,
   },
 ) {
   // P5: folder is now a top-level param; also accept from meta for backward compat
@@ -61,9 +63,11 @@ export function writeEntryFile(
 
   if (identity_key) fmFields.identity_key = identity_key;
   if (expires_at) fmFields.expires_at = expires_at;
+  if (supersedes?.length) fmFields.supersedes = supersedes;
   fmFields.tags = tags || [];
   fmFields.source = source || "claude-code";
   fmFields.created = created;
+  if (updatedAt && updatedAt !== created) fmFields.updated = updatedAt;
 
   const mdBody = formatBody(kind, { title, body, meta });
 

package/src/capture/index.js

@@ -26,6 +26,7 @@ export function writeEntry(
     folder,
     identity_key,
     expires_at,
+    supersedes,
     userId,
   },
 ) {
@@ -47,6 +48,7 @@ export function writeEntry(
   // Entity upsert: check for existing file at deterministic path
   let id;
   let createdAt;
+  let updatedAt;
   if (category === "entity" && identity_key) {
     const identitySlug = slugify(identity_key);
     const dir = resolve(ctx.config.vaultDir, kindToPath(kind));
@@ -58,13 +60,16 @@ export function writeEntry(
       const { meta: fmMeta } = parseFrontmatter(raw);
       id = fmMeta.id || ulid();
       createdAt = fmMeta.created || new Date().toISOString();
+      updatedAt = new Date().toISOString();
     } else {
       id = ulid();
       createdAt = new Date().toISOString();
+      updatedAt = createdAt;
     }
   } else {
     id = ulid();
     createdAt = new Date().toISOString();
+    updatedAt = createdAt;
   }
 
   const filePath = writeEntryFile(ctx.config.vaultDir, kind, {
@@ -75,10 +80,12 @@ export function writeEntry(
     tags,
     source,
     createdAt,
+    updatedAt,
     folder,
     category,
     identity_key,
     expires_at,
+    supersedes,
   });
 
   return {
@@ -92,8 +99,10 @@ export function writeEntry(
     tags,
     source,
     createdAt,
+    updatedAt,
     identity_key,
     expires_at,
+    supersedes,
     userId: userId || null,
   };
 }
@@ -121,6 +130,10 @@ export function updateEntryFile(ctx, existing, updates) {
     updates.source !== undefined ? updates.source : existing.source;
   const expires_at =
     updates.expires_at !== undefined ? updates.expires_at : existing.expires_at;
+  const supersedes =
+    updates.supersedes !== undefined
+      ? updates.supersedes
+      : fmMeta.supersedes || null;
 
   let mergedMeta;
   if (updates.meta !== undefined) {
@@ -130,6 +143,7 @@ export function updateEntryFile(ctx, existing, updates) {
   }
 
   // Build frontmatter
+  const now = new Date().toISOString();
   const fmFields = { id: existing.id };
   for (const [k, v] of Object.entries(mergedMeta)) {
     if (k === "folder") continue;
@@ -137,9 +151,11 @@ export function updateEntryFile(ctx, existing, updates) {
   }
   if (existing.identity_key) fmFields.identity_key = existing.identity_key;
   if (expires_at) fmFields.expires_at = expires_at;
+  if (supersedes?.length) fmFields.supersedes = supersedes;
   fmFields.tags = tags;
   fmFields.source = source || "claude-code";
   fmFields.created = fmMeta.created || existing.created_at;
+  if (now !== fmFields.created) fmFields.updated = now;
 
   const mdBody = formatBody(existing.kind, { title, body, meta: mergedMeta });
   const md = formatFrontmatter(fmFields) + mdBody;
@@ -159,8 +175,10 @@ export function updateEntryFile(ctx, existing, updates) {
     tags,
     source,
     createdAt: fmMeta.created || existing.created_at,
+    updatedAt: now,
     identity_key: existing.identity_key,
     expires_at,
+    supersedes,
     userId: existing.user_id || null,
   };
 }
@@ -180,6 +198,14 @@ export async function captureAndIndex(ctx, data) {
   const entry = writeEntry(ctx, data);
   try {
     await indexEntry(ctx, entry);
+    // Apply supersedes: mark referenced entries as superseded by this entry
+    if (entry.supersedes?.length && ctx.stmts.updateSupersededBy) {
+      for (const supersededId of entry.supersedes) {
+        if (typeof supersededId === "string" && supersededId.trim()) {
+          ctx.stmts.updateSupersededBy.run(entry.id, supersededId.trim());
+        }
+      }
+    }
     return entry;
   } catch (err) {
     // Rollback: restore previous content for entity upserts, delete for new entries

package/src/constants.js

@@ -6,3 +6,10 @@ export const MAX_TAGS_COUNT = 20;
 export const MAX_META_LENGTH = 10 * 1024; // 10KB
 export const MAX_SOURCE_LENGTH = 200;
 export const MAX_IDENTITY_KEY_LENGTH = 200;
+
+export const DEFAULT_GROWTH_THRESHOLDS = {
+  totalEntries: { warn: 1000, critical: 5000 },
+  eventEntries: { warn: 500, critical: 2000 },
+  vaultSizeBytes: { warn: 50 * 1024 * 1024, critical: 200 * 1024 * 1024 },
+  eventsWithoutTtl: { warn: 200 },
+};

package/src/core/categories.js

@@ -40,6 +40,17 @@ const CATEGORY_DIR_NAMES = {
 /** Set of valid category directory names (for reindex discovery) */
 export const CATEGORY_DIRS = new Set(Object.values(CATEGORY_DIR_NAMES));
 
+/**
+ * Staleness thresholds (in days) per knowledge kind.
+ * Kinds not listed here are considered enduring (no staleness threshold).
+ * Based on updated_at; falls back to created_at if updated_at is null.
+ */
+export const KIND_STALENESS_DAYS = {
+  pattern: 180,
+  decision: 365,
+  reference: 90,
+};
+
 export function categoryFor(kind) {
   return KIND_CATEGORY[kind] || "knowledge";
 }

package/src/core/config.js

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { homedir } from "node:os";
+import { DEFAULT_GROWTH_THRESHOLDS } from "../constants.js";
 
 export function parseArgs(argv) {
   const args = {};
@@ -31,6 +32,8 @@ export function resolveConfig() {
     dbPath: join(dataDir, "vault.db"),
     devDir: join(HOME, "dev"),
     eventDecayDays: 30,
+    thresholds: { ...DEFAULT_GROWTH_THRESHOLDS },
+    telemetry: false,
     resolvedFrom: "defaults",
   };
 
@@ -46,6 +49,30 @@ export function resolveConfig() {
       if (fc.dbPath) config.dbPath = fc.dbPath;
       if (fc.devDir) config.devDir = fc.devDir;
       if (fc.eventDecayDays != null) config.eventDecayDays = fc.eventDecayDays;
+      if (fc.thresholds) {
+        const t = fc.thresholds;
+        if (t.totalEntries)
+          config.thresholds.totalEntries = {
+            ...config.thresholds.totalEntries,
+            ...t.totalEntries,
+          };
+        if (t.eventEntries)
+          config.thresholds.eventEntries = {
+            ...config.thresholds.eventEntries,
+            ...t.eventEntries,
+          };
+        if (t.vaultSizeBytes)
+          config.thresholds.vaultSizeBytes = {
+            ...config.thresholds.vaultSizeBytes,
+            ...t.vaultSizeBytes,
+          };
+        if (t.eventsWithoutTtl)
+          config.thresholds.eventsWithoutTtl = {
+            ...config.thresholds.eventsWithoutTtl,
+            ...t.eventsWithoutTtl,
+          };
+      }
+      if (fc.telemetry != null) config.telemetry = fc.telemetry === true;
       // Hosted account linking (Phase 4)
       if (fc.hostedUrl) config.hostedUrl = fc.hostedUrl;
       if (fc.apiKey) config.apiKey = fc.apiKey;
@@ -96,6 +123,11 @@ export function resolveConfig() {
   if (process.env.CONTEXT_VAULT_HOSTED_URL) {
     config.hostedUrl = process.env.CONTEXT_VAULT_HOSTED_URL;
   }
+  if (process.env.CONTEXT_VAULT_TELEMETRY !== undefined) {
+    config.telemetry =
+      process.env.CONTEXT_VAULT_TELEMETRY === "1" ||
+      process.env.CONTEXT_VAULT_TELEMETRY === "true";
+  }
 
   if (cliArgs.vaultDir) {
     config.vaultDir = cliArgs.vaultDir;

package/src/core/frontmatter.js

@@ -65,8 +65,10 @@ const RESERVED_FM_KEYS = new Set([
   "tags",
   "source",
   "created",
+  "updated",
   "identity_key",
   "expires_at",
+  "supersedes",
 ]);
 
 export function extractCustomMeta(fmMeta) {

package/src/core/status.js

@@ -6,6 +6,7 @@ import { existsSync, readdirSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { walkDir } from "./files.js";
 import { isEmbedAvailable } from "../index/embed.js";
+import { KIND_STALENESS_DAYS } from "./categories.js";
 
 /**
  * Gather raw vault status data for formatting by consumers.
@@ -109,6 +110,30 @@ export function gatherVaultStatus(ctx, opts = {}) {
     errors.push(`Expired count failed: ${e.message}`);
   }
 
+  // Count event-category entries
+  let eventCount = 0;
+  try {
+    eventCount = db
+      .prepare(
+        `SELECT COUNT(*) as c FROM vault WHERE category = 'event' ${userAnd}`,
+      )
+      .get(...userParams).c;
+  } catch (e) {
+    errors.push(`Event count failed: ${e.message}`);
+  }
+
+  // Count event entries without expires_at
+  let eventsWithoutTtlCount = 0;
+  try {
+    eventsWithoutTtlCount = db
+      .prepare(
+        `SELECT COUNT(*) as c FROM vault WHERE category = 'event' AND expires_at IS NULL ${userAnd}`,
+      )
+      .get(...userParams).c;
+  } catch (e) {
+    errors.push(`Events without TTL count failed: ${e.message}`);
+  }
+
   // Embedding/vector status
   let embeddingStatus = null;
   try {
@@ -140,6 +165,27 @@ export function gatherVaultStatus(ctx, opts = {}) {
     errors.push(`Auto-captured feedback count failed: ${e.message}`);
   }
 
+  // Stale knowledge entries — kinds with a threshold, not updated within N days
+  let staleKnowledge = [];
+  try {
+    const stalenessKinds = Object.entries(KIND_STALENESS_DAYS);
+    if (stalenessKinds.length > 0) {
+      const kindClauses = stalenessKinds
+        .map(
+          ([kind, days]) =>
+            `(kind = '${kind}' AND COALESCE(updated_at, created_at) <= datetime('now', '-${days} days'))`,
+        )
+        .join(" OR ");
+      staleKnowledge = db
+        .prepare(
+          `SELECT kind, title, COALESCE(updated_at, created_at) as last_updated FROM vault WHERE category = 'knowledge' AND (${kindClauses}) AND (expires_at IS NULL OR expires_at > datetime('now')) ${userAnd} ORDER BY last_updated ASC LIMIT 10`,
+        )
+        .all(...userParams);
+    }
+  } catch (e) {
+    errors.push(`Stale knowledge check failed: ${e.message}`);
+  }
+
   return {
     fileCount,
     subdirs,
@@ -150,10 +196,129 @@ export function gatherVaultStatus(ctx, opts = {}) {
     stalePaths,
     staleCount,
     expiredCount,
+    eventCount,
+    eventsWithoutTtlCount,
     embeddingStatus,
     embedModelAvailable,
     autoCapturedFeedbackCount,
+    staleKnowledge,
     resolvedFrom: config.resolvedFrom,
     errors,
   };
 }
+
+/**
+ * Compute growth warnings based on vault status and configured thresholds.
+ *
+ * @param {object} status — result of gatherVaultStatus()
+ * @param {object} thresholds — from config.thresholds
+ * @returns {{ warnings: Array, hasCritical: boolean, hasWarnings: boolean, actions: string[] }}
+ */
+export function computeGrowthWarnings(status, thresholds) {
+  if (!thresholds)
+    return {
+      warnings: [],
+      hasCritical: false,
+      hasWarnings: false,
+      actions: [],
+    };
+
+  const t = thresholds;
+  const warnings = [];
+  const actions = [];
+
+  const total = status.embeddingStatus?.total ?? 0;
+  const {
+    eventCount = 0,
+    eventsWithoutTtlCount = 0,
+    expiredCount = 0,
+    dbSizeBytes = 0,
+  } = status;
+
+  if (t.totalEntries?.critical != null && total >= t.totalEntries.critical) {
+    warnings.push({
+      level: "critical",
+      message: `Total entries: ${total.toLocaleString()} (exceeds critical limit of ${t.totalEntries.critical.toLocaleString()})`,
+    });
+  } else if (t.totalEntries?.warn != null && total >= t.totalEntries.warn) {
+    warnings.push({
+      level: "warn",
+      message: `Total entries: ${total.toLocaleString()} (exceeds recommended ${t.totalEntries.warn.toLocaleString()})`,
+    });
+  }
+
+  if (
+    t.eventEntries?.critical != null &&
+    eventCount >= t.eventEntries.critical
+  ) {
+    warnings.push({
+      level: "critical",
+      message: `Event entries: ${eventCount.toLocaleString()} (exceeds critical limit of ${t.eventEntries.critical.toLocaleString()})`,
+    });
+  } else if (
+    t.eventEntries?.warn != null &&
+    eventCount >= t.eventEntries.warn
+  ) {
+    const ttlNote =
+      eventsWithoutTtlCount > 0
+        ? ` (${eventsWithoutTtlCount.toLocaleString()} without TTL)`
+        : "";
+    warnings.push({
+      level: "warn",
+      message: `Event entries: ${eventCount.toLocaleString()}${ttlNote} (exceeds recommended ${t.eventEntries.warn.toLocaleString()})`,
+    });
+  }
+
+  if (
+    t.vaultSizeBytes?.critical != null &&
+    dbSizeBytes >= t.vaultSizeBytes.critical
+  ) {
+    warnings.push({
+      level: "critical",
+      message: `Database size: ${(dbSizeBytes / 1024 / 1024).toFixed(1)}MB (exceeds critical limit of ${(t.vaultSizeBytes.critical / 1024 / 1024).toFixed(0)}MB)`,
+    });
+  } else if (
+    t.vaultSizeBytes?.warn != null &&
+    dbSizeBytes >= t.vaultSizeBytes.warn
+  ) {
+    warnings.push({
+      level: "warn",
+      message: `Database size: ${(dbSizeBytes / 1024 / 1024).toFixed(1)}MB (exceeds recommended ${(t.vaultSizeBytes.warn / 1024 / 1024).toFixed(0)}MB)`,
+    });
+  }
+
+  if (
+    t.eventsWithoutTtl?.warn != null &&
+    eventsWithoutTtlCount >= t.eventsWithoutTtl.warn
+  ) {
+    warnings.push({
+      level: "warn",
+      message: `Event entries without expires_at: ${eventsWithoutTtlCount.toLocaleString()} (exceeds recommended ${t.eventsWithoutTtl.warn.toLocaleString()})`,
+    });
+  }
+
+  const hasCritical = warnings.some((w) => w.level === "critical");
+
+  if (expiredCount > 0) {
+    actions.push(
+      `Run \`context-vault prune\` to remove ${expiredCount} expired event entr${expiredCount === 1 ? "y" : "ies"}`,
+    );
+  }
+  const eventThresholdExceeded =
+    eventCount >= (t.eventEntries?.warn ?? Infinity);
+  const ttlThresholdExceeded =
+    eventsWithoutTtlCount >= (t.eventsWithoutTtl?.warn ?? Infinity);
+  if (
+    eventsWithoutTtlCount > 0 &&
+    (eventThresholdExceeded || ttlThresholdExceeded)
+  ) {
+    actions.push(
+      "Add `expires_at` to event/session entries to enable automatic cleanup",
+    );
+  }
+  if (total >= (t.totalEntries?.warn ?? Infinity)) {
+    actions.push("Consider archiving events older than 90 days");
+  }
+
+  return { warnings, hasCritical, hasWarnings: warnings.length > 0, actions };
+}

package/src/core/telemetry.js

@@ -0,0 +1,64 @@
+import { existsSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+const TELEMETRY_ENDPOINT = "https://api.context-vault.com/telemetry";
+const NOTICE_MARKER = ".telemetry-notice-shown";
+
+export function isTelemetryEnabled(config) {
+  const envVal = process.env.CONTEXT_VAULT_TELEMETRY;
+  if (envVal !== undefined) return envVal === "1" || envVal === "true";
+  return config?.telemetry === true;
+}
+
+/**
+ * Fire-and-forget telemetry event. Never throws, never blocks.
+ * Payload contains only: event, code, tool, cv_version, node_version, platform, arch, ts.
+ * No message text, stack traces, vault content, file paths, or user identifiers.
+ */
+export function sendTelemetryEvent(config, payload) {
+  if (!isTelemetryEnabled(config)) return;
+
+  const event = {
+    event: payload.event,
+    code: payload.code || null,
+    tool: payload.tool || null,
+    cv_version: payload.cv_version,
+    node_version: process.version,
+    platform: process.platform,
+    arch: process.arch,
+    ts: new Date().toISOString(),
+  };
+
+  fetch(TELEMETRY_ENDPOINT, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(event),
+    signal: AbortSignal.timeout(5000),
+  }).catch(() => {});
+}
+
+/**
+ * Print the one-time telemetry notice to stderr.
+ * Uses a marker file in dataDir to ensure it's only shown once.
+ */
+export function maybeShowTelemetryNotice(dataDir) {
+  try {
+    const markerPath = join(dataDir, NOTICE_MARKER);
+    if (existsSync(markerPath)) return;
+    writeFileSync(markerPath, new Date().toISOString() + "\n");
+  } catch {
+    return;
+  }
+
+  const lines = [
+    "[context-vault] Telemetry: disabled by default.",
+    "[context-vault] To help improve context-vault, you can opt in to anonymous error reporting.",
+    "[context-vault] Reports contain only: event type, error code, tool name, version, node version, platform, arch, timestamp.",
+    "[context-vault] No vault content, file paths, or personal data is ever sent.",
+    '[context-vault] Opt in: set "telemetry": true in ~/.context-mcp/config.json or set CONTEXT_VAULT_TELEMETRY=1.',
+    "[context-vault] Full payload schema: https://contextvault.dev/telemetry",
+  ];
+  for (const line of lines) {
+    process.stderr.write(line + "\n");
+  }
+}

package/src/index/db.js

@@ -55,7 +55,9 @@ export const SCHEMA_DDL = `
     file_path       TEXT UNIQUE,
     identity_key    TEXT,
     expires_at      TEXT,
+    superseded_by   TEXT,
     created_at      TEXT DEFAULT (datetime('now')),
+    updated_at      TEXT,
     user_id         TEXT,
     team_id         TEXT,
     body_encrypted  BLOB,
@@ -67,9 +69,11 @@ export const SCHEMA_DDL = `
   CREATE INDEX IF NOT EXISTS idx_vault_kind ON vault(kind);
   CREATE INDEX IF NOT EXISTS idx_vault_category ON vault(category);
   CREATE INDEX IF NOT EXISTS idx_vault_category_created ON vault(category, created_at DESC);
+  CREATE INDEX IF NOT EXISTS idx_vault_updated ON vault(updated_at DESC);
   CREATE INDEX IF NOT EXISTS idx_vault_user ON vault(user_id);
   CREATE INDEX IF NOT EXISTS idx_vault_team ON vault(team_id);
   CREATE UNIQUE INDEX IF NOT EXISTS idx_vault_identity ON vault(user_id, kind, identity_key) WHERE identity_key IS NOT NULL;
+  CREATE INDEX IF NOT EXISTS idx_vault_superseded ON vault(superseded_by) WHERE superseded_by IS NOT NULL;
 
   -- Single FTS5 table
   CREATE VIRTUAL TABLE IF NOT EXISTS vault_fts USING fts5(
@@ -147,13 +151,13 @@ export async function initDatabase(dbPath) {
 
     const freshDb = createDb(dbPath);
     freshDb.exec(SCHEMA_DDL);
-    freshDb.exec("PRAGMA user_version = 7");
+    freshDb.exec("PRAGMA user_version = 9");
     return freshDb;
   }
 
   if (version < 5) {
     db.exec(SCHEMA_DDL);
-    db.exec("PRAGMA user_version = 7");
+    db.exec("PRAGMA user_version = 9");
   } else if (version === 5) {
     // v5 -> v6 migration: add multi-tenancy + encryption columns
     // Wrapped in transaction with duplicate-column guards for idempotent retry
@@ -171,24 +175,91 @@ export async function initDatabase(dbPath) {
       addColumnSafe(`ALTER TABLE vault ADD COLUMN meta_encrypted BLOB`);
       addColumnSafe(`ALTER TABLE vault ADD COLUMN iv BLOB`);
       addColumnSafe(`ALTER TABLE vault ADD COLUMN team_id TEXT`);
+      addColumnSafe(`ALTER TABLE vault ADD COLUMN updated_at TEXT`);
+      addColumnSafe(`ALTER TABLE vault ADD COLUMN superseded_by TEXT`);
       db.exec(`CREATE INDEX IF NOT EXISTS idx_vault_user ON vault(user_id)`);
       db.exec(`CREATE INDEX IF NOT EXISTS idx_vault_team ON vault(team_id)`);
       db.exec(`DROP INDEX IF EXISTS idx_vault_identity`);
       db.exec(
         `CREATE UNIQUE INDEX IF NOT EXISTS idx_vault_identity ON vault(user_id, kind, identity_key) WHERE identity_key IS NOT NULL`,
       );
-      db.exec("PRAGMA user_version = 7");
+      db.exec(
+        `UPDATE vault SET updated_at = created_at WHERE updated_at IS NULL`,
+      );
+      db.exec(
+        `CREATE INDEX IF NOT EXISTS idx_vault_updated ON vault(updated_at DESC)`,
+      );
+      db.exec(
+        `CREATE INDEX IF NOT EXISTS idx_vault_superseded ON vault(superseded_by) WHERE superseded_by IS NOT NULL`,
+      );
+      db.exec("PRAGMA user_version = 9");
     });
   } else if (version === 6) {
-    // v6 -> v7 migration: add team_id column
+    // v6 -> v7+v8+v9 migration: add team_id, updated_at, superseded_by columns
     runTransaction(db, () => {
       try {
         db.exec(`ALTER TABLE vault ADD COLUMN team_id TEXT`);
       } catch (e) {
         if (!e.message.includes("duplicate column")) throw e;
       }
+      try {
+        db.exec(`ALTER TABLE vault ADD COLUMN updated_at TEXT`);
+      } catch (e) {
+        if (!e.message.includes("duplicate column")) throw e;
+      }
+      try {
+        db.exec(`ALTER TABLE vault ADD COLUMN superseded_by TEXT`);
+      } catch (e) {
+        if (!e.message.includes("duplicate column")) throw e;
+      }
       db.exec(`CREATE INDEX IF NOT EXISTS idx_vault_team ON vault(team_id)`);
-      db.exec("PRAGMA user_version = 7");
+      db.exec(
+        `UPDATE vault SET updated_at = created_at WHERE updated_at IS NULL`,
+      );
+      db.exec(
+        `CREATE INDEX IF NOT EXISTS idx_vault_updated ON vault(updated_at DESC)`,
+      );
+      db.exec(
+        `CREATE INDEX IF NOT EXISTS idx_vault_superseded ON vault(superseded_by) WHERE superseded_by IS NOT NULL`,
+      );
+      db.exec("PRAGMA user_version = 9");
+    });
+  } else if (version === 7) {
+    // v7 -> v8+v9 migration: add updated_at, superseded_by columns
+    runTransaction(db, () => {
+      try {
+        db.exec(`ALTER TABLE vault ADD COLUMN updated_at TEXT`);
+      } catch (e) {
+        if (!e.message.includes("duplicate column")) throw e;
+      }
+      try {
+        db.exec(`ALTER TABLE vault ADD COLUMN superseded_by TEXT`);
+      } catch (e) {
+        if (!e.message.includes("duplicate column")) throw e;
+      }
+      db.exec(
+        `UPDATE vault SET updated_at = created_at WHERE updated_at IS NULL`,
+      );
+      db.exec(
+        `CREATE INDEX IF NOT EXISTS idx_vault_updated ON vault(updated_at DESC)`,
+      );
+      db.exec(
+        `CREATE INDEX IF NOT EXISTS idx_vault_superseded ON vault(superseded_by) WHERE superseded_by IS NOT NULL`,
+      );
+      db.exec("PRAGMA user_version = 9");
+    });
+  } else if (version === 8) {
+    // v8 -> v9 migration: add superseded_by column
+    runTransaction(db, () => {
+      try {
+        db.exec(`ALTER TABLE vault ADD COLUMN superseded_by TEXT`);
+      } catch (e) {
+        if (!e.message.includes("duplicate column")) throw e;
+      }
+      db.exec(
+        `CREATE INDEX IF NOT EXISTS idx_vault_superseded ON vault(superseded_by) WHERE superseded_by IS NOT NULL`,
+      );
+      db.exec("PRAGMA user_version = 9");
     });
   }
 
@@ -199,13 +270,13 @@ export function prepareStatements(db) {
   try {
     return {
       insertEntry: db.prepare(
-        `INSERT INTO vault (id, user_id, kind, category, title, body, meta, tags, source, file_path, identity_key, expires_at, created_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+        `INSERT INTO vault (id, user_id, kind, category, title, body, meta, tags, source, file_path, identity_key, expires_at, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
       ),
       insertEntryEncrypted: db.prepare(
-        `INSERT INTO vault (id, user_id, kind, category, title, body, meta, tags, source, file_path, identity_key, expires_at, created_at, body_encrypted, title_encrypted, meta_encrypted, iv) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+        `INSERT INTO vault (id, user_id, kind, category, title, body, meta, tags, source, file_path, identity_key, expires_at, created_at, updated_at, body_encrypted, title_encrypted, meta_encrypted, iv) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
       ),
       updateEntry: db.prepare(
-        `UPDATE vault SET title = ?, body = ?, meta = ?, tags = ?, source = ?, category = ?, identity_key = ?, expires_at = ? WHERE file_path = ?`,
+        `UPDATE vault SET title = ?, body = ?, meta = ?, tags = ?, source = ?, category = ?, identity_key = ?, expires_at = ?, updated_at = datetime('now') WHERE file_path = ?`,
       ),
       deleteEntry: db.prepare(`DELETE FROM vault WHERE id = ?`),
       getRowid: db.prepare(`SELECT rowid FROM vault WHERE id = ?`),
@@ -215,12 +286,18 @@ export function prepareStatements(db) {
         `SELECT * FROM vault WHERE kind = ? AND identity_key = ? AND user_id IS ?`,
       ),
       upsertByIdentityKey: db.prepare(
-        `UPDATE vault SET title = ?, body = ?, meta = ?, tags = ?, source = ?, category = ?, file_path = ?, expires_at = ? WHERE kind = ? AND identity_key = ? AND user_id IS ?`,
+        `UPDATE vault SET title = ?, body = ?, meta = ?, tags = ?, source = ?, category = ?, file_path = ?, expires_at = ?, updated_at = datetime('now') WHERE kind = ? AND identity_key = ? AND user_id IS ?`,
       ),
       insertVecStmt: db.prepare(
         `INSERT INTO vault_vec (rowid, embedding) VALUES (?, ?)`,
       ),
       deleteVecStmt: db.prepare(`DELETE FROM vault_vec WHERE rowid = ?`),
+      updateSupersededBy: db.prepare(
+        `UPDATE vault SET superseded_by = ? WHERE id = ?`,
+      ),
+      clearSupersededByRef: db.prepare(
+        `UPDATE vault SET superseded_by = NULL WHERE superseded_by = ?`,
+      ),
     };
   } catch (e) {
     throw new Error(

package/src/index/index.js

@@ -111,6 +111,7 @@ export async function indexEntry(
           identity_key || null,
           expires_at || null,
           createdAt,
+          createdAt,
           encrypted.body_encrypted,
           encrypted.title_encrypted,
           encrypted.meta_encrypted,
@@ -131,6 +132,7 @@ export async function indexEntry(
           identity_key || null,
           expires_at || null,
           createdAt,
+          createdAt,
         );
       }
     } catch (e) {
@@ -186,6 +188,39 @@ export async function indexEntry(
   }
 }
 
+/**
+ * Prune expired entries: delete files, vec rows, and DB rows for all entries
+ * where expires_at <= now(). Safe to call on startup or CLI — non-destructive
+ * to active data.
+ *
+ * @param {import('../server/types.js').BaseCtx} ctx
+ * @returns {Promise<number>} count of pruned entries
+ */
+export async function pruneExpired(ctx) {
+  const expired = ctx.db
+    .prepare(
+      "SELECT id, file_path FROM vault WHERE expires_at IS NOT NULL AND expires_at <= datetime('now')",
+    )
+    .all();
+
+  for (const row of expired) {
+    if (row.file_path) {
+      try {
+        unlinkSync(row.file_path);
+      } catch {}
+    }
+    const vRowid = ctx.stmts.getRowid.get(row.id)?.rowid;
+    if (vRowid) {
+      try {
+        ctx.deleteVec(Number(vRowid));
+      } catch {}
+    }
+    ctx.stmts.deleteEntry.run(row.id);
+  }
+
+  return expired.length;
+}
+
 /**
  * Bulk reindex: sync vault directory into the database.
  * P2: Wrapped in a transaction for atomicity.
@@ -205,7 +240,7 @@ export async function reindex(ctx, opts = {}) {
   // Use INSERT OR IGNORE for reindex — handles files with duplicate frontmatter IDs
   // user_id is NULL for reindex (always local mode)
   const upsertEntry = ctx.db.prepare(
-    `INSERT OR IGNORE INTO vault (id, user_id, kind, category, title, body, meta, tags, source, file_path, identity_key, expires_at, created_at) VALUES (?, NULL, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    `INSERT OR IGNORE INTO vault (id, user_id, kind, category, title, body, meta, tags, source, file_path, identity_key, expires_at, created_at, updated_at) VALUES (?, NULL, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
   );
 
   // Auto-discover kind directories, supporting both:
@@ -309,6 +344,7 @@ export async function reindex(ctx, opts = {}) {
             identity_key,
             expires_at,
             created,
+            fmMeta.updated || created,
           );
           if (result.changes > 0) {
             const rowidResult = ctx.stmts.getRowid.get(id);

package/src/index.js

@@ -47,7 +47,7 @@ export {
   deleteVec,
 } from "./index/db.js";
 export { embed, embedBatch, resetEmbedPipeline } from "./index/embed.js";
-export { indexEntry, reindex } from "./index/index.js";
+export { indexEntry, reindex, pruneExpired } from "./index/index.js";
 
 // Retrieve layer
 export { hybridSearch } from "./retrieve/index.js";

package/src/retrieve/index.js

@@ -9,10 +9,23 @@
 
 const FTS_WEIGHT = 0.4;
 const VEC_WEIGHT = 0.6;
+const NEAR_DUP_THRESHOLD = 0.92;
 
 /**
- * Strip FTS5 metacharacters from query words and build an AND query.
- * Returns null if no valid words remain.
+ * Dot product of two Float32Array vectors (cosine similarity for unit vectors).
+ */
+export function dotProduct(a, b) {
+  let sum = 0;
+  for (let i = 0; i < a.length; i++) sum += a[i] * b[i];
+  return sum;
+}
+
+/**
+ * Build a tiered FTS5 query that prioritises phrase match, then proximity,
+ * then AND.  Multi-word queries become:
+ *   "word1 word2" OR NEAR("word1" "word2", 10) OR "word1" AND "word2"
+ * Single-word queries remain a simple quoted term.
+ * Returns null if no valid words remain after stripping FTS5 metacharacters.
  */
 export function buildFtsQuery(query) {
   const words = query
@@ -20,7 +33,11 @@ export function buildFtsQuery(query) {
     .map((w) => w.replace(/[*"():^~{}]/g, ""))
     .filter((w) => w.length > 0);
   if (!words.length) return null;
-  return words.map((w) => `"${w}"`).join(" AND ");
+  if (words.length === 1) return `"${words[0]}"`;
+  const phrase = `"${words.join(" ")}"`;
+  const near = `NEAR(${words.map((w) => `"${w}"`).join(" ")}, 10)`;
+  const and = words.map((w) => `"${w}"`).join(" AND ");
+  return `${phrase} OR ${near} OR ${and}`;
 }
 
 /**
@@ -44,6 +61,7 @@ export function buildFilterClauses({
   until,
   userIdFilter,
   teamIdFilter,
+  includeSuperseeded = false,
 }) {
   const clauses = [];
   const params = [];
@@ -68,6 +86,9 @@ export function buildFilterClauses({
     params.push(until);
   }
   clauses.push("(e.expires_at IS NULL OR e.expires_at > datetime('now'))");
+  if (!includeSuperseeded) {
+    clauses.push("e.superseded_by IS NULL");
+  }
   return { clauses, params };
 }
 
@@ -92,15 +113,19 @@ export async function hybridSearch(
     decayDays = 30,
     userIdFilter,
     teamIdFilter = null,
+    includeSuperseeded = false,
   } = {},
 ) {
   const results = new Map();
+  const idToRowid = new Map();
+  let queryVec = null;
   const extraFilters = buildFilterClauses({
     categoryFilter,
     since,
     until,
     userIdFilter,
     teamIdFilter,
+    includeSuperseeded,
   });
 
   // FTS5 search
@@ -144,7 +169,7 @@ export async function hybridSearch(
       .prepare("SELECT COUNT(*) as c FROM vault_vec")
       .get().c;
     if (vecCount > 0) {
-      const queryVec = await ctx.embed(query);
+      queryVec = await ctx.embed(query);
       if (queryVec) {
         // Increase limits in hosted mode to compensate for post-filtering
         const hasPostFilter = userIdFilter !== undefined || teamIdFilter;
@@ -188,6 +213,7 @@ export async function hybridSearch(
               continue;
 
             const { rowid: _rowid, ...cleanRow } = row;
+            idToRowid.set(cleanRow.id, Number(row.rowid));
             // sqlite-vec returns L2 distance [0, 2] for normalized vectors.
             // Convert to similarity [1, 0] with: 1 - distance/2
             const vecScore = Math.max(0, 1 - vr.distance / 2) * VEC_WEIGHT;
@@ -215,5 +241,56 @@ export async function hybridSearch(
   }
 
   const sorted = [...results.values()].sort((a, b) => b.score - a.score);
+
+  // Near-duplicate suppression: when embeddings are available and we have more
+  // candidates than needed, skip results that are too similar to already-selected ones.
+  if (queryVec && idToRowid.size > 0 && sorted.length > limit) {
+    const rowidsToFetch = sorted
+      .filter((c) => idToRowid.has(c.id))
+      .map((c) => idToRowid.get(c.id));
+
+    const embeddingMap = new Map();
+    if (rowidsToFetch.length > 0) {
+      try {
+        const placeholders = rowidsToFetch.map(() => "?").join(",");
+        const vecData = ctx.db
+          .prepare(
+            `SELECT rowid, embedding FROM vault_vec WHERE rowid IN (${placeholders})`,
+          )
+          .all(...rowidsToFetch);
+        for (const row of vecData) {
+          const buf = row.embedding;
+          if (buf) {
+            embeddingMap.set(
+              Number(row.rowid),
+              new Float32Array(buf.buffer, buf.byteOffset, buf.byteLength / 4),
+            );
+          }
+        }
+      } catch (_) {
+        return sorted.slice(offset, offset + limit);
+      }
+    }
+
+    const selected = [];
+    const selectedVecs = [];
+    for (const candidate of sorted) {
+      if (selected.length >= offset + limit) break;
+      const rowid = idToRowid.get(candidate.id);
+      const vec = rowid !== undefined ? embeddingMap.get(rowid) : null;
+      if (vec && selectedVecs.length > 0) {
+        let maxSim = 0;
+        for (const sv of selectedVecs) {
+          const sim = dotProduct(sv, vec);
+          if (sim > maxSim) maxSim = sim;
+        }
+        if (maxSim > NEAR_DUP_THRESHOLD) continue;
+      }
+      selected.push(candidate);
+      if (vec) selectedVecs.push(vec);
+    }
+    return selected.slice(offset, offset + limit);
+  }
+
   return sorted.slice(offset, offset + limit);
 }

package/src/server/tools/context-status.js

@@ -1,4 +1,4 @@
-import { gatherVaultStatus } from "../../core/status.js";
+import { gatherVaultStatus, computeGrowthWarnings } from "../../core/status.js";
 import { errorLogPath, errorLogCount } from "../../core/error-log.js";
 import { ok } from "../helpers.js";
 
@@ -40,7 +40,7 @@ export function handler(_args, ctx) {
     `Data dir:  ${config.dataDir}`,
     `Config:    ${config.configPath}`,
     `Resolved via: ${status.resolvedFrom}`,
-    `Schema:    v7 (teams)`,
+    `Schema:    v9 (updated_at, superseded_by)`,
   ];
 
   if (status.embeddingStatus) {
@@ -58,7 +58,7 @@ export function handler(_args, ctx) {
   lines.push(`Decay:     ${config.eventDecayDays} days (event recency window)`);
   if (status.expiredCount > 0) {
     lines.push(
-      `Expired:   ${status.expiredCount} entries (pruned on next reindex)`,
+      `Expired:   ${status.expiredCount} entries pending prune (run \`context-vault prune\` to remove now)`,
     );
   }
 
@@ -93,6 +93,25 @@ export function handler(_args, ctx) {
     lines.push(`Auto-reindex will fix this on next search or save.`);
   }
 
+  if (status.staleKnowledge?.length > 0) {
+    lines.push(``);
+    lines.push(`### ⚠ Potentially Stale Knowledge`);
+    lines.push(
+      `Not updated within kind staleness window (pattern: 180d, decision: 365d, reference: 90d):`,
+    );
+    for (const entry of status.staleKnowledge) {
+      const lastUpdated = entry.last_updated
+        ? entry.last_updated.split("T")[0]
+        : "unknown";
+      lines.push(
+        `- "${entry.title}" (${entry.kind}) — last updated ${lastUpdated}`,
+      );
+    }
+    lines.push(
+      `Use save_context to refresh or add expires_at to retire stale entries.`,
+    );
+  }
+
   // Error log
   const logPath = errorLogPath(config.dataDir);
   const logCount = errorLogCount(config.dataDir);
@@ -120,6 +139,21 @@ export function handler(_args, ctx) {
     }
   }
 
+  // Growth warnings
+  const growth = computeGrowthWarnings(status, config.thresholds);
+  if (growth.hasWarnings) {
+    lines.push("", "### ⚠ Vault Growth Warning");
+    for (const w of growth.warnings) {
+      lines.push(`  ${w.message}`);
+    }
+    if (growth.actions.length) {
+      lines.push("", "Suggested growth actions:");
+      for (const a of growth.actions) {
+        lines.push(`  • ${a}`);
+      }
+    }
+  }
+
   // Suggested actions
   const actions = [];
   if (status.stalePaths)

package/src/server/tools/get-context.js

@@ -42,6 +42,12 @@ export const inputSchema = {
     .optional()
     .describe("ISO date, return entries created before this"),
   limit: z.number().optional().describe("Max results to return (default 10)"),
+  include_superseded: z
+    .boolean()
+    .optional()
+    .describe(
+      "If true, include entries that have been superseded by newer ones. Default: false.",
+    ),
 };
 
 /**
@@ -50,7 +56,17 @@ export const inputSchema = {
  * @param {import('../types.js').ToolShared} shared
  */
 export async function handler(
-  { query, kind, category, identity_key, tags, since, until, limit },
+  {
+    query,
+    kind,
+    category,
+    identity_key,
+    tags,
+    since,
+    until,
+    limit,
+    include_superseded,
+  },
   ctx,
   { ensureIndexed, reindexFailed },
 ) {
@@ -126,6 +142,7 @@ export async function handler(
       limit: fetchLimit,
       decayDays: config.eventDecayDays || 30,
       userIdFilter: userId,
+      includeSuperseeded: include_superseded ?? false,
     });
 
     // Post-filter by tags if provided, then apply requested limit
@@ -238,8 +255,12 @@ export async function handler(
     lines.push(
       `### [${i + 1}/${filtered.length}] ${r.title || "(untitled)"} [${r.kind}/${r.category}]`,
     );
+    const dateStr =
+      r.updated_at && r.updated_at !== r.created_at
+        ? `${r.created_at} (updated ${r.updated_at})`
+        : r.created_at || "";
     lines.push(
-      `${r.score.toFixed(3)} · ${tagStr} · ${relPath} · id: \`${r.id}\``,
+      `${r.score.toFixed(3)} · ${tagStr} · ${relPath} · ${dateStr} · id: \`${r.id}\``,
     );
     lines.push(r.body?.slice(0, 300) + (r.body?.length > 300 ? "..." : ""));
     lines.push("");

package/src/server/tools/ingest-url.js

@@ -65,17 +65,6 @@ export async function handler(
 
   await ensureIndexed();
 
-  // Hosted tier limit enforcement
-  if (ctx.checkLimits) {
-    const usage = ctx.checkLimits();
-    if (usage.entryCount >= usage.maxEntries) {
-      return err(
-        `Entry limit reached (${usage.maxEntries}). Upgrade to Pro for unlimited entries.`,
-        "LIMIT_EXCEEDED",
-      );
-    }
-  }
-
   try {
     const { ingestUrl } = await import("../../capture/ingest-url.js");
     const entryData = await ingestUrl(targetUrl, { kind, tags });

package/src/server/tools/list-context.js

@@ -6,7 +6,7 @@ import { ok } from "../helpers.js";
 export const name = "list_context";
 
 export const description =
-  "Browse vault entries without a search query. Returns id, title, kind, category, tags, created_at. Use get_context with a query for semantic search. Use this to browse by tags or find recent entries.";
+  "Browse vault entries without a search query. Returns id, title, kind, category, tags, created_at, updated_at. Use get_context with a query for semantic search. Use this to browse by tags or find recent entries.";
 
 export const inputSchema = {
   kind: z
@@ -101,7 +101,7 @@ export async function handler(
   params.push(fetchLimit, effectiveOffset);
   const rows = ctx.db
     .prepare(
-      `SELECT id, title, kind, category, tags, created_at, SUBSTR(body, 1, 120) as preview FROM vault ${where} ORDER BY created_at DESC LIMIT ? OFFSET ?`,
+      `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);
 
@@ -140,8 +140,12 @@ export async function handler(
   for (const r of filtered) {
     const entryTags = r.tags ? JSON.parse(r.tags) : [];
     const tagStr = entryTags.length ? entryTags.join(", ") : "none";
+    const dateStr =
+      r.updated_at && r.updated_at !== r.created_at
+        ? `${r.created_at} (updated ${r.updated_at})`
+        : r.created_at;
     lines.push(
-      `- **${r.title || "(untitled)"}** [${r.kind}/${r.category}] — ${tagStr} — ${r.created_at} — \`${r.id}\``,
+      `- **${r.title || "(untitled)"}** [${r.kind}/${r.category}] — ${tagStr} — ${dateStr} — \`${r.id}\``,
     );
     if (r.preview)
       lines.push(

package/src/server/tools/save-context.js

@@ -15,6 +15,63 @@ import {
   MAX_IDENTITY_KEY_LENGTH,
 } from "../../constants.js";
 
+const DEFAULT_SIMILARITY_THRESHOLD = 0.85;
+
+async function findSimilar(ctx, embedding, threshold, userId) {
+  try {
+    const vecCount = ctx.db
+      .prepare("SELECT COUNT(*) as c FROM vault_vec")
+      .get().c;
+    if (vecCount === 0) return [];
+
+    const vecRows = ctx.db
+      .prepare(
+        `SELECT v.rowid, v.distance FROM vault_vec v WHERE embedding MATCH ? ORDER BY distance LIMIT ?`,
+      )
+      .all(embedding, 10);
+
+    if (!vecRows.length) return [];
+
+    const rowids = vecRows.map((vr) => vr.rowid);
+    const placeholders = rowids.map(() => "?").join(",");
+    const hydrated = ctx.db
+      .prepare(
+        `SELECT rowid, id, title, category, user_id FROM vault WHERE rowid IN (${placeholders})`,
+      )
+      .all(...rowids);
+
+    const byRowid = new Map();
+    for (const row of hydrated) byRowid.set(row.rowid, row);
+
+    const results = [];
+    for (const vr of vecRows) {
+      const similarity = Math.max(0, 1 - vr.distance / 2);
+      if (similarity < threshold) continue;
+      const row = byRowid.get(vr.rowid);
+      if (!row) continue;
+      if (userId !== undefined && row.user_id !== userId) continue;
+      if (row.category === "entity") continue;
+      results.push({ id: row.id, title: row.title, score: similarity });
+    }
+    return results;
+  } catch {
+    return [];
+  }
+}
+
+function formatSimilarWarning(similar) {
+  const lines = ["", "⚠ Similar entries already exist:"];
+  for (const e of similar) {
+    const score = e.score.toFixed(2);
+    const title = e.title ? `"${e.title}"` : "(no title)";
+    lines.push(`  - ${title} (${score}) — id: ${e.id}`);
+  }
+  lines.push(
+    "  Consider using `id: <existing>` in save_context to update instead.",
+  );
+  return lines.join("\n");
+}
+
 /**
  * Validate input fields for save_context. Returns an error response or null.
  */
@@ -150,6 +207,26 @@ export const inputSchema = {
       "Required for entity kinds (contact, project, tool, source). The unique identifier for this entity.",
     ),
   expires_at: z.string().optional().describe("ISO date for TTL expiry"),
+  supersedes: z
+    .array(z.string())
+    .optional()
+    .describe(
+      "Array of entry IDs that this entry supersedes/replaces. Those entries will be marked with superseded_by pointing to this new entry and excluded from future search results by default.",
+    ),
+  dry_run: z
+    .boolean()
+    .optional()
+    .describe(
+      "If true, check for similar entries without saving. Returns similarity results without creating a new entry. Only applies to knowledge and event categories.",
+    ),
+  similarity_threshold: z
+    .number()
+    .min(0)
+    .max(1)
+    .optional()
+    .describe(
+      "Cosine similarity threshold for duplicate detection (0–1, default 0.85). Entries above this score are flagged as similar. Only applies to knowledge and event categories.",
+    ),
 };
 
 /**
@@ -169,6 +246,9 @@ export async function handler(
     source,
     identity_key,
     expires_at,
+    supersedes,
+    dry_run,
+    similarity_threshold,
   },
   ctx,
   { ensureIndexed },
@@ -231,6 +311,7 @@ export async function handler(
       meta,
       source,
       expires_at,
+      supersedes,
     });
     await indexEntry(ctx, entry);
     const relPath = entry.filePath
@@ -261,25 +342,45 @@ export async function handler(
     );
   }
 
-  // Hosted tier limit enforcement (skipped in local mode — no checkLimits on ctx)
-  if (ctx.checkLimits) {
-    const usage = ctx.checkLimits();
-    if (usage.entryCount >= usage.maxEntries) {
-      return err(
-        `Entry limit reached (${usage.maxEntries}). Upgrade to Pro for unlimited entries.`,
-        "LIMIT_EXCEEDED",
+  await ensureIndexed();
+
+  // ── Similarity check (knowledge + event only) ────────────────────────────
+  const category = categoryFor(normalizedKind);
+  let similarEntries = [];
+
+  if (category === "knowledge" || category === "event") {
+    const threshold = similarity_threshold ?? DEFAULT_SIMILARITY_THRESHOLD;
+    const embeddingText = [title, body].filter(Boolean).join(" ");
+    const queryEmbedding = await ctx.embed(embeddingText);
+    if (queryEmbedding) {
+      similarEntries = await findSimilar(
+        ctx,
+        queryEmbedding,
+        threshold,
+        userId,
       );
     }
-    if (usage.storageMb >= usage.maxStorageMb) {
-      return err(
-        `Storage limit reached (${usage.maxStorageMb} MB). Upgrade to Pro for more storage.`,
-        "LIMIT_EXCEEDED",
+  }
+
+  if (dry_run) {
+    const parts = ["(dry run — nothing saved)"];
+    if (similarEntries.length) {
+      parts.push("", "⚠ Similar entries already exist:");
+      for (const e of similarEntries) {
+        const score = e.score.toFixed(2);
+        const titleDisplay = e.title ? `"${e.title}"` : "(no title)";
+        parts.push(`  - ${titleDisplay} (${score}) — id: ${e.id}`);
+      }
+      parts.push(
+        "",
+        "Use save_context with `id: <existing>` to update one, or omit `dry_run` to save as new.",
       );
+    } else {
+      parts.push("", "No similar entries found. Safe to save.");
     }
+    return ok(parts.join("\n"));
   }
 
-  await ensureIndexed();
-
   const mergedMeta = { ...(meta || {}) };
   if (folder) mergedMeta.folder = folder;
   const finalMeta = Object.keys(mergedMeta).length ? mergedMeta : undefined;
@@ -294,6 +395,7 @@ export async function handler(
     folder,
     identity_key,
     expires_at,
+    supersedes,
     userId,
   });
   const relPath = entry.filePath
@@ -303,5 +405,28 @@ export async function handler(
   if (title) parts.push(`  title: ${title}`);
   if (tags?.length) parts.push(`  tags: ${tags.join(", ")}`);
   parts.push("", "_Use this id to update or delete later._");
+  if (similarEntries.length) {
+    parts.push(formatSimilarWarning(similarEntries));
+  }
+
+  const criticalLimit = config.thresholds?.totalEntries?.critical;
+  if (criticalLimit != null) {
+    try {
+      const countRow = ctx.db
+        .prepare(
+          userId !== undefined
+            ? "SELECT COUNT(*) as c FROM vault WHERE user_id = ?"
+            : "SELECT COUNT(*) as c FROM vault",
+        )
+        .get(...(userId !== undefined ? [userId] : []));
+      if (countRow.c >= criticalLimit) {
+        parts.push(
+          ``,
+          `ℹ Vault has ${countRow.c.toLocaleString()} entries. Consider running \`context-vault reindex\` or reviewing old entries.`,
+        );
+      }
+    } catch {}
+  }
+
   return ok(parts.join("\n"));
 }

package/src/server/tools.js

@@ -1,6 +1,7 @@
 import { reindex } from "../index/index.js";
 import { captureAndIndex } from "../capture/index.js";
 import { err } from "./helpers.js";
+import { sendTelemetryEvent } from "../core/telemetry.js";
 import pkg from "../../package.json" with { type: "json" };
 
 import * as getContext from "./tools/get-context.js";
@@ -57,6 +58,12 @@ export function registerTools(server, ctx) {
               timestamp: Date.now(),
             };
           }
+          sendTelemetryEvent(ctx.config, {
+            event: "tool_error",
+            code: "TIMEOUT",
+            tool: toolName,
+            cv_version: pkg.version,
+          });
           return err(
             "Tool timed out after 60s. Try a simpler query or run `context-vault reindex` first.",
             "TIMEOUT",
@@ -70,6 +77,12 @@ export function registerTools(server, ctx) {
             timestamp: Date.now(),
           };
         }
+        sendTelemetryEvent(ctx.config, {
+          event: "tool_error",
+          code: "UNKNOWN",
+          tool: toolName,
+          cv_version: pkg.version,
+        });
         try {
           await captureAndIndex(ctx, {
             kind: "feedback",