context-vault 3.5.1 → 3.7.0

package/src/tools/clear-context.ts

@@ -1,6 +1,11 @@
 import { z } from 'zod';
-import { ok } from '../helpers.js';
-import type { ToolResult } from '../types.js';
+import { ok, ensureVaultExists, kindIcon, fmtDate } from '../helpers.js';
+import type { LocalCtx, SharedCtx, ToolResult } from '../types.js';
+
+const DEFAULT_PRELOAD_TOKENS = 2000;
+const MAX_BODY_PER_ENTRY = 300;
+const RECENT_DAYS = 7;
+const PRIORITY_KINDS = ['decision', 'insight', 'pattern'];
 
 export const name = 'clear_context';
 
@@ -14,28 +19,208 @@ export const inputSchema = {
     .describe(
       'Optional tag or project name to focus on going forward. When provided, treat subsequent get_context calls as if filtered to this tag.'
     ),
+  preload_bucket: z
+    .string()
+    .optional()
+    .describe(
+      'Bucket name to preload context from after clearing. Loads recent decisions, insights, and patterns scoped to this bucket into the response so the agent has immediate context for the new project.'
+    ),
+  max_tokens: z
+    .number()
+    .optional()
+    .describe(
+      'Token budget for preloaded context (rough estimate: 1 token ~ 4 chars). Default: 2000. Only applies when preload_bucket is set.'
+    ),
 };
 
-export function handler({ scope }: { scope?: string } = {}): ToolResult {
+function estimateTokens(text: string | null | undefined): number {
+  return Math.ceil((text || '').length / 4);
+}
+
+function truncateBody(body: string | null | undefined, maxLen = MAX_BODY_PER_ENTRY): string {
+  if (!body) return '(no body)';
+  if (body.length <= maxLen) return body;
+  return body.slice(0, maxLen) + '...';
+}
+
+function formatEntry(entry: any): string {
+  const tags = entry.tags ? JSON.parse(entry.tags) : [];
+  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 [
+    `- ${icon} **${entry.title || '(untitled)'}**`,
+    `  ${meta} · \`${entry.id}\``,
+    `  ${truncateBody(entry.body).replace(/\n+/g, ' ').trim()}`,
+  ].join('\n');
+}
+
+function preloadBucketContext(
+  ctx: LocalCtx,
+  bucket: string,
+  tokenBudget: number
+): { sections: string[]; tokensUsed: number; entryCount: number } {
+  const sections: string[] = [];
+  let tokensUsed = 0;
+  let entryCount = 0;
+
+  const bucketTag = `bucket:${bucket}`;
+  const sinceDate = new Date(Date.now() - RECENT_DAYS * 86400000).toISOString();
+
+  // Query priority kinds (decisions, insights, patterns)
+  const kindPlaceholders = PRIORITY_KINDS.map(() => '?').join(',');
+  const priorityRows = ctx.db
+    .prepare(
+      `SELECT * FROM vault
+       WHERE kind IN (${kindPlaceholders})
+         AND created_at >= ?
+         AND (expires_at IS NULL OR expires_at > datetime('now'))
+         AND superseded_by IS NULL
+       ORDER BY created_at DESC
+       LIMIT 30`
+    )
+    .all(...PRIORITY_KINDS, sinceDate) as any[];
+
+  // Filter to bucket-tagged entries
+  const taggedPriority = priorityRows.filter((r: any) => {
+    const tags = r.tags ? JSON.parse(r.tags) : [];
+    return tags.includes(bucketTag);
+  });
+
+  if (taggedPriority.length > 0) {
+    const header = '### Active Decisions, Insights & Patterns\n';
+    const headerTokens = estimateTokens(header);
+    if (tokensUsed + headerTokens <= tokenBudget) {
+      const entryLines: string[] = [];
+      tokensUsed += headerTokens;
+      for (const entry of taggedPriority) {
+        const line = formatEntry(entry);
+        const lineTokens = estimateTokens(line);
+        if (tokensUsed + lineTokens > tokenBudget) break;
+        entryLines.push(line);
+        tokensUsed += lineTokens;
+        entryCount++;
+      }
+      if (entryLines.length > 0) {
+        sections.push(header + entryLines.join('\n'));
+      }
+    }
+  }
+
+  // Query recent entries (any kind)
+  const recentRows = ctx.db
+    .prepare(
+      `SELECT * FROM vault
+       WHERE created_at >= ?
+         AND (expires_at IS NULL OR expires_at > datetime('now'))
+         AND superseded_by IS NULL
+       ORDER BY created_at DESC
+       LIMIT 30`
+    )
+    .all(sinceDate) as any[];
+
+  const seenIds = new Set(taggedPriority.map((r: any) => r.id));
+  const taggedRecent = recentRows.filter((r: any) => {
+    if (seenIds.has(r.id)) return false;
+    const tags = r.tags ? JSON.parse(r.tags) : [];
+    return tags.includes(bucketTag);
+  });
+
+  if (taggedRecent.length > 0) {
+    const header = `\n### Recent Entries (last ${RECENT_DAYS} days)\n`;
+    const headerTokens = estimateTokens(header);
+    if (tokensUsed + headerTokens <= tokenBudget) {
+      const entryLines: string[] = [];
+      tokensUsed += headerTokens;
+      for (const entry of taggedRecent) {
+        const line = formatEntry(entry);
+        const lineTokens = estimateTokens(line);
+        if (tokensUsed + lineTokens > tokenBudget) break;
+        entryLines.push(line);
+        tokensUsed += lineTokens;
+        entryCount++;
+      }
+      if (entryLines.length > 0) {
+        sections.push(header + entryLines.join('\n'));
+      }
+    }
+  }
+
+  return { sections, tokensUsed, entryCount };
+}
+
+export async function handler(
+  { scope, preload_bucket, max_tokens }: { scope?: string; preload_bucket?: string; max_tokens?: number } = {},
+  ctx?: LocalCtx,
+  shared?: SharedCtx
+): Promise<ToolResult> {
   const lines = [
     '## Context Reset',
     '',
     'Active session context has been cleared. All previous context from this session should be disregarded.',
     '',
-    'Vault entries are unchanged — no data was deleted.',
+    'Vault entries are unchanged -- no data was deleted.',
   ];
 
-  if (scope?.trim()) {
-    const trimmed = scope.trim();
+  const trimmedScope = scope?.trim() || '';
+  // If preload_bucket is set but scope is not, infer scope from the bucket
+  const effectiveScope = trimmedScope || preload_bucket?.trim() || '';
+
+  if (effectiveScope) {
     lines.push(
       '',
-      `### Active Scope: \`${trimmed}\``,
+      `### Active Scope: \`${effectiveScope}\``,
       '',
-      `Going forward, treat \`get_context\` calls as scoped to the tag or project **"${trimmed}"** unless the user explicitly requests a different scope or passes their own tag filters.`
+      `Going forward, treat \`get_context\` calls as scoped to the tag or project **"${effectiveScope}"** unless the user explicitly requests a different scope or passes their own tag filters.`
     );
   } else {
-    lines.push('', 'No scope set. Use `get_context` normally — all vault entries are accessible.');
+    lines.push('', 'No scope set. Use `get_context` normally -- all vault entries are accessible.');
+  }
+
+  // Preload bucket context if requested and ctx is available
+  const bucket = preload_bucket?.trim();
+  let preloadMeta: Record<string, unknown> = {};
+  if (bucket && ctx) {
+    const vaultErr = ensureVaultExists(ctx.config);
+    if (vaultErr) {
+      lines.push('', `> **Warning:** Could not preload bucket context: vault not found.`);
+    } else {
+      if (shared?.ensureIndexed) {
+        await shared.ensureIndexed({ blocking: false });
+      }
+
+      const tokenBudget = max_tokens || DEFAULT_PRELOAD_TOKENS;
+      const { sections, tokensUsed, entryCount } = preloadBucketContext(ctx, bucket, tokenBudget);
+
+      if (sections.length > 0) {
+        lines.push(
+          '',
+          `## Preloaded Context: \`${bucket}\``,
+          `_${entryCount} entries | ${tokensUsed} / ${tokenBudget} tokens used_`,
+          '',
+          ...sections
+        );
+      } else {
+        lines.push(
+          '',
+          `_No recent entries found in bucket \`${bucket}\`. Use \`get_context\` to search across all entries._`
+        );
+      }
+
+      preloadMeta = {
+        preload_bucket: bucket,
+        preload_entries: entryCount,
+        preload_tokens_used: tokensUsed,
+        preload_tokens_budget: tokenBudget,
+      };
+    }
   }
 
-  return ok(lines.join('\n'));
+  const result: ToolResult = ok(lines.join('\n'));
+  result._meta = {
+    scope: effectiveScope || null,
+    ...preloadMeta,
+  };
+  return result;
 }

package/src/tools/context-status.ts

@@ -14,6 +14,47 @@ function relativeTime(ts: number): string {
   return `${hrs} hour${hrs === 1 ? '' : 's'} ago`;
 }
 
+interface LearningRate {
+  saved7d: number;
+  saved30d: number;
+  sessions30d: number;
+  savesPerSession: string;
+  recalls30d: number;
+  recallToSaveRatio: string;
+}
+
+function computeLearningRate(ctx: LocalCtx): LearningRate | null {
+  try {
+    const saved7d = (ctx.db.prepare(
+      `SELECT COUNT(*) as c FROM vault WHERE created_at >= datetime('now', '-7 days') AND kind NOT IN ('bucket', 'session', 'brief')`
+    ).get() as any)?.c ?? 0;
+
+    const saved30d = (ctx.db.prepare(
+      `SELECT COUNT(*) as c FROM vault WHERE created_at >= datetime('now', '-30 days') AND kind NOT IN ('bucket', 'session', 'brief')`
+    ).get() as any)?.c ?? 0;
+
+    const sessions30d = (ctx.db.prepare(
+      `SELECT COUNT(*) as c FROM vault WHERE created_at >= datetime('now', '-30 days') AND kind = 'session'`
+    ).get() as any)?.c ?? 0;
+
+    const savesPerSession = sessions30d > 0
+      ? (saved30d / sessions30d).toFixed(1)
+      : '0.0';
+
+    const recalls30d = (ctx.db.prepare(
+      `SELECT SUM(recall_count) as c FROM vault WHERE last_recalled_at >= datetime('now', '-30 days')`
+    ).get() as any)?.c ?? 0;
+
+    const recallToSaveRatio = saved30d > 0
+      ? `${(recalls30d / saved30d).toFixed(1)}:1`
+      : recalls30d > 0 ? `${recalls30d}:0 (all recall, no save)` : 'n/a';
+
+    return { saved7d, saved30d, sessions30d, savesPerSession, recalls30d, recallToSaveRatio };
+  } catch {
+    return null;
+  }
+}
+
 export const name = 'context_status';
 
 export const description =
@@ -114,6 +155,30 @@ export function handler(_args: Record<string, any>, ctx: LocalCtx): ToolResult {
       }
     }
 
+    const learningRate = computeLearningRate(ctx);
+    if (learningRate) {
+      lines.push(``, `### Learning Rate`);
+      lines.push(`| Metric | Value |`);
+      lines.push(`|---|---|`);
+      lines.push(`| **Saved (7 days)** | ${learningRate.saved7d} |`);
+      lines.push(`| **Saved (30 days)** | ${learningRate.saved30d} |`);
+      lines.push(`| **Sessions (30 days)** | ${learningRate.sessions30d} |`);
+      if (learningRate.sessions30d > 0) {
+        lines.push(`| **Saves per session** | ${learningRate.savesPerSession} |`);
+      }
+      if (learningRate.recalls30d > 0 || learningRate.saved30d > 0) {
+        lines.push(`| **Recalls (30 days)** | ${learningRate.recalls30d} |`);
+        lines.push(`| **Recall:save ratio** | ${learningRate.recallToSaveRatio} |`);
+      }
+      if (learningRate.saved30d === 0) {
+        lines.push('');
+        lines.push('_No entries saved in 30 days. Knowledge may be getting lost between sessions._');
+      } else if (learningRate.sessions30d > 0 && learningRate.savesPerSession === '0.0') {
+        lines.push('');
+        lines.push('_Very low save rate. Consider using `session_end` to capture learnings._');
+      }
+    }
+
     if (status.stalePaths) {
       lines.push(``);
       lines.push(`### ⚠ Stale Paths`);

package/src/tools/get-context.ts

@@ -243,6 +243,22 @@ function checkStaleness(entry: any): { stale: boolean; stale_reason: string } |
   return null;
 }
 
+const ERROR_TERMS = /\b(error|bug|fix|debug|failing|broken|crash|exception|issue|wrong|unexpected|stacktrace|traceback)\b/i;
+
+function generateSaveHint(query: string | undefined, resultCount: number): string | null {
+  if (!query) return null;
+
+  if (ERROR_TERMS.test(query)) {
+    return 'If you solve this, save the root cause and fix as an insight.';
+  }
+
+  if (resultCount === 0) {
+    return 'No existing entries for this topic. If you learn something useful, save it for future sessions.';
+  }
+
+  return null;
+}
+
 export const name = 'get_context';
 
 export const description =
@@ -679,7 +695,7 @@ export async function handler(
     }
   }
 
-  // Graph traversal: follow related_to links bidirectionally
+  // Graph traversal: follow related_to links bidirectionally + co-retrieval edges
   if (follow_links) {
     const { forward, backward } = collectLinkedEntries(ctx.db, filtered as any);
     const allLinked: any[] = [...(forward as any[]), ...(backward as any[])];
@@ -706,6 +722,69 @@ export async function handler(
     } else {
       lines.push(`## Linked Entries\n\nNo related entries found.\n`);
     }
+
+    // Co-retrieval graph traversal: edges with count > 3
+    const primaryIds = filtered.map((e: any) => e.id);
+    const primaryIdSet = new Set([...primaryIds, ...Array.from(seen)]);
+    const coRetrieved: any[] = [];
+
+    try {
+      const CO_RETRIEVAL_THRESHOLD = 3;
+      const placeholders = primaryIds.map(() => '?').join(',');
+      const coRows = ctx.db
+        .prepare(
+          `SELECT entry_a, entry_b, count FROM co_retrievals
+           WHERE count > ? AND (entry_a IN (${placeholders}) OR entry_b IN (${placeholders}))`
+        )
+        .all(CO_RETRIEVAL_THRESHOLD, ...primaryIds, ...primaryIds) as {
+        entry_a: string;
+        entry_b: string;
+        count: number;
+      }[];
+
+      const linkedIds = new Map<string, number>();
+      for (const row of coRows) {
+        for (const candidate of [row.entry_a, row.entry_b]) {
+          if (!primaryIdSet.has(candidate)) {
+            const existing = linkedIds.get(candidate) ?? 0;
+            if (row.count > existing) linkedIds.set(candidate, row.count);
+          }
+        }
+      }
+
+      if (linkedIds.size > 0) {
+        const coIds = Array.from(linkedIds.keys());
+        const coPlaceholders = coIds.map(() => '?').join(',');
+        const coEntries = ctx.db
+          .prepare(
+            `SELECT * FROM vault WHERE id IN (${coPlaceholders}) AND (expires_at IS NULL OR expires_at > datetime('now')) AND superseded_by IS NULL`
+          )
+          .all(...coIds) as any[];
+
+        for (const entry of coEntries) {
+          coRetrieved.push({ ...entry, co_retrieval_weight: linkedIds.get(entry.id) ?? 0 });
+        }
+      }
+    } catch {
+      // Non-fatal: co-retrieval traversal is best-effort
+    }
+
+    if (coRetrieved.length > 0) {
+      coRetrieved.sort((a: any, b: any) => b.co_retrieval_weight - a.co_retrieval_weight);
+      lines.push(
+        `## Co-Retrieved Entries (${coRetrieved.length} via usage patterns)\n`
+      );
+      for (const r of coRetrieved) {
+        const entryTags = r.tags ? JSON.parse(r.tags) : [];
+        const tagStr = entryTags.length ? entryTags.join(', ') : '';
+        const icon = kindIcon(r.kind);
+        lines.push(`### ${icon} ${r.title || '(untitled)'} (weight: ${r.co_retrieval_weight})`);
+        const meta = [`\`${r.kind}\``, tagStr].filter(Boolean).join(' · ');
+        lines.push(`${meta}  \nid: \`${r.id}\``);
+        lines.push(truncateBody(r.body, body_limit ?? 300));
+        lines.push('');
+      }
+    }
   }
 
   // Consolidation suggestion detection — lazy, opportunistic, vault-wide
@@ -743,6 +822,12 @@ export async function handler(
   if (consolidationSuggestions.length > 0) {
     meta.consolidation_suggestions = consolidationSuggestions;
   }
+
+  const saveHint = generateSaveHint(query, filtered.length);
+  if (saveHint) {
+    meta.save_hint = saveHint;
+  }
+
   result._meta = meta;
   return result;
 }