@context-vault/core 2.14.0 → 2.15.0

package/src/server/tools/list-buckets.js

@@ -0,0 +1,116 @@
+import { z } from "zod";
+import { ok } from "../helpers.js";
+
+export const name = "list_buckets";
+
+export const description =
+  "List all registered bucket entities in the vault. Buckets are named scopes used to group entries via 'bucket:' prefixed tags. Returns each bucket's name, description, parent, and optional entry count.";
+
+export const inputSchema = {
+  include_counts: z
+    .boolean()
+    .optional()
+    .describe(
+      "Include count of entries tagged with each bucket (default true). Set false to skip the count queries for faster response.",
+    ),
+};
+
+/**
+ * @param {object} args
+ * @param {import('../types.js').BaseCtx & Partial<import('../types.js').HostedCtxExtensions>} ctx
+ * @param {import('../types.js').ToolShared} shared
+ */
+export async function handler(
+  { include_counts = true },
+  ctx,
+  { ensureIndexed, reindexFailed },
+) {
+  const userId = ctx.userId !== undefined ? ctx.userId : undefined;
+
+  await ensureIndexed();
+
+  const userClause = userId !== undefined ? "AND user_id = ?" : "";
+  const userParams = userId !== undefined ? [userId] : [];
+
+  const buckets = ctx.db
+    .prepare(
+      `SELECT id, title, identity_key, body, tags, meta, created_at, updated_at
+       FROM vault
+       WHERE kind = 'bucket'
+         AND (expires_at IS NULL OR expires_at > datetime('now'))
+         AND superseded_by IS NULL
+         ${userClause}
+       ORDER BY title ASC`,
+    )
+    .all(...userParams);
+
+  if (!buckets.length) {
+    return ok(
+      "No buckets registered.\n\nCreate one with `save_context(kind: \"bucket\", identity_key: \"bucket:myproject\", title: \"My Project\", body: \"...\")` to register a bucket.",
+    );
+  }
+
+  const lines = [];
+  if (reindexFailed) {
+    lines.push(
+      `> **Warning:** Auto-reindex failed. Results may be stale. Run \`context-vault reindex\` to fix.\n`,
+    );
+  }
+  lines.push(`## Registered Buckets (${buckets.length})\n`);
+
+  for (const b of buckets) {
+    let meta = {};
+    if (b.meta) {
+      try {
+        meta = typeof b.meta === "string" ? JSON.parse(b.meta) : b.meta;
+      } catch {
+        meta = {};
+      }
+    }
+
+    const bucketTags = b.tags ? JSON.parse(b.tags) : [];
+    const name = b.identity_key
+      ? b.identity_key.replace(/^bucket:/, "")
+      : b.title || b.id;
+    const parent = meta.parent || null;
+
+    let entryCount = null;
+    if (include_counts && b.identity_key) {
+      const countUserClause =
+        userId !== undefined ? "AND user_id = ?" : "";
+      const countParams = userId !== undefined ? [userId] : [];
+      const row = ctx.db
+        .prepare(
+          `SELECT COUNT(*) as c FROM vault
+           WHERE tags LIKE ?
+             AND kind != 'bucket'
+             AND (expires_at IS NULL OR expires_at > datetime('now'))
+             AND superseded_by IS NULL
+             ${countUserClause}`,
+        )
+        .get(`%"${b.identity_key}"%`, ...countParams);
+      entryCount = row ? row.c : 0;
+    }
+
+    const titleDisplay = b.title || name;
+    const headerParts = [`**${titleDisplay}**`];
+    if (b.identity_key) headerParts.push(`\`${b.identity_key}\``);
+    if (parent) headerParts.push(`parent: ${parent}`);
+    if (entryCount !== null) headerParts.push(`${entryCount} entries`);
+    lines.push(`- ${headerParts.join(" — ")}`);
+
+    if (b.body) {
+      const preview = b.body.replace(/\n+/g, " ").trim().slice(0, 120);
+      lines.push(`  ${preview}${b.body.length > 120 ? "…" : ""}`);
+    }
+    if (bucketTags.length) {
+      lines.push(`  tags: ${bucketTags.join(", ")}`);
+    }
+  }
+
+  lines.push(
+    "\n_Register a new bucket with `save_context(kind: \"bucket\", identity_key: \"bucket:<name>\", title: \"...\", body: \"...\")`_",
+  );
+
+  return ok(lines.join("\n"));
+}

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

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { captureAndIndex, updateEntryFile } from "../../capture/index.js";
 import { indexEntry } from "../../index/index.js";
-import { categoryFor } from "../../core/categories.js";
+import { categoryFor, defaultTierFor } from "../../core/categories.js";
 import { normalizeKind } from "../../core/files.js";
 import { ok, err, ensureVaultExists, ensureValidKind } from "../helpers.js";
 import { maybeShowFeedbackPrompt } from "../../core/telemetry.js";
@@ -17,8 +17,16 @@ import {
 } from "../../constants.js";
 
 const DEFAULT_SIMILARITY_THRESHOLD = 0.85;
+const SKIP_THRESHOLD = 0.95;
+const UPDATE_THRESHOLD = 0.85;
 
-async function findSimilar(ctx, embedding, threshold, userId) {
+async function findSimilar(
+  ctx,
+  embedding,
+  threshold,
+  userId,
+  { hydrate = false } = {},
+) {
   try {
     const vecCount = ctx.db
       .prepare("SELECT COUNT(*) as c FROM vault_vec")
@@ -35,14 +43,15 @@ async function findSimilar(ctx, embedding, threshold, userId) {
 
     const rowids = vecRows.map((vr) => vr.rowid);
     const placeholders = rowids.map(() => "?").join(",");
-    const hydrated = ctx.db
-      .prepare(
-        `SELECT rowid, id, title, category, user_id FROM vault WHERE rowid IN (${placeholders})`,
-      )
+    const columns = hydrate
+      ? "rowid, id, title, body, kind, tags, category, user_id, updated_at"
+      : "rowid, id, title, category, user_id";
+    const hydratedRows = ctx.db
+      .prepare(`SELECT ${columns} FROM vault WHERE rowid IN (${placeholders})`)
       .all(...rowids);
 
     const byRowid = new Map();
-    for (const row of hydrated) byRowid.set(row.rowid, row);
+    for (const row of hydratedRows) byRowid.set(row.rowid, row);
 
     const results = [];
     for (const vr of vecRows) {
@@ -52,7 +61,14 @@ async function findSimilar(ctx, embedding, threshold, userId) {
       if (!row) continue;
       if (userId !== undefined && row.user_id !== userId) continue;
       if (row.category === "entity") continue;
-      results.push({ id: row.id, title: row.title, score: similarity });
+      const entry = { id: row.id, title: row.title, score: similarity };
+      if (hydrate) {
+        entry.body = row.body;
+        entry.kind = row.kind;
+        entry.tags = row.tags;
+        entry.updated_at = row.updated_at;
+      }
+      results.push(entry);
     }
     return results;
   } catch {
@@ -73,6 +89,68 @@ function formatSimilarWarning(similar) {
   return lines.join("\n");
 }
 
+export function buildConflictCandidates(similarEntries) {
+  return similarEntries.map((entry) => {
+    let suggested_action;
+    let reasoning_context;
+
+    if (entry.score >= SKIP_THRESHOLD) {
+      suggested_action = "SKIP";
+      reasoning_context =
+        `Near-duplicate detected (${(entry.score * 100).toFixed(0)}% similarity)` +
+        `${entry.title ? ` with "${entry.title}"` : ""}. ` +
+        `Content is nearly identical — saving would create a redundant entry. ` +
+        `Use save_context with id: "${entry.id}" to update instead, or skip saving entirely.`;
+    } else if (entry.score >= UPDATE_THRESHOLD) {
+      suggested_action = "UPDATE";
+      reasoning_context =
+        `High content similarity (${(entry.score * 100).toFixed(0)}%)` +
+        `${entry.title ? ` with "${entry.title}"` : ""}. ` +
+        `Likely the same knowledge — consider updating this entry via save_context with id: "${entry.id}".`;
+    } else {
+      suggested_action = "ADD";
+      reasoning_context =
+        `Moderate similarity (${(entry.score * 100).toFixed(0)}%)` +
+        `${entry.title ? ` with "${entry.title}"` : ""}. ` +
+        `Content is related but distinct enough to coexist.`;
+    }
+
+    let parsedTags = [];
+    if (entry.tags) {
+      try {
+        parsedTags =
+          typeof entry.tags === "string" ? JSON.parse(entry.tags) : entry.tags;
+      } catch {
+        parsedTags = [];
+      }
+    }
+
+    return {
+      id: entry.id,
+      title: entry.title || null,
+      body: entry.body || null,
+      kind: entry.kind || null,
+      tags: parsedTags,
+      score: entry.score,
+      updated_at: entry.updated_at || null,
+      suggested_action,
+      reasoning_context,
+    };
+  });
+}
+
+function formatConflictSuggestions(candidates) {
+  const lines = ["", "── Conflict Resolution Suggestions ──"];
+  for (const c of candidates) {
+    const titleDisplay = c.title ? `"${c.title}"` : "(no title)";
+    lines.push(
+      `  [${c.suggested_action}] ${titleDisplay} (${(c.score * 100).toFixed(0)}%) — id: ${c.id}`,
+    );
+    lines.push(`    ${c.reasoning_context}`);
+  }
+  return lines.join("\n");
+}
+
 /**
  * Validate input fields for save_context. Returns an error response or null.
  */
@@ -189,7 +267,9 @@ export const inputSchema = {
   tags: z
     .array(z.string())
     .optional()
-    .describe("Tags for categorization and search"),
+    .describe(
+      "Tags for categorization and search. Use 'bucket:' prefix for project/domain scoping (e.g., 'bucket:autohub') to enable project-scoped retrieval.",
+    ),
   meta: z
     .any()
     .optional()
@@ -214,6 +294,25 @@ export const inputSchema = {
     .describe(
       "Array of entry IDs that this entry supersedes/replaces. Those entries will be marked with superseded_by pointing to this new entry and excluded from future search results by default.",
     ),
+  source_files: z
+    .array(
+      z.object({
+        path: z.string().describe("File path (absolute or relative to cwd)"),
+        hash: z
+          .string()
+          .describe("SHA-256 hash of the file contents at observation time"),
+      }),
+    )
+    .optional()
+    .describe(
+      "Source code files this entry is derived from. When these files change (hash mismatch), the entry will be flagged as stale in get_context results.",
+    ),
+  tier: z
+    .enum(["ephemeral", "working", "durable"])
+    .optional()
+    .describe(
+      "Memory tier for lifecycle management. 'ephemeral': short-lived session data. 'working': active context (default). 'durable': long-term reference material. Defaults based on kind when not specified.",
+    ),
   dry_run: z
     .boolean()
     .optional()
@@ -228,6 +327,18 @@ export const inputSchema = {
     .describe(
       "Cosine similarity threshold for duplicate detection (0–1, default 0.85). Entries above this score are flagged as similar. Only applies to knowledge and event categories.",
     ),
+  tier: z
+    .enum(["ephemeral", "working", "durable"])
+    .optional()
+    .describe(
+      "Memory tier for lifecycle management. 'ephemeral': short-lived session data. 'working': active context (default). 'durable': long-term reference material. Defaults based on kind when not specified.",
+    ),
+  conflict_resolution: z
+    .enum(["suggest", "off"])
+    .optional()
+    .describe(
+      'Conflict resolution mode. "suggest" (default): when similar entries are found, return structured conflict_candidates with suggested_action (ADD/UPDATE/SKIP) and reasoning_context for the calling agent to decide. Thresholds: score > 0.95 → SKIP (near-duplicate), score > 0.85 → UPDATE (very similar), score < 0.85 → ADD (distinct enough). "off": flag similar entries only (legacy behavior).',
+    ),
 };
 
 /**
@@ -248,14 +359,18 @@ export async function handler(
     identity_key,
     expires_at,
     supersedes,
+    source_files,
     dry_run,
     similarity_threshold,
+    tier,
+    conflict_resolution,
   },
   ctx,
   { ensureIndexed },
 ) {
   const { config } = ctx;
   const userId = ctx.userId !== undefined ? ctx.userId : undefined;
+  const suggestMode = conflict_resolution !== "off";
 
   const vaultErr = ensureVaultExists(config);
   if (vaultErr) return vaultErr;
@@ -313,6 +428,7 @@ export async function handler(
       source,
       expires_at,
       supersedes,
+      source_files,
     });
     await indexEntry(ctx, entry);
     const relPath = entry.filePath
@@ -359,6 +475,7 @@ export async function handler(
         queryEmbedding,
         threshold,
         userId,
+        { hydrate: suggestMode },
       );
     }
   }
@@ -366,16 +483,31 @@ export async function handler(
   if (dry_run) {
     const parts = ["(dry run — nothing saved)"];
     if (similarEntries.length) {
-      parts.push("", "⚠ Similar entries already exist:");
-      for (const e of similarEntries) {
-        const score = e.score.toFixed(2);
-        const titleDisplay = e.title ? `"${e.title}"` : "(no title)";
-        parts.push(`  - ${titleDisplay} (${score}) — id: ${e.id}`);
+      if (suggestMode) {
+        const candidates = buildConflictCandidates(similarEntries);
+        parts.push("", "⚠ Similar entries already exist:");
+        for (const e of similarEntries) {
+          const score = e.score.toFixed(2);
+          const titleDisplay = e.title ? `"${e.title}"` : "(no title)";
+          parts.push(`  - ${titleDisplay} (${score}) — id: ${e.id}`);
+        }
+        parts.push(formatConflictSuggestions(candidates));
+        parts.push(
+          "",
+          "Use save_context with `id: <existing>` to update one, or omit `dry_run` to save as new.",
+        );
+      } else {
+        parts.push("", "⚠ Similar entries already exist:");
+        for (const e of similarEntries) {
+          const score = e.score.toFixed(2);
+          const titleDisplay = e.title ? `"${e.title}"` : "(no title)";
+          parts.push(`  - ${titleDisplay} (${score}) — id: ${e.id}`);
+        }
+        parts.push(
+          "",
+          "Use save_context with `id: <existing>` to update one, or omit `dry_run` to save as new.",
+        );
       }
-      parts.push(
-        "",
-        "Use save_context with `id: <existing>` to update one, or omit `dry_run` to save as new.",
-      );
     } else {
       parts.push("", "No similar entries found. Safe to save.");
     }
@@ -386,6 +518,8 @@ export async function handler(
   if (folder) mergedMeta.folder = folder;
   const finalMeta = Object.keys(mergedMeta).length ? mergedMeta : undefined;
 
+  const effectiveTier = tier ?? defaultTierFor(normalizedKind);
+
   const entry = await captureAndIndex(ctx, {
     kind: normalizedKind,
     title,
@@ -397,7 +531,9 @@ export async function handler(
     identity_key,
     expires_at,
     supersedes,
+    source_files,
     userId,
+    tier: effectiveTier,
   });
 
   if (ctx.config?.dataDir) {
@@ -410,9 +546,44 @@ export async function handler(
   const parts = [`✓ Saved ${normalizedKind} → ${relPath}`, `  id: ${entry.id}`];
   if (title) parts.push(`  title: ${title}`);
   if (tags?.length) parts.push(`  tags: ${tags.join(", ")}`);
+  parts.push(`  tier: ${effectiveTier}`);
   parts.push("", "_Use this id to update or delete later._");
+  const hasBucketTag = (tags || []).some(
+    (t) => typeof t === "string" && t.startsWith("bucket:"),
+  );
+  if (tags && tags.length > 0 && !hasBucketTag) {
+    parts.push(
+      "",
+      "_Tip: Consider adding a `bucket:` tag (e.g., `bucket:myproject`) for project-scoped retrieval._",
+    );
+  }
+  const bucketTags = (tags || []).filter(
+    (t) => typeof t === "string" && t.startsWith("bucket:"),
+  );
+  for (const bt of bucketTags) {
+    const bucketUserClause = userId !== undefined ? "AND user_id = ?" : "";
+    const bucketParams =
+      userId !== undefined ? [bt, userId] : [bt];
+    const exists = ctx.db
+      .prepare(
+        `SELECT 1 FROM vault WHERE kind = 'bucket' AND identity_key = ? ${bucketUserClause} LIMIT 1`,
+      )
+      .get(...bucketParams);
+    if (!exists) {
+      parts.push(
+        ``,
+        `_Note: bucket '${bt}' is not registered. Use save_context(kind: "bucket", identity_key: "${bt}") to register it._`,
+      );
+    }
+  }
   if (similarEntries.length) {
-    parts.push(formatSimilarWarning(similarEntries));
+    if (suggestMode) {
+      const candidates = buildConflictCandidates(similarEntries);
+      parts.push(formatSimilarWarning(similarEntries));
+      parts.push(formatConflictSuggestions(candidates));
+    } else {
+      parts.push(formatSimilarWarning(similarEntries));
+    }
   }
 
   const criticalLimit = config.thresholds?.totalEntries?.critical;