@context-vault/core 2.10.3 → 2.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@context-vault/core",
-  "version": "2.10.3",
+  "version": "2.12.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

@@ -1,3 +1,9 @@
+export const APP_URL = "https://app.context-vault.com";
+export const API_URL = "https://api.context-vault.com";
+export const MARKETING_URL = "https://contextvault.dev";
+export const GITHUB_ISSUES_URL =
+  "https://github.com/fellanH/context-vault/issues";
+
 export const MAX_BODY_LENGTH = 100 * 1024; // 100KB
 export const MAX_TITLE_LENGTH = 500;
 export const MAX_KIND_LENGTH = 64;
@@ -6,3 +12,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,90 @@
+import { existsSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { API_URL, MARKETING_URL, GITHUB_ISSUES_URL } from "../constants.js";
+
+const TELEMETRY_ENDPOINT = `${API_URL}/telemetry`;
+const NOTICE_MARKER = ".telemetry-notice-shown";
+const FEEDBACK_PROMPT_MARKER = ".feedback-prompt-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: ${MARKETING_URL}/telemetry`,
+  ];
+  for (const line of lines) {
+    process.stderr.write(line + "\n");
+  }
+}
+
+/**
+ * Print a one-time feedback prompt after the user's first successful save.
+ * Uses a marker file in dataDir to ensure it's only shown once.
+ * Never throws, never blocks.
+ */
+export function maybeShowFeedbackPrompt(dataDir) {
+  try {
+    const markerPath = join(dataDir, FEEDBACK_PROMPT_MARKER);
+    if (existsSync(markerPath)) return;
+    writeFileSync(markerPath, new Date().toISOString() + "\n");
+  } catch {
+    return;
+  }
+
+  const lines = [
+    "[context-vault] First entry saved — nice work!",
+    "[context-vault] Got feedback, a bug, or a feature request?",
+    `[context-vault] Open an issue: ${GITHUB_ISSUES_URL}`,
+  ];
+  for (const line of lines) {
+    process.stderr.write(line + "\n");
+  }
+}