@context-vault/core 2.17.0 → 3.0.0

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

@@ -1,182 +0,0 @@
-import { gatherVaultStatus, computeGrowthWarnings } from "../../core/status.js";
-import { errorLogPath, errorLogCount } from "../../core/error-log.js";
-import { ok } from "../helpers.js";
-
-function relativeTime(ts) {
-  const secs = Math.floor((Date.now() - ts) / 1000);
-  if (secs < 60) return `${secs}s ago`;
-  const mins = Math.floor(secs / 60);
-  if (mins < 60) return `${mins} minute${mins === 1 ? "" : "s"} ago`;
-  const hrs = Math.floor(mins / 60);
-  return `${hrs} hour${hrs === 1 ? "" : "s"} ago`;
-}
-
-export const name = "context_status";
-
-export const description =
-  "Show vault health: resolved config, file counts per kind, database size, and any issues. Use to verify setup or troubleshoot. Call this when a user asks about their vault or to debug search issues.";
-
-export const inputSchema = {};
-
-/**
- * @param {object} _args
- * @param {import('../types.js').BaseCtx & Partial<import('../types.js').HostedCtxExtensions>} ctx
- */
-export function handler(_args, ctx) {
-  const { config } = ctx;
-  const userId = ctx.userId !== undefined ? ctx.userId : undefined;
-
-  const status = gatherVaultStatus(ctx, { userId });
-
-  const hasIssues = status.stalePaths || status.embeddingStatus?.missing > 0;
-  const healthIcon = hasIssues ? "⚠" : "✓";
-
-  const lines = [
-    `## ${healthIcon} Vault Status (connected)`,
-    ``,
-    `Vault:     ${config.vaultDir} (${config.vaultDirExists ? status.fileCount + " files" : "missing"})`,
-    `Database:  ${config.dbPath} (${status.dbSize})`,
-    `Dev dir:   ${config.devDir}`,
-    `Data dir:  ${config.dataDir}`,
-    `Config:    ${config.configPath}`,
-    `Resolved via: ${status.resolvedFrom}`,
-    `Schema:    v9 (updated_at, superseded_by)`,
-  ];
-
-  if (status.embeddingStatus) {
-    const { indexed, total, missing } = status.embeddingStatus;
-    const pct = total > 0 ? Math.round((indexed / total) * 100) : 100;
-    lines.push(`Embeddings: ${indexed}/${total} (${pct}%)`);
-  }
-  if (status.embedModelAvailable === false) {
-    lines.push(
-      `Embed model: unavailable (semantic search disabled, FTS still works)`,
-    );
-  } else if (status.embedModelAvailable === true) {
-    lines.push(`Embed model: loaded`);
-  }
-  lines.push(`Decay:     ${config.eventDecayDays} days (event recency window)`);
-  if (status.expiredCount > 0) {
-    lines.push(
-      `Expired:   ${status.expiredCount} entries pending prune (run \`context-vault prune\` to remove now)`,
-    );
-  }
-
-  lines.push(``, `### Indexed`);
-
-  if (status.kindCounts.length) {
-    for (const { kind, c } of status.kindCounts) lines.push(`- ${c} ${kind}s`);
-  } else {
-    lines.push(`- (empty)`);
-  }
-
-  if (status.categoryCounts.length) {
-    lines.push(``);
-    lines.push(`### Categories`);
-    for (const { category, c } of status.categoryCounts)
-      lines.push(`- ${category}: ${c}`);
-  }
-
-  if (status.subdirs.length) {
-    lines.push(``);
-    lines.push(`### Disk Directories`);
-    for (const { name, count } of status.subdirs)
-      lines.push(`- ${name}/: ${count} files`);
-  }
-
-  if (status.stalePaths) {
-    lines.push(``);
-    lines.push(`### ⚠ Stale Paths`);
-    lines.push(
-      `DB contains ${status.staleCount} paths not matching current vault dir.`,
-    );
-    lines.push(`Auto-reindex will fix this on next search or save.`);
-  }
-
-  if (status.staleKnowledge?.length > 0) {
-    lines.push(``);
-    lines.push(`### ⚠ Potentially Stale Knowledge`);
-    lines.push(
-      `Not updated within kind staleness window (pattern: 180d, decision: 365d, reference: 90d):`,
-    );
-    for (const entry of status.staleKnowledge) {
-      const lastUpdated = entry.last_updated
-        ? entry.last_updated.split("T")[0]
-        : "unknown";
-      lines.push(
-        `- "${entry.title}" (${entry.kind}) — last updated ${lastUpdated}`,
-      );
-    }
-    lines.push(
-      `Use save_context to refresh or add expires_at to retire stale entries.`,
-    );
-  }
-
-  // Error log
-  const logPath = errorLogPath(config.dataDir);
-  const logCount = errorLogCount(config.dataDir);
-  if (logCount > 0) {
-    lines.push(``, `### Startup Error Log`);
-    lines.push(`- Path: ${logPath}`);
-    lines.push(`- Entries: ${logCount} (share this file for support)`);
-  }
-
-  // Health: session-level tool call stats
-  const ts = ctx.toolStats;
-  if (ts) {
-    lines.push(``, `### Health`);
-    lines.push(`- Tool calls (session): ${ts.ok} ok, ${ts.errors} errors`);
-    if (ts.lastError) {
-      const { tool, code, timestamp } = ts.lastError;
-      lines.push(
-        `- Last error: ${tool ?? "unknown"} — ${code} (${relativeTime(timestamp)})`,
-      );
-    }
-    if (status.autoCapturedFeedbackCount > 0) {
-      lines.push(
-        `- Auto-captured feedback entries: ${status.autoCapturedFeedbackCount} (run get_context with kind:feedback tags:auto-captured)`,
-      );
-    }
-  }
-
-  // Growth warnings
-  const growth = computeGrowthWarnings(status, config.thresholds);
-  if (growth.hasWarnings) {
-    lines.push("", "### ⚠ Vault Growth Warning");
-    for (const w of growth.warnings) {
-      lines.push(`  ${w.message}`);
-    }
-    if (growth.kindBreakdown.length) {
-      lines.push("");
-      lines.push("  Breakdown by kind:");
-      for (const { kind, count, pct } of growth.kindBreakdown) {
-        lines.push(`    ${kind}: ${count.toLocaleString()} (${pct}%)`);
-      }
-    }
-    if (growth.actions.length) {
-      lines.push("", "Suggested growth actions:");
-      for (const a of growth.actions) {
-        lines.push(`  • ${a}`);
-      }
-    }
-  }
-
-  // Suggested actions
-  const actions = [];
-  if (status.stalePaths)
-    actions.push("- Run `context-vault reindex` to fix stale paths");
-  if (status.embeddingStatus?.missing > 0)
-    actions.push(
-      "- Run `context-vault reindex` to generate missing embeddings",
-    );
-  if (!config.vaultDirExists)
-    actions.push("- Run `context-vault setup` to create the vault directory");
-  if (status.kindCounts.length === 0 && config.vaultDirExists)
-    actions.push("- Use `save_context` to add your first entry");
-
-  if (actions.length) {
-    lines.push("", "### Suggested Actions", ...actions);
-  }
-
-  return ok(lines.join("\n"));
-}

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

@@ -1,231 +0,0 @@
-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"),
-  buckets: z
-    .array(z.string())
-    .optional()
-    .describe(
-      "Filter by project-scoped buckets. Each name expands to a 'bucket:<name>' tag. Composes with 'tags' via OR (entries matching any tag or any bucket are included).",
-    ),
-  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, buckets, 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) ?? [];
-  // Expand buckets to bucket: prefixed tags and merge with explicit tags
-  const bucketTags = buckets?.length ? buckets.map((b) => `bucket:${b}`) : [];
-  const effectiveTags = [...(tags ?? []), ...bucketTags];
-
-  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 (effectiveTags.length) {
-    candidates = candidates.filter((r) => {
-      const entryTags = r.tags ? JSON.parse(r.tags) : [];
-      return effectiveTags.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/delete-context.js

@@ -1,60 +0,0 @@
-import { z } from "zod";
-import { unlinkSync } from "node:fs";
-import { ok, err } from "../helpers.js";
-
-export const name = "delete_context";
-
-export const description =
-  "Delete an entry from your vault by its ULID id. Removes the file from disk and cleans up the search index.";
-
-export const inputSchema = {
-  id: z.string().describe("The entry ULID to delete"),
-};
-
-/**
- * @param {object} args
- * @param {import('../types.js').BaseCtx & Partial<import('../types.js').HostedCtxExtensions>} ctx
- * @param {import('../types.js').ToolShared} shared
- */
-export async function handler({ id }, ctx, { ensureIndexed }) {
-  const userId = ctx.userId !== undefined ? ctx.userId : undefined;
-
-  if (!id?.trim())
-    return err("Required: id (non-empty string)", "INVALID_INPUT");
-  await ensureIndexed();
-
-  const entry = ctx.stmts.getEntryById.get(id);
-  if (!entry) return err(`Entry not found: ${id}`, "NOT_FOUND");
-
-  // Ownership check: don't leak existence across users
-  if (userId !== undefined && entry.user_id !== userId) {
-    return err(`Entry not found: ${id}`, "NOT_FOUND");
-  }
-
-  // Delete file from disk first (source of truth)
-  let fileWarning = null;
-  if (entry.file_path) {
-    try {
-      unlinkSync(entry.file_path);
-    } catch (e) {
-      // ENOENT = already gone — not an error worth surfacing
-      if (e.code !== "ENOENT") {
-        fileWarning = `file could not be removed from disk (${e.code}): ${entry.file_path}`;
-      }
-    }
-  }
-
-  // Delete vector embedding
-  const rowidResult = ctx.stmts.getRowid.get(id);
-  if (rowidResult?.rowid) {
-    try {
-      ctx.deleteVec(Number(rowidResult.rowid));
-    } catch {}
-  }
-
-  // Delete DB row (FTS trigger handles FTS cleanup)
-  ctx.stmts.deleteEntry.run(id);
-
-  const msg = `Deleted ${entry.kind}: ${entry.title || "(untitled)"} [${id}]`;
-  return ok(fileWarning ? `${msg}\nWarning: ${fileWarning}` : msg);
-}