@danielmarbach/mnemonic-mcp 0.19.5 → 0.21.0

package/build/index.js

@@ -10,15 +10,16 @@ import { embed, cosineSimilarity, embedModel } from "./embeddings.js";
 import { buildTemporalHistoryEntry, computeConfidence, getNoteProvenance } from "./provenance.js";
 import { enrichTemporalHistory } from "./temporal-interpretation.js";
 import { getOrBuildProjection } from "./projections.js";
-import { invalidateActiveProjectCache, getOrBuildVaultEmbeddings, getOrBuildVaultNoteList, getSessionCachedNote, } from "./cache.js";
+import { invalidateActiveProjectCache, getOrBuildVaultEmbeddings, getOrBuildVaultNoteList, getSessionCachedNote, getSessionCachedProjection, setSessionCachedProjection, } from "./cache.js";
 import { performance } from "perf_hooks";
 import { filterRelationships, mergeRelationshipsFromNotes, normalizeMergePlanSourceIds, resolveEffectiveConsolidationMode, } from "./consolidate.js";
-import { computeRecallMetadataBoost, selectRecallResults } from "./recall.js";
+import { computeRecallMetadataBoost, computeHybridScore, selectRecallResults, applyLexicalReranking } from "./recall.js";
+import { shouldTriggerLexicalRescue, computeLexicalScore, LEXICAL_RESCUE_CANDIDATE_LIMIT, LEXICAL_RESCUE_THRESHOLD, LEXICAL_RESCUE_RESULT_LIMIT, } from "./lexical.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";
-import { classifyTheme, classifyThemeWithGraduation, computeThemesWithGraduation, summarizePreview, titleCaseTheme, withinThemeScore, anchorScore, computeConnectionDiversity, } from "./project-introspection.js";
+import { classifyTheme, classifyThemeWithGraduation, computeThemesWithGraduation, summarizePreview, titleCaseTheme, daysSinceUpdate, withinThemeScore, anchorScore, computeConnectionDiversity, workingStateScore, extractNextAction, } from "./project-introspection.js";
 import { getEffectiveMetadata } from "./role-suggestions.js";
 import { detectProject, getCurrentGitBranch, resolveProjectIdentity } from "./project.js";
 import { VaultManager } from "./vault.js";
@@ -320,6 +321,18 @@ async function resolveProject(cwd) {
         getProjectIdentityOverride: async (projectId) => configStore.getProjectIdentityOverride(projectId),
     });
 }
+function toProjectRef(project) {
+    return project ? { id: project.id, name: project.name } : undefined;
+}
+function noteProjectRef(note) {
+    if (!note.project || !note.projectName) {
+        return undefined;
+    }
+    return {
+        id: note.project,
+        name: note.projectName,
+    };
+}
 async function resolveProjectIdentityForCwd(cwd) {
     if (!cwd)
         return undefined;
@@ -1727,6 +1740,52 @@ server.registerTool("get_project_memory_policy", {
         structuredContent,
     };
 });
+// ── Lexical rescue helper ─────────────────────────────────────────────────────
+async function collectLexicalRescueCandidates(vaults, query, project, scope, tags, existingIds) {
+    const existingIdSet = new Set(existingIds.map((c) => c.id));
+    const candidates = [];
+    for (const vault of vaults) {
+        const notes = await vault.storage.listNotes().catch(() => []);
+        for (const note of notes) {
+            if (existingIdSet.has(note.id))
+                continue;
+            if (tags && tags.length > 0) {
+                const noteTags = new Set(note.tags);
+                if (!tags.every((t) => noteTags.has(t)))
+                    continue;
+            }
+            const isProjectNote = note.project !== undefined;
+            const isCurrentProject = project && note.project === project.id;
+            if (scope === "project" && !isCurrentProject)
+                continue;
+            if (scope === "global" && isProjectNote)
+                continue;
+            const projection = await getOrBuildProjection(vault.storage, note).catch(() => undefined);
+            if (!projection)
+                continue;
+            const lexicalScore = computeLexicalScore(query, projection.projectionText);
+            if (lexicalScore < LEXICAL_RESCUE_THRESHOLD)
+                continue;
+            const metadataBoost = computeRecallMetadataBoost(getEffectiveMetadata(note));
+            const boost = (isCurrentProject ? 0.15 : 0) + metadataBoost;
+            candidates.push({
+                id: note.id,
+                score: 0,
+                boosted: boost,
+                vault,
+                isCurrentProject: Boolean(isCurrentProject),
+                lexicalScore,
+            });
+            if (candidates.length >= LEXICAL_RESCUE_CANDIDATE_LIMIT)
+                break;
+        }
+        if (candidates.length >= LEXICAL_RESCUE_CANDIDATE_LIMIT)
+            break;
+    }
+    return candidates
+        .sort((a, b) => computeHybridScore(b) - computeHybridScore(a))
+        .slice(0, LEXICAL_RESCUE_RESULT_LIMIT);
+}
 // ── recall ────────────────────────────────────────────────────────────────────
 server.registerTool("recall", {
     title: "Recall",
@@ -1768,9 +1827,10 @@ server.registerTool("recall", {
             .describe("'project' = only this project's memories (project-scoped storage), " +
             "'global' = only unscoped memories (main/global storage), " +
             "'all' = both, with project notes boosted (default)"),
+        lifecycle: z.enum(["temporary", "permanent"]).optional().describe("Filter results by lifecycle. Useful for recovering working-state with `lifecycle: temporary` after `project_memory_summary` orientation."),
     }),
     outputSchema: RecallResultSchema,
-}, async ({ query, cwd, limit, minSimilarity, mode, verbose, tags, scope }) => {
+}, async ({ query, cwd, limit, minSimilarity, mode, verbose, tags, scope, lifecycle }) => {
     const t0Recall = performance.now();
     await ensureBranchSynced(cwd);
     const project = await resolveProject(cwd);
@@ -1816,6 +1876,9 @@ server.registerTool("recall", {
                 if (!tags.every((t) => noteTags.has(t)))
                     continue;
             }
+            if (lifecycle && note.lifecycle !== lifecycle) {
+                continue;
+            }
             const isProjectNote = note.project !== undefined;
             const isCurrentProject = project && note.project === project.id;
             if (scope === "project") {
@@ -1831,7 +1894,42 @@ server.registerTool("recall", {
             scored.push({ id: rec.id, score: rawScore, boosted: rawScore + boost, vault, isCurrentProject: Boolean(isCurrentProject) });
         }
     }
-    const top = selectRecallResults(scored, limit, scope);
+    const projectionTexts = new Map();
+    for (const candidate of scored) {
+        const note = await readCachedNote(candidate.vault, candidate.id).catch(() => null);
+        if (!note) {
+            continue;
+        }
+        const projection = await getOrBuildProjection(candidate.vault.storage, note).catch(() => undefined);
+        if (!projection) {
+            continue;
+        }
+        projectionTexts.set(candidate.id, projection.projectionText);
+        if (project) {
+            setSessionCachedProjection(project.id, candidate.id, projection);
+        }
+    }
+    // Apply lexical reranking over semantic candidates (fail-soft)
+    const getProjectionText = (id) => {
+        const inlineProjection = projectionTexts.get(id);
+        if (inlineProjection) {
+            return inlineProjection;
+        }
+        if (project) {
+            const cached = getSessionCachedProjection(project.id, id);
+            if (cached)
+                return cached.projectionText;
+        }
+        return undefined;
+    };
+    const reranked = applyLexicalReranking(scored, query, getProjectionText);
+    // Lexical rescue: when semantic results are weak, scan projections for additional candidates
+    const topScore = reranked.length > 0 ? reranked[0].score : undefined;
+    if (shouldTriggerLexicalRescue(topScore, reranked.length)) {
+        const rescueCandidates = await collectLexicalRescueCandidates(vaults, query, project ?? undefined, scope, tags, reranked);
+        reranked.push(...rescueCandidates);
+    }
+    const top = selectRecallResults(reranked, limit, scope);
     if (top.length === 0) {
         const structuredContent = { action: "recalled", query, scope: scope || "all", results: [] };
         return { content: [{ type: "text", text: "No memories found matching that query." }], structuredContent };
@@ -1885,8 +1983,7 @@ server.registerTool("recall", {
                 title: note.title,
                 score,
                 boosted,
-                project: note.project,
-                projectName: note.projectName,
+                project: noteProjectRef(note),
                 vault: storageLabel(vault),
                 tags: note.tags,
                 lifecycle: note.lifecycle,
@@ -2060,8 +2157,7 @@ server.registerTool("update", {
         title: updated.title,
         fieldsModified: changes,
         timestamp: now,
-        project: updated.project,
-        projectName: updated.projectName,
+        project: noteProjectRef(updated),
         lifecycle: updated.lifecycle,
         persistence,
     };
@@ -2165,8 +2261,7 @@ server.registerTool("forget", {
         action: "forgotten",
         id,
         title: note.title,
-        project: note.project,
-        projectName: note.projectName,
+        project: noteProjectRef(note),
         relationshipsCleaned: vaultChanges.size > 0 ? Array.from(vaultChanges.values()).reduce((sum, files) => sum + files.length - 1, 0) : 0,
         vaultsModified: Array.from(vaultChanges.keys()).map(v => storageLabel(v)),
         retry,
@@ -2244,10 +2339,10 @@ server.registerTool("get", {
             id: note.id,
             title: note.title,
             content: note.content,
-            project: note.project,
-            projectName: note.projectName,
+            project: noteProjectRef(note),
             tags: note.tags,
             lifecycle: note.lifecycle,
+            alwaysLoad: note.alwaysLoad,
             relatedTo: note.relatedTo,
             createdAt: note.createdAt,
             updatedAt: note.updatedAt,
@@ -2258,7 +2353,7 @@ server.registerTool("get", {
     const lines = [];
     for (const note of found) {
         lines.push(`## ${note.title} (${note.id})`);
-        lines.push(`project: ${note.projectName ?? note.project ?? "global"} | stored: ${note.vault} | lifecycle: ${note.lifecycle}`);
+        lines.push(`project: ${note.project?.name ?? "global"} | stored: ${note.vault} | lifecycle: ${note.lifecycle}`);
         if (note.tags.length > 0)
             lines.push(`tags: ${note.tags.join(", ")}`);
         lines.push("");
@@ -2323,8 +2418,7 @@ server.registerTool("where_is_memory", {
         action: "located",
         id: note.id,
         title: note.title,
-        project: note.project,
-        projectName: note.projectName,
+        project: noteProjectRef(note),
         vault: vaultLabel,
         updatedAt: note.updatedAt,
         relatedCount,
@@ -2402,8 +2496,7 @@ server.registerTool("list", {
     const structuredNotes = entries.map(({ note, vault }) => ({
         id: note.id,
         title: note.title,
-        project: note.project,
-        projectName: note.projectName,
+        project: noteProjectRef(note),
         tags: note.tags,
         lifecycle: note.lifecycle,
         vault: storageLabel(vault),
@@ -2704,16 +2797,21 @@ server.registerTool("recent_memories", {
         limit: z.number().int().min(1).max(20).optional().default(5),
         includePreview: z.boolean().optional().default(true),
         includeStorage: z.boolean().optional().default(true),
+        lifecycle: z.enum(["temporary", "permanent"]).optional().describe("Filter results by lifecycle. Useful for recovering working-state with `lifecycle: temporary` after `project_memory_summary` orientation."),
     }),
     outputSchema: RecentResultSchema,
-}, async ({ cwd, scope, storedIn, limit, includePreview, includeStorage }) => {
+}, async ({ cwd, scope, storedIn, limit, includePreview, includeStorage, lifecycle }) => {
     await ensureBranchSynced(cwd);
     const { project, entries } = await collectVisibleNotes(cwd, scope, undefined, storedIn);
-    const recent = [...entries]
+    let filteredEntries = entries;
+    if (lifecycle) {
+        filteredEntries = entries.filter(({ note }) => note.lifecycle === lifecycle);
+    }
+    const recent = [...filteredEntries]
         .sort((a, b) => b.note.updatedAt.localeCompare(a.note.updatedAt))
         .slice(0, limit);
     if (recent.length === 0) {
-        const structuredContent = { action: "recent_shown", project: project?.id, projectName: project?.name, count: 0, limit: limit || 5, notes: [] };
+        const structuredContent = { action: "recent_shown", project: toProjectRef(project), count: 0, limit: limit || 5, notes: [] };
         return { content: [{ type: "text", text: "No memories found." }], structuredContent };
     }
     const header = project && scope !== "global"
@@ -2728,8 +2826,7 @@ server.registerTool("recent_memories", {
     const structuredNotes = recent.map(({ note, vault }) => ({
         id: note.id,
         title: note.title,
-        project: note.project,
-        projectName: note.projectName,
+        project: noteProjectRef(note),
         tags: note.tags,
         lifecycle: note.lifecycle,
         vault: storageLabel(vault),
@@ -2738,8 +2835,7 @@ server.registerTool("recent_memories", {
     }));
     const structuredContent = {
         action: "recent_shown",
-        project: project?.id,
-        projectName: project?.name,
+        project: toProjectRef(project),
         count: recent.length,
         limit: limit || 5,
         notes: structuredNotes,
@@ -2778,7 +2874,7 @@ server.registerTool("memory_graph", {
     await ensureBranchSynced(cwd);
     const { project, entries } = await collectVisibleNotes(cwd, scope, undefined, storedIn);
     if (entries.length === 0) {
-        const structuredContent = { action: "graph_shown", project: project?.id, projectName: project?.name, nodes: [], limit, truncated: false };
+        const structuredContent = { action: "graph_shown", project: toProjectRef(project), nodes: [], limit, truncated: false };
         return { content: [{ type: "text", text: "No memories found." }], structuredContent };
     }
     const visibleIds = new Set(entries.map((entry) => entry.note.id));
@@ -2793,7 +2889,7 @@ server.registerTool("memory_graph", {
     })
         .filter(Boolean);
     if (lines.length === 0) {
-        const structuredContent = { action: "graph_shown", project: project?.id, projectName: project?.name, nodes: [], limit, truncated: false };
+        const structuredContent = { action: "graph_shown", project: toProjectRef(project), nodes: [], limit, truncated: false };
         return { content: [{ type: "text", text: "No relationships found for that scope." }], structuredContent };
     }
     const header = project && scope !== "global"
@@ -2817,8 +2913,7 @@ server.registerTool("memory_graph", {
         .filter((node) => node.edges.length > 0);
     const structuredContent = {
         action: "graph_shown",
-        project: project?.id,
-        projectName: project?.name,
+        project: toProjectRef(project),
         nodes: structuredNodes,
         limit,
         truncated: structuredNodes.length < entries.filter(e => (e.note.relatedTo?.length ?? 0) > 0).length,
@@ -2838,6 +2933,7 @@ server.registerTool("project_memory_summary", {
         "Returns:\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" +
+        "- Optional compact working-state recovery hints when relevant temporary notes exist\n\n" +
         "Read-only.\n\n" +
         "Typical next step:\n" +
         "- Use `recall` or `list` to drill down into specific areas.",
@@ -2978,6 +3074,48 @@ server.registerTool("project_memory_summary", {
         .slice(0, recentLimit);
     sections.push(`\nRecent activity (start here):`);
     sections.push(...recent.map(e => `- ${e.note.updatedAt} — ${e.note.title}`));
+    const temporaryEntries = projectEntries
+        .filter((entry) => entry.note.lifecycle === "temporary")
+        .map((entry) => {
+        const metadata = effectiveMetadataById.get(entry.note.id)?.metadata;
+        const score = workingStateScore(entry.note, metadata);
+        const nextAction = extractNextAction(entry.note);
+        const relatedCount = entry.note.relatedTo?.length ?? 0;
+        const days = daysSinceUpdate(entry.note.updatedAt);
+        const rationaleParts = [`updated ${days < 1 ? "today" : `${Math.round(days)}d ago`}`];
+        if (relatedCount > 0)
+            rationaleParts.push(`${relatedCount} linked note${relatedCount === 1 ? "" : "s"}`);
+        if (nextAction)
+            rationaleParts.push("explicit next action");
+        if (metadata?.role === "plan" || metadata?.role === "context")
+            rationaleParts.push(`${metadata.role} note`);
+        return {
+            entry,
+            score,
+            rationale: rationaleParts.join(", "),
+            preview: summarizePreview(entry.note.content, 120),
+            nextAction,
+        };
+    })
+        .filter((candidate) => candidate.score > -Infinity)
+        .sort((a, b) => b.score - a.score || b.entry.note.updatedAt.localeCompare(a.entry.note.updatedAt))
+        .slice(0, 3);
+    const workingState = temporaryEntries.length > 0
+        ? {
+            summary: temporaryEntries.length === 1
+                ? `1 temporary note may help resume active work.`
+                : `${temporaryEntries.length} temporary notes may help resume active work.`,
+            recoveryHint: "Orient with project_memory_summary first, then inspect these temporary notes if you need to continue in-progress work.",
+            notes: temporaryEntries.map(({ entry, rationale, preview, nextAction }) => ({
+                id: entry.note.id,
+                title: entry.note.title,
+                updatedAt: entry.note.updatedAt,
+                rationale,
+                preview,
+                nextAction,
+            })),
+        }
+        : undefined;
     // Anchor notes with diversity constraint (project-scoped only)
     const scoredAnchorCandidates = projectEntries
         .map(e => {
@@ -3127,11 +3265,14 @@ server.registerTool("project_memory_summary", {
     }
     const suggestedEnriched = await Promise.all(suggestedCandidates.map(enrichOrientationNote));
     const suggestedRelationships = await Promise.all(suggestedCandidates.map(enrichOrientationNoteWithRelationships));
+    const recentPermanent = recent.find((entry) => entry.note.lifecycle === "permanent");
+    const fallbackEntry = recentPermanent ?? recent[0];
+    const permanentOverrideUsed = Boolean(recentPermanent && recent[0] && recentPermanent.note.id !== recent[0].note.id);
     // Enrich fallback primaryEntry when no anchors exist
     let fallbackEnriched = {};
     let fallbackRelationships = {};
-    if (!primaryAnchor && recent[0]) {
-        const fallbackNote = recent[0].note;
+    if (!primaryAnchor && fallbackEntry) {
+        const fallbackNote = fallbackEntry.note;
         const vault = noteVaultMap.get(fallbackNote.id);
         if (vault) {
             const filePath = `${vault.notesRelDir}/${fallbackNote.id}.md`;
@@ -3153,11 +3294,13 @@ server.registerTool("project_memory_summary", {
                 ...primaryRelationships,
             }
             : {
-                id: recent[0]?.note.id ?? projectEntries[0]?.note.id ?? "",
-                title: recent[0]?.note.title ?? projectEntries[0]?.note.title ?? "No notes",
-                rationale: recent[0]
-                    ? "Most recent note — no high-centrality anchors found"
-                    : "Only note available",
+                id: fallbackEntry?.note.id ?? projectEntries[0]?.note.id ?? "",
+                title: fallbackEntry?.note.title ?? projectEntries[0]?.note.title ?? "No notes",
+                rationale: permanentOverrideUsed
+                    ? "Most recent permanent note — no high-centrality anchors found"
+                    : fallbackEntry
+                        ? "Most recent note — no high-centrality anchors found"
+                        : "Only note available",
                 ...fallbackEnriched,
                 ...fallbackRelationships,
             },
@@ -3203,6 +3346,18 @@ server.registerTool("project_memory_summary", {
             sections.push(`  - ${w}`);
         }
     }
+    if (workingState) {
+        sections.push(`\nWorking state:`);
+        sections.push(workingState.summary);
+        sections.push(`Recovery hint: ${workingState.recoveryHint}`);
+        for (const note of workingState.notes) {
+            sections.push(`- ${note.title} (\`${note.id}\`) — ${note.rationale}`);
+            sections.push(`  Preview: ${note.preview}`);
+            if (note.nextAction) {
+                sections.push(`  Next action: ${note.nextAction}`);
+            }
+        }
+    }
     // Related global notes (optional, anchor-based similarity)
     const structuredContent = {
         action: "project_summary_shown",
@@ -3222,6 +3377,7 @@ server.registerTool("project_memory_summary", {
         })),
         anchors,
         orientation,
+        workingState,
         relatedGlobal,
     };
     console.error(`[summary:timing] ${(performance.now() - t0Summary).toFixed(1)}ms`);
@@ -3977,8 +4133,7 @@ async function detectDuplicates(entries, threshold, project) {
     const structuredContent = {
         action: "consolidated",
         strategy: "detect-duplicates",
-        project: project?.id,
-        projectName: project?.name,
+        project: toProjectRef(project),
         notesProcessed: entries.length,
         notesModified: 0,
     };
@@ -4065,8 +4220,7 @@ function findClusters(entries, project) {
     const structuredContent = {
         action: "consolidated",
         strategy: "find-clusters",
-        project: project?.id,
-        projectName: project?.name,
+        project: toProjectRef(project),
         notesProcessed: entries.length,
         notesModified: 0,
         themeGroups,
@@ -4153,8 +4307,7 @@ async function suggestMerges(entries, threshold, defaultConsolidationMode, proje
     const structuredContent = {
         action: "consolidated",
         strategy: "suggest-merges",
-        project: project?.id,
-        projectName: project?.name,
+        project: toProjectRef(project),
         notesProcessed: entries.length,
         notesModified: 0,
     };
@@ -4178,8 +4331,7 @@ async function executeMerge(entries, mergePlan, defaultConsolidationMode, projec
         const structuredContent = {
             action: "consolidated",
             strategy: "execute-merge",
-            project: project?.id,
-            projectName: project?.name,
+            project: toProjectRef(project),
             notesProcessed: entries.length,
             notesModified: 0,
             warnings: ["execute-merge requires at least two distinct sourceIds."],
@@ -4190,8 +4342,7 @@ async function executeMerge(entries, mergePlan, defaultConsolidationMode, projec
         const structuredContent = {
             action: "consolidated",
             strategy: "execute-merge",
-            project: project?.id,
-            projectName: project?.name,
+            project: toProjectRef(project),
             notesProcessed: entries.length,
             notesModified: 0,
             warnings: ["execute-merge requires a non-empty targetTitle."],
@@ -4206,8 +4357,7 @@ async function executeMerge(entries, mergePlan, defaultConsolidationMode, projec
             const structuredContent = {
                 action: "consolidated",
                 strategy: "execute-merge",
-                project: project?.id,
-                projectName: project?.name,
+                project: toProjectRef(project),
                 notesProcessed: entries.length,
                 notesModified: 0,
                 warnings: [`Source note '${id}' not found.`],
@@ -4242,8 +4392,7 @@ async function executeMerge(entries, mergePlan, defaultConsolidationMode, projec
             const structuredContent = {
                 action: "consolidated",
                 strategy: "execute-merge",
-                project: project?.id,
-                projectName: project?.name,
+                project: toProjectRef(project),
                 notesProcessed: entries.length,
                 notesModified: 0,
                 warnings: [message],
@@ -4455,8 +4604,7 @@ async function executeMerge(entries, mergePlan, defaultConsolidationMode, projec
     const structuredContent = {
         action: "consolidated",
         strategy: "execute-merge",
-        project: project?.id,
-        projectName: project?.name,
+        project: toProjectRef(project),
         notesProcessed: entries.length,
         notesModified: vaultChanges.size,
         persistence,
@@ -4496,8 +4644,7 @@ async function pruneSuperseded(entries, consolidationMode, project, cwd, policy,
         const structuredContent = {
             action: "consolidated",
             strategy: "prune-superseded",
-            project: project?.id,
-            projectName: project?.name,
+            project: toProjectRef(project),
             notesProcessed: entries.length,
             notesModified: 0,
             warnings: [`prune-superseded requires consolidationMode="delete". Current mode: ${consolidationMode}.`],
@@ -4529,8 +4676,7 @@ async function pruneSuperseded(entries, consolidationMode, project, cwd, policy,
         const structuredContent = {
             action: "consolidated",
             strategy: "prune-superseded",
-            project: project?.id,
-            projectName: project?.name,
+            project: toProjectRef(project),
             notesProcessed: entries.length,
             notesModified: 0,
         };
@@ -4559,8 +4705,7 @@ async function pruneSuperseded(entries, consolidationMode, project, cwd, policy,
             const structuredContent = {
                 action: "consolidated",
                 strategy: "prune-superseded",
-                project: project?.id,
-                projectName: project?.name,
+                project: toProjectRef(project),
                 notesProcessed: entries.length,
                 notesModified: 0,
                 warnings: [message],
@@ -4615,8 +4760,7 @@ async function pruneSuperseded(entries, consolidationMode, project, cwd, policy,
     const structuredContent = {
         action: "consolidated",
         strategy: "prune-superseded",
-        project: project?.id,
-        projectName: project?.name,
+        project: toProjectRef(project),
         notesProcessed: entries.length,
         notesModified: vaultChanges.size,
         retry,
@@ -4644,8 +4788,7 @@ async function dryRunAll(entries, threshold, defaultConsolidationMode, project,
     const structuredContent = {
         action: "consolidated",
         strategy: "dry-run",
-        project: project?.id,
-        projectName: project?.name,
+        project: toProjectRef(project),
         notesProcessed: entries.length,
         notesModified: 0,
     };
@@ -4691,11 +4834,32 @@ server.registerPrompt("mnemonic-workflow-hint", {
                     "- For repo-related tasks, pass `cwd` so mnemonic can route project memories correctly.\n\n" +
                     "Workflow: `recall`/`list` -> `get` -> `update` or `remember` -> `relate`/`consolidate`/`move_memory`. Use `discover_tags` only when tag choice is ambiguous.\n\n" +
                     "Roles are optional prioritization hints, not schema. Lifecycle still governs durability. `role: plan` does not imply `temporary`. Inferred roles are internal hints only. Prioritization is language-independent by default.\n\n" +
+                    "### Working-state continuity\n\n" +
+                    "Preserve in-progress work as temporary notes when continuation value is high. Recovery happens after project orientation.\n\n" +
+                    "**Checkpoint note structure (temporary notes):**\n" +
+                    "- Title pattern: 'WIP: <topic>' or 'Checkpoint: <description>'\n" +
+                    "- Opening paragraph: current status and next immediate step\n" +
+                    "- Body: what was attempted, what worked, blockers, alternatives considered\n" +
+                    "- End with explicit next action and confidence level\n\n" +
+                    "**Checkpoint note guidance:**\n" +
+                    "- One checkpoint per active task or investigation thread\n" +
+                    "- Update the same checkpoint note as work progresses (don't create new ones)\n" +
+                    "- Link to related decisions: use `relate` to connect temporary checkpoints to permanent decisions\n" +
+                    "- Consolidate into a durable note when complete; let lifecycle defaults delete temporary scaffolding unless you intentionally need preserved history\n\n" +
+                    "**Recovery workflow:**\n" +
+                    "- Call `project_memory_summary` first for orientation (do not skip to recovery)\n" +
+                    "- Use `lifecycle: temporary` for active plans, WIP checkpoints, draft investigations, and unvalidated options\n" +
+                    "- Use `lifecycle: permanent` for decisions, discovered constraints, bug causes, and reusable lessons\n" +
+                    "- After orientation, recover working-state from temporary notes via `recall` with lifecycle filter\n" +
+                    "- Consolidate temporary notes into durable ones once knowledge stabilizes\n" +
+                    "- Recovery is a follow-on step, not a replacement for orientation\n\n" +
                     "### Anti-patterns\n\n" +
                     "- Bad: call `remember` immediately because the user said 'remember'.\n" +
                     "- Good: `recall` or `list` first, then `get`, then `update` or `remember`.\n" +
                     "- Bad: create another note when `recall` or `list` already found the same decision.\n" +
-                    "- Good: `update` the existing memory and relate it if needed.\n\n" +
+                    "- Good: `update` the existing memory and relate it if needed.\n" +
+                    "- Bad: skip orientation and jump straight to working-state recovery.\n" +
+                    "- Good: `project_memory_summary` first, then recover temporary notes.\n\n" +
                     "### Storage model\n\n" +
                     "Memories can live in:\n" +
                     "- `main-vault` for global knowledge\n" +
@@ -4708,7 +4872,8 @@ server.registerPrompt("mnemonic-workflow-hint", {
                     "### 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` with note context -> create with `remember`.\n" +
-                    "- Two notes overlap heavily -> inspect -> clean up with `consolidate`.",
+                    "- Two notes overlap heavily -> inspect -> clean up with `consolidate`.\n" +
+                    "- Resume work: `project_memory_summary` -> `recall` (lifecycle: temporary) -> continue from temporary notes.",
             },
         },
     ],