context-vault 2.17.0 → 3.0.1

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

@@ -0,0 +1,285 @@
+import type { BaseCtx, SearchResult, SearchOptions, VaultEntry } from "./types.js";
+
+const NEAR_DUP_THRESHOLD = 0.92;
+const RRF_K = 60;
+
+export function recencyDecayScore(updatedAt: string | null | undefined, decayRate = 0.05): number {
+  if (updatedAt == null) return 0.5;
+  const ageDays = (Date.now() - new Date(updatedAt).getTime()) / 86400000;
+  return Math.exp(-decayRate * ageDays);
+}
+
+export function dotProduct(a: Float32Array, b: Float32Array): number {
+  let sum = 0;
+  for (let i = 0; i < a.length; i++) sum += a[i] * b[i];
+  return sum;
+}
+
+export function buildFtsQuery(query: string): string | null {
+  const words = query
+    .split(/[\s-]+/)
+    .map((w) => w.replace(/[*"():^~{}]/g, ""))
+    .filter((w) => w.length > 0);
+  if (!words.length) return null;
+  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}`;
+}
+
+export function recencyBoost(createdAt: string, category: string, decayDays = 30): number {
+  if (category !== "event") return 1.0;
+  const ageDays = (Date.now() - new Date(createdAt).getTime()) / 86400000;
+  return 1 / (1 + ageDays / decayDays);
+}
+
+export function buildFilterClauses({
+  categoryFilter,
+  excludeEvents = false,
+  since,
+  until,
+  includeSuperseeded = false,
+}: {
+  categoryFilter?: string | null;
+  excludeEvents?: boolean;
+  since?: string | null;
+  until?: string | null;
+  includeSuperseeded?: boolean;
+}): { clauses: string[]; params: unknown[] } {
+  const clauses: string[] = [];
+  const params: unknown[] = [];
+  if (categoryFilter) {
+    clauses.push("e.category = ?");
+    params.push(categoryFilter);
+  }
+  if (excludeEvents && !categoryFilter) {
+    clauses.push("e.category != 'event'");
+  }
+  if (since) {
+    clauses.push("e.created_at >= ?");
+    params.push(since);
+  }
+  if (until) {
+    clauses.push("e.created_at <= ?");
+    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 };
+}
+
+export function reciprocalRankFusion(
+  rankedLists: string[][],
+  k: number = RRF_K,
+): Map<string, number> {
+  const scores = new Map<string, number>();
+  for (const list of rankedLists) {
+    for (let rank = 0; rank < list.length; rank++) {
+      const id = list[rank];
+      scores.set(id, (scores.get(id) ?? 0) + 1 / (k + rank + 1));
+    }
+  }
+  return scores;
+}
+
+export async function hybridSearch(
+  ctx: BaseCtx,
+  query: string,
+  opts: SearchOptions = {},
+): Promise<SearchResult[]> {
+  const {
+    kindFilter = null,
+    categoryFilter = null,
+    excludeEvents = false,
+    since = null,
+    until = null,
+    limit = 20,
+    offset = 0,
+    decayDays = 30,
+    includeSuperseeded = false,
+  } = opts;
+
+  const rowMap = new Map<string, VaultEntry>();
+  const idToRowid = new Map<string, number>();
+  let queryVec: Float32Array | null = null;
+
+  const extraFilters = buildFilterClauses({
+    categoryFilter,
+    excludeEvents,
+    since,
+    until,
+    includeSuperseeded,
+  });
+
+  const ftsRankedIds: string[] = [];
+
+  const ftsQuery = buildFtsQuery(query);
+  if (ftsQuery) {
+    try {
+      const whereParts = ["vault_fts MATCH ?"];
+      const ftsParams: unknown[] = [ftsQuery];
+
+      if (kindFilter) {
+        whereParts.push("e.kind = ?");
+        ftsParams.push(kindFilter);
+      }
+      whereParts.push(...extraFilters.clauses);
+      ftsParams.push(...extraFilters.params);
+
+      const ftsSQL = `SELECT e.*, rank FROM vault_fts f JOIN vault e ON f.rowid = e.rowid WHERE ${whereParts.join(" AND ")} ORDER BY rank LIMIT 15`;
+      // @ts-expect-error -- node:sqlite types are overly strict for dynamic SQL params
+      const rows = ctx.db.prepare(ftsSQL).all(...ftsParams) as unknown as (VaultEntry & { rank: number })[];
+
+      for (const { rank: _rank, ...row } of rows) {
+        ftsRankedIds.push(row.id);
+        if (!rowMap.has(row.id)) rowMap.set(row.id, row);
+      }
+    } catch (err) {
+      if (!(err as Error).message?.includes("fts5: syntax error")) {
+        console.error(`[retrieve] FTS search error: ${(err as Error).message}`);
+      }
+    }
+  }
+
+  const vecRankedIds: string[] = [];
+  const vecSimMap = new Map<string, number>();
+
+  try {
+    const vecCount = (ctx.db.prepare("SELECT COUNT(*) as c FROM vault_vec").get() as { c: number }).c;
+    if (vecCount > 0) {
+      queryVec = await ctx.embed(query);
+      if (queryVec) {
+        const vecLimit = kindFilter ? 30 : 15;
+        const vecRows = ctx.db
+          .prepare(
+            `SELECT v.rowid, v.distance FROM vault_vec v WHERE embedding MATCH ? ORDER BY distance LIMIT ?`,
+          )
+          .all(queryVec, vecLimit) as { rowid: number; distance: number }[];
+
+        if (vecRows.length) {
+          const rowids = vecRows.map((vr) => vr.rowid);
+          const placeholders = rowids.map(() => "?").join(",");
+          const hydrated = ctx.db
+            .prepare(
+              `SELECT rowid, * FROM vault WHERE rowid IN (${placeholders})`,
+            )
+            .all(...rowids) as unknown as (VaultEntry & { rowid: number })[];
+
+          const byRowid = new Map<number, VaultEntry & { rowid: number }>();
+          for (const row of hydrated) byRowid.set(row.rowid, row);
+
+          for (const vr of vecRows) {
+            const row = byRowid.get(vr.rowid);
+            if (!row) continue;
+            if (kindFilter && row.kind !== kindFilter) continue;
+            if (categoryFilter && row.category !== categoryFilter) continue;
+            if (excludeEvents && row.category === "event") continue;
+            if (since && row.created_at < since) continue;
+            if (until && row.created_at > until) continue;
+            if (row.expires_at && new Date(row.expires_at) <= new Date())
+              continue;
+
+            const { rowid: _rowid, ...cleanRow } = row;
+            idToRowid.set(cleanRow.id, Number(row.rowid));
+
+            const vecSim = Math.max(0, 1 - vr.distance / 2);
+            vecSimMap.set(cleanRow.id, vecSim);
+            vecRankedIds.push(cleanRow.id);
+
+            if (!rowMap.has(cleanRow.id)) rowMap.set(cleanRow.id, cleanRow);
+          }
+        }
+      }
+    }
+  } catch (err) {
+    if (!(err as Error).message?.includes("no such table")) {
+      console.error(`[retrieve] Vector search error: ${(err as Error).message}`);
+    }
+  }
+
+  if (rowMap.size === 0) return [];
+
+  const rrfScores = reciprocalRankFusion([ftsRankedIds, vecRankedIds]);
+
+  for (const [id, entry] of rowMap) {
+    const boost = recencyBoost(entry.created_at, entry.category, decayDays);
+    rrfScores.set(id, (rrfScores.get(id) ?? 0) * boost);
+  }
+
+  const candidates: SearchResult[] = [...rowMap.values()].map((entry) => ({
+    ...entry,
+    score: rrfScores.get(entry.id) ?? 0,
+  }));
+  candidates.sort((a, b) => b.score - a.score);
+
+  const embeddingMap = new Map<string, Float32Array>();
+  if (queryVec && idToRowid.size > 0) {
+    const rowidToId = new Map<number, string>();
+    for (const [id, rowid] of idToRowid) rowidToId.set(rowid, id);
+
+    const rowidsToFetch = [...idToRowid.values()];
+    try {
+      const placeholders = rowidsToFetch.map(() => "?").join(",");
+      const vecData = ctx.db
+        .prepare(
+          `SELECT rowid, embedding FROM vault_vec WHERE rowid IN (${placeholders})`,
+        )
+        .all(...rowidsToFetch) as { rowid: number; embedding: Buffer }[];
+      for (const row of vecData) {
+        const id = rowidToId.get(Number(row.rowid));
+        const buf = row.embedding;
+        if (id && buf) {
+          embeddingMap.set(
+            id,
+            new Float32Array(buf.buffer, buf.byteOffset, buf.byteLength / 4),
+          );
+        }
+      }
+    } catch {
+      // Embeddings unavailable
+    }
+  }
+
+  if (queryVec && embeddingMap.size > 0) {
+    const selected: SearchResult[] = [];
+    const selectedVecs: Float32Array[] = [];
+    for (const candidate of candidates) {
+      if (selected.length >= offset + limit) break;
+      const vec = embeddingMap.get(candidate.id);
+      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);
+    }
+    const dedupedPage = selected.slice(offset, offset + limit);
+    trackAccess(ctx, dedupedPage);
+    return dedupedPage;
+  }
+
+  const finalPage = candidates.slice(offset, offset + limit);
+  trackAccess(ctx, finalPage);
+  return finalPage;
+}
+
+function trackAccess(ctx: BaseCtx, entries: SearchResult[]): void {
+  if (!entries.length) return;
+  try {
+    const placeholders = entries.map(() => "?").join(",");
+    ctx.db
+      .prepare(
+        `UPDATE vault SET hit_count = hit_count + 1, last_accessed_at = datetime('now') WHERE id IN (${placeholders})`,
+      )
+      .run(...entries.map((e) => e.id));
+  } catch {
+    // Non-fatal
+  }
+}

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

@@ -0,0 +1,166 @@
+import type { DatabaseSync, StatementSync } from "node:sqlite";
+
+export interface VaultConfig {
+  vaultDir: string;
+  dataDir: string;
+  dbPath: string;
+  devDir: string;
+  eventDecayDays: number;
+  thresholds: GrowthThresholds;
+  telemetry: boolean;
+  resolvedFrom: string;
+  configPath?: string;
+  vaultDirExists?: boolean;
+  recall: RecallConfig;
+  consolidation: ConsolidationConfig;
+  lifecycle: Record<string, { archiveAfterDays?: number }>;
+}
+
+export interface RecallConfig {
+  maxResults: number;
+  maxOutputBytes: number;
+  minRelevanceScore: number;
+  excludeKinds: string[];
+  excludeCategories: string[];
+  bodyTruncateChars: number;
+}
+
+export interface ConsolidationConfig {
+  tagThreshold: number;
+  maxAgeDays: number;
+  autoConsolidate: boolean;
+}
+
+export interface GrowthThresholds {
+  totalEntries: { warn: number; critical: number };
+  eventEntries: { warn: number; critical: number };
+  vaultSizeBytes: { warn: number; critical: number };
+  eventsWithoutTtl: { warn: number };
+}
+
+export interface PreparedStatements {
+  insertEntry: StatementSync;
+  updateEntry: StatementSync;
+  deleteEntry: StatementSync;
+  getRowid: StatementSync;
+  getRowidByPath: StatementSync;
+  getEntryById: StatementSync;
+  getByIdentityKey: StatementSync;
+  upsertByIdentityKey: StatementSync;
+  updateSourceFiles: StatementSync;
+  updateRelatedTo: StatementSync;
+  insertVecStmt: StatementSync;
+  deleteVecStmt: StatementSync;
+  updateSupersededBy: StatementSync;
+  clearSupersededByRef: StatementSync;
+}
+
+export interface VaultEntry {
+  id: string;
+  kind: string;
+  category: string;
+  title: string | null;
+  body: string;
+  meta: string | null;
+  tags: string | null;
+  source: string | null;
+  file_path: string | null;
+  identity_key: string | null;
+  expires_at: string | null;
+  superseded_by: string | null;
+  created_at: string;
+  updated_at: string | null;
+  hit_count: number;
+  last_accessed_at: string | null;
+  source_files: string | null;
+  tier: string;
+  related_to: string | null;
+  rowid?: number;
+}
+
+export interface SearchResult extends VaultEntry {
+  score: number;
+  stale?: boolean;
+  stale_reason?: string;
+}
+
+export interface CaptureInput {
+  kind: string;
+  title?: string | null;
+  body: string;
+  meta?: Record<string, unknown> | null;
+  tags?: string[] | null;
+  source?: string | null;
+  folder?: string | null;
+  identity_key?: string | null;
+  expires_at?: string | null;
+  supersedes?: string[] | null;
+  related_to?: string[] | null;
+  source_files?: Array<{ path: string; hash: string }> | null;
+  tier?: string | null;
+}
+
+export interface CaptureResult {
+  id: string;
+  filePath: string;
+  kind: string;
+  category: string;
+  title: string | null;
+  body: string;
+  meta: Record<string, unknown> | undefined;
+  tags: string[] | null;
+  source: string | null;
+  createdAt: string;
+  updatedAt: string;
+  identity_key: string | null;
+  expires_at: string | null;
+  supersedes: string[] | null;
+  related_to: string[] | null;
+  source_files: Array<{ path: string; hash: string }> | null;
+  tier: string | null;
+}
+
+export interface IndexEntryInput {
+  id: string;
+  kind: string;
+  category: string;
+  title: string | null;
+  body: string;
+  meta: Record<string, unknown> | undefined;
+  tags: string[] | null;
+  source: string | null;
+  filePath: string;
+  createdAt: string;
+  identity_key: string | null;
+  expires_at: string | null;
+  source_files: Array<{ path: string; hash: string }> | null;
+  tier: string | null;
+}
+
+export interface ReindexStats {
+  added: number;
+  updated: number;
+  removed: number;
+  unchanged: number;
+}
+
+export interface BaseCtx {
+  db: DatabaseSync;
+  config: VaultConfig;
+  stmts: PreparedStatements;
+  embed: (text: string) => Promise<Float32Array | null>;
+  insertVec: (rowid: number, embedding: Float32Array) => void;
+  deleteVec: (rowid: number) => void;
+}
+
+export interface SearchOptions {
+  kindFilter?: string | null;
+  categoryFilter?: string | null;
+  excludeEvents?: boolean;
+  since?: string | null;
+  until?: string | null;
+  limit?: number;
+  offset?: number;
+  decayDays?: number;
+  includeSuperseeded?: boolean;
+}

package/package.json

@@ -1,15 +1,16 @@
 {
   "name": "context-vault",
-  "version": "2.17.0",
+  "version": "3.0.1",
   "type": "module",
   "description": "Persistent memory for AI agents — saves and searches knowledge across sessions",
   "bin": {
     "context-vault": "bin/cli.js",
-    "context-mcp": "bin/cli.js"
+    "context-mcp": "bin/cli.js",
+    "memory": "bin/cli.js"
   },
-  "main": "src/server/index.js",
+  "main": "src/server.js",
   "exports": {
-    ".": "./src/server/index.js",
+    ".": "./src/server.js",
     "./cli": "./bin/cli.js"
   },
   "scripts": {
@@ -26,7 +27,7 @@
   ],
   "license": "MIT",
   "engines": {
-    "node": ">=24"
+    "node": ">=22"
   },
   "author": "Felix Hellstrom",
   "repository": {
@@ -56,8 +57,12 @@
     "@context-vault/core"
   ],
   "dependencies": {
-    "@context-vault/core": "^2.17.0",
+    "@context-vault/core": "^3.0.0",
     "@modelcontextprotocol/sdk": "^1.26.0",
+    "adm-zip": "^0.5.16",
     "sqlite-vec": "^0.1.0"
-  }
+  },
+  "bundleDependencies": [
+    "@context-vault/core"
+  ]
 }

package/scripts/postinstall.js

@@ -56,7 +56,7 @@ async function main() {
   // `npx context-vault serve` instead, so skip writing the launcher.
   const isNpx = PKG_ROOT.includes("/_npx/") || PKG_ROOT.includes("\\_npx\\");
   if (!isNpx) {
-    const SERVER_ABS = join(PKG_ROOT, "src", "server", "index.js");
+    const SERVER_ABS = join(PKG_ROOT, "src", "server.js");
     const DATA_DIR = join(homedir(), ".context-mcp");
     const LAUNCHER = join(DATA_DIR, "server.mjs");
     mkdirSync(DATA_DIR, { recursive: true });

package/{node_modules/@context-vault/core/src/core → src}/error-log.js

@@ -8,20 +8,12 @@ import {
 } from "node:fs";
 import { join } from "node:path";
 
-const MAX_LOG_SIZE = 1024 * 1024; // 1MB
+const MAX_LOG_SIZE = 1024 * 1024;
 
 export function errorLogPath(dataDir) {
   return join(dataDir, "error.log");
 }
 
-/**
- * Append a structured JSON entry to the startup error log.
- * Rotates the file if it exceeds MAX_LOG_SIZE.
- * Never throws — logging failures must not mask the original error.
- *
- * @param {string} dataDir
- * @param {object} entry
- */
 export function appendErrorLog(dataDir, entry) {
   try {
     mkdirSync(dataDir, { recursive: true });
@@ -35,12 +27,6 @@ export function appendErrorLog(dataDir, entry) {
   }
 }
 
-/**
- * Return number of log lines in the error log, or 0 if absent.
- *
- * @param {string} dataDir
- * @returns {number}
- */
 export function errorLogCount(dataDir) {
   try {
     const logPath = errorLogPath(dataDir);

package/{node_modules/@context-vault/core/src/server → src}/helpers.js

@@ -1,8 +1,11 @@
-/**
- * helpers.js — Shared MCP response helpers and validation
- */
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
 
-import pkg from "../../package.json" with { type: "json" };
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(
+  readFileSync(join(__dirname, "..", "..", "package.json"), "utf-8"),
+);
 
 export function ok(text) {
   return { content: [{ type: "text", text }] };
@@ -42,3 +45,5 @@ export function ensureValidKind(kind) {
   }
   return null;
 }
+
+export { pkg };

package/src/linking.js

@@ -0,0 +1,100 @@
+import type { DatabaseSync } from "node:sqlite";
+
+export function parseRelatedTo(raw: string | null | undefined): string[] {
+  if (!raw) return [];
+  try {
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed)) return [];
+    return parsed.filter((id: unknown) => typeof id === "string" && (id as string).trim());
+  } catch {
+    return [];
+  }
+}
+
+export function resolveLinks(
+  db: DatabaseSync,
+  ids: string[],
+): Record<string, unknown>[] {
+  if (!ids.length) return [];
+  const unique = [...new Set(ids)];
+  const placeholders = unique.map(() => "?").join(",");
+  try {
+    return db
+      .prepare(
+        `SELECT * FROM vault
+         WHERE id IN (${placeholders})
+           AND (expires_at IS NULL OR expires_at > datetime('now'))
+           AND superseded_by IS NULL`,
+      )
+      .all(...unique) as unknown as Record<string, unknown>[];
+  } catch {
+    return [];
+  }
+}
+
+export function resolveBacklinks(
+  db: DatabaseSync,
+  entryId: string,
+): Record<string, unknown>[] {
+  if (!entryId) return [];
+  const likePattern = `%"${entryId}"%`;
+  try {
+    return db
+      .prepare(
+        `SELECT * FROM vault
+         WHERE related_to LIKE ?
+           AND (expires_at IS NULL OR expires_at > datetime('now'))
+           AND superseded_by IS NULL`,
+      )
+      .all(likePattern) as unknown as Record<string, unknown>[];
+  } catch {
+    return [];
+  }
+}
+
+export function collectLinkedEntries(
+  db: DatabaseSync,
+  primaryEntries: Record<string, unknown>[],
+): { forward: Record<string, unknown>[]; backward: Record<string, unknown>[] } {
+  const primaryIds = new Set(primaryEntries.map((e) => e.id as string));
+
+  const forwardIds: string[] = [];
+  for (const entry of primaryEntries) {
+    const ids = parseRelatedTo(entry.related_to as string);
+    for (const id of ids) {
+      if (!primaryIds.has(id)) forwardIds.push(id);
+    }
+  }
+  const forwardEntries = resolveLinks(db, forwardIds).filter(
+    (e) => !primaryIds.has(e.id as string),
+  );
+
+  const backwardSeen = new Set<string>();
+  const backwardEntries: Record<string, unknown>[] = [];
+  for (const entry of primaryEntries) {
+    const backlinks = resolveBacklinks(db, entry.id as string);
+    for (const bl of backlinks) {
+      if (!primaryIds.has(bl.id as string) && !backwardSeen.has(bl.id as string)) {
+        backwardSeen.add(bl.id as string);
+        backwardEntries.push(bl);
+      }
+    }
+  }
+
+  return { forward: forwardEntries, backward: backwardEntries };
+}
+
+export function validateRelatedTo(relatedTo: unknown): string | null {
+  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;
+}