@context-vault/core 2.15.0 → 2.17.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@context-vault/core",
-  "version": "2.15.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": {
@@ -36,7 +36,6 @@
     "access": "public"
   },
   "dependencies": {
-    "@anthropic-ai/sdk": "^0.78.0",
     "@modelcontextprotocol/sdk": "^1.26.0",
     "sqlite-vec": "^0.1.0"
   },

package/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/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/src/constants.js

@@ -14,8 +14,13 @@ 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 },
+  totalEntries: { warn: 2000, critical: 5000 },
+  eventEntries: { warn: 1000, critical: 3000 },
   vaultSizeBytes: { warn: 50 * 1024 * 1024, critical: 200 * 1024 * 1024 },
   eventsWithoutTtl: { warn: 200 },
 };
+
+export const DEFAULT_LIFECYCLE = {
+  event: { archiveAfterDays: 90 },
+  ephemeral: { archiveAfterDays: 30 },
+};

package/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/src/core/config.js

@@ -1,7 +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";
+import { DEFAULT_GROWTH_THRESHOLDS, DEFAULT_LIFECYCLE } from "../constants.js";
 
 export function parseArgs(argv) {
   const args = {};
@@ -27,7 +27,7 @@ export function resolveConfig() {
       join(HOME, ".context-mcp"),
   );
   const config = {
-    vaultDir: join(HOME, "vault"),
+    vaultDir: join(HOME, ".vault"),
     dataDir,
     dbPath: join(dataDir, "vault.db"),
     devDir: join(HOME, "dev"),
@@ -48,6 +48,7 @@ export function resolveConfig() {
       maxAgeDays: 7,
       autoConsolidate: false,
     },
+    lifecycle: structuredClone(DEFAULT_LIFECYCLE),
   };
 
   const configPath = join(dataDir, "config.json");
@@ -62,6 +63,12 @@ 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.growthWarningThreshold != null) {
+        config.thresholds.totalEntries = {
+          ...config.thresholds.totalEntries,
+          warn: Number(fc.growthWarningThreshold),
+        };
+      }
       if (fc.thresholds) {
         const t = fc.thresholds;
         if (t.totalEntries)

package/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/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/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;
+}

package/src/core/migrate-dirs.js

@@ -0,0 +1,196 @@
+/**
+ * migrate-dirs.js — Rename plural vault directories to singular
+ *
+ * After context-vault >= 2.18.0, kindToDir() returns singular names.
+ * Existing vaults still have plural dirs (e.g. knowledge/decisions/).
+ * This module plans and executes the rename/merge migration.
+ *
+ * Architecture: pure planning function + I/O execution function.
+ */
+
+import {
+  existsSync,
+  readdirSync,
+  mkdirSync,
+  renameSync,
+  copyFileSync,
+  rmSync,
+  statSync,
+} from "node:fs";
+import { join, basename } from "node:path";
+
+/**
+ * Complete plural→singular mapping for vault directory names.
+ * Covers the old PLURAL_MAP from files.js plus extended kinds seen in the wild.
+ *
+ * @type {Record<string, string>}
+ */
+export const PLURAL_TO_SINGULAR = {
+  // From old PLURAL_MAP in files.js
+  insights: "insight",
+  decisions: "decision",
+  patterns: "pattern",
+  statuses: "status",
+  analyses: "analysis",
+  contacts: "contact",
+  projects: "project",
+  tools: "tool",
+  sources: "source",
+  conversations: "conversation",
+  messages: "message",
+  sessions: "session",
+  logs: "log",
+  feedbacks: "feedback",
+  // Extended kinds from categories.js + observed in vaults
+  notes: "note",
+  prompts: "prompt",
+  documents: "document",
+  references: "reference",
+  tasks: "task",
+  buckets: "bucket",
+  architectures: "architecture",
+  briefs: "brief",
+  companies: "company",
+  discoveries: "discovery",
+  events: "event",
+  ideas: "idea",
+  issues: "issue",
+  agents: "agent",
+  "session-summaries": "session-summary",
+  "session-reviews": "session-review",
+  "user-prompts": "user-prompt",
+};
+
+/**
+ * Category directory names that are scanned for plural kind subdirectories.
+ */
+const CATEGORY_DIRS = ["knowledge", "entities", "events"];
+
+/**
+ * Count .md files recursively in a directory.
+ *
+ * @param {string} dir
+ * @returns {number}
+ */
+function countMdFiles(dir) {
+  let count = 0;
+  try {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      if (entry.isDirectory()) {
+        count += countMdFiles(join(dir, entry.name));
+      } else if (entry.isFile() && entry.name.endsWith(".md")) {
+        count++;
+      }
+    }
+  } catch {
+    // ignore unreadable dirs
+  }
+  return count;
+}
+
+/**
+ * Plan migration operations: walk the vault and detect plural dirs that need renaming.
+ * Pure I/O read-only — does not modify any files.
+ *
+ * @param {string} vaultDir - Absolute path to vault root
+ * @returns {MigrationOp[]} Array of planned operations
+ *
+ * @typedef {{ action: 'rename'|'merge', pluralDir: string, singularDir: string, pluralName: string, singularName: string, fileCount: number }} MigrationOp
+ */
+export function planMigration(vaultDir) {
+  const ops = [];
+
+  for (const catName of CATEGORY_DIRS) {
+    const catDir = join(vaultDir, catName);
+    if (!existsSync(catDir) || !statSync(catDir).isDirectory()) continue;
+
+    let entries;
+    try {
+      entries = readdirSync(catDir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      const dirName = entry.name;
+      const singular = PLURAL_TO_SINGULAR[dirName];
+
+      // Not a known plural — skip (might already be singular or unknown kind)
+      if (!singular) continue;
+
+      const pluralDir = join(catDir, dirName);
+      const singularDir = join(catDir, singular);
+
+      // Guard: plural and singular are the same (shouldn't happen but be safe)
+      if (pluralDir === singularDir) continue;
+
+      const fileCount = countMdFiles(pluralDir);
+      const singularExists = existsSync(singularDir);
+
+      ops.push({
+        action: singularExists ? "merge" : "rename",
+        pluralDir,
+        singularDir,
+        pluralName: dirName,
+        singularName: singular,
+        fileCount,
+      });
+    }
+  }
+
+  return ops;
+}
+
+/**
+ * Copy all files and subdirectories from src into dst (non-overwriting).
+ * Mirrors `cp -rn src/* dst/`.
+ *
+ * @param {string} src
+ * @param {string} dst
+ */
+function mergeDir(src, dst) {
+  mkdirSync(dst, { recursive: true });
+  for (const entry of readdirSync(src, { withFileTypes: true })) {
+    const srcPath = join(src, entry.name);
+    const dstPath = join(dst, entry.name);
+    if (entry.isDirectory()) {
+      mergeDir(srcPath, dstPath);
+    } else if (entry.isFile()) {
+      if (!existsSync(dstPath)) {
+        copyFileSync(srcPath, dstPath);
+      }
+    }
+  }
+}
+
+/**
+ * Execute migration operations. Renames or merges plural dirs into singular dirs.
+ * Safe to call multiple times — already-renamed dirs produce no-op ops from planMigration.
+ *
+ * @param {MigrationOp[]} ops - Operations from planMigration()
+ * @returns {{ renamed: number, merged: number, errors: string[] }}
+ */
+export function executeMigration(ops) {
+  let renamed = 0;
+  let merged = 0;
+  const errors = [];
+
+  for (const op of ops) {
+    try {
+      if (op.action === "rename") {
+        renameSync(op.pluralDir, op.singularDir);
+        renamed++;
+      } else {
+        // merge: copy files from plural into singular, then remove plural
+        mergeDir(op.pluralDir, op.singularDir);
+        rmSync(op.pluralDir, { recursive: true, force: true });
+        merged++;
+      }
+    } catch (e) {
+      errors.push(`${op.pluralName} → ${op.singularName}: ${e.message}`);
+    }
+  }
+
+  return { renamed, merged, errors };
+}

package/src/core/status.js

@@ -212,7 +212,7 @@ export function gatherVaultStatus(ctx, opts = {}) {
  *
  * @param {object} status — result of gatherVaultStatus()
  * @param {object} thresholds — from config.thresholds
- * @returns {{ warnings: Array, hasCritical: boolean, hasWarnings: boolean, actions: string[] }}
+ * @returns {{ warnings: Array, hasCritical: boolean, hasWarnings: boolean, actions: string[], kindBreakdown: Array }}
  */
 export function computeGrowthWarnings(status, thresholds) {
   if (!thresholds)
@@ -221,6 +221,7 @@ export function computeGrowthWarnings(status, thresholds) {
       hasCritical: false,
       hasWarnings: false,
       actions: [],
+      kindBreakdown: [],
     };
 
   const t = thresholds;
@@ -235,12 +236,16 @@ export function computeGrowthWarnings(status, thresholds) {
     dbSizeBytes = 0,
   } = status;
 
+  let totalExceeded = false;
+
   if (t.totalEntries?.critical != null && total >= t.totalEntries.critical) {
+    totalExceeded = true;
     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) {
+    totalExceeded = true;
     warnings.push({
       level: "warn",
       message: `Total entries: ${total.toLocaleString()} (exceeds recommended ${t.totalEntries.warn.toLocaleString()})`,
@@ -320,5 +325,26 @@ export function computeGrowthWarnings(status, thresholds) {
     actions.push("Consider archiving events older than 90 days");
   }
 
-  return { warnings, hasCritical, hasWarnings: warnings.length > 0, actions };
+  const kindBreakdown = totalExceeded
+    ? buildKindBreakdown(status.kindCounts, total)
+    : [];
+
+  return {
+    warnings,
+    hasCritical,
+    hasWarnings: warnings.length > 0,
+    actions,
+    kindBreakdown,
+  };
+}
+
+function buildKindBreakdown(kindCounts, total) {
+  if (!kindCounts?.length || total === 0) return [];
+  return [...kindCounts]
+    .sort((a, b) => b.c - a.c)
+    .map(({ kind, c }) => ({
+      kind,
+      count: c,
+      pct: Math.round((c / total) * 100),
+    }));
 }