@context-vault/core 2.15.0 → 2.17.1

package/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
@@ -74,6 +72,7 @@ export function recencyBoost(createdAt, category, decayDays = 30) {
  */
 export function buildFilterClauses({
   categoryFilter,
+  excludeEvents = false,
   since,
   until,
   userIdFilter,
@@ -94,6 +93,9 @@ export function buildFilterClauses({
     clauses.push("e.category = ?");
     params.push(categoryFilter);
   }
+  if (excludeEvents && !categoryFilter) {
+    clauses.push("e.category != 'event'");
+  }
   if (since) {
     clauses.push("e.created_at >= ?");
     params.push(since);
@@ -128,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
@@ -242,6 +152,7 @@ export async function hybridSearch(
   {
     kindFilter = null,
     categoryFilter = null,
+    excludeEvents = false,
     since = null,
     until = null,
     limit = 20,
@@ -258,6 +169,7 @@ export async function hybridSearch(
 
   const extraFilters = buildFilterClauses({
     categoryFilter,
+    excludeEvents,
     since,
     until,
     userIdFilter,
@@ -340,6 +252,7 @@ export async function hybridSearch(
             if (teamIdFilter && row.team_id !== teamIdFilter) continue;
             if (kindFilter && row.kind !== kindFilter) continue;
             if (categoryFilter && row.category !== categoryFilter) continue;
+            if (excludeEvents && row.category === "event") continue;
             if (since && row.created_at < since) continue;
             if (until && row.created_at > until) continue;
             if (row.expires_at && new Date(row.expires_at) <= new Date())
@@ -376,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,
@@ -397,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();
@@ -422,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) {
@@ -468,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/src/server/tools/context-status.js

@@ -146,6 +146,13 @@ export function handler(_args, ctx) {
     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) {

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()
@@ -316,6 +322,24 @@ export const inputSchema = {
     .describe(
       "If true, include ephemeral tier entries in results. Default: false — only working and durable tiers are returned.",
     ),
+  include_events: z
+    .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. 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.",
+    ),
 };
 
 /**
@@ -339,6 +363,9 @@ export async function handler(
     max_tokens,
     pivot_count,
     include_ephemeral,
+    include_events,
+    scope,
+    follow_links,
   },
   ctx,
   { ensureIndexed, reindexFailed },
@@ -346,12 +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();
+
+  // 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)",
@@ -365,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";
@@ -390,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;
@@ -412,7 +469,8 @@ 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,
       limit: fetchLimit,
@@ -442,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 >= ?");
@@ -490,6 +548,11 @@ export async function handler(
     filtered = filtered.filter((r) => r.tier !== "ephemeral");
   }
 
+  // Event category filter: exclude events from semantic search by default
+  if (shouldExcludeEvents) {
+    filtered = filtered.filter((r) => r.category !== "event");
+  }
+
   if (!filtered.length) {
     if (autoWindowed) {
       const days = config.eventDecayDays || 30;
@@ -618,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:
@@ -647,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;
@@ -657,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;
 }