context-vault 2.17.0 → 2.17.1

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

@@ -66,37 +66,53 @@ export async function indexEntry(
   const cat = category || categoryFor(kind);
   const effectiveTier = tier || defaultTierFor(kind);
   const userIdVal = userId || null;
+  const isLocal = ctx.stmts._mode === "local";
 
   let wasUpdate = false;
 
-  // Entity upsert: check by (kind, identity_key, user_id) first
+  // Entity upsert: check by (kind, identity_key[, user_id]) first.
+  // Local mode omits user_id — all entries are user-agnostic.
   if (cat === "entity" && identity_key) {
-    const existing = ctx.stmts.getByIdentityKey.get(
-      kind,
-      identity_key,
-      userIdVal,
-    );
+    const existing = isLocal
+      ? ctx.stmts.getByIdentityKey.get(kind, identity_key)
+      : ctx.stmts.getByIdentityKey.get(kind, identity_key, userIdVal);
     if (existing) {
-      ctx.stmts.upsertByIdentityKey.run(
-        title || null,
-        body,
-        metaJson,
-        tagsJson,
-        source || "claude-code",
-        cat,
-        filePath,
-        expires_at || null,
-        sourceFilesJson,
-        kind,
-        identity_key,
-        userIdVal,
-      );
+      if (isLocal) {
+        ctx.stmts.upsertByIdentityKey.run(
+          title || null,
+          body,
+          metaJson,
+          tagsJson,
+          source || "claude-code",
+          cat,
+          filePath,
+          expires_at || null,
+          sourceFilesJson,
+          kind,
+          identity_key,
+        );
+      } else {
+        ctx.stmts.upsertByIdentityKey.run(
+          title || null,
+          body,
+          metaJson,
+          tagsJson,
+          source || "claude-code",
+          cat,
+          filePath,
+          expires_at || null,
+          sourceFilesJson,
+          kind,
+          identity_key,
+          userIdVal,
+        );
+      }
       wasUpdate = true;
     }
   }
 
   if (!wasUpdate) {
-    // Prepare encryption if ctx.encrypt is available
+    // Prepare encryption if ctx.encrypt is available (hosted mode only)
     let encrypted = null;
     if (ctx.encrypt) {
       encrypted = await ctx.encrypt({ title, body, meta });
@@ -104,7 +120,8 @@ export async function indexEntry(
 
     try {
       if (encrypted) {
-        // Encrypted insert: store preview in body column for FTS, full content in encrypted columns
+        // Hosted-mode encrypted insert: store preview in body for FTS,
+        // full content in encrypted columns.
         const bodyPreview = body.slice(0, 200);
         ctx.stmts.insertEntryEncrypted.run(
           id,
@@ -128,7 +145,27 @@ export async function indexEntry(
           sourceFilesJson,
           effectiveTier,
         );
+      } else if (isLocal) {
+        // Local mode: no user_id column — 15 params.
+        ctx.stmts.insertEntry.run(
+          id,
+          kind,
+          cat,
+          title || null,
+          body,
+          metaJson,
+          tagsJson,
+          source || "claude-code",
+          filePath,
+          identity_key || null,
+          expires_at || null,
+          createdAt,
+          createdAt,
+          sourceFilesJson,
+          effectiveTier,
+        );
       } else {
+        // Hosted mode without encryption: 16 params (includes user_id).
         ctx.stmts.insertEntry.run(
           id,
           userIdVal,
@@ -262,10 +299,14 @@ export async function reindex(ctx, opts = {}) {
 
   if (!existsSync(ctx.config.vaultDir)) return stats;
 
-  // Use INSERT OR IGNORE for reindex — handles files with duplicate frontmatter IDs
-  // user_id is NULL for reindex (always local mode)
+  // Use INSERT OR IGNORE for reindex — handles files with duplicate frontmatter IDs.
+  // Local mode: no user_id column (15 params).
+  // Hosted mode: user_id is NULL for file-sourced entries (14 params, NULL literal).
+  const isLocalReindex = ctx.stmts._mode === "local";
   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, updated_at) VALUES (?, NULL, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    isLocalReindex
+      ? `INSERT OR IGNORE INTO vault (id, kind, category, title, body, meta, tags, source, file_path, identity_key, expires_at, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
+      : `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:
@@ -317,7 +358,7 @@ export async function reindex(ctx, opts = {}) {
       // P3: Fetch all mutable fields for change detection
       const dbRows = ctx.db
         .prepare(
-          "SELECT id, file_path, body, title, tags, meta FROM vault WHERE kind = ?",
+          "SELECT id, file_path, body, title, tags, meta, related_to FROM vault WHERE kind = ?",
         )
         .all(kind);
       const dbByPath = new Map(dbRows.map((r) => [r.file_path, r]));
@@ -343,6 +384,12 @@ export async function reindex(ctx, opts = {}) {
         // Extract identity_key and expires_at from frontmatter
         const identity_key = fmMeta.identity_key || null;
         const expires_at = fmMeta.expires_at || null;
+        const related_to = Array.isArray(fmMeta.related_to)
+          ? fmMeta.related_to
+          : null;
+        const relatedToJson = related_to?.length
+          ? JSON.stringify(related_to)
+          : null;
 
         // Derive folder from disk location (source of truth)
         const meta = { ...(parsed.meta || {}) };
@@ -372,6 +419,9 @@ export async function reindex(ctx, opts = {}) {
             fmMeta.updated || created,
           );
           if (result.changes > 0) {
+            if (relatedToJson && ctx.stmts.updateRelatedTo) {
+              ctx.stmts.updateRelatedTo.run(relatedToJson, id);
+            }
             if (category !== "event") {
               const rowidResult = ctx.stmts.getRowid.get(id);
               if (rowidResult?.rowid) {
@@ -396,8 +446,16 @@ export async function reindex(ctx, opts = {}) {
           const bodyChanged = existing.body !== parsed.body;
           const tagsChanged = tagsJson !== (existing.tags || null);
           const metaChanged = metaJson !== (existing.meta || null);
-
-          if (bodyChanged || titleChanged || tagsChanged || metaChanged) {
+          const relatedToChanged =
+            relatedToJson !== (existing.related_to || null);
+
+          if (
+            bodyChanged ||
+            titleChanged ||
+            tagsChanged ||
+            metaChanged ||
+            relatedToChanged
+          ) {
             ctx.stmts.updateEntry.run(
               parsed.title || null,
               parsed.body,
@@ -409,6 +467,9 @@ export async function reindex(ctx, opts = {}) {
               expires_at,
               filePath,
             );
+            if (relatedToChanged && ctx.stmts.updateRelatedTo) {
+              ctx.stmts.updateRelatedTo.run(relatedToJson, existing.id);
+            }
 
             // Queue re-embed if title or body changed (vector ops deferred to Phase 2)
             if ((bodyChanged || titleChanged) && category !== "event") {

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

@@ -29,6 +29,11 @@ export {
   parseEntryFromMarkdown,
 } from "./core/frontmatter.js";
 export { gatherVaultStatus } from "./core/status.js";
+export {
+  PLURAL_TO_SINGULAR,
+  planMigration,
+  executeMigration,
+} from "./core/migrate-dirs.js";
 
 // Capture layer
 export {

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

@@ -11,8 +11,6 @@ const NEAR_DUP_THRESHOLD = 0.92;
 
 const RRF_K = 60;
 
-const MMR_LAMBDA = 0.7;
-
 /**
  * Exponential recency decay score based on updated_at timestamp.
  * Returns e^(-decayRate * ageDays) for valid dates, or 0.5 as a neutral
@@ -132,108 +130,16 @@ export function reciprocalRankFusion(rankedLists, k = RRF_K) {
   return scores;
 }
 
-/**
- * Jaccard similarity between two strings based on word sets.
- * Used as a fallback for MMR when embedding vectors are unavailable.
- *
- * @param {string} a
- * @param {string} b
- * @returns {number} Similarity in [0, 1].
- */
-export function jaccardSimilarity(a, b) {
-  const wordsA = new Set((a ?? "").toLowerCase().split(/\W+/).filter(Boolean));
-  const wordsB = new Set((b ?? "").toLowerCase().split(/\W+/).filter(Boolean));
-  if (wordsA.size === 0 && wordsB.size === 0) return 1;
-  if (wordsA.size === 0 || wordsB.size === 0) return 0;
-  let intersection = 0;
-  for (const w of wordsA) if (wordsB.has(w)) intersection++;
-  return intersection / (wordsA.size + wordsB.size - intersection);
-}
-
-/**
- * Maximal Marginal Relevance reranking.
- *
- * Selects up to n candidates that balance relevance to the query and
- * diversity from already-selected results.
- *
- * MMR_score = lambda * querySim(doc) - (1 - lambda) * max(sim(doc, selected))
- *
- * @param {Array<object>} candidates - Entries with at least {id, title, body}.
- * @param {Map<string, number>} querySimMap - Map of id -> relevance score.
- * @param {Map<string, Float32Array|null>} embeddingMap - Map of id -> embedding (null if unavailable).
- * @param {number} n - Number of results to select.
- * @param {number} lambda - Trade-off weight (default MMR_LAMBDA = 0.7).
- * @returns {Array<object>} Reranked subset of candidates (length <= n).
- */
-export function maximalMarginalRelevance(
-  candidates,
-  querySimMap,
-  embeddingMap,
-  n,
-  lambda = MMR_LAMBDA,
-) {
-  if (candidates.length === 0) return [];
-
-  const remaining = [...candidates];
-  const selected = [];
-  const selectedVecs = [];
-  const selectedEntries = [];
-
-  while (selected.length < n && remaining.length > 0) {
-    let bestIdx = -1;
-    let bestScore = -Infinity;
-
-    for (let i = 0; i < remaining.length; i++) {
-      const candidate = remaining[i];
-      const relevance = querySimMap.get(candidate.id) ?? 0;
-
-      let maxRedundancy = 0;
-      if (selectedVecs.length > 0) {
-        const vec = embeddingMap.get(candidate.id);
-        for (let j = 0; j < selectedVecs.length; j++) {
-          let sim;
-          if (vec && selectedVecs[j]) {
-            sim = dotProduct(vec, selectedVecs[j]);
-          } else {
-            const selEntry = selectedEntries[j];
-            sim = jaccardSimilarity(
-              `${candidate.title} ${candidate.body}`,
-              `${selEntry.title} ${selEntry.body}`,
-            );
-          }
-          if (sim > maxRedundancy) maxRedundancy = sim;
-        }
-      }
-
-      const score = lambda * relevance - (1 - lambda) * maxRedundancy;
-      if (score > bestScore) {
-        bestScore = score;
-        bestIdx = i;
-      }
-    }
-
-    if (bestIdx === -1) break;
-
-    const chosen = remaining.splice(bestIdx, 1)[0];
-    selected.push(chosen);
-    selectedVecs.push(embeddingMap.get(chosen.id) ?? null);
-    selectedEntries.push(chosen);
-  }
-
-  return selected;
-}
-
 /**
  * Hybrid search combining FTS5 text matching and vector similarity,
- * with RRF merging and MMR reranking for diversity.
+ * with RRF merging, recency decay, and near-duplicate suppression.
  *
  * Pipeline:
  *   1. FTS5 ranked list
  *   2. Vector (semantic) ranked list
  *   3. RRF: merge the two ranked lists into a single score
- *   4. Apply recency decay to RRF scores
- *   5. MMR: rerank top candidates for diversity (uses embeddings or Jaccard fallback)
- *   6. Near-duplicate suppression on the final selection
+ *   4. Recency decay: penalise old events (knowledge/entity entries unaffected)
+ *   5. Near-duplicate suppression (cosine similarity > 0.92 threshold)
  *
  * @param {import('../server/types.js').BaseCtx} ctx
  * @param {string} query
@@ -383,20 +289,6 @@ export async function hybridSearch(
     rrfScores.set(id, (rrfScores.get(id) ?? 0) * boost);
   }
 
-  // Stage 3b: Frequency signal — log(1 + hit_count) / log(1 + max_hit_count)
-  const allRows = [...rowMap.values()];
-  const maxHitCount = Math.max(...allRows.map((e) => e.hit_count || 0), 0);
-  if (maxHitCount > 0) {
-    const logMax = Math.log(1 + maxHitCount);
-    for (const entry of allRows) {
-      const freqScore = Math.log(1 + (entry.hit_count || 0)) / logMax;
-      rrfScores.set(
-        entry.id,
-        (rrfScores.get(entry.id) ?? 0) + freqScore * 0.13,
-      );
-    }
-  }
-
   // Attach final score to each entry and sort by RRF score descending
   const candidates = [...rowMap.values()].map((entry) => ({
     ...entry,
@@ -404,7 +296,7 @@ export async function hybridSearch(
   }));
   candidates.sort((a, b) => b.score - a.score);
 
-  // Stage 4: Fetch embeddings for all candidates that have a rowid
+  // Stage 4: Fetch embeddings for near-duplicate suppression
   const embeddingMap = new Map();
   if (queryVec && idToRowid.size > 0) {
     const rowidToId = new Map();
@@ -429,34 +321,15 @@ export async function hybridSearch(
         }
       }
     } catch (_) {
-      // Embeddings unavailable — MMR will fall back to Jaccard similarity
+      // Embeddings unavailable — near-dup suppression skipped
     }
   }
 
-  // Use vecSim as the query-relevance signal for MMR; fall back to RRF score
-  const querySimMap = new Map();
-  for (const candidate of candidates) {
-    querySimMap.set(
-      candidate.id,
-      vecSimMap.has(candidate.id)
-        ? vecSimMap.get(candidate.id)
-        : candidate.score,
-    );
-  }
-
-  // Stage 5: MMR — rerank for diversity using embeddings or Jaccard fallback
-  const mmrSelected = maximalMarginalRelevance(
-    candidates,
-    querySimMap,
-    embeddingMap,
-    offset + limit,
-  );
-
-  // Stage 6: Near-duplicate suppression (hard filter, not reorder)
-  if (queryVec && embeddingMap.size > 0 && mmrSelected.length > limit) {
+  // Stage 5: Near-duplicate suppression (cosine similarity > 0.92 threshold)
+  if (queryVec && embeddingMap.size > 0) {
     const selected = [];
     const selectedVecs = [];
-    for (const candidate of mmrSelected) {
+    for (const candidate of candidates) {
       if (selected.length >= offset + limit) break;
       const vec = embeddingMap.get(candidate.id);
       if (vec && selectedVecs.length > 0) {
@@ -475,7 +348,7 @@ export async function hybridSearch(
     return dedupedPage;
   }
 
-  const finalPage = mmrSelected.slice(offset, offset + limit);
+  const finalPage = candidates.slice(offset, offset + limit);
   trackAccess(ctx.db, finalPage);
   return finalPage;
 }

package/node_modules/@context-vault/core/src/server/tools/create-snapshot.js

@@ -5,14 +5,13 @@ import { normalizeKind } from "../../core/files.js";
 import { ok, err, ensureVaultExists } from "../helpers.js";
 
 const NOISE_KINDS = new Set(["prompt-history", "task-notification"]);
-const SYNTHESIS_MODEL = "claude-haiku-4-5-20251001";
-const MAX_ENTRIES_FOR_SYNTHESIS = 40;
+const MAX_ENTRIES_FOR_GATHER = 40;
 const MAX_BODY_PER_ENTRY = 600;
 
 export const name = "create_snapshot";
 
 export const description =
-  "Pull all relevant vault entries matching a topic, run an LLM synthesis pass to deduplicate and structure them into a context brief, then save and return the brief's ULID. The brief is saved as kind: 'brief' with a deterministic identity_key for retrieval.";
+  "Pull all relevant vault entries matching a topic, deduplicate, and save them as a structured context brief (kind: 'brief'). Entries are formatted as markdown — no external API or LLM call required. The calling agent can synthesize the gathered content directly. Retrieve with: get_context(kind: 'brief', identity_key: '<key>').";
 
 export const inputSchema = {
   topic: z.string().describe("The topic or project name to snapshot"),
@@ -38,62 +37,42 @@ export const inputSchema = {
     ),
 };
 
-function buildSynthesisPrompt(topic, entries) {
-  const entriesBlock = entries
+function formatGatheredEntries(topic, entries) {
+  const header = [
+    `# ${topic} — Context Brief`,
+    "",
+    `*Gathered from ${entries.length} vault ${entries.length === 1 ? "entry" : "entries"}. Synthesize the content below to extract key decisions, patterns, and constraints.*`,
+    "",
+    "---",
+    "",
+  ].join("\n");
+
+  const body = entries
     .map((e, i) => {
       const tags = e.tags ? JSON.parse(e.tags) : [];
       const tagStr = tags.length ? tags.join(", ") : "none";
-      const body = e.body
+      const updated = e.updated_at || e.created_at || "unknown";
+      const bodyText = e.body
         ? e.body.slice(0, MAX_BODY_PER_ENTRY) +
           (e.body.length > MAX_BODY_PER_ENTRY ? "…" : "")
         : "(no body)";
+      const title = e.title || `Entry ${i + 1}`;
       return [
-        `### Entry ${i + 1} [${e.kind}] id: ${e.id}`,
-        `tags: ${tagStr}`,
-        `updated: ${e.updated_at || e.created_at || "unknown"}`,
-        body,
+        `## ${i + 1}. [${e.kind}] ${title}`,
+        "",
+        `**Tags:** ${tagStr}`,
+        `**Updated:** ${updated}`,
+        `**ID:** \`${e.id}\``,
+        "",
+        bodyText,
+        "",
+        "---",
+        "",
       ].join("\n");
     })
-    .join("\n\n");
-
-  return `You are a knowledge synthesis assistant. Given the following vault entries about "${topic}", produce a structured context brief.
-
-Deduplicate overlapping information, resolve any contradictions (note them in Audit Notes), and organise the content into the sections below. Keep each section concise and actionable. Omit sections that have no relevant content.
-
-Output ONLY the markdown document — no preamble, no explanation.
-
-Required format:
-# ${topic} — Context Brief
-## Status
-(current state of the topic)
-## Key Decisions
-(architectural or strategic decisions made)
-## Patterns & Conventions
-(recurring patterns, coding conventions, standards)
-## Active Constraints
-(known limitations, hard requirements, deadlines)
-## Open Questions
-(unresolved questions or areas needing investigation)
-## Audit Notes
-(contradictions detected, stale entries flagged with their ids)
+    .join("");
 
----
-VAULT ENTRIES:
-
-${entriesBlock}`;
-}
-
-async function callLlm(prompt) {
-  const { Anthropic } = await import("@anthropic-ai/sdk");
-  const client = new Anthropic();
-  const message = await client.messages.create({
-    model: SYNTHESIS_MODEL,
-    max_tokens: 2048,
-    messages: [{ role: "user", content: prompt }],
-  });
-  const block = message.content.find((b) => b.type === "text");
-  if (!block) throw new Error("LLM returned no text content");
-  return block.text;
+  return header + body;
 }
 
 function slugifyTopic(topic) {
@@ -122,7 +101,6 @@ export async function handler(
   await ensureIndexed();
 
   const normalizedKinds = kinds?.map(normalizeKind) ?? [];
-  // Expand buckets to bucket: prefixed tags and merge with explicit tags
   const bucketTags = buckets?.length ? buckets.map((b) => `bucket:${b}`) : [];
   const effectiveTags = [...(tags ?? []), ...bucketTags];
 
@@ -132,7 +110,7 @@ export async function handler(
     for (const kindFilter of normalizedKinds) {
       const rows = await hybridSearch(ctx, topic, {
         kindFilter,
-        limit: Math.ceil(MAX_ENTRIES_FOR_SYNTHESIS / normalizedKinds.length),
+        limit: Math.ceil(MAX_ENTRIES_FOR_GATHER / normalizedKinds.length),
         userIdFilter: userId,
         includeSuperseeded: false,
       });
@@ -146,7 +124,7 @@ export async function handler(
     });
   } else {
     candidates = await hybridSearch(ctx, topic, {
-      limit: MAX_ENTRIES_FOR_SYNTHESIS,
+      limit: MAX_ENTRIES_FOR_GATHER,
       userIdFilter: userId,
       includeSuperseeded: false,
     });
@@ -163,25 +141,16 @@ export async function handler(
     .filter((r) => NOISE_KINDS.has(r.kind))
     .map((r) => r.id);
 
-  const synthesisEntries = candidates.filter((r) => !NOISE_KINDS.has(r.kind));
+  const gatherEntries = candidates.filter((r) => !NOISE_KINDS.has(r.kind));
 
-  if (synthesisEntries.length === 0) {
+  if (gatherEntries.length === 0) {
     return err(
-      `No entries found for topic "${topic}" to synthesize. Try a broader topic or different tags.`,
+      `No entries found for topic "${topic}". Try a broader topic or different tags.`,
       "NO_ENTRIES",
     );
   }
 
-  let briefBody;
-  try {
-    const prompt = buildSynthesisPrompt(topic, synthesisEntries);
-    briefBody = await callLlm(prompt);
-  } catch (e) {
-    return err(
-      `LLM synthesis failed: ${e.message}. Ensure ANTHROPIC_API_KEY is set.`,
-      "LLM_ERROR",
-    );
-  }
+  const briefBody = formatGatheredEntries(topic, gatherEntries);
 
   const effectiveIdentityKey =
     identity_key ?? `snapshot-${slugifyTopic(topic)}`;
@@ -205,9 +174,9 @@ export async function handler(
     userId,
     meta: {
       topic,
-      entry_count: synthesisEntries.length,
+      entry_count: gatherEntries.length,
       noise_superseded: noiseIds.length,
-      synthesized_from: synthesisEntries.map((e) => e.id),
+      synthesized_from: gatherEntries.map((e) => e.id),
     },
   });
 
@@ -215,7 +184,7 @@ export async function handler(
     `✓ Snapshot created → id: ${entry.id}`,
     `  title: ${entry.title}`,
     `  identity_key: ${effectiveIdentityKey}`,
-    `  synthesized from: ${synthesisEntries.length} entries`,
+    `  synthesized from: ${gatherEntries.length} entries`,
     noiseIds.length > 0
       ? `  noise superseded: ${noiseIds.length} entries`
       : null,