@context-vault/core 2.12.0 → 2.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@context-vault/core",
-  "version": "2.12.0",
+  "version": "2.14.0",
   "type": "module",
   "description": "Shared core: capture, index, retrieve, tools, and utilities for context-vault",
   "main": "src/index.js",
@@ -36,6 +36,7 @@
     "access": "public"
   },
   "dependencies": {
+    "@anthropic-ai/sdk": "^0.78.0",
     "@modelcontextprotocol/sdk": "^1.26.0",
     "sqlite-vec": "^0.1.0"
   },

package/src/server/tools/clear-context.js

@@ -0,0 +1,47 @@
+import { z } from "zod";
+import { ok } from "../helpers.js";
+
+export const name = "clear_context";
+
+export const description =
+  "Reset active in-memory session context without deleting vault entries. Call this when switching projects or topics mid-session. With `scope`, all subsequent get_context calls should filter to that tag/project. Vault data is never modified.";
+
+export const inputSchema = {
+  scope: z
+    .string()
+    .optional()
+    .describe(
+      "Optional tag or project name to focus on going forward. When provided, treat subsequent get_context calls as if filtered to this tag.",
+    ),
+};
+
+/**
+ * @param {object} args
+ * @param {import('../types.js').BaseCtx & Partial<import('../types.js').HostedCtxExtensions>} _ctx
+ */
+export function handler({ scope } = {}) {
+  const lines = [
+    "## Context Reset",
+    "",
+    "Active session context has been cleared. All previous context from this session should be disregarded.",
+    "",
+    "Vault entries are unchanged — no data was deleted.",
+  ];
+
+  if (scope?.trim()) {
+    const trimmed = scope.trim();
+    lines.push(
+      "",
+      `### Active Scope: \`${trimmed}\``,
+      "",
+      `Going forward, treat \`get_context\` calls as scoped to the tag or project **"${trimmed}"** unless the user explicitly requests a different scope or passes their own tag filters.`,
+    );
+  } else {
+    lines.push(
+      "",
+      "No scope set. Use `get_context` normally — all vault entries are accessible.",
+    );
+  }
+
+  return ok(lines.join("\n"));
+}

package/src/server/tools/create-snapshot.js

@@ -0,0 +1,222 @@
+import { z } from "zod";
+import { hybridSearch } from "../../retrieve/index.js";
+import { captureAndIndex } from "../../capture/index.js";
+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_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.";
+
+export const inputSchema = {
+  topic: z.string().describe("The topic or project name to snapshot"),
+  tags: z
+    .array(z.string())
+    .optional()
+    .describe("Optional tag filters — entries must match at least one"),
+  kinds: z
+    .array(z.string())
+    .optional()
+    .describe("Optional kind filters to restrict which entry types are pulled"),
+  identity_key: z
+    .string()
+    .optional()
+    .describe(
+      "Deterministic key for the saved brief (defaults to slugified topic). Use the same key to overwrite a previous snapshot.",
+    ),
+};
+
+function buildSynthesisPrompt(topic, entries) {
+  const entriesBlock = entries
+    .map((e, i) => {
+      const tags = e.tags ? JSON.parse(e.tags) : [];
+      const tagStr = tags.length ? tags.join(", ") : "none";
+      const body = e.body
+        ? e.body.slice(0, MAX_BODY_PER_ENTRY) +
+          (e.body.length > MAX_BODY_PER_ENTRY ? "…" : "")
+        : "(no body)";
+      return [
+        `### Entry ${i + 1} [${e.kind}] id: ${e.id}`,
+        `tags: ${tagStr}`,
+        `updated: ${e.updated_at || e.created_at || "unknown"}`,
+        body,
+      ].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)
+
+---
+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;
+}
+
+function slugifyTopic(topic) {
+  return topic
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 120);
+}
+
+export async function handler(
+  { topic, tags, kinds, identity_key },
+  ctx,
+  { ensureIndexed },
+) {
+  const { config } = ctx;
+  const userId = ctx.userId !== undefined ? ctx.userId : undefined;
+
+  const vaultErr = ensureVaultExists(config);
+  if (vaultErr) return vaultErr;
+
+  if (!topic?.trim()) {
+    return err("Required: topic (non-empty string)", "INVALID_INPUT");
+  }
+
+  await ensureIndexed();
+
+  const normalizedKinds = kinds?.map(normalizeKind) ?? [];
+
+  let candidates = [];
+
+  if (normalizedKinds.length > 0) {
+    for (const kindFilter of normalizedKinds) {
+      const rows = await hybridSearch(ctx, topic, {
+        kindFilter,
+        limit: Math.ceil(MAX_ENTRIES_FOR_SYNTHESIS / normalizedKinds.length),
+        userIdFilter: userId,
+        includeSuperseeded: false,
+      });
+      candidates.push(...rows);
+    }
+    const seen = new Set();
+    candidates = candidates.filter((r) => {
+      if (seen.has(r.id)) return false;
+      seen.add(r.id);
+      return true;
+    });
+  } else {
+    candidates = await hybridSearch(ctx, topic, {
+      limit: MAX_ENTRIES_FOR_SYNTHESIS,
+      userIdFilter: userId,
+      includeSuperseeded: false,
+    });
+  }
+
+  if (tags?.length) {
+    candidates = candidates.filter((r) => {
+      const entryTags = r.tags ? JSON.parse(r.tags) : [];
+      return tags.some((t) => entryTags.includes(t));
+    });
+  }
+
+  const noiseIds = candidates
+    .filter((r) => NOISE_KINDS.has(r.kind))
+    .map((r) => r.id);
+
+  const synthesisEntries = candidates.filter((r) => !NOISE_KINDS.has(r.kind));
+
+  if (synthesisEntries.length === 0) {
+    return err(
+      `No entries found for topic "${topic}" to synthesize. 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 effectiveIdentityKey =
+    identity_key ?? `snapshot-${slugifyTopic(topic)}`;
+
+  const briefTags = [
+    "snapshot",
+    ...(tags ?? []),
+    ...(normalizedKinds.length > 0 ? [] : []),
+  ];
+
+  const supersedes = noiseIds.length > 0 ? noiseIds : undefined;
+
+  const entry = await captureAndIndex(ctx, {
+    kind: "brief",
+    title: `${topic} — Context Brief`,
+    body: briefBody,
+    tags: briefTags,
+    source: "create_snapshot",
+    identity_key: effectiveIdentityKey,
+    supersedes,
+    userId,
+    meta: {
+      topic,
+      entry_count: synthesisEntries.length,
+      noise_superseded: noiseIds.length,
+      synthesized_from: synthesisEntries.map((e) => e.id),
+    },
+  });
+
+  const parts = [
+    `✓ Snapshot created → id: ${entry.id}`,
+    `  title: ${entry.title}`,
+    `  identity_key: ${effectiveIdentityKey}`,
+    `  synthesized from: ${synthesisEntries.length} entries`,
+    noiseIds.length > 0
+      ? `  noise superseded: ${noiseIds.length} entries`
+      : null,
+    "",
+    "_Retrieve with: get_context(kind: 'brief', identity_key: '" +
+      effectiveIdentityKey +
+      "')_",
+  ]
+    .filter((l) => l !== null)
+    .join("\n");
+
+  return ok(parts);
+}

package/src/server/tools/get-context.js

@@ -5,6 +5,87 @@ import { normalizeKind } from "../../core/files.js";
 import { ok, err } from "../helpers.js";
 import { isEmbedAvailable } from "../../index/embed.js";
 
+const STALE_DUPLICATE_DAYS = 7;
+
+/**
+ * Detect conflicts among a set of search result entries.
+ *
+ * Two checks are performed:
+ *   1. Supersession: if entry A's `superseded_by` points to any entry B in the
+ *      result set, A is stale and should be discarded in favour of B.
+ *   2. Stale duplicate: two entries share the same kind and at least one common
+ *      tag, but their `updated_at` timestamps differ by more than
+ *      STALE_DUPLICATE_DAYS days — suggesting the older one may be outdated.
+ *
+ * No LLM calls, no new dependencies — pure in-memory set operations on the
+ * rows already fetched from the DB.
+ *
+ * @param {Array} entries - Result rows (as returned by hybridSearch / filter-only mode)
+ * @param {import('../types.js').BaseCtx} _ctx - Unused for now; reserved for future DB look-ups
+ * @returns {Array<{entry_a_id: string, entry_b_id: string, reason: string, recommendation: string}>}
+ */
+export function detectConflicts(entries, _ctx) {
+  const conflicts = [];
+  const idSet = new Set(entries.map((e) => e.id));
+
+  for (const entry of entries) {
+    if (entry.superseded_by && idSet.has(entry.superseded_by)) {
+      conflicts.push({
+        entry_a_id: entry.id,
+        entry_b_id: entry.superseded_by,
+        reason: "superseded",
+        recommendation: `Discard \`${entry.id}\` — it has been explicitly superseded by \`${entry.superseded_by}\`.`,
+      });
+    }
+  }
+
+  const supersededConflictPairs = new Set(
+    conflicts.map((c) => `${c.entry_a_id}|${c.entry_b_id}`),
+  );
+
+  for (let i = 0; i < entries.length; i++) {
+    for (let j = i + 1; j < entries.length; j++) {
+      const a = entries[i];
+      const b = entries[j];
+
+      if (
+        supersededConflictPairs.has(`${a.id}|${b.id}`) ||
+        supersededConflictPairs.has(`${b.id}|${a.id}`)
+      ) {
+        continue;
+      }
+
+      if (a.kind !== b.kind) continue;
+
+      const tagsA = a.tags ? JSON.parse(a.tags) : [];
+      const tagsB = b.tags ? JSON.parse(b.tags) : [];
+
+      if (!tagsA.length || !tagsB.length) continue;
+
+      const tagsSetA = new Set(tagsA);
+      const sharedTag = tagsB.some((t) => tagsSetA.has(t));
+      if (!sharedTag) continue;
+
+      const dateA = new Date(a.updated_at || a.created_at);
+      const dateB = new Date(b.updated_at || b.created_at);
+      if (isNaN(dateA.getTime()) || isNaN(dateB.getTime())) continue;
+
+      const diffDays = Math.abs(dateA - dateB) / 86400000;
+      if (diffDays <= STALE_DUPLICATE_DAYS) continue;
+
+      const [older, newer] = dateA < dateB ? [a, b] : [b, a];
+      conflicts.push({
+        entry_a_id: older.id,
+        entry_b_id: newer.id,
+        reason: "stale_duplicate",
+        recommendation: `Verify \`${older.id}\` is still accurate — it shares kind "${older.kind}" and tags with \`${newer.id}\` but was last updated ${Math.round(diffDays)} days earlier.`,
+      });
+    }
+  }
+
+  return conflicts;
+}
+
 export const name = "get_context";
 
 export const description =
@@ -48,6 +129,12 @@ export const inputSchema = {
     .describe(
       "If true, include entries that have been superseded by newer ones. Default: false.",
     ),
+  detect_conflicts: z
+    .boolean()
+    .optional()
+    .describe(
+      "If true, compare results for contradicting entries and append a conflicts array. Flags superseded entries still in results and stale duplicates (same kind+tags, updated_at >7 days apart). No LLM calls — pure DB logic.",
+    ),
 };
 
 /**
@@ -66,6 +153,7 @@ export async function handler(
     until,
     limit,
     include_superseded,
+    detect_conflicts,
   },
   ctx,
   { ensureIndexed, reindexFailed },
@@ -227,6 +315,9 @@ export async function handler(
     }
   }
 
+  // Conflict detection
+  const conflicts = detect_conflicts ? detectConflicts(filtered, ctx) : [];
+
   const lines = [];
   if (reindexFailed)
     lines.push(
@@ -265,5 +356,23 @@ export async function handler(
     lines.push(r.body?.slice(0, 300) + (r.body?.length > 300 ? "..." : ""));
     lines.push("");
   }
+
+  if (detect_conflicts) {
+    if (conflicts.length === 0) {
+      lines.push(
+        `## Conflict Detection\n\nNo conflicts detected among results.\n`,
+      );
+    } else {
+      lines.push(`## Conflict Detection (${conflicts.length} flagged)\n`);
+      for (const c of conflicts) {
+        lines.push(
+          `- **${c.reason}**: \`${c.entry_a_id}\` vs \`${c.entry_b_id}\``,
+        );
+        lines.push(`  Recommendation: ${c.recommendation}`);
+      }
+      lines.push("");
+    }
+  }
+
   return ok(lines.join("\n"));
 }

package/src/server/tools.js

@@ -11,6 +11,8 @@ import * as deleteContext from "./tools/delete-context.js";
 import * as submitFeedback from "./tools/submit-feedback.js";
 import * as ingestUrl from "./tools/ingest-url.js";
 import * as contextStatus from "./tools/context-status.js";
+import * as clearContext from "./tools/clear-context.js";
+import * as createSnapshot from "./tools/create-snapshot.js";
 
 const toolModules = [
   getContext,
@@ -20,6 +22,8 @@ const toolModules = [
   submitFeedback,
   ingestUrl,
   contextStatus,
+  clearContext,
+  createSnapshot,
 ];
 
 const TOOL_TIMEOUT_MS = 60_000;