context-vault 2.17.0 → 2.17.1

package/bin/cli.js

@@ -282,7 +282,7 @@ function printDetectionResults(results) {
   }
 }
 
-function showHelp() {
+function showHelp(showAll = false) {
   console.log(`
   ${bold("◇ context-vault")} ${dim(`v${VERSION}`)}
   ${dim("Persistent memory for AI agents")}
@@ -293,37 +293,48 @@ ${bold("Usage:")}
   ${dim("No command → runs setup (first time) or shows status (existing vault)")}
 
 ${bold("Commands:")}
-  ${cyan("setup")}                 Interactive MCP server installer
-  ${cyan("connect")} --key cv_...  Connect AI tools to hosted vault
-  ${cyan("switch")} local|hosted      Switch between local and hosted MCP modes
-  ${cyan("serve")}                 Start the MCP server (used by AI clients)
-  ${cyan("hooks")} install|uninstall  Install or remove Claude Code memory hook
-  ${cyan("claude")} install|uninstall  Alias for hooks install|uninstall
-  ${cyan("skills")} install          Install bundled Claude Code skills
-  ${cyan("health")}                Quick health check — vault, DB, entry count
-  ${cyan("restart")}               Stop running MCP server processes (client auto-restarts)
-  ${cyan("flush")}                 Check vault health and confirm DB is accessible
-  ${cyan("recall")}                Search vault from a Claude Code hook (reads stdin)
-  ${cyan("session-capture")}       Save a session summary entry (reads JSON from stdin)
-  ${cyan("session-end")}           Run session-end hook (parse transcript + capture)
-  ${cyan("post-tool-call")}        Run post-tool-call hook (log tool usage)
-  ${cyan("save")}                  Save an entry to the vault from CLI
-  ${cyan("search")}                Search vault entries from CLI
-  ${cyan("reindex")}               Rebuild search index from knowledge files
-  ${cyan("prune")}                 Remove expired entries (use --dry-run to preview)
-  ${cyan("status")}                Show vault diagnostics
-  ${cyan("doctor")}                Diagnose and repair common issues
-  ${cyan("update")}                Check for and install updates
-  ${cyan("uninstall")}             Remove MCP configs and optionally data
-  ${cyan("import")} <path>          Import entries from file or directory
-  ${cyan("export")}                Export vault to JSON or CSV
-  ${cyan("ingest")} <url>          Fetch URL and save as vault entry
-  ${cyan("ingest-project")} <path>  Scan project directory and register as project entity
-  ${cyan("migrate")}               Migrate vault between local and hosted
-  ${cyan("consolidate")}           Find hot tags and cold entries for maintenance
-
-${bold("Options:")}
+  ${cyan("setup")}                      Interactive MCP server installer
+  ${cyan("connect")} --key cv_...       Connect AI tools to hosted vault
+  ${cyan("switch")} local|hosted        Switch between local and hosted MCP modes
+  ${cyan("serve")}                      Start the MCP server (used by AI clients)
+  ${cyan("hooks")} install|uninstall    Install or remove Claude Code memory hook
+  ${cyan("claude")} install|uninstall   Alias for hooks install|uninstall
+  ${cyan("skills")} install             Install bundled Claude Code skills
+  ${cyan("health")}                     Quick health check — vault, DB, entry count
+  ${cyan("status")}                     Show vault diagnostics
+  ${cyan("doctor")}                     Diagnose and repair common issues
+  ${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
+  ${cyan("import")} <path>              Import entries from file or directory
+  ${cyan("export")}                     Export vault to JSON or CSV
+  ${cyan("ingest")} <url>               Fetch URL and save as vault entry
+  ${cyan("ingest-project")} <path>      Scan project directory and register as project entity
+  ${cyan("reindex")}                    Rebuild search index from knowledge files
+  ${cyan("migrate-dirs")} [--dry-run]   Rename plural vault dirs to singular (post-2.18.0)
+  ${cyan("prune")}                      Remove expired entries (use --dry-run to preview)
+  ${cyan("update")}                     Check for and install updates
+  ${cyan("uninstall")}                  Remove MCP configs and optionally data
+`);
+
+  if (showAll) {
+    console.log(`${bold("Plumbing")} ${dim("(internal — hook implementations and maintenance utilities):")}
+  ${cyan("recall")}                     Search vault from a Claude Code hook (reads stdin)
+  ${cyan("session-capture")}            Save a session summary entry (reads JSON from stdin)
+  ${cyan("session-end")}                Run session-end hook (parse transcript + capture)
+  ${cyan("post-tool-call")}             Run post-tool-call hook (log tool usage)
+  ${cyan("flush")}                      Check vault health and confirm DB is accessible
+  ${cyan("consolidate")}                Find hot tags and cold entries for maintenance
+  ${cyan("migrate")}                    Migrate vault between local and hosted
+`);
+  } else {
+    console.log(`  ${dim("Run")} ${dim("context-vault --help --all")} ${dim("to show internal plumbing commands.")}
+`);
+  }
+
+  console.log(`${bold("Options:")}
   --help                Show this help
+  --help --all          Show all commands including internal plumbing
   --version             Show version
   --vault-dir <path>    Set vault directory (setup/serve)
   --yes                 Non-interactive mode (accept all defaults)
@@ -1696,6 +1707,80 @@ async function runReindex() {
   console.log(`  ${dim("·")} ${stats.unchanged} unchanged`);
 }
 
+async function runMigrateDirs() {
+  const dryRun = flags.has("--dry-run");
+
+  // Vault dir: positional arg (skip --flags), or fall back to configured vault
+  const positional = args.slice(1).find((a) => !a.startsWith("--"));
+  let vaultDir = positional;
+
+  if (!vaultDir) {
+    const { resolveConfig } = await import("@context-vault/core/core/config");
+    const config = resolveConfig();
+    if (!config.vaultDirExists) {
+      console.error(red(`Vault directory not found: ${config.vaultDir}`));
+      console.error("Run " + cyan("context-vault setup") + " to configure.");
+      process.exit(1);
+    }
+    vaultDir = config.vaultDir;
+  }
+
+  if (!existsSync(vaultDir) || !statSync(vaultDir).isDirectory()) {
+    console.error(red(`Error: ${vaultDir} is not a directory`));
+    process.exit(1);
+  }
+
+  const { planMigration, executeMigration } =
+    await import("@context-vault/core/core/migrate-dirs");
+
+  const ops = planMigration(vaultDir);
+
+  if (ops.length === 0) {
+    console.log(green("✓ No plural directories found — vault is up to date."));
+    return;
+  }
+
+  if (dryRun) {
+    console.log(dim("Dry run — no files will be moved.\n"));
+  }
+
+  for (const op of ops) {
+    const fileLabel = `${op.fileCount} ${op.fileCount === 1 ? "file" : "files"}`;
+    const actionLabel = op.action === "rename" ? "RENAME" : "MERGE";
+    const suffix = dryRun ? dim(" [dry-run]") : "";
+    console.log(
+      `  ${cyan(actionLabel)}: ${op.pluralName}/ → ${op.singularName}/ (${fileLabel})${suffix}`,
+    );
+  }
+
+  if (dryRun) {
+    console.log();
+    console.log(
+      dim(
+        `  ${ops.length} ${ops.length === 1 ? "directory" : "directories"} would be renamed/merged.`,
+      ),
+    );
+    console.log(dim("  Remove --dry-run to apply."));
+    return;
+  }
+
+  const { renamed, merged, errors } = executeMigration(ops);
+
+  console.log();
+  if (renamed > 0) console.log(green(`✓ Renamed: ${renamed}`));
+  if (merged > 0) console.log(green(`✓ Merged:  ${merged}`));
+  if (errors.length > 0) {
+    for (const e of errors) console.log(red(`  ✗ ${e}`));
+  }
+
+  if (renamed + merged > 0) {
+    console.log();
+    console.log(
+      dim("Run `context-vault reindex` to rebuild the search index."),
+    );
+  }
+}
+
 async function runPrune() {
   const dryRun = flags.has("--dry-run");
 
@@ -1827,7 +1912,7 @@ async function runStatus() {
       const filled = maxCount > 0 ? Math.round((c / maxCount) * BAR_WIDTH) : 0;
       const bar = "█".repeat(filled) + "░".repeat(BAR_WIDTH - filled);
       const countStr = String(c).padStart(4);
-      console.log(`  ${countStr} ${kind}s   ${dim(bar)}`);
+      console.log(`    ${dim(bar)} ${countStr} ${kind}s`);
     }
   } else {
     console.log(`\n  ${dim("(empty — no entries indexed)")}`);
@@ -2881,6 +2966,7 @@ async function runSearch() {
   const sort = getFlag("--sort") || "relevance";
   const format = getFlag("--format") || "plain";
   const showFull = flags.has("--full");
+  const scopeArg = getFlag("--scope"); // "hot" | "events" | "all"
 
   const valuedFlags = new Set([
     "--kind",
@@ -2888,6 +2974,7 @@ async function runSearch() {
     "--limit",
     "--sort",
     "--format",
+    "--scope",
   ]);
 
   const queryParts = [];
@@ -2927,8 +3014,18 @@ async function runSearch() {
 
     let results;
 
+    // Resolve scope → category/exclude filter
+    const validScopes = new Set(["hot", "events", "all"]);
+    const resolvedScope = validScopes.has(scopeArg) ? scopeArg : "hot";
+    const scopeCategoryFilter = resolvedScope === "events" ? "event" : null;
+    const scopeExcludeEvents = resolvedScope === "hot";
+
     if (query) {
-      results = await hybridSearch(ctx, query, { limit: limit * 2 });
+      results = await hybridSearch(ctx, query, {
+        limit: limit * 2,
+        categoryFilter: scopeCategoryFilter,
+        excludeEvents: scopeExcludeEvents,
+      });
 
       if (kind) {
         results = results.filter((r) => r.kind === kind);
@@ -2941,6 +3038,10 @@ async function runSearch() {
         sql += " AND kind = ?";
         params.push(kind);
       }
+      if (scopeCategoryFilter) {
+        sql += " AND category = ?";
+        params.push(scopeCategoryFilter);
+      }
       sql += " ORDER BY COALESCE(updated_at, created_at) DESC LIMIT ?";
       params.push(limit);
       results = db.prepare(sql).all(...params);
@@ -3840,7 +3941,7 @@ async function runDoctor() {
             console.log(`    ${dim(`${row.created_at} — ${row.title}`)}`);
           }
           console.log(
-            `    ${dim('Review: context-vault search --kind feedback --tag auto-captured')}`,
+            `    ${dim("Review: context-vault search --kind feedback --tag auto-captured")}`,
           );
         }
       } catch {
@@ -3953,9 +4054,7 @@ async function runDoctor() {
         console.log(
           `  ${yellow("!")} ${tool.name}: using old name "context-mcp"`,
         );
-        console.log(
-          `    ${dim("Fix: run context-vault setup to update")}`,
-        );
+        console.log(`    ${dim("Fix: run context-vault setup to update")}`);
         anyToolConfigured = true;
       }
     } catch {
@@ -3979,9 +4078,7 @@ async function runDoctor() {
   }
 
   if (!anyToolConfigured) {
-    console.log(
-      `  ${yellow("!")} No AI tools have context-vault configured`,
-    );
+    console.log(`  ${yellow("!")} No AI tools have context-vault configured`);
     console.log(`    ${dim("Fix: run context-vault setup")}`);
     allOk = false;
   }
@@ -4106,14 +4203,10 @@ async function runDoctor() {
 
       if (hookCount === 0) {
         console.log(`  ${dim("-")} No context-vault hooks installed`);
-        console.log(
-          `    ${dim("Optional: run context-vault hooks install")}`,
-        );
+        console.log(`    ${dim("Optional: run context-vault hooks install")}`);
       }
     } catch {
-      console.log(
-        `  ${yellow("!")} Could not read ${settingsPath}`,
-      );
+      console.log(`  ${yellow("!")} Could not read ${settingsPath}`);
     }
   } else {
     console.log(`  ${dim("-")} No Claude Code settings found`);
@@ -4465,7 +4558,7 @@ async function main() {
   }
 
   if (flags.has("--help") || command === "help") {
-    showHelp();
+    showHelp(flags.has("--all"));
     return;
   }
 
@@ -4537,6 +4630,9 @@ async function main() {
     case "reindex":
       await runReindex();
       break;
+    case "migrate-dirs":
+      await runMigrateDirs();
+      break;
     case "prune":
       await runPrune();
       break;

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

@@ -1,6 +1,6 @@
 {
   "name": "@context-vault/core",
-  "version": "2.17.0",
+  "version": "2.17.1",
   "type": "module",
   "description": "Shared core: capture, index, retrieve, tools, and utilities for context-vault",
   "main": "src/index.js",
@@ -23,7 +23,7 @@
   ],
   "license": "MIT",
   "engines": {
-    "node": ">=24"
+    "node": ">=20"
   },
   "author": "Felix Hellstrom",
   "repository": {

package/node_modules/@context-vault/core/src/capture/file-ops.js

@@ -38,6 +38,7 @@ export function writeEntryFile(
     identity_key,
     expires_at,
     supersedes,
+    related_to,
   },
 ) {
   // P5: folder is now a top-level param; also accept from meta for backward compat
@@ -64,6 +65,7 @@ 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;
+  if (related_to?.length) fmFields.related_to = related_to;
   fmFields.tags = tags || [];
   fmFields.source = source || "claude-code";
   fmFields.created = created;

package/node_modules/@context-vault/core/src/capture/index.js

@@ -27,6 +27,7 @@ export function writeEntry(
     identity_key,
     expires_at,
     supersedes,
+    related_to,
     source_files,
     tier,
     userId,
@@ -88,6 +89,7 @@ export function writeEntry(
     identity_key,
     expires_at,
     supersedes,
+    related_to,
   });
 
   return {
@@ -105,6 +107,7 @@ export function writeEntry(
     identity_key,
     expires_at,
     supersedes,
+    related_to: related_to || null,
     source_files: source_files || null,
     tier: tier || null,
     userId: userId || null,
@@ -126,6 +129,9 @@ export function updateEntryFile(ctx, existing, updates) {
 
   const existingMeta = existing.meta ? JSON.parse(existing.meta) : {};
   const existingTags = existing.tags ? JSON.parse(existing.tags) : [];
+  const existingRelatedTo = existing.related_to
+    ? JSON.parse(existing.related_to)
+    : fmMeta.related_to || null;
 
   const title = updates.title !== undefined ? updates.title : existing.title;
   const body = updates.body !== undefined ? updates.body : existing.body;
@@ -138,6 +144,8 @@ export function updateEntryFile(ctx, existing, updates) {
     updates.supersedes !== undefined
       ? updates.supersedes
       : fmMeta.supersedes || null;
+  const related_to =
+    updates.related_to !== undefined ? updates.related_to : existingRelatedTo;
   const source_files =
     updates.source_files !== undefined
       ? updates.source_files
@@ -162,6 +170,7 @@ 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;
+  if (related_to?.length) fmFields.related_to = related_to;
   fmFields.tags = tags;
   fmFields.source = source || "claude-code";
   fmFields.created = fmMeta.created || existing.created_at;
@@ -189,6 +198,7 @@ export function updateEntryFile(ctx, existing, updates) {
     identity_key: existing.identity_key,
     expires_at,
     supersedes,
+    related_to: related_to || null,
     source_files: source_files || null,
     userId: existing.user_id || null,
   };
@@ -217,6 +227,10 @@ export async function captureAndIndex(ctx, data) {
         }
       }
     }
+    // Store related_to links in DB
+    if (entry.related_to?.length && ctx.stmts.updateRelatedTo) {
+      ctx.stmts.updateRelatedTo.run(JSON.stringify(entry.related_to), entry.id);
+    }
     return entry;
   } catch (err) {
     // Rollback: restore previous content for entity upserts, delete for new entries

package/node_modules/@context-vault/core/src/core/categories.js

@@ -23,6 +23,7 @@ const KIND_CATEGORY = {
   source: "entity",
   bucket: "entity",
   // Event — append-only, decaying
+  event: "event",
   conversation: "event",
   message: "event",
   session: "event",

package/node_modules/@context-vault/core/src/core/files.js

@@ -37,42 +37,19 @@ export function slugify(text, maxLen = 60) {
   return slug;
 }
 
-const PLURAL_MAP = {
-  insight: "insights",
-  decision: "decisions",
-  pattern: "patterns",
-  status: "statuses",
-  analysis: "analyses",
-  contact: "contacts",
-  project: "projects",
-  tool: "tools",
-  source: "sources",
-  conversation: "conversations",
-  message: "messages",
-  session: "sessions",
-  log: "logs",
-  feedback: "feedbacks",
-};
-
-const SINGULAR_MAP = Object.fromEntries(
-  Object.entries(PLURAL_MAP).map(([k, v]) => [v, k]),
-);
-
+/** Map kind name to its directory name. Kind names are used as-is (no pluralization). */
 export function kindToDir(kind) {
-  if (PLURAL_MAP[kind]) return PLURAL_MAP[kind];
-  return kind.endsWith("s") ? kind : kind + "s";
+  return kind;
 }
 
+/** Map directory name back to kind name. Directory names equal kind names (identity). */
 export function dirToKind(dirName) {
-  if (SINGULAR_MAP[dirName]) return SINGULAR_MAP[dirName];
-  return dirName.replace(/s$/, "");
+  return dirName;
 }
 
-/** Normalize a kind input (singular or plural) to its canonical singular form. */
+/** Normalize a kind input to its canonical form. Kind names are returned as-is. */
 export function normalizeKind(input) {
-  if (PLURAL_MAP[input]) return input; // Already a known singular kind
-  if (SINGULAR_MAP[input]) return SINGULAR_MAP[input]; // Known plural → singular
-  return input; // Unknown — use as-is (don't strip 's')
+  return input;
 }
 
 /** Returns relative path from vault root → kind dir: "knowledge/insights", "events/sessions", etc. */

package/node_modules/@context-vault/core/src/core/frontmatter.js

@@ -69,6 +69,7 @@ const RESERVED_FM_KEYS = new Set([
   "identity_key",
   "expires_at",
   "supersedes",
+  "related_to",
 ]);
 
 export function extractCustomMeta(fmMeta) {

package/node_modules/@context-vault/core/src/core/linking.js

@@ -0,0 +1,161 @@
+/**
+ * linking.js — Pure graph traversal for related_to links.
+ *
+ * All functions accept a db handle and return data — no side effects.
+ * The calling layer (get-context handler) is responsible for I/O wiring.
+ */
+
+/**
+ * Parse a `related_to` JSON string from the DB into an array of ID strings.
+ * Returns an empty array on any parse failure or null input.
+ *
+ * @param {string|null|undefined} raw
+ * @returns {string[]}
+ */
+export function parseRelatedTo(raw) {
+  if (!raw) return [];
+  try {
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed)) return [];
+    return parsed.filter((id) => typeof id === "string" && id.trim());
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Fetch vault entries by their IDs, scoped to a user.
+ * Returns only entries that exist and are not expired or superseded.
+ *
+ * @param {import('node:sqlite').DatabaseSync} db
+ * @param {string[]} ids
+ * @param {string|null|undefined} userId
+ * @returns {object[]} Matching DB rows
+ */
+export function resolveLinks(db, ids, userId) {
+  if (!ids.length) return [];
+  const unique = [...new Set(ids)];
+  const placeholders = unique.map(() => "?").join(",");
+  // When userId is defined (hosted mode), scope to that user.
+  // When userId is undefined (local mode), no user scoping — all entries accessible.
+  const userClause =
+    userId !== undefined && userId !== null ? "AND user_id = ?" : "";
+  const params =
+    userId !== undefined && userId !== null ? [...unique, userId] : unique;
+  try {
+    return db
+      .prepare(
+        `SELECT * FROM vault
+         WHERE id IN (${placeholders})
+           ${userClause}
+           AND (expires_at IS NULL OR expires_at > datetime('now'))
+           AND superseded_by IS NULL`,
+      )
+      .all(...params);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Find all entries that declare `entryId` in their `related_to` field
+ * (i.e. entries that point *to* this entry — backlinks).
+ * Scoped to the same user. Excludes expired and superseded entries.
+ *
+ * @param {import('node:sqlite').DatabaseSync} db
+ * @param {string} entryId
+ * @param {string|null|undefined} userId
+ * @returns {object[]} Entries with a backlink to entryId
+ */
+export function resolveBacklinks(db, entryId, userId) {
+  if (!entryId) return [];
+  // When userId is defined (hosted mode), scope to that user.
+  // When userId is undefined (local mode), no user scoping — all entries accessible.
+  const userClause =
+    userId !== undefined && userId !== null ? "AND user_id = ?" : "";
+  const likePattern = `%"${entryId}"%`;
+  const params =
+    userId !== undefined && userId !== null
+      ? [likePattern, userId]
+      : [likePattern];
+  try {
+    return db
+      .prepare(
+        `SELECT * FROM vault
+         WHERE related_to LIKE ?
+           ${userClause}
+           AND (expires_at IS NULL OR expires_at > datetime('now'))
+           AND superseded_by IS NULL`,
+      )
+      .all(...params);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * For a set of primary entry IDs, collect all forward links (entries pointed
+ * to by `related_to`) and backlinks (entries that point back to any primary).
+ *
+ * Returns a Map of id → entry row for all linked entries, excluding entries
+ * already present in `primaryIds`.
+ *
+ * @param {import('node:sqlite').DatabaseSync} db
+ * @param {object[]} primaryEntries - Full entry rows (must have id + related_to fields)
+ * @param {string|null|undefined} userId
+ * @returns {{ forward: object[], backward: object[] }}
+ */
+export function collectLinkedEntries(db, primaryEntries, userId) {
+  const primaryIds = new Set(primaryEntries.map((e) => e.id));
+
+  // Forward: resolve all IDs from related_to fields
+  const forwardIds = [];
+  for (const entry of primaryEntries) {
+    const ids = parseRelatedTo(entry.related_to);
+    for (const id of ids) {
+      if (!primaryIds.has(id)) forwardIds.push(id);
+    }
+  }
+  const forwardEntries = resolveLinks(db, forwardIds, userId).filter(
+    (e) => !primaryIds.has(e.id),
+  );
+
+  // Backward: find all entries that link to any primary entry
+  const backwardSeen = new Set();
+  const backwardEntries = [];
+  const forwardIds2 = new Set(forwardEntries.map((e) => e.id));
+  for (const entry of primaryEntries) {
+    const backlinks = resolveBacklinks(db, entry.id, userId);
+    for (const bl of backlinks) {
+      if (!primaryIds.has(bl.id) && !backwardSeen.has(bl.id)) {
+        backwardSeen.add(bl.id);
+        backwardEntries.push(bl);
+      }
+    }
+  }
+
+  return { forward: forwardEntries, backward: backwardEntries };
+}
+
+/**
+ * Validate a `related_to` value from user input.
+ * Must be an array of non-empty strings (ULID-like IDs).
+ * Returns an error message string if invalid, or null if valid.
+ *
+ * @param {unknown} relatedTo
+ * @returns {string|null}
+ */
+export function validateRelatedTo(relatedTo) {
+  if (relatedTo === undefined || relatedTo === null) return null;
+  if (!Array.isArray(relatedTo))
+    return "related_to must be an array of entry IDs";
+  for (const id of relatedTo) {
+    if (typeof id !== "string" || !id.trim()) {
+      return "each related_to entry must be a non-empty string ID";
+    }
+    if (id.length > 32) {
+      return `related_to ID too long (max 32 chars): "${id.slice(0, 32)}..."`;
+    }
+  }
+  return null;
+}