context-vault 3.4.3 → 3.4.5

package/src/tools/get-context.ts

@@ -2,12 +2,13 @@ import { z } from 'zod';
 import { createHash } from 'node:crypto';
 import { readFileSync, existsSync } from 'node:fs';
 import { resolve } from 'node:path';
-import { hybridSearch } from '@context-vault/core/search';
+import { hybridSearch, trackAccess } from '@context-vault/core/search';
 import { categoryFor } from '@context-vault/core/categories';
 import { normalizeKind } from '@context-vault/core/files';
+import { parseContextParam } from '@context-vault/core/context';
 import { resolveTemporalParams } from '../temporal.js';
 import { collectLinkedEntries } from '../linking.js';
-import { ok, err, errWithHint } from '../helpers.js';
+import { ok, err, errWithHint, kindIcon, fmtDate } from '../helpers.js';
 import { isEmbedAvailable } from '@context-vault/core/embed';
 import type { LocalCtx, SharedCtx, ToolResult } from '../types.js';
 
@@ -346,6 +347,12 @@ export const inputSchema = {
     .describe(
       'When true with identity_key, return a clear "not found" instead of falling through to semantic search on miss. Default: false.'
     ),
+  context: z
+    .any()
+    .optional()
+    .describe(
+      'Current context for contextual reinstatement. Boosts entries that were saved in a similar context. Pass a structured object (e.g. { project: "myapp", arc: "auth-rewrite", task: "debugging token expiry" }) or a free-text string. Entries saved with matching encoding_context will rank higher.'
+    ),
 };
 
 export async function handler(
@@ -369,6 +376,7 @@ export async function handler(
     follow_links,
     body_limit,
     strict,
+    context,
   }: Record<string, any>,
   ctx: LocalCtx,
   { ensureIndexed, reindexFailed }: SharedCtx
@@ -413,6 +421,7 @@ export async function handler(
     if (!kindFilter) return err('identity_key requires kind to be specified', 'INVALID_INPUT');
     const match = ctx.stmts.getByIdentityKey.get(kindFilter, identity_key) as any;
     if (match) {
+      trackAccess(ctx, [{ ...match, score: 1 }]);
       const entryTags = match.tags ? JSON.parse(match.tags) : [];
       const tagStr = entryTags.length ? entryTags.join(', ') : 'none';
       const relPath =
@@ -452,6 +461,17 @@ export async function handler(
     ? Math.min(effectiveLimit * 10, MAX_FETCH_LIMIT)
     : effectiveLimit;
 
+  // Generate context embedding for contextual reinstatement boosting
+  let contextEmbedding: Float32Array | null = null;
+  const parsedCtx = parseContextParam(context);
+  if (parsedCtx?.text) {
+    try {
+      contextEmbedding = await ctx.embed(parsedCtx.text);
+    } catch {
+      // Non-fatal: proceed without context boosting
+    }
+  }
+
   let filtered: any[];
   if (hasQuery) {
     // Hybrid search mode
@@ -465,6 +485,7 @@ export async function handler(
       decayDays: config.eventDecayDays || 30,
       includeSuperseeded: include_superseded ?? false,
       includeEphemeral: include_ephemeral ?? false,
+      contextEmbedding,
     });
 
     // Post-filter by tags if provided, then apply requested limit
@@ -532,6 +553,9 @@ export async function handler(
 
     // Add score field for consistent output
     for (const r of filtered) r.score = 0;
+
+    // Track access for filter-only results (hybrid search tracks its own)
+    trackAccess(ctx, filtered);
   }
 
   // Brief score boost: briefs rank slightly higher so consolidated snapshots
@@ -609,23 +633,24 @@ export async function handler(
     const r = filtered[i];
     const isSkeleton = i >= effectivePivot;
     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';
-    const skeletonLabel = isSkeleton ? ' ⊘ skeleton' : '';
-    lines.push(
-      `### [${i + 1}/${filtered.length}] ${r.title || '(untitled)'} [${r.kind}/${r.category}]${skeletonLabel}`
-    );
-    const dateStr =
-      r.updated_at && r.updated_at !== r.created_at
-        ? `${r.created_at} (updated ${r.updated_at})`
-        : r.created_at || '';
-    const tierStr = r.tier ? ` · tier: ${r.tier}` : '';
+    const tagStr = entryTags.length ? entryTags.join(', ') : '';
+    const icon = kindIcon(r.kind);
+    const skeletonLabel = isSkeleton ? ' `skeleton`' : '';
+    const tierLabel = r.tier ? `**${r.tier}**` : '';
+    const dateStr = r.updated_at && r.updated_at !== r.created_at
+      ? `${fmtDate(r.created_at)} (upd ${fmtDate(r.updated_at)})`
+      : fmtDate(r.created_at);
     lines.push(
-      `${r.score.toFixed(3)} · ${tagStr} · ${relPath} · ${dateStr} · skeleton: ${isSkeleton}${tierStr} · id: \`${r.id}\``
+      `### ${icon} ${r.title || '(untitled)'}${skeletonLabel}`
     );
+    const meta = [
+      `\`${r.score.toFixed(2)}\``,
+      `\`${r.kind}\``,
+      tierLabel,
+      tagStr,
+      dateStr,
+    ].filter(Boolean).join(' · ');
+    lines.push(`${meta}  \nid: \`${r.id}\``);
     const stalenessResult = checkStaleness(r);
     if (stalenessResult) {
       r.stale = true;
@@ -667,15 +692,13 @@ export async function handler(
     if (uniqueLinked.length > 0) {
       lines.push(`## Linked Entries (${uniqueLinked.length} via related_to)\n`);
       for (const r of uniqueLinked) {
-        const direction = forward.some((f: any) => f.id === r.id) ? '→ forward' : '← backlink';
+        const direction = forward.some((f: any) => f.id === r.id) ? '→' : '←';
         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}\``);
+        const tagStr = entryTags.length ? entryTags.join(', ') : '';
+        const icon = kindIcon(r.kind);
+        lines.push(`### ${icon} ${r.title || '(untitled)'} ${direction}`);
+        const meta = [`\`${r.kind}\``, tagStr].filter(Boolean).join(' · ');
+        lines.push(`${meta}  \nid: \`${r.id}\``);
         lines.push(truncateBody(r.body, body_limit ?? 300));
         lines.push('');
       }

package/src/tools/list-context.ts

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 import { normalizeKind } from '@context-vault/core/files';
 import { categoryFor } from '@context-vault/core/categories';
-import { ok, err, errWithHint } from '../helpers.js';
+import { ok, err, errWithHint, kindIcon, fmtDate } from '../helpers.js';
 import { resolveTemporalParams } from '../temporal.js';
 import type { LocalCtx, SharedCtx, ToolResult } from '../types.js';
 
@@ -124,18 +124,15 @@ export async function handler(
       `> ℹ Event search limited to last ${days} days. Use \`since\` parameter for older results.\n`
     );
   }
+  lines.push('| | Title | Kind | Tags | Date | ID |');
+  lines.push('|---|---|---|---|---|---|');
   for (const r of filtered) {
     const entryTags = r.tags ? JSON.parse(r.tags) : [];
-    const tagStr = entryTags.length ? entryTags.join(', ') : 'none';
-    const dateStr =
-      r.updated_at && r.updated_at !== r.created_at
-        ? `${r.created_at} (updated ${r.updated_at})`
-        : r.created_at;
-    lines.push(
-      `- **${r.title || '(untitled)'}** [${r.kind}/${r.category}] — ${tagStr} — ${dateStr} — \`${r.id}\``
-    );
-    if (r.preview)
-      lines.push(`  ${r.preview.replace(/\n+/g, ' ').trim()}${r.preview.length >= 120 ? '…' : ''}`);
+    const tagStr = entryTags.length ? entryTags.join(', ') : '';
+    const date = fmtDate(r.updated_at && r.updated_at !== r.created_at ? r.updated_at : r.created_at);
+    const icon = kindIcon(r.kind);
+    const title = (r.title || '(untitled)').replace(/\|/g, '\\|');
+    lines.push(`| ${icon} | **${title}** | \`${r.kind}\` | ${tagStr} | ${date} | \`${r.id}\` |`);
   }
 
   if (effectiveOffset + effectiveLimit < total) {

package/src/tools/save-context.ts

@@ -3,7 +3,8 @@ import { captureAndIndex, updateEntryFile } from '@context-vault/core/capture';
 import { indexEntry } from '@context-vault/core/index';
 import { categoryFor, defaultTierFor } from '@context-vault/core/categories';
 import { normalizeKind } from '@context-vault/core/files';
-import { ok, err, errWithHint, ensureVaultExists, ensureValidKind } from '../helpers.js';
+import { parseContextParam } from '@context-vault/core/context';
+import { ok, err, errWithHint, ensureVaultExists, ensureValidKind, kindIcon } from '../helpers.js';
 import { maybeShowFeedbackPrompt } from '../telemetry.js';
 import { validateRelatedTo } from '../linking.js';
 import type { LocalCtx, SharedCtx, ToolResult } from '../types.js';
@@ -81,13 +82,13 @@ async function findSimilar(
 }
 
 function formatSimilarWarning(similar: any[]): string {
-  const lines = ['', '⚠ Similar entries already exist:'];
+  const lines = ['', '### ⚠ Similar entries'];
   for (const e of similar) {
-    const score = e.score.toFixed(2);
-    const title = e.title ? `"${e.title}"` : '(no title)';
-    lines.push(`  - ${title} (${score}) — id: ${e.id}`);
+    const score = (e.score * 100).toFixed(0);
+    const title = e.title ? `**${e.title}**` : '(no title)';
+    lines.push(`- ${title} \`${score}%\` · \`${e.id}\``);
   }
-  lines.push('  Consider using `id: <existing>` in save_context to update instead.');
+  lines.push('_Use `id` param to update instead of creating a duplicate._');
   return lines.join('\n');
 }
 
@@ -141,13 +142,12 @@ export function buildConflictCandidates(similarEntries: any[]): any[] {
 }
 
 function formatConflictSuggestions(candidates: any[]): string {
-  const lines = ['', '── Conflict Resolution Suggestions ──'];
+  const lines = ['', '### Conflict Resolution'];
   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}`);
+    const titleDisplay = c.title ? `**${c.title}**` : '(no title)';
+    const actionIcon = c.suggested_action === 'SKIP' ? '⊘' : c.suggested_action === 'UPDATE' ? '↻' : '＋';
+    lines.push(`${actionIcon} **${c.suggested_action}** ${titleDisplay} \`${(c.score * 100).toFixed(0)}%\` · \`${c.id}\``);
+    lines.push(`  ${c.reasoning_context}`);
   }
   return lines.join('\n');
 }
@@ -310,6 +310,12 @@ export const inputSchema = {
     .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).'
     ),
+  encoding_context: z
+    .any()
+    .optional()
+    .describe(
+      'Encoding context for contextual reinstatement. Captures the situation when this entry was created, enabling context-aware retrieval boosting. Pass a structured object (e.g. { project: "myapp", arc: "auth-rewrite", task: "implementing JWT" }) or a free-text string describing the current context.'
+    ),
 };
 
 export async function handler(
@@ -331,6 +337,7 @@ export async function handler(
     similarity_threshold,
     tier,
     conflict_resolution,
+    encoding_context,
   }: Record<string, any>,
   ctx: LocalCtx,
   { ensureIndexed }: SharedCtx
@@ -388,13 +395,21 @@ export async function handler(
       );
     }
 
+    // Merge encoding context into meta for update path
+    const updateParsedCtx = parseContextParam(encoding_context);
+    let updateMeta = meta;
+    if (updateParsedCtx) {
+      updateMeta = { ...(meta || {}) };
+      updateMeta.encoding_context = updateParsedCtx.structured || updateParsedCtx.text;
+    }
+
     let entry;
     try {
       entry = updateEntryFile(ctx, existing, {
         title,
         body,
         tags,
-        meta,
+        meta: updateMeta,
         source,
         expires_at,
         supersedes,
@@ -409,6 +424,24 @@ export async function handler(
         'context-vault save_context update is failing. Check `cat ~/.context-mcp/error.log | tail -5` and help me debug.'
       );
     }
+
+    // Store context embedding for updated entry
+    if (updateParsedCtx?.text) {
+      try {
+        const ctxEmbed = await ctx.embed(updateParsedCtx.text);
+        if (ctxEmbed) {
+          const rowidResult = ctx.stmts.getRowid.get(entry.id) as { rowid: number } | undefined;
+          if (rowidResult?.rowid) {
+            const rowid = Number(rowidResult.rowid);
+            try { ctx.deleteCtxVec(rowid); } catch {}
+            ctx.insertCtxVec(rowid, ctxEmbed);
+          }
+        }
+      } catch (e) {
+        console.warn(`[context-vault] Context embedding update failed: ${(e as Error).message}`);
+      }
+    }
+
     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) {
@@ -502,6 +535,15 @@ export async function handler(
 
   const mergedMeta = { ...(meta || {}) };
   if (folder) mergedMeta.folder = folder;
+
+  // Merge encoding context into meta for persistence
+  const parsedCtx = parseContextParam(encoding_context);
+  if (parsedCtx?.structured) {
+    mergedMeta.encoding_context = parsedCtx.structured;
+  } else if (parsedCtx?.text) {
+    mergedMeta.encoding_context = parsedCtx.text;
+  }
+
   const finalMeta = Object.keys(mergedMeta).length ? mergedMeta : undefined;
 
   const effectiveTier = tier ?? defaultTierFor(normalizedKind);
@@ -538,6 +580,24 @@ export async function handler(
     );
   }
 
+  // Store context embedding in vault_ctx_vec for contextual reinstatement
+  if (parsedCtx?.text && entry) {
+    try {
+      const ctxEmbedding = await ctx.embed(parsedCtx.text);
+      if (ctxEmbedding) {
+        const rowidResult = ctx.stmts.getRowid.get(entry.id) as { rowid: number } | undefined;
+        if (rowidResult?.rowid) {
+          const rowid = Number(rowidResult.rowid);
+          try { ctx.deleteCtxVec(rowid); } catch {}
+          ctx.insertCtxVec(rowid, ctxEmbedding);
+        }
+      }
+    } catch (e) {
+      // Non-fatal: context embedding failure should not block the save
+      console.warn(`[context-vault] Context embedding failed: ${(e as Error).message}`);
+    }
+  }
+
   if (ctx.config?.dataDir) {
     maybeShowFeedbackPrompt(ctx.config.dataDir);
   }
@@ -545,11 +605,19 @@ export async function handler(
   const relPath = entry.filePath
     ? entry.filePath.replace(config.vaultDir + '/', '')
     : entry.filePath;
-  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 icon = kindIcon(normalizedKind);
+  const parts = [
+    `## ✓ Saved`,
+    `${icon} **${title || '(untitled)'}**`,
+    `\`${normalizedKind}\` · **${effectiveTier}**${tags?.length ? ` · ${tags.join(', ')}` : ''}`,
+    `\`${entry.id}\` → ${relPath}`,
+  ];
+  if (effectiveTier === 'ephemeral') {
+    parts.push(
+      '',
+      '_Note: ephemeral entries are excluded from default search. Use `include_ephemeral: true` in get_context to find them._'
+    );
+  }
   const hasBucketTag = (tags || []).some(
     (t: any) => typeof t === 'string' && t.startsWith('bucket:')
   );
@@ -563,18 +631,25 @@ export async function handler(
     (t: any) => typeof t === 'string' && t.startsWith('bucket:')
   );
   for (const bt of bucketTags) {
-    const bucketUserClause = '';
-    const bucketParams = false ? [bt] : [bt];
     const exists = ctx.db
       .prepare(
-        `SELECT 1 FROM vault WHERE kind = 'bucket' AND identity_key = ? ${bucketUserClause} LIMIT 1`
+        `SELECT 1 FROM vault WHERE kind = 'bucket' AND identity_key = ? LIMIT 1`
       )
-      .get(...bucketParams);
+      .get(bt);
     if (!exists) {
-      parts.push(
-        ``,
-        `_Note: bucket '${bt}' is not registered. Use save_context(kind: "bucket", identity_key: "${bt}") to register it._`
-      );
+      // Auto-register the bucket silently
+      const bucketName = bt.replace(/^bucket:/, '');
+      try {
+        await captureAndIndex(ctx, {
+          kind: 'bucket',
+          title: bucketName,
+          body: `Bucket for project: ${bucketName}`,
+          tags: [bt],
+          identity_key: bt,
+        });
+      } catch {
+        // Non-fatal: bucket registration failure should not block the save
+      }
     }
   }
   if (similarEntries.length) {

package/src/tools/session-start.ts

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { execSync } from 'node:child_process';
-import { ok, err, ensureVaultExists } from '../helpers.js';
+import { readdirSync } from 'node:fs';
+import { ok, err, ensureVaultExists, kindIcon, fmtDate } from '../helpers.js';
 import type { LocalCtx, SharedCtx, ToolResult } from '../types.js';
 
 const DEFAULT_MAX_TOKENS = 4000;
@@ -67,11 +68,13 @@ function estimateTokens(text: string | null | undefined): number {
 
 function formatEntry(entry: any): string {
   const tags = entry.tags ? JSON.parse(entry.tags) : [];
-  const tagStr = tags.length ? tags.join(', ') : 'none';
-  const date = entry.updated_at || entry.created_at || 'unknown';
+  const tagStr = tags.length ? tags.join(', ') : '';
+  const date = fmtDate(entry.updated_at || entry.created_at);
+  const icon = kindIcon(entry.kind);
+  const meta = [`\`${entry.kind}\``, tagStr, date].filter(Boolean).join(' · ');
   return [
-    `- **${entry.title || '(untitled)'}** [${entry.kind}]`,
-    `  tags: ${tagStr} | ${date} | id: \`${entry.id}\``,
+    `- ${icon} **${entry.title || '(untitled)'}**`,
+    `  ${meta} · \`${entry.id}\``,
     `  ${truncateBody(entry.body).replace(/\n+/g, ' ').trim()}`,
   ].join('\n');
 }
@@ -88,6 +91,30 @@ export async function handler(
 
   await ensureIndexed();
 
+  // Sanity check: compare DB entries vs disk files
+  let indexWarning = '';
+  try {
+    const dbCount = (ctx.db.prepare('SELECT COUNT(*) as cnt FROM vault').get() as any)?.cnt ?? 0;
+    let diskCount = 0;
+    const walk = (dir: string, depth = 0) => {
+      if (depth > 3 || diskCount >= 100) return;
+      try {
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+          if (diskCount >= 100) return;
+          if (entry.isDirectory() && !entry.name.startsWith('.') && entry.name !== '_archive') {
+            walk(`${dir}/${entry.name}`, depth + 1);
+          } else if (entry.name.endsWith('.md')) {
+            diskCount++;
+          }
+        }
+      } catch {}
+    };
+    walk(config.vaultDir);
+    if (diskCount >= 100 && dbCount < diskCount / 10) {
+      indexWarning = `\n> **WARNING:** Vault has significantly more files on disk (~${diskCount}+) than indexed entries (${dbCount}). The search index may be out of sync. Run \`context-vault reconnect\` to fix.\n`;
+    }
+  } catch {}
+
   const effectiveProject = project?.trim() || detectProject();
   const tokenBudget = max_tokens || DEFAULT_MAX_TOKENS;
 
@@ -175,6 +202,10 @@ export async function handler(
       return true;
     }).length;
 
+  if (indexWarning) {
+    sections.push(indexWarning);
+  }
+
   sections.push('---');
   sections.push(
     `_${tokensUsed} / ${tokenBudget} tokens used | project: ${effectiveProject || 'unscoped'}_`