@context-vault/core 2.17.0 → 2.17.1

package/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,

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

@@ -5,6 +5,8 @@ import { resolve } from "node:path";
 import { hybridSearch } from "../../retrieve/index.js";
 import { categoryFor } from "../../core/categories.js";
 import { normalizeKind } from "../../core/files.js";
+import { resolveTemporalParams } from "../../core/temporal.js";
+import { collectLinkedEntries } from "../../core/linking.js";
 import { ok, err } from "../helpers.js";
 import { isEmbedAvailable } from "../../index/embed.js";
 
@@ -152,8 +154,9 @@ export function detectConsolidationHints(entries, db, userId, opts = {}) {
   for (const tag of candidateTags) {
     let vaultCount = 0;
     try {
-      const userClause =
-        userId !== undefined ? " AND user_id = ?" : " AND user_id IS NULL";
+      // When userId is defined (hosted mode), scope to that user.
+      // When userId is undefined (local mode), no user scoping — column may not exist.
+      const userClause = userId !== undefined ? " AND user_id = ?" : "";
       const countParams =
         userId !== undefined ? [`%"${tag}"%`, userId] : [`%"${tag}"%`];
       const countRow = db
@@ -170,8 +173,7 @@ export function detectConsolidationHints(entries, db, userId, opts = {}) {
 
     let lastSnapshotAgeDays = null;
     try {
-      const userClause =
-        userId !== undefined ? " AND user_id = ?" : " AND user_id IS NULL";
+      const userClause = userId !== undefined ? " AND user_id = ?" : "";
       const params =
         userId !== undefined ? [`%"${tag}"%`, userId] : [`%"${tag}"%`];
       const recentBrief = db
@@ -280,11 +282,15 @@ export const inputSchema = {
   since: z
     .string()
     .optional()
-    .describe("ISO date, return entries created after this"),
+    .describe(
+      "Return entries created after this date. Accepts ISO date strings (e.g. '2025-01-01') or natural shortcuts: 'today', 'yesterday', 'this_week', 'this_month', 'last_3_days', 'last_2_weeks', 'last_1_month'. Spaces and underscores are interchangeable.",
+    ),
   until: z
     .string()
     .optional()
-    .describe("ISO date, return entries created before this"),
+    .describe(
+      "Return entries created before this date. Accepts ISO date strings or the same natural shortcuts as `since`. When `since` is 'yesterday' and `until` is omitted, `until` is automatically set to the end of yesterday.",
+    ),
   limit: z.number().optional().describe("Max results to return (default 10)"),
   include_superseded: z
     .boolean()
@@ -320,7 +326,19 @@ export const inputSchema = {
     .boolean()
     .optional()
     .describe(
-      "If true, include event category entries in semantic search results. Default: false — events are excluded from query-based search but remain accessible via category/tag filters.",
+      "If true, include event category entries in semantic search results. Default: false — events are excluded from query-based search but remain accessible via category/tag filters. Deprecated: prefer scope parameter.",
+    ),
+  scope: z
+    .enum(["hot", "events", "all"])
+    .optional()
+    .describe(
+      "Index scope: 'hot' (default) — knowledge + entity entries only; 'events' — event entries only (cold index); 'all' — entire vault including events. Overrides include_events when set.",
+    ),
+  follow_links: z
+    .boolean()
+    .optional()
+    .describe(
+      "If true, follow related_to links from result entries and include linked entries (forward links) and backlinks (entries that reference the results). Enables bidirectional graph traversal.",
     ),
 };
 
@@ -346,6 +364,8 @@ export async function handler(
     pivot_count,
     include_ephemeral,
     include_events,
+    scope,
+    follow_links,
   },
   ctx,
   { ensureIndexed, reindexFailed },
@@ -353,13 +373,37 @@ export async function handler(
   const { config } = ctx;
   const userId = ctx.userId !== undefined ? ctx.userId : undefined;
 
+  // Resolve natural-language temporal shortcuts → ISO date strings
+  const resolved = resolveTemporalParams({ since, until });
+  since = resolved.since;
+  until = resolved.until;
+
   const hasQuery = query?.trim();
-  const shouldExcludeEvents = hasQuery && !include_events && !category;
+
+  // Resolve effective scope — explicit scope param wins over include_events legacy flag.
+  // scope "hot" (default): knowledge + entity only — events excluded from search
+  // scope "events": force category filter to "event" (cold index query)
+  // scope "all": no category restriction — full vault
+  let effectiveScope = scope;
+  if (!effectiveScope) {
+    effectiveScope = include_events ? "all" : "hot";
+  }
+
+  // Scope "events" forces category to "event" unless caller already set a narrower category
+  const scopedCategory =
+    !category && effectiveScope === "events" ? "event" : category;
+  const shouldExcludeEvents =
+    hasQuery && effectiveScope === "hot" && !scopedCategory;
   // Expand buckets to bucket: prefixed tags and merge with explicit tags
   const bucketTags = buckets?.length ? buckets.map((b) => `bucket:${b}`) : [];
   const effectiveTags = [...(tags ?? []), ...bucketTags];
   const hasFilters =
-    kind || category || effectiveTags.length || since || until || identity_key;
+    kind ||
+    scopedCategory ||
+    effectiveTags.length ||
+    since ||
+    until ||
+    identity_key;
   if (!hasQuery && !hasFilters)
     return err(
       "Required: query or at least one filter (kind, category, tags, since, until, identity_key)",
@@ -373,11 +417,16 @@ export async function handler(
   if (identity_key) {
     if (!kindFilter)
       return err("identity_key requires kind to be specified", "INVALID_INPUT");
-    const match = ctx.stmts.getByIdentityKey.get(
-      kindFilter,
-      identity_key,
-      userId !== undefined ? userId : null,
-    );
+    // Local mode: getByIdentityKey takes 2 params (no user_id).
+    // Hosted mode: 3 params — (kind, identity_key, userId).
+    const match =
+      ctx.stmts._mode === "local"
+        ? ctx.stmts.getByIdentityKey.get(kindFilter, identity_key)
+        : ctx.stmts.getByIdentityKey.get(
+            kindFilter,
+            identity_key,
+            userId !== undefined ? userId : null,
+          );
     if (match) {
       const entryTags = match.tags ? JSON.parse(match.tags) : [];
       const tagStr = entryTags.length ? entryTags.join(", ") : "none";
@@ -398,7 +447,7 @@ export async function handler(
 
   // Gap 2: Event default time-window
   const effectiveCategory =
-    category || (kindFilter ? categoryFor(kindFilter) : null);
+    scopedCategory || (kindFilter ? categoryFor(kindFilter) : null);
   let effectiveSince = since || null;
   let effectiveUntil = until || null;
   let autoWindowed = false;
@@ -420,7 +469,7 @@ export async function handler(
     // Hybrid search mode
     const sorted = await hybridSearch(ctx, query, {
       kindFilter,
-      categoryFilter: category || null,
+      categoryFilter: scopedCategory || null,
       excludeEvents: shouldExcludeEvents,
       since: effectiveSince,
       until: effectiveUntil,
@@ -451,9 +500,9 @@ export async function handler(
       clauses.push("kind = ?");
       params.push(kindFilter);
     }
-    if (category) {
+    if (scopedCategory) {
       clauses.push("category = ?");
-      params.push(category);
+      params.push(scopedCategory);
     }
     if (effectiveSince) {
       clauses.push("created_at >= ?");
@@ -632,6 +681,45 @@ export async function handler(
     }
   }
 
+  // Graph traversal: follow related_to links bidirectionally
+  if (follow_links) {
+    const { forward, backward } = collectLinkedEntries(
+      ctx.db,
+      filtered,
+      userId,
+    );
+    const allLinked = [...forward, ...backward];
+    const seen = new Set();
+    const uniqueLinked = allLinked.filter((e) => {
+      if (seen.has(e.id)) return false;
+      seen.add(e.id);
+      return true;
+    });
+
+    if (uniqueLinked.length > 0) {
+      lines.push(`## Linked Entries (${uniqueLinked.length} via related_to)\n`);
+      for (const r of uniqueLinked) {
+        const direction = forward.some((f) => f.id === r.id)
+          ? "→ forward"
+          : "← backlink";
+        const entryTags = r.tags ? JSON.parse(r.tags) : [];
+        const tagStr = entryTags.length ? entryTags.join(", ") : "none";
+        const relPath =
+          r.file_path && config.vaultDir
+            ? r.file_path.replace(config.vaultDir + "/", "")
+            : r.file_path || "n/a";
+        lines.push(
+          `### ${r.title || "(untitled)"} [${r.kind}/${r.category}] ${direction}`,
+        );
+        lines.push(`${tagStr} · ${relPath} · id: \`${r.id}\``);
+        lines.push(r.body?.slice(0, 200) + (r.body?.length > 200 ? "..." : ""));
+        lines.push("");
+      }
+    } else {
+      lines.push(`## Linked Entries\n\nNo related entries found.\n`);
+    }
+  }
+
   // Consolidation suggestion detection — lazy, opportunistic, vault-wide
   const consolidationOpts = {
     tagThreshold:
@@ -661,6 +749,7 @@ export async function handler(
 
   const result = ok(lines.join("\n"));
   const meta = {};
+  meta.scope = effectiveScope;
   if (tokensBudget != null) {
     meta.tokens_used = tokensUsed;
     meta.tokens_budget = tokensBudget;
@@ -671,8 +760,6 @@ export async function handler(
   if (consolidationSuggestions.length > 0) {
     meta.consolidation_suggestions = consolidationSuggestions;
   }
-  if (Object.keys(meta).length > 0) {
-    result._meta = meta;
-  }
+  result._meta = meta;
   return result;
 }

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

@@ -5,6 +5,7 @@ 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";
+import { validateRelatedTo } from "../../core/linking.js";
 import {
   MAX_BODY_LENGTH,
   MAX_TITLE_LENGTH,
@@ -43,9 +44,15 @@ async function findSimilar(
 
     const rowids = vecRows.map((vr) => vr.rowid);
     const placeholders = rowids.map(() => "?").join(",");
-    const columns = hydrate
-      ? "rowid, id, title, body, kind, tags, category, user_id, updated_at"
-      : "rowid, id, title, category, user_id";
+    // Local mode has no user_id column — omit it from the SELECT list.
+    const isLocal = ctx.stmts._mode === "local";
+    const columns = isLocal
+      ? hydrate
+        ? "rowid, id, title, body, kind, tags, category, updated_at"
+        : "rowid, id, title, category"
+      : 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);
@@ -59,7 +66,7 @@ async function findSimilar(
       if (similarity < threshold) continue;
       const row = byRowid.get(vr.rowid);
       if (!row) continue;
-      if (userId !== undefined && row.user_id !== userId) continue;
+      if (!isLocal && userId !== undefined && row.user_id !== userId) continue;
       if (row.category === "entity") continue;
       const entry = { id: row.id, title: row.title, score: similarity };
       if (hydrate) {
@@ -294,6 +301,12 @@ 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.",
     ),
+  related_to: z
+    .array(z.string())
+    .optional()
+    .describe(
+      "Array of entry IDs this entry is related to. Enables bidirectional graph traversal — use get_context with follow_links:true to retrieve linked entries.",
+    ),
   source_files: z
     .array(
       z.object({
@@ -359,6 +372,7 @@ export async function handler(
     identity_key,
     expires_at,
     supersedes,
+    related_to,
     source_files,
     dry_run,
     similarity_threshold,
@@ -375,6 +389,9 @@ export async function handler(
   const vaultErr = ensureVaultExists(config);
   if (vaultErr) return vaultErr;
 
+  const relatedToErr = validateRelatedTo(related_to);
+  if (relatedToErr) return err(relatedToErr, "INVALID_INPUT");
+
   const inputErr = validateSaveInput({
     kind,
     title,
@@ -428,9 +445,15 @@ export async function handler(
       source,
       expires_at,
       supersedes,
+      related_to,
       source_files,
     });
     await indexEntry(ctx, entry);
+    if (entry.related_to?.length && ctx.stmts.updateRelatedTo) {
+      ctx.stmts.updateRelatedTo.run(JSON.stringify(entry.related_to), entry.id);
+    } else if (entry.related_to === null && ctx.stmts.updateRelatedTo) {
+      ctx.stmts.updateRelatedTo.run(null, entry.id);
+    }
     const relPath = entry.filePath
       ? entry.filePath.replace(config.vaultDir + "/", "")
       : entry.filePath;
@@ -531,6 +554,7 @@ export async function handler(
     identity_key,
     expires_at,
     supersedes,
+    related_to,
     source_files,
     userId,
     tier: effectiveTier,
@@ -562,8 +586,7 @@ export async function handler(
   );
   for (const bt of bucketTags) {
     const bucketUserClause = userId !== undefined ? "AND user_id = ?" : "";
-    const bucketParams =
-      userId !== undefined ? [bt, userId] : [bt];
+    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`,

package/src/server/tools.js

@@ -8,7 +8,6 @@ import * as getContext from "./tools/get-context.js";
 import * as saveContext from "./tools/save-context.js";
 import * as listContext from "./tools/list-context.js";
 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";
@@ -22,7 +21,6 @@ const toolModules = [
   saveContext,
   listContext,
   deleteContext,
-  submitFeedback,
   ingestUrl,
   ingestProject,
   contextStatus,

package/src/server/tools/submit-feedback.js

@@ -1,55 +0,0 @@
-import { z } from "zod";
-import { captureAndIndex } from "../../capture/index.js";
-import { ok, ensureVaultExists } from "../helpers.js";
-
-export const name = "submit_feedback";
-
-export const description =
-  "Report a bug, request a feature, or suggest an improvement. Feedback is stored in the vault and triaged by the development pipeline.";
-
-export const inputSchema = {
-  type: z.enum(["bug", "feature", "improvement"]).describe("Type of feedback"),
-  title: z.string().describe("Short summary of the feedback"),
-  body: z.string().describe("Detailed description"),
-  severity: z
-    .enum(["low", "medium", "high"])
-    .optional()
-    .describe("Severity level (default: medium)"),
-};
-
-/**
- * @param {object} args
- * @param {import('../types.js').BaseCtx & Partial<import('../types.js').HostedCtxExtensions>} ctx
- * @param {import('../types.js').ToolShared} shared
- */
-export async function handler(
-  { type, title, body, severity },
-  ctx,
-  { ensureIndexed },
-) {
-  const { config } = ctx;
-  const userId = ctx.userId !== undefined ? ctx.userId : undefined;
-
-  const vaultErr = ensureVaultExists(config);
-  if (vaultErr) return vaultErr;
-
-  await ensureIndexed();
-
-  const effectiveSeverity = severity || "medium";
-  const entry = await captureAndIndex(ctx, {
-    kind: "feedback",
-    title,
-    body,
-    tags: [type, effectiveSeverity],
-    source: "submit_feedback",
-    meta: { feedback_type: type, severity: effectiveSeverity, status: "new" },
-    userId,
-  });
-
-  const relPath = entry.filePath
-    ? entry.filePath.replace(config.vaultDir + "/", "")
-    : entry.filePath;
-  return ok(
-    `Feedback submitted: ${type} [${effectiveSeverity}] → ${relPath}\n  id: ${entry.id}\n  title: ${title}`,
-  );
-}