context-vault 3.6.0 → 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/get-context.ts

@@ -695,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[])];
@@ -722,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

package/src/tools/recall.ts

@@ -0,0 +1,307 @@
+import { z } from 'zod';
+import { ok } from '../helpers.js';
+import { isEmbedAvailable } from '@context-vault/core/embed';
+import type { LocalCtx, SharedCtx, ToolResult } from '../types.js';
+
+const SEMANTIC_SIMILARITY_THRESHOLD = 0.6;
+const CO_RETRIEVAL_WEIGHT_CAP = 50;
+
+const STOPWORDS = new Set([
+  'the', 'a', 'an', 'is', 'are', 'was', 'were', 'be', 'been', 'being',
+  'have', 'has', 'had', 'do', 'does', 'did', 'will', 'would', 'could',
+  'should', 'may', 'might', 'shall', 'can', 'need', 'must', 'ought',
+  'and', 'but', 'or', 'nor', 'not', 'so', 'yet', 'for', 'with',
+  'from', 'into', 'during', 'before', 'after', 'above', 'below',
+  'to', 'of', 'in', 'on', 'at', 'by', 'about', 'between', 'through',
+  'this', 'that', 'these', 'those', 'it', 'its', 'they', 'them',
+  'their', 'we', 'our', 'you', 'your', 'he', 'she', 'him', 'her',
+  'all', 'each', 'every', 'both', 'few', 'more', 'most', 'other',
+  'some', 'such', 'no', 'only', 'own', 'same', 'than', 'too', 'very',
+  'just', 'also', 'now', 'then', 'here', 'there', 'when', 'where',
+  'how', 'what', 'which', 'who', 'whom', 'why', 'if', 'because',
+  'as', 'until', 'while', 'use', 'using', 'used',
+]);
+
+const DEFAULT_MAX_HINTS = 3;
+
+/** Module-level session dedup map: session_id -> Set of surfaced entry IDs */
+const sessionSurfaced = new Map<string, Set<string>>();
+
+/**
+ * Extract keywords from a signal string.
+ * Split on whitespace, filter stopwords and words under 4 chars, keep top 10.
+ */
+export function extractKeywords(signal: string): string[] {
+  const words = signal
+    .toLowerCase()
+    .replace(/[^a-z0-9\s_-]/g, ' ')
+    .split(/\s+/)
+    .filter((w) => w.length >= 4 && !STOPWORDS.has(w));
+
+  const seen = new Set<string>();
+  const unique: string[] = [];
+  for (const w of words) {
+    if (seen.has(w)) continue;
+    seen.add(w);
+    unique.push(w);
+    if (unique.length >= 10) break;
+  }
+  return unique;
+}
+
+export const name = 'recall';
+
+export const description =
+  'Search the vault using a raw signal (prompt text, error message, file path, or task context). Returns lightweight hints for proactive surfacing. Designed for runtime hooks, not direct user interaction.';
+
+export const inputSchema = {
+  signal: z
+    .string()
+    .describe('Raw text: prompt, error message, file path, or combined signal.'),
+  signal_type: z
+    .enum(['prompt', 'error', 'file', 'task'])
+    .describe('Type of signal, used to weight results.'),
+  bucket: z
+    .string()
+    .optional()
+    .describe('Scope results to a project bucket.'),
+  session_id: z
+    .string()
+    .optional()
+    .describe('Session identifier for dedup. Entries already surfaced this session are suppressed.'),
+  max_hints: z
+    .number()
+    .optional()
+    .describe('Maximum hints to return. Default: 3.'),
+};
+
+export async function handler(
+  { signal, signal_type, bucket, session_id, max_hints }: Record<string, any>,
+  ctx: LocalCtx,
+  { ensureIndexed }: SharedCtx
+): Promise<ToolResult> {
+  const start = Date.now();
+
+  await ensureIndexed();
+
+  const keywords = extractKeywords(signal || '');
+  const limit = max_hints ?? DEFAULT_MAX_HINTS;
+
+  if (keywords.length === 0) {
+    const result = ok('No relevant entries found.');
+    result._meta = {
+      latency_ms: Date.now() - start,
+      method: 'none' as const,
+      signal_keywords: [],
+      suppressed: 0,
+    };
+    return result;
+  }
+
+  // Build fast-path query: tag/title LIKE match for each keyword
+  const conditions: string[] = [];
+  const params: string[] = [];
+  for (const kw of keywords) {
+    conditions.push('(title LIKE ? OR tags LIKE ?)');
+    params.push(`%${kw}%`, `%${kw}%`);
+  }
+
+  const bucketClause = bucket ? ' AND tags LIKE ?' : '';
+  if (bucket) params.push(`%"bucket:${bucket}"%`);
+
+  const sql = `SELECT id, title, substr(body, 1, 100) as summary, kind, tags
+    FROM vault
+    WHERE indexed = 1
+      AND (expires_at IS NULL OR expires_at > datetime('now'))
+      AND superseded_by IS NULL
+      AND (${conditions.join(' OR ')})${bucketClause}
+    LIMIT 20`;
+
+  let rows: any[];
+  try {
+    rows = ctx.db.prepare(sql).all(...params);
+  } catch {
+    rows = [];
+  }
+
+  // Session dedup
+  let suppressed = 0;
+  const bypassDedup = signal_type === 'error';
+  const sessionSet = session_id
+    ? (sessionSurfaced.get(session_id) ?? (() => { const s = new Set<string>(); sessionSurfaced.set(session_id, s); return s; })())
+    : null;
+
+  const hints: Array<{
+    id: string;
+    title: string;
+    summary: string;
+    relevance: 'high' | 'medium';
+    kind: string;
+    tags: string[];
+  }> = [];
+
+  for (const row of rows) {
+    if (hints.length >= limit) break;
+
+    // Dedup check
+    if (sessionSet && !bypassDedup && sessionSet.has(row.id)) {
+      suppressed++;
+      continue;
+    }
+
+    const entryTags: string[] = row.tags ? JSON.parse(row.tags) : [];
+
+    // Score relevance: count how many keywords match title or tags
+    let matchCount = 0;
+    const titleLower = (row.title || '').toLowerCase();
+    const tagsLower = (row.tags || '').toLowerCase();
+    for (const kw of keywords) {
+      if (titleLower.includes(kw) || tagsLower.includes(kw)) matchCount++;
+    }
+    const relevance: 'high' | 'medium' = matchCount >= 2 ? 'high' : 'medium';
+
+    hints.push({
+      id: row.id,
+      title: row.title || '(untitled)',
+      summary: row.summary || '',
+      relevance,
+      kind: row.kind || 'knowledge',
+      tags: entryTags,
+    });
+
+    // Track surfaced
+    if (sessionSet) sessionSet.add(row.id);
+  }
+
+  let method: 'tag_match' | 'semantic' | 'none' = hints.length > 0 ? 'tag_match' : 'none';
+
+  // Semantic fallback: when fast-path returns 0 results and signal is not file-based
+  if (hints.length === 0 && signal_type !== 'file' && isEmbedAvailable()) {
+    try {
+      const vecCount = (
+        ctx.db.prepare('SELECT COUNT(*) as c FROM vault_vec').get() as { c: number }
+      ).c;
+
+      if (vecCount > 0) {
+        const queryVec = await ctx.embed(signal);
+        if (queryVec) {
+          const vecRows = ctx.db
+            .prepare(
+              'SELECT v.rowid, v.distance FROM vault_vec v WHERE embedding MATCH ? ORDER BY distance LIMIT 5'
+            )
+            .all(queryVec) as { rowid: number; distance: number }[];
+
+          if (vecRows.length) {
+            const rowids = vecRows.map((vr) => vr.rowid);
+            const placeholders = rowids.map(() => '?').join(',');
+
+            let bucketFilter = '';
+            const hydrateParams: any[] = [...rowids];
+            if (bucket) {
+              bucketFilter = ' AND tags LIKE ?';
+              hydrateParams.push(`%"bucket:${bucket}"%`);
+            }
+
+            const hydrated = ctx.db
+              .prepare(
+                `SELECT rowid, id, title, substr(body, 1, 100) as summary, kind, tags FROM vault WHERE rowid IN (${placeholders}) AND indexed = 1 AND (expires_at IS NULL OR expires_at > datetime('now')) AND superseded_by IS NULL${bucketFilter}`
+              )
+              .all(...hydrateParams) as any[];
+
+            const byRowid = new Map<number, any>();
+            for (const row of hydrated) byRowid.set(row.rowid, row);
+
+            for (const vr of vecRows) {
+              if (hints.length >= limit) break;
+              const row = byRowid.get(vr.rowid);
+              if (!row) continue;
+
+              const similarity = Math.max(0, 1 - vr.distance / 2);
+              if (similarity < SEMANTIC_SIMILARITY_THRESHOLD) continue;
+
+              // Session dedup
+              if (sessionSet && !bypassDedup && sessionSet.has(row.id)) {
+                suppressed++;
+                continue;
+              }
+
+              const entryTags: string[] = row.tags ? JSON.parse(row.tags) : [];
+              hints.push({
+                id: row.id,
+                title: row.title || '(untitled)',
+                summary: row.summary || '',
+                relevance: similarity >= 0.8 ? 'high' : 'medium',
+                kind: row.kind || 'knowledge',
+                tags: entryTags,
+              });
+
+              if (sessionSet) sessionSet.add(row.id);
+            }
+
+            if (hints.length > 0) method = 'semantic';
+          }
+        }
+      }
+    } catch {
+      // Semantic fallback is best-effort; fast path already ran
+    }
+  }
+
+  const latency = Date.now() - start;
+
+  if (hints.length === 0) {
+    const result = ok('No relevant entries found.');
+    result._meta = {
+      latency_ms: latency,
+      method,
+      signal_keywords: keywords,
+      suppressed,
+    };
+    return result;
+  }
+
+  // Record co-retrieval pairs (fire and forget, non-blocking)
+  if (hints.length >= 2) {
+    recordCoRetrieval(ctx, hints.map((h) => h.id));
+  }
+
+  // Format output
+  const lines = [`[Vault: ${hints.length} ${hints.length === 1 ? 'entry' : 'entries'} may be relevant]`];
+  for (const h of hints) {
+    lines.push(`- "${h.title}" (${h.kind}, ${h.relevance})`);
+  }
+  lines.push('Use get_context to retrieve full details.');
+
+  const result = ok(lines.join('\n'));
+  result._meta = {
+    latency_ms: latency,
+    method,
+    signal_keywords: keywords,
+    suppressed,
+    hints,
+  };
+  return result;
+}
+
+function recordCoRetrieval(ctx: LocalCtx, ids: string[]): void {
+  try {
+    const now = new Date().toISOString();
+    const upsert = ctx.db.prepare(
+      `INSERT INTO co_retrievals (entry_a, entry_b, count, last_at) VALUES (?, ?, 1, ?)
+       ON CONFLICT(entry_a, entry_b) DO UPDATE SET count = MIN(count + 1, ?), last_at = ?`
+    );
+    for (let i = 0; i < ids.length; i++) {
+      for (let j = i + 1; j < ids.length; j++) {
+        const [a, b] = ids[i] < ids[j] ? [ids[i], ids[j]] : [ids[j], ids[i]];
+        upsert.run(a, b, now, CO_RETRIEVAL_WEIGHT_CAP, now);
+      }
+    }
+  } catch {
+    // Non-fatal: co-retrieval recording is best-effort
+  }
+}
+
+/** Reset session dedup state (for testing) */
+export function _resetSessionState(): void {
+  sessionSurfaced.clear();
+}

package/src/tools/session-start.ts

@@ -143,6 +143,12 @@ export const inputSchema = {
     .describe(
       "Bucket names to scope the session brief. Each name expands to a 'bucket:<name>' tag filter. When provided, the brief only includes entries from these buckets."
     ),
+  auto_memory_path: z
+    .string()
+    .optional()
+    .describe(
+      "Explicit path to the Claude Code auto-memory directory. Overrides auto-detection. If not provided, session_start attempts to detect ~/.claude/projects/-<project-key>/memory/ from cwd."
+    ),
 };
 
 function detectProject() {
@@ -191,7 +197,7 @@ function formatEntry(entry: any): string {
 }
 
 export async function handler(
-  { project, max_tokens, buckets }: Record<string, any>,
+  { project, max_tokens, buckets, auto_memory_path }: Record<string, any>,
   ctx: LocalCtx,
   { ensureIndexed }: SharedCtx
 ): Promise<ToolResult> {
@@ -234,12 +240,17 @@ export async function handler(
 
   const sinceDate = new Date(Date.now() - RECENT_DAYS * 86400000).toISOString();
 
-  // Auto-detect Claude Code auto-memory
-  const autoMemoryPath = detectAutoMemoryPath();
-  const autoMemory: AutoMemoryResult = autoMemoryPath
-    ? readAutoMemory(autoMemoryPath)
+  // Auto-detect Claude Code auto-memory (explicit path overrides auto-detection)
+  const resolvedMemoryPath = auto_memory_path?.trim()
+    ? (existsSync(join(auto_memory_path.trim(), 'MEMORY.md')) ? auto_memory_path.trim() : null)
+    : detectAutoMemoryPath();
+  const autoMemory: AutoMemoryResult = resolvedMemoryPath
+    ? readAutoMemory(resolvedMemoryPath)
     : { detected: false, path: null, entries: [], linesUsed: 0 };
   const autoMemoryContext = buildAutoMemoryContext(autoMemory.entries);
+  const topicsExtracted = autoMemory.entries.length > 0
+    ? extractKeywords(autoMemoryContext).slice(0, 20)
+    : [];
 
   const sections = [];
   let tokensUsed = 0;
@@ -346,8 +357,10 @@ export async function handler(
     },
     auto_memory: {
       detected: autoMemory.detected,
+      path: autoMemory.path,
       entries: autoMemory.entries.length,
       lines_used: autoMemory.linesUsed,
+      topics_extracted: topicsExtracted,
     },
   };
   return result;