@danielmarbach/mnemonic-mcp 0.15.0 → 0.17.0

package/build/index.js

@@ -9,8 +9,11 @@ import { NOTE_LIFECYCLES } from "./storage.js";
 import { embed, cosineSimilarity, embedModel } from "./embeddings.js";
 import { buildTemporalHistoryEntry, computeConfidence, getNoteProvenance } from "./provenance.js";
 import { getOrBuildProjection } from "./projections.js";
+import { invalidateActiveProjectCache, getOrBuildVaultEmbeddings, getOrBuildVaultNoteList, getSessionCachedNote, } from "./cache.js";
+import { performance } from "perf_hooks";
 import { filterRelationships, mergeRelationshipsFromNotes, normalizeMergePlanSourceIds, resolveEffectiveConsolidationMode, } from "./consolidate.js";
 import { selectRecallResults } from "./recall.js";
+import { getRelationshipPreview } from "./relationships.js";
 import { cleanMarkdown } from "./markdown.js";
 import { MnemonicConfigStore, readVaultSchemaVersion } from "./config.js";
 import { CONSOLIDATION_MODES, PROTECTED_BRANCH_BEHAVIORS, PROJECT_POLICY_SCOPES, WRITE_SCOPES, isProtectedBranch, resolveProtectedBranchBehavior, resolveProtectedBranchPatterns, resolveConsolidationMode, resolveWriteScope, } from "./project-memory-policy.js";
@@ -359,6 +362,8 @@ async function ensureBranchSynced(cwd) {
     }
     const mainBackfill = await backfillEmbeddingsAfterSync(vaultManager.main.storage, "main vault", [], true);
     console.error(`[branch] Main vault embedded ${mainBackfill.embedded} notes`);
+    // Vault contents changed — discard session cache so next access rebuilds from fresh state
+    invalidateActiveProjectCache();
     return true;
 }
 function formatProjectIdentityText(identity) {
@@ -382,10 +387,10 @@ function formatProjectIdentityText(identity) {
 function describeLifecycle(lifecycle) {
     return `lifecycle: ${lifecycle}`;
 }
-function formatNote(note, score) {
+function formatNote(note, score, showRawRelated = true) {
     const scoreStr = score !== undefined ? ` | similarity: ${score.toFixed(3)}` : "";
     const projectStr = note.project ? ` | project: ${note.projectName ?? note.project}` : " | global";
-    const relStr = note.relatedTo && note.relatedTo.length > 0
+    const relStr = showRawRelated && note.relatedTo && note.relatedTo.length > 0
         ? `\n**related:** ${note.relatedTo.map((r) => `\`${r.id}\` (${r.type})`).join(", ")}`
         : "";
     return (`## ${note.title}\n` +
@@ -404,6 +409,15 @@ function formatTemporalHistory(history) {
     }
     return lines.join("\n");
 }
+function formatRelationshipPreview(preview) {
+    const shown = preview.shown
+        .map(r => `${r.title} (\`${r.id}\`) [${r.relationType ?? "related-to"}]`)
+        .join(", ");
+    const more = preview.truncated
+        ? ` [+${preview.totalDirectRelations - preview.shown.length} more]`
+        : "";
+    return `**related (${preview.totalDirectRelations}):** ${shown}${more}`;
+}
 // ── Git commit message helpers ────────────────────────────────────────────────
 /**
  * Extract a short human-readable summary from note content.
@@ -772,7 +786,7 @@ function vaultMatchesStorageScope(vault, storedIn) {
     // "project-vault" covers the primary project vault and all submodule vaults.
     return vault.isProject;
 }
-async function collectVisibleNotes(cwd, scope = "all", tags, storedIn = "any") {
+async function collectVisibleNotes(cwd, scope = "all", tags, storedIn = "any", sessionProjectId) {
     const project = await resolveProject(cwd);
     const vaults = await vaultManager.searchOrder(cwd);
     let filterProject = undefined;
@@ -783,8 +797,23 @@ async function collectVisibleNotes(cwd, scope = "all", tags, storedIn = "any") {
     const seen = new Set();
     const entries = [];
     for (const vault of vaults) {
-        const vaultNotes = await vault.storage.listNotes(filterProject !== undefined ? { project: filterProject } : undefined);
-        for (const note of vaultNotes) {
+        let rawNotes;
+        if (sessionProjectId) {
+            const cached = await getOrBuildVaultNoteList(sessionProjectId, vault);
+            if (cached !== undefined) {
+                // Apply project filter on the full cached list
+                rawNotes = filterProject !== undefined
+                    ? cached.filter((n) => filterProject === null ? !n.project : n.project === filterProject)
+                    : cached;
+            }
+            else {
+                rawNotes = await vault.storage.listNotes(filterProject !== undefined ? { project: filterProject } : undefined);
+            }
+        }
+        else {
+            rawNotes = await vault.storage.listNotes(filterProject !== undefined ? { project: filterProject } : undefined);
+        }
+        for (const note of rawNotes) {
             if (seen.has(note.id)) {
                 continue;
             }
@@ -1432,6 +1461,7 @@ server.registerTool("remember", {
         timestamp: now,
         persistence,
     };
+    invalidateActiveProjectCache();
     return {
         content: [{ type: "text", text: textContent }],
         structuredContent,
@@ -1636,6 +1666,7 @@ server.registerTool("recall", {
         "- You just want to browse by tags or scope; use `list`\n\n" +
         "Returns:\n" +
         "- Ranked memory matches with scores, vault label, tags, lifecycle, and updated time\n" +
+        "- Bounded 1-hop relationship previews automatically attached to top results\n" +
         "- In temporal mode, optional compact history entries for top matches\n\n" +
         "Read-only.\n\n" +
         "Typical next step:\n" +
@@ -1663,6 +1694,7 @@ server.registerTool("recall", {
     }),
     outputSchema: RecallResultSchema,
 }, async ({ query, cwd, limit, minSimilarity, mode, verbose, tags, scope }) => {
+    const t0Recall = performance.now();
     await ensureBranchSynced(cwd);
     const project = await resolveProject(cwd);
     const queryVec = await embed(query);
@@ -1670,6 +1702,12 @@ server.registerTool("recall", {
     const noteCache = new Map();
     const noteCacheKey = (vault, id) => `${vault.storage.vaultPath}::${id}`;
     const readCachedNote = async (vault, id) => {
+        // Check session cache first (populated when getOrBuildVaultEmbeddings was called)
+        if (project) {
+            const sessionNote = getSessionCachedNote(project.id, vault.storage.vaultPath, id);
+            if (sessionNote !== undefined)
+                return sessionNote;
+        }
         const key = noteCacheKey(vault, id);
         const cached = noteCache.get(key);
         if (cached) {
@@ -1686,7 +1724,9 @@ server.registerTool("recall", {
     }
     const scored = [];
     for (const vault of vaults) {
-        const embeddings = await vault.storage.listEmbeddings();
+        const embeddings = project
+            ? (await getOrBuildVaultEmbeddings(project.id, vault)) ?? await vault.storage.listEmbeddings()
+            : await vault.storage.listEmbeddings();
         for (const rec of embeddings) {
             const rawScore = cosineSimilarity(queryVec, rec.embedding);
             if (rawScore < minSimilarity)
@@ -1723,6 +1763,9 @@ server.registerTool("recall", {
         : `Recall results (global):`;
     const sections = [];
     const structuredResults = [];
+    // Determine how many top results get relationship expansion
+    // Top 1 by default, top 3 if result count is small
+    const recallRelationshipLimit = top.length <= 3 ? 3 : 1;
     for (const [index, { id, score, vault, boosted }] of top.entries()) {
         const note = await readCachedNote(vault, id);
         if (note) {
@@ -1740,10 +1783,19 @@ server.registerTool("recall", {
                     }));
                 }
             }
+            // Add relationship preview for top N results (fail-soft)
+            let relationships;
+            if (index < recallRelationshipLimit) {
+                relationships = await getRelationshipPreview(note, vaultManager.allKnownVaults(), { activeProjectId: project?.id, limit: 3 });
+            }
             const formattedHistory = mode === "temporal" && history !== undefined
                 ? `\n\n${formatTemporalHistory(history)}`
                 : "";
-            sections.push(`${formatNote(note, score)}${formattedHistory}`);
+            const formattedRelationships = relationships !== undefined
+                ? `\n\n${formatRelationshipPreview(relationships)}`
+                : "";
+            // Suppress raw related IDs when enriched preview is shown to avoid duplication
+            sections.push(`${formatNote(note, score, relationships === undefined)}${formattedHistory}${formattedRelationships}`);
             structuredResults.push({
                 id,
                 title: note.title,
@@ -1758,6 +1810,7 @@ server.registerTool("recall", {
                 provenance,
                 confidence,
                 history,
+                relationships,
             });
         }
     }
@@ -1768,6 +1821,7 @@ server.registerTool("recall", {
         scope: scope || "all",
         results: structuredResults,
     };
+    console.error(`[recall:timing] ${(performance.now() - t0Recall).toFixed(1)}ms`);
     return {
         content: [{ type: "text", text: textContent }],
         structuredContent,
@@ -1918,6 +1972,7 @@ server.registerTool("update", {
         lifecycle: updated.lifecycle,
         persistence,
     };
+    invalidateActiveProjectCache();
     return { content: [{ type: "text", text: `Updated memory '${id}'\n${formatPersistenceSummary(persistence)}` }], structuredContent };
 });
 // ── forget ────────────────────────────────────────────────────────────────────
@@ -2024,6 +2079,7 @@ server.registerTool("forget", {
         retry,
     };
     const retrySummary = formatRetrySummary(retry);
+    invalidateActiveProjectCache();
     return {
         content: [{
                 type: "text",
@@ -2044,7 +2100,8 @@ server.registerTool("get", {
         "- You are still searching by topic; use `recall`\n" +
         "- You want to browse many notes; use `list`\n\n" +
         "Returns:\n" +
-        "- Full note content and metadata for the requested ids, including storage label\n\n" +
+        "- Full note content and metadata for the requested ids, including storage label\n" +
+        "- Bounded 1-hop relationship previews when `includeRelationships` is true (max 3 shown)\n\n" +
         "Read-only.\n\n" +
         "Typical next step:\n" +
         "- Use `update`, `forget`, `move_memory`, or `relate` after inspection.",
@@ -2056,19 +2113,39 @@ server.registerTool("get", {
     inputSchema: z.object({
         ids: z.array(z.string()).min(1).describe("One or more memory ids to fetch"),
         cwd: projectParam,
+        includeRelationships: z.boolean().optional().default(false).describe("Include bounded direct relationship previews (1-hop expansion, max 3 shown)"),
     }),
     outputSchema: GetResultSchema,
-}, async ({ ids, cwd }) => {
+}, async ({ ids, cwd, includeRelationships }) => {
+    const t0Get = performance.now();
     await ensureBranchSynced(cwd);
+    const project = await resolveProject(cwd);
     const found = [];
     const notFound = [];
     for (const id of ids) {
-        const result = await vaultManager.findNote(id, cwd);
+        // Check session cache before hitting storage
+        let result = null;
+        if (project) {
+            for (const vault of vaultManager.allKnownVaults()) {
+                const cached = getSessionCachedNote(project.id, vault.storage.vaultPath, id);
+                if (cached !== undefined) {
+                    result = { note: cached, vault };
+                    break;
+                }
+            }
+        }
+        if (!result) {
+            result = await vaultManager.findNote(id, cwd);
+        }
         if (!result) {
             notFound.push(id);
             continue;
         }
         const { note, vault } = result;
+        let relationships;
+        if (includeRelationships) {
+            relationships = await getRelationshipPreview(note, vaultManager.allKnownVaults(), { activeProjectId: project?.id, limit: 3 });
+        }
         found.push({
             id: note.id,
             title: note.title,
@@ -2081,6 +2158,7 @@ server.registerTool("get", {
             createdAt: note.createdAt,
             updatedAt: note.updatedAt,
             vault: storageLabel(vault),
+            relationships,
         });
     }
     const lines = [];
@@ -2091,6 +2169,10 @@ server.registerTool("get", {
             lines.push(`tags: ${note.tags.join(", ")}`);
         lines.push("");
         lines.push(note.content);
+        if (note.relationships) {
+            lines.push("");
+            lines.push(formatRelationshipPreview(note.relationships));
+        }
         lines.push("");
     }
     if (notFound.length > 0) {
@@ -2102,6 +2184,7 @@ server.registerTool("get", {
         notes: found,
         notFound,
     };
+    console.error(`[get:timing] ${(performance.now() - t0Get).toFixed(1)}ms`);
     return { content: [{ type: "text", text: lines.join("\n").trim() }], structuredContent };
 });
 // ── where_is_memory ───────────────────────────────────────────────────────────
@@ -2247,24 +2330,42 @@ server.registerTool("list", {
     };
     return { content: [{ type: "text", text: textContent }], structuredContent };
 });
-// ── discover_tags ───────────────────────────────────────────────────────────
+function tokenizeTagDiscoveryText(value) {
+    return value
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter(Boolean);
+}
+function countTokenOverlap(tokens, other) {
+    let matches = 0;
+    for (const token of other) {
+        if (tokens.has(token)) {
+            matches++;
+        }
+    }
+    return matches;
+}
+function hasExactTagContextMatch(tag, values) {
+    const normalizedTag = tag.toLowerCase();
+    return values.some(value => value?.toLowerCase().includes(normalizedTag) ?? false);
+}
 server.registerTool("discover_tags", {
     title: "Discover Tags",
-    description: "Discover existing tags across vaults with usage statistics and examples.\n\n" +
+    description: "Suggest canonical tags for a specific note before `remember` when tag choice is ambiguous.\n\n" +
         "Use this when:\n" +
-        "- Before `remember` to find canonical tag names for consistent terminology\n" +
-        "- Starting a new topic and unsure which tags exist (e.g., 'bug' vs 'bugs')\n" +
-        "- Identifying tags only on temporary notes (cleanup candidates)\n\n" +
+        "- You have a note title, content, or query and want compact tag suggestions\n" +
+        "- You want canonical project terminology without exposing lots of unrelated tags\n" +
+        "- You want to demote temporary-only tags unless they fit the note\n\n" +
         "Do not use this when:\n" +
         "- You need to browse notes by tag; use `list` with `tags` filter instead\n" +
-        "- You already know the exact tags you want to use\n\n" +
+        "- You already know the exact tags you want to use\n" +
+        "- You want broad inventory output but are not explicitly requesting `mode: \"browse\"`\n\n" +
         "Returns:\n" +
-        "- Tags sorted by usageCount (canonical tags first)\n" +
-        "- Example note titles (up to 3 per tag) showing usage context\n" +
-        "- lifecycleTypes showing temporary vs permanent distribution\n" +
-        "- isTemporaryOnly flag identifying cleanup candidates\n\n" +
+        "- Default: bounded `recommendedTags` ranked by note relevance first and usage count second\n" +
+        "- Each suggestion includes canonicality and lifecycle signals plus one compact example\n" +
+        "- Optional `mode: \"browse\"` returns broader inventory output\n\n" +
         "Typical next step:\n" +
-        "- Use canonical tags from discover_tags when appropriate, or create new tags when genuinely novel.\n\n" +
+        "- Reuse suggested canonical tags when they fit, or create a new tag only when genuinely novel.\n\n" +
         "Performance: O(n) where n = total notes scanned. Expect 100-200ms for 500 notes.\n\n" +
         "Read-only.",
     annotations: {
@@ -2274,6 +2375,12 @@ server.registerTool("discover_tags", {
     },
     inputSchema: z.object({
         cwd: projectParam,
+        mode: z.enum(["suggest", "browse"]).optional().default("suggest"),
+        title: z.string().optional(),
+        content: z.string().optional(),
+        query: z.string().optional(),
+        candidateTags: z.array(z.string()).optional(),
+        lifecycle: z.enum(NOTE_LIFECYCLES).optional(),
         scope: z
             .enum(["project", "global", "all"])
             .optional()
@@ -2286,65 +2393,170 @@ server.registerTool("discover_tags", {
             .optional()
             .default("any")
             .describe("Filter by vault storage label like list tool."),
+        limit: z.number().int().min(1).max(50).optional(),
     }),
     outputSchema: DiscoverTagsResultSchema,
-}, async ({ cwd, scope, storedIn }) => {
+}, async ({ cwd, mode, title, content, query, candidateTags, lifecycle, scope, storedIn, limit }) => {
     await ensureBranchSynced(cwd);
     const startTime = Date.now();
     const { project, entries } = await collectVisibleNotes(cwd, scope, undefined, storedIn);
     const tagStats = new Map();
+    const candidateTagSet = new Set((candidateTags || []).map(tag => tag.toLowerCase()));
+    const contextValues = [title, content, query, ...(candidateTags || [])];
+    const contextTokens = new Set(tokenizeTagDiscoveryText(contextValues.filter(Boolean).join(" ")));
+    const isTemporaryTarget = lifecycle === "temporary";
+    const effectiveLimit = limit ?? (mode === "browse" ? 20 : 10);
     for (const { note } of entries) {
+        const noteTokens = new Set(tokenizeTagDiscoveryText(`${note.title} ${note.content} ${note.tags.join(" ")}`));
+        const contextMatches = contextTokens.size > 0 ? countTokenOverlap(contextTokens, noteTokens) : 0;
         for (const tag of note.tags) {
-            const stats = tagStats.get(tag) || { count: 0, examples: [], lifecycles: new Set() };
+            const stats = tagStats.get(tag) || {
+                count: 0,
+                examples: [],
+                lifecycles: new Set(),
+                contextMatches: 0,
+                exactCandidateMatch: false,
+            };
             stats.count++;
             if (stats.examples.length < 3) {
                 stats.examples.push(note.title);
             }
             stats.lifecycles.add(note.lifecycle);
+            stats.contextMatches += contextMatches;
+            if (candidateTagSet.has(tag.toLowerCase())) {
+                stats.exactCandidateMatch = true;
+            }
             tagStats.set(tag, stats);
         }
     }
-    const tags = Array.from(tagStats.entries())
-        .map(([tag, stats]) => ({
-        tag,
-        usageCount: stats.count,
-        examples: stats.examples,
-        lifecycleTypes: Array.from(stats.lifecycles),
-        isTemporaryOnly: stats.lifecycles.size === 1 && stats.lifecycles.has("temporary"),
-    }))
-        .sort((a, b) => b.usageCount - a.usageCount);
+    const rawTags = Array.from(tagStats.entries())
+        .map(([tag, stats]) => {
+        const lifecycleTypes = Array.from(stats.lifecycles);
+        const isTemporaryOnly = stats.lifecycles.size === 1 && stats.lifecycles.has("temporary");
+        const tagTokens = tokenizeTagDiscoveryText(tag);
+        const exactContextMatch = stats.exactCandidateMatch || hasExactTagContextMatch(tag, contextValues);
+        const tagTokenOverlap = contextTokens.size > 0
+            ? countTokenOverlap(contextTokens, tagTokens)
+            : 0;
+        const averageContextMatch = stats.count > 0 ? stats.contextMatches / stats.count : 0;
+        const reason = exactContextMatch
+            ? "matches a candidate tag already present in the note context"
+            : tagTokenOverlap > 0 || stats.contextMatches > 0
+                ? "matches the note context and existing project usage"
+                : "high-usage canonical tag from existing project notes";
+        return {
+            tag,
+            usageCount: stats.count,
+            examples: stats.examples,
+            example: stats.examples[0],
+            reason,
+            lifecycleTypes,
+            isTemporaryOnly,
+            exactContextMatch,
+            tagTokenOverlap,
+            averageContextMatch,
+            isBroadSingleToken: tagTokens.length === 1,
+            isHighFrequency: stats.count >= 4,
+            specificityBoost: tagTokens.length > 1 ? 4 : 0,
+        };
+    });
+    const hasStrongSpecificCandidate = rawTags.some(tag => tag.exactContextMatch && (!tag.isBroadSingleToken || tag.usageCount > 1));
+    const tags = rawTags
+        .map((tag) => {
+        const hasWeakDirectMatch = tag.tagTokenOverlap <= 1 && tag.averageContextMatch <= 2;
+        const genericPenalty = hasStrongSpecificCandidate && tag.isBroadSingleToken && tag.isHighFrequency && hasWeakDirectMatch
+            ? 10
+            : 0;
+        const score = hasStrongSpecificCandidate
+            ? (tag.exactContextMatch ? 12 : 0) +
+                (tag.tagTokenOverlap * 5) +
+                tag.specificityBoost +
+                (tag.averageContextMatch * 3) +
+                (tag.usageCount * 0.1) -
+                genericPenalty -
+                (!isTemporaryTarget && tag.isTemporaryOnly ? 2 : 0)
+            : (tag.usageCount * 1.5) +
+                (tag.isTemporaryOnly ? -3 : 1) -
+                (!isTemporaryTarget && tag.isTemporaryOnly ? 2 : 0);
+        return {
+            ...tag,
+            score,
+        };
+    })
+        .sort((a, b) => b.score - a.score || b.usageCount - a.usageCount || a.tag.localeCompare(b.tag));
     const durationMs = Date.now() - startTime;
+    const vaultsSearched = new Set(entries.map(e => storageLabel(e.vault))).size;
     const lines = [];
-    if (project && scope !== "global") {
-        lines.push(`Tags for ${project.name} (scope: ${scope}):`);
+    if (mode === "browse") {
+        if (project && scope !== "global") {
+            lines.push(`Tags for ${project.name} (scope: ${scope}):`);
+        }
+        else {
+            lines.push(`Tags (scope: ${scope}):`);
+        }
+        lines.push("");
+        lines.push(`Total: ${tags.length} unique tags across ${entries.length} notes (${durationMs}ms)`);
+        lines.push("");
+        lines.push("Tags sorted by usage:");
+        for (const t of tags.slice(0, effectiveLimit)) {
+            const lifecycleMark = t.isTemporaryOnly ? " [temp-only]" : "";
+            lines.push(`  ${t.tag} (${t.usageCount})${lifecycleMark}`);
+            if (t.examples.length > 0) {
+                lines.push(`    Example: "${t.examples[0]}"`);
+            }
+        }
+        if (tags.length > effectiveLimit) {
+            lines.push(`  ... and ${tags.length - effectiveLimit} more`);
+        }
     }
     else {
-        lines.push(`Tags (scope: ${scope}):`);
-    }
-    lines.push("");
-    lines.push(`Total: ${tags.length} unique tags across ${entries.length} notes (${durationMs}ms)`);
-    lines.push("");
-    lines.push("Tags sorted by usage:");
-    for (const t of tags.slice(0, 20)) {
-        const lifecycleMark = t.isTemporaryOnly ? " [temp-only]" : "";
-        lines.push(`  ${t.tag} (${t.usageCount})${lifecycleMark}`);
-        if (t.examples.length > 0) {
-            lines.push(`    Example: "${t.examples[0]}"`);
+        const suggestedTags = tags.slice(0, effectiveLimit);
+        if (project && scope !== "global") {
+            lines.push(`Suggested tags for ${project.name} (scope: ${scope}):`);
+        }
+        else {
+            lines.push(`Suggested tags (scope: ${scope}):`);
+        }
+        lines.push("");
+        lines.push(`Considered ${tags.length} unique tags across ${entries.length} notes (${durationMs}ms)`);
+        lines.push("");
+        if (contextTokens.size === 0) {
+            lines.push("No note context provided; showing the most canonical existing tags.");
+            lines.push("");
+        }
+        lines.push("Recommended tags:");
+        for (const t of suggestedTags) {
+            const lifecycleMark = t.isTemporaryOnly ? " [temp-only]" : "";
+            lines.push(`  ${t.tag} (${t.usageCount})${lifecycleMark}`);
+            if (t.example) {
+                lines.push(`    Example: "${t.example}"`);
+            }
+            lines.push(`    Why: ${t.reason}`);
         }
     }
-    if (tags.length > 20) {
-        lines.push(`  ... and ${tags.length - 20} more`);
-    }
-    const structuredContent = {
-        action: "tags_discovered",
-        project: project ? { id: project.id, name: project.name } : undefined,
-        scope: scope || "all",
-        tags,
-        totalTags: tags.length,
-        totalNotes: entries.length,
-        vaultsSearched: new Set(entries.map(e => storageLabel(e.vault))).size,
-        durationMs,
-    };
+    const structuredContent = mode === "browse"
+        ? {
+            action: "tags_discovered",
+            project: project ? { id: project.id, name: project.name } : undefined,
+            mode,
+            scope: scope || "all",
+            tags: tags.slice(0, effectiveLimit).map(({ score, example, reason, ...tag }) => tag),
+            totalTags: tags.length,
+            totalNotes: entries.length,
+            vaultsSearched,
+            durationMs,
+        }
+        : {
+            action: "tags_discovered",
+            project: project ? { id: project.id, name: project.name } : undefined,
+            mode,
+            scope: scope || "all",
+            recommendedTags: tags.slice(0, effectiveLimit).map(({ score, examples, ...tag }) => tag),
+            totalTags: tags.length,
+            totalNotes: entries.length,
+            vaultsSearched,
+            durationMs,
+        };
     return { content: [{ type: "text", text: lines.join("\n") }], structuredContent };
 });
 // ── recent_memories ───────────────────────────────────────────────────────────
@@ -2505,7 +2717,8 @@ server.registerTool("project_memory_summary", {
         "- You need exact note contents; use `get`\n" +
         "- You need direct semantic matches for a query; use `recall`\n\n" +
         "Returns:\n" +
-        "- A synthesized project-level summary based on stored memories\n\n" +
+        "- A synthesized project-level summary based on stored memories\n" +
+        "- Bounded 1-hop relationship previews on orientation entry points (primaryEntry and suggestedNext)\n\n" +
         "Read-only.\n\n" +
         "Typical next step:\n" +
         "- Use `recall` or `list` to drill down into specific areas.",
@@ -2524,8 +2737,11 @@ server.registerTool("project_memory_summary", {
     }),
     outputSchema: ProjectSummaryResultSchema,
 }, async ({ cwd, maxPerTheme, recentLimit, anchorLimit, includeRelatedGlobal, relatedGlobalLimit }) => {
+    const t0Summary = performance.now();
     await ensureBranchSynced(cwd);
-    const { project, entries } = await collectVisibleNotes(cwd, "all");
+    // Pre-resolve project so we can pass its id to collectVisibleNotes for session caching
+    const preProject = await resolveProject(cwd);
+    const { project, entries } = await collectVisibleNotes(cwd, "all", undefined, "any", preProject?.id);
     if (!project) {
         return { content: [{ type: "text", text: `Could not detect a project for: ${cwd}` }], isError: true };
     }
@@ -2729,10 +2945,24 @@ server.registerTool("project_memory_summary", {
         const confidence = computeConfidence("permanent", anchor.updatedAt, anchor.centrality);
         return { provenance, confidence };
     };
+    // Helper to enrich an anchor with relationships (1-hop expansion)
+    const enrichOrientationNoteWithRelationships = async (anchor) => {
+        const vault = noteVaultMap.get(anchor.id);
+        if (!vault)
+            return {};
+        const note = await vault.storage.readNote(anchor.id);
+        if (!note)
+            return {};
+        const relationships = await getRelationshipPreview(note, vaultManager.allKnownVaults(), { activeProjectId: project.id, limit: 3 });
+        return { relationships };
+    };
     const primaryEnriched = primaryAnchor ? await enrichOrientationNote(primaryAnchor) : {};
+    const primaryRelationships = primaryAnchor ? await enrichOrientationNoteWithRelationships(primaryAnchor) : {};
     const suggestedEnriched = await Promise.all(anchors.slice(1, 4).map(enrichOrientationNote));
+    const suggestedRelationships = await Promise.all(anchors.slice(1, 4).map(enrichOrientationNoteWithRelationships));
     // Enrich fallback primaryEntry when no anchors exist
     let fallbackEnriched = {};
+    let fallbackRelationships = {};
     if (!primaryAnchor && recent[0]) {
         const fallbackNote = recent[0].note;
         const vault = noteVaultMap.get(fallbackNote.id);
@@ -2742,6 +2972,9 @@ server.registerTool("project_memory_summary", {
             const confidence = computeConfidence(fallbackNote.lifecycle, fallbackNote.updatedAt, 0);
             fallbackEnriched = { provenance, confidence };
         }
+        const preview = await getRelationshipPreview(fallbackNote, vaultManager.allKnownVaults(), { activeProjectId: project.id, limit: 3 });
+        if (preview)
+            fallbackRelationships = { relationships: preview };
     }
     const orientation = {
         primaryEntry: primaryAnchor
@@ -2750,6 +2983,7 @@ server.registerTool("project_memory_summary", {
                 title: primaryAnchor.title,
                 rationale: `Centrality ${primaryAnchor.centrality}, connects ${primaryAnchor.connectionDiversity} themes`,
                 ...primaryEnriched,
+                ...primaryRelationships,
             }
             : {
                 id: recent[0]?.note.id ?? projectEntries[0]?.note.id ?? "",
@@ -2758,12 +2992,14 @@ server.registerTool("project_memory_summary", {
                     ? "Most recent note — no high-centrality anchors found"
                     : "Only note available",
                 ...fallbackEnriched,
+                ...fallbackRelationships,
             },
         suggestedNext: anchors.slice(1, 4).map((a, i) => ({
             id: a.id,
             title: a.title,
             rationale: `Centrality ${a.centrality}, connects ${a.connectionDiversity} themes`,
             ...suggestedEnriched[i],
+            ...suggestedRelationships[i],
         })),
     };
     // Warning for taxonomy dilution
@@ -2782,10 +3018,16 @@ server.registerTool("project_memory_summary", {
     if (orientation.primaryEntry.confidence) {
         sections.push(`  Confidence: ${orientation.primaryEntry.confidence}`);
     }
+    if (orientation.primaryEntry.relationships) {
+        sections.push(`  ${formatRelationshipPreview(orientation.primaryEntry.relationships)}`);
+    }
     if (orientation.suggestedNext.length > 0) {
         sections.push(`Then check:`);
         for (const next of orientation.suggestedNext) {
             sections.push(`  - ${next.title} (\`${next.id}\`) — ${next.rationale}${next.confidence ? ` [${next.confidence}]` : ""}`);
+            if (next.relationships) {
+                sections.push(`    ${formatRelationshipPreview(next.relationships)}`);
+            }
         }
     }
     if (orientation.warnings && orientation.warnings.length > 0) {
@@ -2815,6 +3057,7 @@ server.registerTool("project_memory_summary", {
         orientation,
         relatedGlobal,
     };
+    console.error(`[summary:timing] ${(performance.now() - t0Summary).toFixed(1)}ms`);
     return { content: [{ type: "text", text: sections.join("\n") }], structuredContent };
 });
 // ── sync ──────────────────────────────────────────────────────────────────────
@@ -2901,6 +3144,8 @@ server.registerTool("sync", {
         action: "synced",
         vaults: vaultResults,
     };
+    // Vault contents may have changed via pull — discard session cache
+    invalidateActiveProjectCache();
     return { content: [{ type: "text", text: lines.join("\n") }], structuredContent };
 });
 // ── move_memory ───────────────────────────────────────────────────────────────
@@ -3052,6 +3297,7 @@ server.registerTool("move_memory", {
     const associationText = metadataRewritten
         ? `Project association is now ${associationValue}.`
         : `Project association remains ${associationValue}.`;
+    invalidateActiveProjectCache();
     return {
         content: [{
                 type: "text",
@@ -3224,6 +3470,7 @@ server.registerTool("relate", {
         retry,
     };
     const retrySummary = formatRetrySummary(retry);
+    invalidateActiveProjectCache();
     return {
         content: [{
                 type: "text",
@@ -3390,6 +3637,7 @@ server.registerTool("unrelate", {
         retry,
     };
     const retrySummary = formatRetrySummary(retry);
+    invalidateActiveProjectCache();
     return {
         content: [{
                 type: "text",
@@ -3488,13 +3736,19 @@ server.registerTool("consolidate", {
             return findClusters(projectNotes, project);
         case "suggest-merges":
             return suggestMerges(projectNotes, threshold, defaultConsolidationMode, project, mode);
-        case "execute-merge":
+        case "execute-merge": {
             if (!mergePlan) {
                 return { content: [{ type: "text", text: "execute-merge strategy requires a mergePlan with sourceIds and targetTitle." }], isError: true };
             }
-            return executeMerge(entries, mergePlan, defaultConsolidationMode, project, cwd, mode, policy, allowProtectedBranch);
-        case "prune-superseded":
-            return pruneSuperseded(projectNotes, mode ?? defaultConsolidationMode, project, cwd, policy, allowProtectedBranch);
+            const mergeResult = await executeMerge(entries, mergePlan, defaultConsolidationMode, project, cwd, mode, policy, allowProtectedBranch);
+            invalidateActiveProjectCache();
+            return mergeResult;
+        }
+        case "prune-superseded": {
+            const pruneResult = await pruneSuperseded(projectNotes, mode ?? defaultConsolidationMode, project, cwd, policy, allowProtectedBranch);
+            invalidateActiveProjectCache();
+            return pruneResult;
+        }
         case "dry-run":
             return dryRunAll(projectNotes, threshold, defaultConsolidationMode, project, mode);
         default:
@@ -4268,7 +4522,7 @@ server.registerPrompt("mnemonic-workflow-hint", {
                     "1. Need to store, refine, or connect knowledge about a topic? Start with `recall`, or use `list` when you need deterministic browsing by scope, storage, or tags.\n" +
                     "2. If `recall` or `list` returns matching ids, use `get` to inspect the best match.\n" +
                     "3. If one memory should be refined, call `update`.\n" +
-                    "4. If no memory covers the topic, call `discover_tags` if tags matter, then call `remember`.\n" +
+                    "4. If no memory covers the topic and tag choice is ambiguous, call `discover_tags` with note context, then call `remember`.\n" +
                     "5. After storing or updating, use `relate` for strong connections, `consolidate` for overlap, and `move_memory` for wrong storage location.\n\n" +
                     "### Anti-patterns\n\n" +
                     "- Bad: call `remember` immediately because the user said 'remember'.\n" +
@@ -4286,7 +4540,7 @@ server.registerPrompt("mnemonic-workflow-hint", {
                     "- project memory policy lookup\n\n" +
                     "### Tiny examples\n\n" +
                     "- Existing bug note found by `recall` -> inspect with `get` -> refine with `update`.\n" +
-                    "- No matching note found by `recall` -> optional `discover_tags` -> create with `remember`.\n" +
+                    "- No matching note found by `recall` -> optional `discover_tags` with note context -> create with `remember`.\n" +
                     "- Two notes overlap heavily -> inspect -> clean up with `consolidate`.",
             },
         },